NAME

OpenGL::Sandbox::V1::FTGLFont - Wrapper object for FTGL Fonts

VERSION

version 0.042

DESCRIPTION

FTGL is a C++ library that uses the FreeType library to read font glyphs and encodes them as OpenGL textures or vertex geometry. It then handles all the details of rendering a string of text with correct font spacing.

The library has a spectacularly designed API, and supports unicode, and other great things. Unfortunately, it is very tied to the OpenGL 1.x API, which is deprecated. If you are working on something simple and the 1.x API works for you, then this will solve your font needs and you can go merrily on your way.

This module is based on Inline::CPP, so it requires a C++ compiler in order to be installed.

ATTRIBUTES

type

The C++ font class to use. FTGL implements fonts in several different ways, such as texture-of-glyphs, texture-of-string, 3D model, 2D model, etc. These are represented by various C++ classes. The module Inline::CPP cannot currently parse the external class definitions of FTGL, so each FTGL class must be wrapped by code in the C++ portion of this module.

Currently must be one of 'FTTextureFont', 'FTExtrudeFont', 'FTPolygonFont', 'FTPixmapFont', 'FTOutlineFont', 'FTBufferFont', or 'FTBitmapFont'.

data

A scalar-ref to the bytes of a TrueType font, preferably via a "OpenGL::Sandbox::MMap" object.

filename

The name this data was loaded from, for informational purposes only.

face_size

When using textured fonts, this is roughly the pixel/texel size of the glyphs that will be rendered into the texture. When using geometric fonts (i.e. polygon-based) this will be the OpenGL coordinate space scale of the font.

ascender

The distance from baseline to top of typical glyph, in same units as face_size.

descender

The distance below the baseline that "hanging" portions of glyphs might reach, in same units as face_size.

line_height

Line spacing for the font, in same units as face_size.

METHODS

advance

  my $length= $font->advance("String of glyphs");

Calculate the width of a sting of text, in same units as face_size.

render

  $font->render($text, %opts);

Render some text using this font. By default, it renders with the baseline starting at the OpenGL origin. To save some awkward math, the following options are supported:

x, y

Use this reference coordinate instead of the OpenGL origin.

xalign

A number between 0 (left align) and 1 (right align). i.e. to center the text use 0.5.

yalign

0 puts the baseline at the y coordinate. 1 puts the ascender-line at the y coordinate. -1 puts the descender-line at the y coordinate. Numbers inbetween yield some fraction of those distances.

In other words,

   1   = 'top'
   0.5 = 'center'
   0   = 'baseline'
  -1   = 'bottom'

monospace

Ignore the spacing of the font face and always use this value to advance between glyphs. This number is in the same units as font_face. This value is affected by scale (below).

scale

Scale the x and y axis by this number before rendering. (but restores the OpenGL matrix before returning). This overrides a setting of height.

h, height

Scale the y axis so that the "ascender" equals this value. Also scale the x axis to match unless scale or height were specified, in which case this can change the aspect ratio of the text.

w, width

Scale x axis so that the length of the text is width. Also scale the y axis to match unless scale or height were specified, in which case this can change the aspect ratio of the text.

Note: If this is a TextureFont, it will change the current bound texture.

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm OpenGL::Sandbox::V1::FTGLFont

perl -MCPAN -e shell
install OpenGL::Sandbox::V1::FTGLFont