Panda3D
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
DynamicTextFont Class Reference

A DynamicTextFont is a special TextFont object that rasterizes its glyphs from a standard font file (e.g. More...

Inheritance diagram for DynamicTextFont:
TextFont FreetypeFont TypedReferenceCount Namable Namable TypedObject ReferenceCount

Public Member Functions

 __init__ (const DynamicTextFont copy)
 
 __init__ (const Filename font_filename, int face_index)
 The constructor expects the name of some font file that FreeType can read, along with face_index, indicating which font within the file to load (usually 0). More...
 
 __init__ (str font_data, int data_length, int face_index)
 This constructor accepts a table of data representing the font file, loaded from some source other than a filename on disk. More...
 
 clear ()
 Drops all the glyphs out of the cache and frees any association with any previously-generated pages. More...
 
int garbageCollect ()
 Removes all of the glyphs from the font that are no longer being used by any Geoms. More...
 
int getAnisotropicDegree ()
 Returns the current anisotropic degree for textures created for this font. More...
 
const LColor getBg ()
 Returns the color of the background pixels of the font as they are rendered into the font texture. More...
 
const LColor getFg ()
 Returns the color of the foreground pixels of the font as they are rendered into the font texture. More...
 
int getFontPixelSize ()
 This is used to report whether the requested pixel size is being only approximated by a fixed-pixel-size font. More...
 
float getLineHeight ()
 Returns the number of units high each line of text is. More...
 
SamplerState::FilterType getMagfilter ()
 Returns the filter type used when enlarging the textures created for this font. More...
 
SamplerState::FilterType getMinfilter ()
 Returns the filter type used when minimizing the textures created for this font. More...
 
str getName ()
 Disambiguates the get_name() method between that inherited from TextFont and that inherited from FreetypeFont. More...
 
bool getNativeAntialias ()
 Returns whether Freetype's built-in antialias mode is enabled. More...
 
int getNumPages ()
 Returns the number of pages associated with the font. More...
 
const LColor getOutlineColor ()
 Returns the color of the outline pixels of the font as they are rendered into the font texture. More...
 
float getOutlineFeather ()
 Returns the softness of the outline pixels of the font, as a value in the range 0.0 to 1.0. More...
 
float getOutlineWidth ()
 Returns the width of the outline pixels of the font, as the number of points beyond each letter. More...
 
DynamicTextPage getPage (int n)
 Returns the nth page associated with the font. More...
 
list getPages ()
 
const LVecBase2i getPageSize ()
 Returns the size of the textures that are created for the DynamicTextFont. More...
 
int getPageXSize ()
 Returns the x size of the textures that are created for the DynamicTextFont. More...
 
int getPageYSize ()
 Returns the y size of the textures that are created for the DynamicTextFont. More...
 
float getPixelsPerUnit ()
 Returns the resolution of the texture map. More...
 
float getPointSize ()
 Returns the point size of the font. More...
 
float getPolyMargin ()
 Returns the number of pixels of padding that is included around each glyph in the generated polygons. More...
 
TextFont::RenderMode getRenderMode ()
 Returns the way the glyphs on this particular font are generated. More...
 
float getScaleFactor ()
 Returns the antialiasing scale factor. More...
 
float getSpaceAdvance ()
 Returns the number of units wide a space is. More...
 
Texture::Format getTexFormat ()
 Returns the texture format used to render the individual pages. More...
 
int getTextureMargin ()
 Returns the number of pixels of padding that is added around the border of each glyph in the texture map. More...
 
TextFont makeCopy ()
 Returns a new copy of the same font. More...
 
 setAnisotropicDegree (int anisotropic_degree)
 Enables or disables anisotropic filtering on the textures created for this font. More...
 
 setBg (const LColor bg)
 Changes the color of the background pixels of the font as they are rendered into the font texture. More...
 
 setFg (const LColor fg)
 Changes the color of the foreground pixels of the font as they are rendered into the font texture. More...
 
 setMagfilter (SamplerState::FilterType filter)
 Sets the filter type used when enlarging the textures created for this font. More...
 
 setMinfilter (SamplerState::FilterType filter)
 Sets the filter type used when minimizing the textures created for this font. More...
 
 setNativeAntialias (bool native_antialias)
 Sets whether the Freetype library's built-in antialias mode is enabled. More...
 
 setOutline (const LColor outline_color, float outline_width, float outline_feather)
 Sets up the font to have an outline around each font letter. More...
 
 setPageSize (const LVecBase2i page_size)
 Sets the x, y size of the textures that are created for the DynamicTextFont. More...
 
 setPageSize (int x_size, int y_size)
 Sets the x, y size of the textures that are created for the DynamicTextFont. More...
 
bool setPixelsPerUnit (float pixels_per_unit)
 Set the resolution of the texture map, and hence the clarity of the resulting font. More...
 
bool setPointSize (float point_size)
 Sets the point size of the font. More...
 
 setPolyMargin (float poly_margin)
 Sets the number of pixels of padding that is included around each glyph in the generated polygons. More...
 
 setRenderMode (TextFont::RenderMode render_mode)
 Specifies the way the glyphs on this particular font are generated. More...
 
bool setScaleFactor (float scale_factor)
 Sets the factor by which the font is rendered larger by the FreeType library before being filtered down to its actual size in the texture as specified by set_pixels_per_unit(). More...
 
 setTextureMargin (int texture_margin)
 Sets the number of pixels of padding that is added around the border of each glyph before adding it to the texture map. More...
 
 write (Ostream out, int indent_level)
 
- Public Member Functions inherited from TextFont
const TextGlyph getGlyph (int character)
 Gets the glyph associated with the given character code, as well as an optional scaling parameter that should be applied to the glyph's geometry and advance parameters. More...
 
float getKerning (int first, int second)
 Returns the amount by which to offset the second glyph when it directly follows the first glyph. More...
 
float getLineHeight ()
 Returns the number of units high each line of text is. More...
 
float getSpaceAdvance ()
 Returns the number of units wide a space is. More...
 
bool isValid ()
 Returns true if the font is valid and ready to use, false otherwise. More...
 
TextFont makeCopy ()
 
 setLineHeight (float line_height)
 Changes the number of units high each line of text is. More...
 
 setSpaceAdvance (float space_advance)
 Changes the number of units wide a space is. More...
 
 write (Ostream out, int indent_level)
 
- Public Member Functions inherited from TypedObject
TypeHandle getType ()
 
int getTypeIndex ()
 Returns the internal index number associated with this object's TypeHandle, a unique number for each different type. More...
 
bool isExactType (TypeHandle handle)
 Returns true if the current object is the indicated type exactly. More...
 
bool isOfType (TypeHandle handle)
 Returns true if the current object is or derives from the indicated type. More...
 
- Public Member Functions inherited from ReferenceCount
int getRefCount ()
 Returns the current reference count. More...
 
 ref ()
 Explicitly increments the reference count. More...
 
bool testRefCountIntegrity ()
 Does some easy checks to make sure that the reference count isn't completely bogus. More...
 
bool testRefCountNonzero ()
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More...
 
bool unref ()
 Explicitly decrements the reference count. More...
 
- Public Member Functions inherited from Namable
 __init__ (const Namable)
 
 __init__ (str initial_name)
 
 clearName ()
 Resets the Namable's name to empty. More...
 
str getName ()
 
bool hasName ()
 Returns true if the Namable has a nonempty name set, false if the name is empty. More...
 
 output (Ostream out)
 Outputs the Namable. More...
 
 setName (str name)
 
- Public Member Functions inherited from FreetypeFont
int getFontPixelSize ()
 This is used to report whether the requested pixel size is being only approximated by a fixed-pixel-size font. More...
 
float getLineHeight ()
 Returns the number of units high each line of text is. More...
 
bool getNativeAntialias ()
 Returns whether Freetype's built-in antialias mode is enabled. More...
 
float getPixelSize ()
 Returns the size of the font in pixels, as it appears in the texture. More...
 
float getPixelsPerUnit ()
 Returns the resolution of the texture map. More...
 
float getPointSize ()
 Returns the point size of the font. More...
 
float getScaleFactor ()
 Returns the antialiasing scale factor. More...
 
float getSpaceAdvance ()
 Returns the number of units wide a space is. More...
 
FreetypeFont::WindingOrder getWindingOrder ()
 Returns the winding order set via set_winding_order(). More...
 
 setNativeAntialias (bool native_antialias)
 Sets whether the Freetype library's built-in antialias mode is enabled. More...
 
bool setPixelSize (float pixel_size)
 Computes the appropriate pixels_per_unit value to set the size of the font in the texture to the indicated number of pixels. More...
 
bool setPixelsPerUnit (float pixels_per_unit)
 Set the resolution of the texture map, and hence the clarity of the resulting font. More...
 
bool setPointSize (float point_size)
 Sets the point size of the font. More...
 
bool setScaleFactor (float scale_factor)
 Sets the factor by which the font is rendered larger by the FreeType library before being filtered down to its actual size in the texture as specified by set_pixels_per_unit(). More...
 
 setWindingOrder (FreetypeFont::WindingOrder winding_order)
 Specifies an explicitly winding order on this particular font. More...
 

Static Public Member Functions

static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TextFont
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedReferenceCount
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from TypedObject
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from ReferenceCount
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from Namable
static TypeHandle getClassType ()
 
- Static Public Member Functions inherited from FreetypeFont
static float getPointsPerInch ()
 Returns the number of points in one inch. More...
 
static float getPointsPerUnit ()
 Returns the point size of the font that is one Panda unit high. More...
 

Public Attributes

int anisotropic_degree
 Returns the current anisotropic degree for textures created for this font. More...
 
const LColor bg
 Returns the color of the background pixels of the font as they are rendered into the font texture. More...
 
const LColor fg
 Returns the color of the foreground pixels of the font as they are rendered into the font texture. More...
 
int font_pixel_size
 This is used to report whether the requested pixel size is being only approximated by a fixed-pixel-size font. More...
 
SamplerState::FilterType magfilter
 Returns the filter type used when enlarging the textures created for this font. More...
 
SamplerState::FilterType minfilter
 Returns the filter type used when minimizing the textures created for this font. More...
 
bool native_antialias
 Returns whether Freetype's built-in antialias mode is enabled. More...
 
const LVecBase2i page_size
 Returns the size of the textures that are created for the DynamicTextFont. More...
 
DynamicTextPage pages []
 
float pixels_per_unit
 Returns the resolution of the texture map. More...
 
float point_size
 Returns the point size of the font. More...
 
float poly_margin
 Returns the number of pixels of padding that is included around each glyph in the generated polygons. More...
 
TextFont::RenderMode render_mode
 Returns the way the glyphs on this particular font are generated. More...
 
float scale_factor
 Returns the antialiasing scale factor. More...
 
Texture::Format tex_format
 Returns the texture format used to render the individual pages. More...
 
int texture_margin
 Returns the number of pixels of padding that is added around the border of each glyph in the texture map. More...
 
- Public Attributes inherited from TextFont
float line_height
 Returns the number of units high each line of text is. More...
 
float space_advance
 Returns the number of units wide a space is. More...
 
bool valid
 Returns true if the font is valid and ready to use, false otherwise. More...
 
- Public Attributes inherited from TypedObject
TypeHandle type
 Returns the TypeHandle representing this object's type. More...
 
- Public Attributes inherited from ReferenceCount
int ref_count
 The current reference count. More...
 
- Public Attributes inherited from Namable
const String name
 
- Public Attributes inherited from FreetypeFont
FreetypeFont::WindingOrder winding_order
 Returns the winding order set via set_winding_order(). More...
 

Additional Inherited Members

- Public Types inherited from TextFont
enum  RenderMode {
  RM_texture = 0, RM_wireframe = 1, RM_polygon = 2, RM_extruded = 3,
  RM_solid = 4, RM_distance_field = 5, RM_invalid = 6
}
 
- Public Types inherited from FreetypeFont
enum  WindingOrder { WO_default = 0, WO_left = 1, WO_right = 2, WO_invalid = 3 }
 

Detailed Description

A DynamicTextFont is a special TextFont object that rasterizes its glyphs from a standard font file (e.g.

a TTF file) on the fly. It requires the FreeType 2.0 library (or any higher, backward-compatible version).

Member Function Documentation

◆ __init__() [1/3]

__init__ ( const DynamicTextFont  copy)

◆ __init__() [2/3]

__init__ ( const Filename  font_filename,
int  face_index 
)

The constructor expects the name of some font file that FreeType can read, along with face_index, indicating which font within the file to load (usually 0).

◆ __init__() [3/3]

__init__ ( str  font_data,
int  data_length,
int  face_index 
)

This constructor accepts a table of data representing the font file, loaded from some source other than a filename on disk.

◆ clear()

clear ( )

Drops all the glyphs out of the cache and frees any association with any previously-generated pages.

Calling this frequently can result in wasted texture memory, as any previously rendered text will still keep a pointer to the old, previously- generated pages. As long as the previously rendered text remains around, the old pages will also remain around.

◆ garbageCollect()

int garbageCollect ( )

Removes all of the glyphs from the font that are no longer being used by any Geoms.

Returns the number of glyphs removed.

◆ getAnisotropicDegree()

int getAnisotropicDegree ( )

Returns the current anisotropic degree for textures created for this font.

See set_anisotropic_degree().

◆ getBg()

const LColor getBg ( )

Returns the color of the background pixels of the font as they are rendered into the font texture.

See set_bg().

◆ getClassType()

static TypeHandle getClassType ( )
static

◆ getFg()

const LColor getFg ( )

Returns the color of the foreground pixels of the font as they are rendered into the font texture.

See set_fg().

◆ getFontPixelSize()

int getFontPixelSize ( )

This is used to report whether the requested pixel size is being only approximated by a fixed-pixel-size font.

This returns 0 in the normal case, in which a scalable font is used, or the fixed-pixel-size font has exactly the requested pixel size.

If this returns non-zero, it is the pixel size of the font that we are using to approximate our desired size.

◆ getLineHeight()

float getLineHeight ( )

Returns the number of units high each line of text is.

◆ getMagfilter()

SamplerState::FilterType getMagfilter ( )

Returns the filter type used when enlarging the textures created for this font.

◆ getMinfilter()

SamplerState::FilterType getMinfilter ( )

Returns the filter type used when minimizing the textures created for this font.

◆ getName()

str getName ( )

Disambiguates the get_name() method between that inherited from TextFont and that inherited from FreetypeFont.

◆ getNativeAntialias()

bool getNativeAntialias ( )

Returns whether Freetype's built-in antialias mode is enabled.

See set_native_antialias().

◆ getNumPages()

int getNumPages ( )

Returns the number of pages associated with the font.

Initially, the font has zero pages; when the first piece of text is rendered with the font, it will add additional pages as needed. Each page is a Texture object that contains the images for each of the glyphs currently in use somewhere.

◆ getOutlineColor()

const LColor getOutlineColor ( )

Returns the color of the outline pixels of the font as they are rendered into the font texture.

See set_outline().

◆ getOutlineFeather()

float getOutlineFeather ( )

Returns the softness of the outline pixels of the font, as a value in the range 0.0 to 1.0.

See set_outline().

◆ getOutlineWidth()

float getOutlineWidth ( )

Returns the width of the outline pixels of the font, as the number of points beyond each letter.

See set_outline().

◆ getPage()

DynamicTextPage getPage ( int  n)

Returns the nth page associated with the font.

Initially, the font has zero pages; when the first piece of text is rendered with the font, it will add additional pages as needed. Each page is a Texture object that contains the images for each of the glyphs currently in use somewhere.

◆ getPages()

list getPages ( )

◆ getPageSize()

const LVecBase2i getPageSize ( )

Returns the size of the textures that are created for the DynamicTextFont.

See set_page_size().

◆ getPageXSize()

int getPageXSize ( )

Returns the x size of the textures that are created for the DynamicTextFont.

See set_page_size().

◆ getPageYSize()

int getPageYSize ( )

Returns the y size of the textures that are created for the DynamicTextFont.

See set_page_size().

◆ getPixelsPerUnit()

float getPixelsPerUnit ( )

Returns the resolution of the texture map.

See set_pixels_per_unit().

◆ getPointSize()

float getPointSize ( )

Returns the point size of the font.

◆ getPolyMargin()

float getPolyMargin ( )

Returns the number of pixels of padding that is included around each glyph in the generated polygons.

See set_poly_margin().

◆ getRenderMode()

TextFont::RenderMode getRenderMode ( )

Returns the way the glyphs on this particular font are generated.

See set_render_mode().

◆ getScaleFactor()

float getScaleFactor ( )

Returns the antialiasing scale factor.

See set_scale_factor().

◆ getSpaceAdvance()

float getSpaceAdvance ( )

Returns the number of units wide a space is.

◆ getTexFormat()

Texture::Format getTexFormat ( )

Returns the texture format used to render the individual pages.

This is set automatically according to the colors selected.

◆ getTextureMargin()

int getTextureMargin ( )

Returns the number of pixels of padding that is added around the border of each glyph in the texture map.

See set_texture_margin().

◆ makeCopy()

TextFont makeCopy ( )

Returns a new copy of the same font.

◆ setAnisotropicDegree()

setAnisotropicDegree ( int  anisotropic_degree)

Enables or disables anisotropic filtering on the textures created for this font.

The default value is specified by the text-anisotropic-degree variable. See Texture::set_anisotropic_degree().

◆ setBg()

setBg ( const LColor  bg)

Changes the color of the background pixels of the font as they are rendered into the font texture.

The default is (1, 1, 1, 0), or transparent white, which allows text created with the font to be colored individually. (Note that it should not generally be (0, 0, 0, 0), which would tend to bleed into the foreground color, unless you have also specified a outline color of (0, 0, 0, 1)) .

Normally, you would not change this unless you really need a particular color effect to appear in the font itself.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setFg()

setFg ( const LColor  fg)

Changes the color of the foreground pixels of the font as they are rendered into the font texture.

The default is (1, 1, 1, 1), or opaque white, which allows text created with the font to be colored individually. Normally, you would not change this unless you really need a particular color effect to appear in the font itself.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setMagfilter()

setMagfilter ( SamplerState::FilterType  filter)

Sets the filter type used when enlarging the textures created for this font.

◆ setMinfilter()

setMinfilter ( SamplerState::FilterType  filter)

Sets the filter type used when minimizing the textures created for this font.

◆ setNativeAntialias()

setNativeAntialias ( bool  native_antialias)

Sets whether the Freetype library's built-in antialias mode is enabled.

There are two unrelated ways to achieve antialiasing: with Freetype's native antialias mode, and with the use of a scale_factor greater than one. By default, both modes are enabled.

At low resolutions, some fonts may do better with one mode or the other. In general, Freetype's native antialiasing will produce less blurry results, but may introduce more artifacts.

◆ setOutline()

setOutline ( const LColor  outline_color,
float  outline_width,
float  outline_feather 
)

Sets up the font to have an outline around each font letter.

This is achieved via a Gaussian post-process as each letter is generated; there is some runtime cost for this effect, but it is minimal as each letter is normally generated only once and then cached.

The color is the desired color of the outline, width is the number of points beyond the letter that the outline extends (a typical font is 10 points high), and feather is a number in the range 0.0 .. 1.0 that controls the softness of the outline. Set the width to 0.0 to disable the outline.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setPageSize() [1/2]

setPageSize ( const LVecBase2i  page_size)

Sets the x, y size of the textures that are created for the DynamicTextFont.

◆ setPageSize() [2/2]

setPageSize ( int  x_size,
int  y_size 
)

Sets the x, y size of the textures that are created for the DynamicTextFont.

◆ setPixelsPerUnit()

bool setPixelsPerUnit ( float  pixels_per_unit)

Set the resolution of the texture map, and hence the clarity of the resulting font.

This sets the number of pixels in the texture map that are used for each onscreen unit.

Setting this number larger results in an easier to read font, but at the cost of more texture memory.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setPointSize()

bool setPointSize ( float  point_size)

Sets the point size of the font.

This controls the apparent size of the font onscreen. By convention, a 10 point font is about 1 screen unit high.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setPolyMargin()

setPolyMargin ( float  poly_margin)

Sets the number of pixels of padding that is included around each glyph in the generated polygons.

This helps prevent the edges of the glyphs from being cut off at small minifications. It is not related to the amount of extra pixels reserved in the texture map (but it should be set somewhat smaller than this number, which is controlled by set_texture_margin(), to prevent bleed-in from neighboring letters in the texture).

◆ setRenderMode()

setRenderMode ( TextFont::RenderMode  render_mode)

Specifies the way the glyphs on this particular font are generated.

The default is RM_texture, which is the only mode supported for bitmap fonts. Other modes are possible for most modern fonts.

◆ setScaleFactor()

bool setScaleFactor ( float  scale_factor)

Sets the factor by which the font is rendered larger by the FreeType library before being filtered down to its actual size in the texture as specified by set_pixels_per_unit().

This may be set to a number larger than 1.0 to improve the font's antialiasing (since FreeType doesn't really do a swell job of antialiasing by itself). There is some performance implication for setting this different than 1.0, but it is probably small.

