/ 
Games-OpenGL-Font-2D-0.07
River stage one • 2 direct dependents • 2 total dependents
/ Games::OpenGL::Font::2D

NAME

Games::OpenGL::Font::2D - load/render 2D colored bitmap fonts via OpenGL

SYNOPSIS

	use Games::OpenGL::Font::2D;

	my $font = Games::OpenGL::Font::2D->new( 
          file => 'font.bmp' );

	use SDL::App::FPS;

	my $app = SDL::App::FPS->new( ... );

	# don't forget to change these on resize events!
	$font->screen_width( $app->width() );
	$font->screen_height( $app->width() );

	$font->pre_output();		# setup rendering for font
	
	$font->color( [ 0,1,0] );	# yellow as array ref
	$font->color( 1,0,0 );		# or red
	$font->alpha( 0.8 );		# nearly opaque

	# half-transparent, red
	$font->output (100,100, 'Hello OpenGL!', [ 1,0,0], 0.5 );
	# using the $font's color and alpha
	$font->output (100,200, 'Hello OpenGL!' );
	
	$font->transparent( 1 );	# render font background transparent
	
	$font->spacing_y( 16 );		# render vertical (costly rebuild!)
	$font->spacing_x( 0 );		# (costly rebuild!)
	$font->output (100,200, 'Hello OpenGL!' );

	$font->post_output();		# if wanted, you can reset OpenGL

EXPORTS

Exports nothing on default. Can export on demand the following:

FONT_ALIGN_LEFT
FONT_ALIGN_RIGHT
FONT_ALIGN_CENTER
FONT_ALIGN_TOP
FONT_ALIGN_BOTTOM

DESCRIPTION

This package lets you load and render colored bitmap fonts via OpenGL.

METHODS

new()
my $font = OpenGL::Font::2D->new( $args );

Load a font into memory and return an object reference. $args is a hash ref containing the following keys:

	file		filename of font bitmap
	transparent	if true, render font background transparent (e.g.
			don't render the background)
	color		color of output text as array ref [r,g,b]
	alpha		blend font over background for semitransparent
	char_width	Width of each char on the texture
	char_height	Width of each char on the texture
  	chars		Number of characters on font-texture
	spacing_x	Spacing in X direction after each char
	spacing_y	Spacing in Y direction after each char
	align_x		Align the font output in X direction
			Possible: FONT_ALIGN_LEFT, FONT_ALIGN_RIGHT and
			FONT_ALIGN_CENTER
	align_y		Align the font output in Y direction
			Possible: FONT_ALIGN_TOP, FONT_ALIGN_BOTTOM and
			FONT_ALIGN_CENTER
	border_x	Space between each char in the texture in X dir
	border_y	Likewise border_x, but in Y dir

Example:

my $font = OpenGL::Font::2D->new( file => 'data/courier.txt',
	char_width => 11, char_height => 21, 
	zoom_x => 2, zoom_y => 1,
	spacing_x => 21, spacing_y => 0,
);
output()
$font->output ($x,$y, $string, $color, $alpha);

Output the string $string at the coordinates $x and $y. 0,0 is at the lower left corner of the screen.

$color and $alpha are optional and if omitted or given as undef, will be taken from the font's internal values, which can be given at new() or modified with the routines below.

transparent()
$model->frames();

Get/set the font's transparent flag. Setting it to true renders the font background as transparent.

color()
$rgb = $font->color();		# [$r,$g, $b ]
$font->color(1,0.1,0.8);	# set RGB
$font->color([1,0.1,0.8]);	# same, as array ref
$font->color(undef);		# no color

Sets the color, that will be set to render the font. No color means the caller can set the color before calling output().

alpha()
        $a = $font->alpha();		# $a
        $font->color(0.8);		# set A
        $font->alpha(undef);		# set's it to 1.0 (seems an OpenGL
					# specific set because
					# glColor($r,$g,$b) also sets $a == 1

Sets the alpha value of the rendered output.

spacing_x()
$x = $font->spacing_x();
$font->spacing_x( $new_width );

Get/set the width of each character. Default is 10. This is costly, since it needs to rebuild the font. See also spacing_y() and spacing().

spacing_y()
$x = $font->spacing_y();
$font->spacing_y( $new_height );

Get/set the width of each character. Default is 0. This is costly, since it needs to rebuild the font. See also spacing_x() and spacing().

spacing()
($x,$y) = $font->spacing();
$font->spacing( $new_width, $new_height );

Get/set the width and height of each character. Default is 10 and 0. This is costly, since it needs to rebuild the font. If you need to render vertical texts, you can use this:

$font->spacing(0,16);

However, for mixing vertical and horizontal text, better create two font's objects by cloning an existing:

$font_hor = OpenGL::Font::2D->new( ... );
$font_ver = $font_hor->copy();
$font_ver->spacing(0,16);

The two font objects will thus share the texture, and you don't need to rebuild the font by setting the spacing for each text you want to render.

See also spacing_x() and spacing_y().

zoom()
($x,$y) = $font->zoom();
$font->zoom( $new_width, $new_height );

Get/set the zoom factor for each character. Default is 1 and 1. This is costly, since it needs to rebuild the font. See spacing() on how to avoid the font-rebuilding for each text output.

pre_output()
$font->pre_output();

Sets up OpenGL so that the font can be rendered on the screen.

post_output()
$font->post_output();

Resets some OpenGL stuff after rendering. If you reset OpenGL for the next frame anyway, or use a different font's pre_ouput() afterwards, you can skip this.

Please remember to enable/disable any flags that you might want.

Also note, post_output() enables writes to the depth buffer, regardless of whether they were enabled or not before pre_output() was called.

border_x()
$bx = $font->border_x();
$font->border_x( 1 );

Get/set the border on the right side of each char on the texture map. E.g. if each char is 31 pixel wide, but occupies 32 pixel, border_x should be set to 1. Costly, since it rebuilds the font.

border_y()
$by = $font->border_y();
$font->border_y( 1 );

Get/set the border on the lower side of each char on the texture map. E.g. if each char is 31 pixel heigh, but occupies 32 pixel, border_y should be set to 1. Costly, since it rebuilds the font.

align_x()
$x = $font->align_x();
$font->align_x( FONT_ALIGN_RIGHT );

Get/set the alignment of the output in X direction.

align_y()
$x = $font->align_y();
$font->align_y( FONT_ALIGN_TOP );

Get/set the alignment of the output in Y direction.

align()
($x,$y) = $font->align();
$font->align( FONT_ALIGN_RIGHT, FONT_ALIGN_TOP );

Get/set the alignment of the output in X and Y direction.

char_width()
$w = $font->char_width();

Get the width of one character.

char_height()
$w = $font->char_height();

Get the height of one character.

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

(c) 2003, 2006 Tels <http://bloodgate.com/>

SEE ALSO

Games::3D, SDL:App::FPS, and SDL::OpenGL.