The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
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.