This should only be called before any characters have been requested out of the font, or immediately after calling clear().

◆ setTextureMargin()

setTextureMargin ( int  texture_margin)

Sets the number of pixels of padding that is added around the border of each glyph before adding it to the texture map.

This reduces the bleed in from neighboring glyphs in the texture map.

◆ write()

write ( Ostream  out,
int  indent_level 
)

Member Data Documentation

◆ anisotropic_degree

int anisotropic_degree

Returns the current anisotropic degree for textures created for this font.

See set_anisotropic_degree().

◆ bg

const LColor bg

Returns the color of the background pixels of the font as they are rendered into the font texture.

See set_bg().

◆ fg

const LColor fg

Returns the color of the foreground pixels of the font as they are rendered into the font texture.

See set_fg().

◆ font_pixel_size

int font_pixel_size

This is used to report whether the requested pixel size is being only approximated by a fixed-pixel-size font.

This returns 0 in the normal case, in which a scalable font is used, or the fixed-pixel-size font has exactly the requested pixel size.

If this returns non-zero, it is the pixel size of the font that we are using to approximate our desired size.

◆ magfilter

Returns the filter type used when enlarging the textures created for this font.

◆ minfilter

Returns the filter type used when minimizing the textures created for this font.

◆ native_antialias

bool native_antialias

Returns whether Freetype's built-in antialias mode is enabled.

See set_native_antialias().

◆ page_size

const LVecBase2i page_size

Returns the size of the textures that are created for the DynamicTextFont.

See set_page_size().

◆ pages

DynamicTextPage pages[]

◆ pixels_per_unit

float pixels_per_unit

Returns the resolution of the texture map.

See set_pixels_per_unit().

◆ point_size

float point_size

Returns the point size of the font.

◆ poly_margin

float poly_margin

Returns the number of pixels of padding that is included around each glyph in the generated polygons.

See set_poly_margin().

◆ render_mode

TextFont::RenderMode render_mode

Returns the way the glyphs on this particular font are generated.

See set_render_mode().

◆ scale_factor

float scale_factor

Returns the antialiasing scale factor.

See set_scale_factor().

◆ tex_format

Texture::Format tex_format

Returns the texture format used to render the individual pages.

This is set automatically according to the colors selected.

◆ texture_margin

int texture_margin

Returns the number of pixels of padding that is added around the border of each glyph in the texture map.

See set_texture_margin().