Murl Engine Lua Addon API  Version 1.0 beta
Murl.IFont

The font interface.


Table members

Methods


SetSize(size)

Set the font size.

Boolean SetSize(Number size)

Parameters
sizeThe font size.
Returns
Boolean true if successful.

GetSize()

Get the font size.

Number GetSize()

Returns
Number The font size.

SetSpacing(spacing)

Set the character spacing value. This method sets the character spacing used for output, i.e. the horizontal distance between neighbored characters. The given spacing value adds to the default value specified in the font used for rendering this text; a value of 0.0 represents the font's original spacing, a positive value increases the horizontal distance between characters, and a negative value decreases it.

Note: The given spacing value is not scaled by the font used; if e.g. a positive value is used for a large font, the same value used with a smaller version of that same font will result in a (relatively) larger distance between characters. It is however influenced by a possible additional scaling operation performed by a text rendering object.

Note also that not all types of fonts allow setting a custom spacing value. If not supported, this method returns false.

Boolean SetSpacing(Number spacing)

Parameters
spacingThe character spacing value.
Returns
Boolean true if successful.

GetSpacing()

Get the character spacing value.

Number GetSpacing()

Returns
Number The character spacing value.

SetLeading(leading)

Set the leading value. This method sets the leading value used for output, i.e. the vertical distance between subsequent text lines. The given leading value adds to the default value specified in the font used for rendering this text; a value of 0.0 represents the font's original leading, a positive value increases the vertical distance between lines, and a negative value decreases it.

Note: The given leading value is not scaled by the font used; if e.g. a positive value is used for a large font, the same value used with a smaller version of that same font will result in a (relatively) larger distance between lines. It is however influenced by a possible additional scaling operation performed by a text rendering object.

Boolean SetLeading(Number leading)

Parameters
leadingThe leading value.
Returns
Boolean true if successful.

GetLeading()

Get the font leading value.

Number GetLeading()

Returns
Number The font leading value.

SetEmbolding(strength)

Set the embolding strength value. The embolding strength determines the "boldness" or "weight" of the font's rendered glyphs. Positive values result in thicker lines, and negative values can be used to make the font "thinner". Useful values are in the range from -1 to +1, but can also lie beyond that range.

Note that not all types of fonts allow glyph embolding. If not supported, this method returns false.

Boolean SetEmbolding(Number strength)

Parameters
strengthThe embolding strength value.
Returns
Boolean true if successful.

GetEmbolding()

Get the embolding strength value.

Number GetEmbolding()

Returns
Number The embolding strength value.

SetBlur(strength)

Set the blur strength value.

Boolean SetBlur(Number strength)

Parameters
strengthThe positive blur strength value.
Returns
Boolean true if successful.

GetBlur()

Get the blur strength value.

Number GetBlur()

Returns
Number The blur strength value.

SetSpaceWidthFactor(factor)

Set the space width factor. This method sets a factor used to control the actual width of the white space character. In some cases, it is useful to manually control the space character's width, when a font's default space width produces too small or too big a distance between subsequent words. A space width factor of 1.0 represents the original width defined by the font used for rendering.

Note that not all types of fonts allow setting a custom space width factor. If not supported, this method returns false.

Boolean SetSpaceWidthFactor(Number factor)

Parameters
factorThe space width factor.
Returns
Boolean true if successful.

GetSpaceWidthFactor()

Get the space width factor.

Number GetSpaceWidthFactor()

Returns
Number The space width factor.

SetDigitWidthFactor(factor)

Set the digit width factor. This method sets a factor used to control the horizontal advance of all digit characters of a font ('0'-'9'). A digit width factor of 1.0 represents the original width defined by the font used for rendering.

Note, that this value only influences distance and not visual width; a value of e.g. 0.1 will result in overlapping digits without actually scaling them.

Note also that not all types of fonts allow setting a custom digit width value. If not supported, this method returns false.

Boolean SetDigitWidthFactor(Number factor)

Parameters
factorThe digit width factor.
Returns
Boolean true if successful.

GetDigitWidthFactor()

Get the digit width factor.

Number GetDigitWidthFactor()

Returns
Number The digit width factor.

SetSameDigitWidthEnabled(enabled)

Enable/disable unified digit width. For certain use cases, such as a score counter in an action game, it is useful to set a common width for all digits ('0'-'9'); doing so prevents the counter from jittering due to different digit widths. Note that not all types of fonts allow a common digit width. If not supported, this method returns false.

Boolean SetSameDigitWidthEnabled(Boolean enabled)

Parameters
enabledIf true, all digits use the same horizontal advance value.
Returns
Boolean true if successful.

IsSameDigitWidthEnabled()

Check if unified digit width is enabled.

Boolean IsSameDigitWidthEnabled()

Returns
Boolean true if all digits use the same horizontal advance value.

RenderText(text, textColor, backgroundColor, clearSurface, enableWordWrap, containerPosX, containerPosY, containerSizeX, containerSizeY, alignX, alignY, surface)

Render a text into a video stream.

Boolean RenderText(String text, Murl.Color textColor, Murl.Color backgroundColor, Boolean clearSurface, Boolean enableWordWrap, Number containerPosX, Number containerPosY, Number containerSizeX, Number containerSizeY, Murl.IEnums.TextAlignmentX alignX, Murl.IEnums.TextAlignmentY alignY, Murl.IVideoSurface surface)

Parameters
textThe text to render.
textColorThe text color to render.
backgroundColorThe text background color to render.
clearSurfaceIf true, the output surface is cleared before rendering.
enableWordWrapIf true, word wrapping is enabled.
containerPosXThe horizontal text position in the video stream.
containerPosYThe vertical text position in the video stream.
containerSizeXThe horizontal size of the text rectangle, or 0 if the video stream's X size should be used
containerSizeYThe vertical size of the text rectangle, or 0 if the video stream's Y size should be used
alignXThe horizontal text alignment.
alignYThe vertical text alignment.
surfaceThe destination video surface.
Returns
Boolean true if successful.

QueryTextSize(text, enableWordWrap, containerPosX, containerPosY, containerSizeX, containerSizeY, textSizeX, textSizeY)

Query the pixel dimensions of a given text.

Boolean, Number, Number QueryTextSize(String text, Boolean enableWordWrap, Number containerPosX, Number containerPosY, Number containerSizeX, Number containerSizeY, Number textSizeX, Number textSizeY)

Parameters
textThe text to query.
enableWordWrapIf true, word wrapping is enabled.
containerPosXThe horizontal text position in the video stream.
containerPosYThe vertical text position in the video stream.
containerSizeXThe horizontal size of the text rectangle, or 0 if the video stream's X size should be used
containerSizeYThe vertical size of the text rectangle, or 0 if the video stream's Y size should be used
textSizeXThe text width return value.
textSizeYThe text height return value.
Returns
Boolean true if successful.
Number textSizeX The text width return value.
Number textSizeY The text height return value.