IFont

Functions

	SET_CID
RED_RC	GetType
RED_RC	SetType
RED_RC	GetRenderMode
RED_RC	SetRenderMode
RED_RC	GetTypeFaceName
RED_RC	SetTypeFaceName
RED_RC	GetCharSet
RED_RC	SetCharSet
RED_RC	GetSize
RED_RC	SetSize
RED_RC	GetChordalDeviation
RED_RC	SetChordalDeviation
RED_RC	GetEscapement
RED_RC	SetEscapement
RED_RC	GetOrientation
RED_RC	SetOrientation
RED_RC	GetGlyphTextureSize
RED_RC	SetGlyphTextureSize
RED_RC	GetGlyphTextureOffset
RED_RC	SetGlyphTextureOffset
RED_RC	PreloadGlyphTexture
RED_RC	GetGlyphTexturePreloadRange
RED_RC	GetStringBox
RED_RC	GetMetrics
RED_RC	CheckString

Detailed Description

class IFont : public RED::IREDObject

Interface that exposes font objects parameters.

@related Text Shapes, class RED::ITextShape, Displaying Texts

The IFont interface exposes the REDsdk font parameters. A font object is used to describe all geometrical parameters of a RED::ITextShape object.

The CID_REDTextShape exposes the RED::ITextShape interface. Font objects are attributes of text shapes. A font defines all geometrical properties of the text to be drawn, and the shape material defines its rendering attributes.

A font is RED::FNT_UNDEFINED at its construction. Font parameters must be set, and the font is dynamically created upon need for the rendering.

There are several types of fonts that can be drawn with REDsdk:

• RED::FNT_BITMAP: Bitmaps are created for the display of fonts. The display of these fonts do not scale and do not rotate. They remain screen aligned. The anchoring position move in 3D.

• RED::FNT_TRIANGLE / RED::FNT_LINE: Triangle or line based fonts in 3D. These fonts are difficult to read when zoomed out. They generate lots of triangles or lines and are the most expensive to draw. Triangle fonts don’t support high definition transforms and should be shaded using the legacy RED::IResourceManager::CreateColorFontMaterial material.

• RED::FNT_TEXTURE: These fonts are drawn using textured quads. The characters textures are anti-aliased to provide a good display quality at all zooming levels. The rendering performances for these fonts is the best. However, these fonts consume video memory for the storage of the font characters texture. The amount of memory used is ruled by the RED::IFont::SetGlyphTextureSize call.

Font parameters can’t be modified with RED::FNT_TEXTURE system fonts. Once font characters (glyphs) have been generated and turned into texture pieces, they can’t be modified. The font has to be destroyed and replaced by another one, so that all shapes geometries are updated.

The notion of ‘font size’ is always subject to different understandings. To clarify the meaning of ‘font size’ for REDsdk the image below show the way the font is calculated:

The size of the font that is declared through RED::IFont::SetSize is the total size that can be occupied by a character, including it’s descent area and internal leading space. The metrics of a font can be accessed through the RED::IFont::GetMetrics call. It returns the three meaningful dimensions of the font.

A few remarks on this schema:

• Metrics returned by RED::IFont::GetMetrics can be used from any baseline attach position. If a string is anchored at a given ‘y’ coordinate, then, ‘y’ - descent_area will give the absolute bottom line of the font. Note that a given string does not necessarily reach the bottom: ‘abc’ for instance does not go down. ‘y’ + ascent_area + internal_leading is the top mark of the font.

• The size of a font can be re-evaluated on the fly before it gets drawn. For example, it’s possible to call RED::IFont::SetSize, then query the font metrics and change the font size for example to get a precise height of the character ascent area.

Numerical accuracy problems may arise with fonts that are too small. If a font is created with a too small size, then the underlying OS API may fail to provide correct offsets for string characters. On Windows OS, the font API uses pixels for offsets, therefore creating fonts whose size is below 10 may lead to numerical inacurracies. In this case, a scaling matrix can be applied to the strings in the font. See the RED::ITextShape and the RED::ITextShape::AddRotatedAndScaledString method for details.

In order to get the best numerical accuracy, we recommend to create fonts with sizes about 2048 units and then to add strings that are scaled or to add a transform shape to scale texts in the scene graph, so that the results are the most accurate.

There’s only one type of fonts that can be rendered using high definition matrices: this is RED::FNT_TEXTURE texts. Bitmaps, triangles or lines texts are using the internal Windows OS API, and can’t be rendered using REDsdk’s high definition matrices as it’s defined using RED::RenderCode::SetHighDefinitionModelViewMatrix; so in the case of texts that have to be displayed with a high accuracy, RED::FNT_TEXTURE fonts should be used.

Note

RED::FNT_CUSTOM kind of fonts (user fonts) are not available yet.

Public Functions

SET_CID(CID_class_REDIFont)

virtual RED_RC GetType(RED::FONT_TYPE &oFontType, int iStateNumber = -1) const = 0

Queries the kind of font we have.

Parameters

• oFontType – The kind of font for this object.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetType(RED::FONT_TYPE iFontType, const RED::State &iState) = 0

Manual assignment of the font type.

Note that the type of a font can only be set once for the entire life of the font.

An example of font definition is accessible here: \ref tk_creating_a_font.

Parameters

• iFontType – New font type to use.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if the font type has been already defined,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetRenderMode(RED::FONT_RENDER_MODE &oFontRenderMode, int iStateNumber = -1) const = 0

Gets the way the font is rendered on screen.

The returned value is only valid for system fonts.

Parameters

• oFontRenderMode – Font rendering mode.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetRenderMode(RED::FONT_RENDER_MODE iFontRenderMode, const RED::State &iState) = 0

Defines the rendering primitives of a system font.

The method is only effective for system fonts.

An example of font definition is accessible here: \ref tk_creating_a_font.

Parameters

• iFontRenderMode – Font rendering mode.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetTypeFaceName(RED::String &oTypeFace, int iStateNumber = -1) const = 0

Gets the font typeface name.

This method is valid for system fonts.

The typeface name of the font is used to uniquely identify it in the system. The list of all available fonts typefaces can be accessed from the

RED::IResourceManager interface.

Parameters

• oTypeFace – String name of the font.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetTypeFaceName(const RED::String &iTypeFace, const RED::State &iState) = 0

Specifies the font typeface name.

The typeface name of the font is used to uniquely identify it in the system. The list of all available fonts typefaces can be accessed from the RED::IResourceManager::GetAllSystemFonts.

Please note that the system is sensitive to the typeface name being specified. If the provided typeface name can’t be found by the operating system, then it’ll decide to use another font as a replacement for the font that was queried. This can lead to rendering errors returned by REDsdk.

An example of font definition is accessible here: \ref tk_creating_a_font.

Parameters

• iTypeFace – String name of the font.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetCharSet(RED::FONT_CHARSET &oCharSet, int iStateNumber = -1) const = 0

Gets the font character set.

The font character set defines the range of unicode characters that can be mapped for the rendering in the font. Refer to www.unicode.org/charts for all charsets and the codes they contain.

Parameters

• oCharSet – Current font character set.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetCharSet(RED::FONT_CHARSET iCharSet, const RED::State &iState) = 0

Specifies the font character set.

Defines the font character set that will be used to map font characters into render-able elements. Default font character set is set to RED::FNT_DEFAULT_CHARSET, that redirects to the system’s locale charset.

An example of font definition is accessible here: \ref tk_creating_a_font.

Parameters

• iCharSet – New font character set.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetSize(float &oWidth, float &oHeight, int iStateNumber = -1) const = 0

Gets the font width and height.

Defined based on the font type:

• RED::FNT_CUSTOM: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_BITMAP: Is the pixel size of the font.

• RED::FNT_SYSTEM / RED::FNT_TRIANGLE: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_LINE: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_TEXTURE: Indicates a model unit size in the object space of the shape. The size of the texture glyphs used for the rendering is specified by RED::IFont::GetGlyphTextureSize.

Parameters

• oWidth – Font width.

• oHeight – Font height.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetSize(float iWidth, float iHeight, const RED::State &iState) = 0

Specifies the font width and height.

Defined based on the font type:

• RED::FNT_CUSTOM: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_BITMAP: Is the pixel size of the font.

• RED::FNT_SYSTEM / RED::FNT_TRIANGLE: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_LINE: Indicates a model unit size in the object space of the shape.

• RED::FNT_SYSTEM / RED::FNT_TEXTURE: Indicates a model unit size in the object space of the shape. The size of the texture glyphs used for the rendering is specified by RED::IFont::SetGlyphTextureSize.

The sizing parameters set by this method are used internally to create the operating system font. On windows, the LOGFONT lfWidth and lfHeight parameters will be set to iWidth and iHeight before proceeding to a CreateFontIndirect call. We use positive values, which means that the size being indicated here is a ‘font cell height’ in windows terminology: this is the sum of the character height (ascent + descent areas) plus the internal leading used for accentuated characters.

An example of font definition is accessible here: \ref tk_creating_a_font.

Parameters

• iWidth – Font width. If this value is 0.0f and if the font is rendered using RED::FNT_BITMAP or RED::FNT_TEXTURE, then the aspect ratio of the font will be automatically calculated by the font mapper during the glyph calculation process. If this value is 0.0f and if the font is rendered using the RED::FNT_TRIANGLE or RED::FNT_LINE type, then the width value is automatically set equal to the font height.

• iHeight – Font height.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetChordalDeviation(float &oChordalDev, int iStateNumber = -1) const = 0

Gets the font chordal deviation.

The returned value is only valid for a RED::FNT_SYSTEM kind of font that is rendered using RED::FNT_LINE or RED::FNT_TRIANGLE primitives.

Parameters

• oChordalDev – Chordal deviation of the font mesh. This is the maximal distance between the font analytic representation and it’s tessellation in lines or triangles. The value is in model units of the object space of the text shape.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetChordalDeviation(float iChordalDev, const RED::State &iState) = 0

Specifies the font chordal deviation.

The method is only effective for a RED::FNT_SYSTEM kind of font that is rendered using RED::FNT_LINE or RED::FNT_TRIANGLE primitives.

Parameters

• iChordalDev – Chordal deviation of the font mesh. This is the maximal distance between the font analytic representation and it’s tessellation in lines or triangles. The value is in model units of the object space of the text shape.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetEscapement(float &oEscapement, int iStateNumber = -1) const = 0

Returns the font escapement angle value.

This method is valid for RED::FNT_SYSTEM

kind of fonts.

The escapement is an angle expressed in tenth of degrees between the device x-axis vector and the line on which is drawn a line of text.

Default value is 0.0f.

Parameters

• oEscapement – Font escapement angle.

• iStateNumber – Queried state number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter.

virtual RED_RC SetEscapement(float iEscapement, const RED::State &iState) = 0

Defines the font escapement angle value.

This method is valid for RED::FNT_SYSTEM

kind of fonts.

The escapement is an angle expressed in tenth of degrees between the device x-axis vector and the line on which is drawn a line of text.

Parameters

• iEscapement – Font escapement angle.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetOrientation(float &oOrientation, int iStateNumber = -1) const = 0

Returns the font orientation angle value.

This method is valid for RED::FNT_SYSTEM

kind of fonts.

Angle between the device x-axis vector and the base line of the character, in tenth of degrees.

Parameters

• oOrientation – Font orientation angle.

• iStateNumber – Queried state number.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual RED_RC SetOrientation(float iOrientation, const RED::State &iState) = 0

Defines the font orientation angle value.

This method is valid for RED::FNT_SYSTEM

kind of fonts.

Angle between the device x-axis vector and the base line of the character, in tenth of degrees.

Parameters

• iOrientation – Font orientation angle.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetGlyphTextureSize(int &oWidth, int &oHeight, int iStateNumber = -1) const = 0

Gets the size of a character in a textured font.

Retrieve the pixel size of a single glyph character in a textured font. The returned value is a POTD value.

Parameters

• oWidth – POTD value of the pixel size of a glyph in the font texture.

• oHeight – POTD value of the pixel size of a glyph in the font texture.

• iStateNumber – Queried state number.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual RED_RC SetGlyphTextureSize(int iWidth, int iHeight, const RED::State &iState) = 0

Defines the size of a character in a textured font.

Define the pixel size of a single glyph character in a textured font. The default value for the size of a glyph is 32 x 32 pixels. The specified size must be a Power-Of-Two value for each dimension (not necessarily the same, so 32 x 64 is a valid input).

Parameters

• iWidth – POTD value of the pixel size of a glyph in the font texture.

• iHeight – POTD value of the pixel size of a glyph in the font texture.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetGlyphTextureOffset(float &oOffset, int iStateNumber = -1) const = 0

Gets the glyph texture offset.

The glyph texture offset is the z coordinate spacing between two consecutive glyphs in a string. This offset is used to avoid z-fighting artifacts that can occur while rendering of textured fonts strings at steep viewing angles.

Please refer to the \ref bk_sg_text_shapes paragraph in the REDsdk documentation for all details on textured strings and on this offset.

The default value of this offset is 0.01 model units before string scaling.

Parameters

• oOffset – The current value of the texture glyph offset for the font.

• iStateNumber – Queried state number.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual RED_RC SetGlyphTextureOffset(float iOffset, const RED::State &iState) = 0

Defines the glyph texture offset.

The glyph texture offset is the z coordinate spacing between two consecutive glyphs in a string. This offset is used to avoid z-fighting artifacts that can occur while rendering of textured fonts strings at steep viewing angles.

Please refer to the \ref bk_sg_text_shapes paragraph in the REDsdk documentation for all details on textured strings and on this offset.

The default value of this offset is 0.01 model units before string scaling.

Parameters

• iOffset – The value of the texture glyph offset to set.

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC PreloadGlyphTexture(int iGlyphMin, int iGlyphMax, const RED::State &iState) = 0

Requests the pre-generation of a list of glyphs.

The construction of texture glyphs for a RED::FNT_TEXTURE

font may be a time consuming task (more than one millisecond per glyph). The glyph creation process is “on the fly” at the time strings have to be rendered.

This method can be used to force series of glyphs to be loaded at the first time the glyph texture will be loaded with new glyphs. This can be used to prevent sudden changes in the frame rate for a time critical application.

Note that this call is ignored if the font has been already used to render a given string.

All base ascii characters can be pre-loaded using a [32,128] glyph range.

Parameters

• iGlyphMin – Min value of the unicode glyph value to preload (inclusive).

• iGlyphMax – Max value of the unicode glyph value to preload (inclusive).

• iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetGlyphTexturePreloadRange(int &oGlyphMin, int &oGlyphMax, int iStateNumber = -1) const = 0

Returns the set of glyphs to preload for a texture font.

Parameters

• oGlyphMin – Min value of the unicode glyph value to preload (inclusive).

• oGlyphMax – Max value of the unicode glyph value to preload (inclusive).

• iStateNumber – Queried state number.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter.

virtual RED_RC GetStringBox(float &oLeft, float &oRight, float &oBottom, float &oTop, const RED::String &iText) = 0

Gets the bounding box enclosing a text.

This method returns the [oLeft,oRight] x [oBottom,oTop] rectangle that encloses the provided iText string. The returned values are in model units corresponding to this font.

Parameters

• oLeft – Left boundary of the text box.

• oRight – Right boundary of the text box.

• oBottom – Bottom boundary of the text box.

• oTop – Top boundary of the text box.

• iText – The text string.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC GetMetrics(float &oAscentArea, float &oDescentArea, float &oInternalLeading) = 0

Retrieves the main dimensions of the font.

This method returns the main dimensions of the font, according to its current setup. Returned units are model units, except for RED::FNT_BITMAP fonts that are specified in pixels.

Parameters

• oAscentArea – Size of the ascent area of characters.

• oDescentArea – Size of the descent area of characters.

• oInternalLeading – Size of the accent mark area of characters.

Returns

RED_OK if the method has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC CheckString(RED::Vector<bool> &oMask, const RED::String &iString) = 0

Checks the existence of glyphs in a font.

This method reads iString and checks for each glyph in iString whether this glyph exists in iFont or not. The method returns a oMask vector for all glyphs in the string, indicating if a glyph is available in the font ( oMask[ glyph_number ] == true ) or not. This method can noticeably be used to split a multi language string into sub-strings that can display it properly.

Parameters

• oMask – Mask indicating, for each glyph in iString whether this glyph exists in the font (true) or not (false).

• iString – The string to check.

Returns

RED_OK if the method has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise,

Other internal RED_RC values due to the operating system calls are possible.