Murl Engine Lua Addon API  Version 1.0 beta
Murl.Graph.ITextGeometry

The ITextGeometry graph node interface.

This interface represents a renderable text object, which makes use of either a read-only Resource::IFont object representing a collection of individual glyph positions in a corresponding font atlas bitmap image, or a system font with a given ID.

To correctly display any given text using a bitmap font, the following prerequisites must be met:

  • The ITextGeometry node must reference a given Resource::IFont object containing bitmap glyph rectangles.
  • There must be an active material used for rendering the font at the material state slot with given index ("materialSlot" attribute, see Graph::IDrawable::SetMaterialSlot()).
  • There must be an active texture containing the actual bitmap glyphs corresponding to the Resource::IFont used, at the texture state slot given via the "textureSlots" attribute or the Graph::IDrawable::SetTextureSlot() method. The texture state unit depends on the actual program used for the material.

To display a given text using an embedded outline font, the following settings are needed:

  • The ITextGeometry node must reference a given Resource::IFont object containig valid outlines
  • The "fontSize" attribute must specify a non-zero positive font size.

To display a given text using a system font, the following settings are needed:

  • The "systemFontName" attribute must be set to a valid system font ID, e.g. "SansRegular"
  • The "fontSize" attribute must specify a non-zero positive font size.

Use the Graph::IText base interface to access common text properties, such as spacing or leading, or the actual text to be shown.

Use the Graph::IScalable base interface to set an overall scaling factor for the object, i.e. define its actual size.


Table members

Inherited


Murl.Graph.IDrawable
Murl.Graph.IText
Murl.Graph.IScalable

Methods


GetNodeInterface()

Get the constant Graph::INode interface. This method returns a constant pointer to the node's Graph::INode interface, to be able to query common node properties such as active state, visibility or ID.

Murl.Graph.INode GetNodeInterface()

Returns
Murl.Graph.INode The constant Graph::INode interface, or null if not available

GetTransformInterface()

Get the constant Graph::ITransform interface. This method returns a constant pointer to the node's Graph::ITransform interface, to be able to query the node's transformation matrix and depth order.

Murl.Graph.ITransform GetTransformInterface()

Returns
Murl.Graph.ITransform The constant Graph::ITransform interface, or null if not available

SetNumberOfReservedCharacters(numReserved)

Set the number of characters to reserve. If the given value is 0, the text object always dynamically expands its underlying buffer to hold the number of characters needed for correctly displaying any given text. If the value is higher than 0, only that number of entries are allocated in the buffers; any text with a length beyond that number will be truncated.

Boolean SetNumberOfReservedCharacters(Integer numReserved)

Parameters
numReservedThe number of characters to reserve.
Returns
Boolean true if successful.

GetNumberOfReservedCharacters()

Get the number of characters currently reserved.

Integer GetNumberOfReservedCharacters()

Returns
Integer The number of characters.

SetContainerSize(sizeX, sizeY)

Set the text node's container size. When text alignment other than IEnums::TEXT_ALIGNMENT_X_CENTER is desired (set via Graph::IText::SetTextAlignmentX and Graph::IText::SetTextAlignmentY) or word wrapping should be performed, it is necessary to specify an explicit container size, so that the text can be laid out correctly. Note that the container size only determines how the text is aligned within that container; use SetContainerAlignmentX() and SetContainerAlignmentY() to control alignment of the container itself.
If any of the given size values are 0, the respective container dimension is automatically calculated from the actual dimension of the text to render, which is the reason why in this case all types of text alignment appear to be centered.
When using bitmap fonts, the container size only affects the size of the resulting geometry. For other font types, which also create a texture object to render to, this also affects the actual dimension of the underlying texture.

Boolean SetContainerSize(Number sizeX, Number sizeY)

Parameters
sizeXThe horizontal size of the text container.
sizeYThe vertical size of the text container.
Returns
Boolean true if successful.

SetContainerSizeX(sizeX)

Set the text node's horizontal container size. See SetContainerSize().

Boolean SetContainerSizeX(Number sizeX)

Parameters
sizeXThe horizontal size of the text container.
Returns
Boolean true if successful.

SetContainerSizeY(sizeY)

Set the text node's vertical container size. See SetContainerSize().

Boolean SetContainerSizeY(Number sizeY)

Parameters
sizeYThe vertical size of the text container.
Returns
Boolean true if successful.

GetContainerSizeX()

Get the text node's horizontal container size.

Number GetContainerSizeX()

Returns
Number The horizontal size of the text container.

GetContainerSizeY()

Get the text node's vertical container size.

Number GetContainerSizeY()

Returns
Number The vertical size of the text container.

SetContainerFittingEnabled(enabled)

Enable/disable container fitting. If enabled, the given text is automatically downscaled when it does not fit into the optional container rectangle given via SetContainerSize().

Boolean SetContainerFittingEnabled(Boolean enabled)

Parameters
enabledIf true, autofitting is enabled.
Returns
Boolean true if successful.

IsContainerFittingEnabled()

Check if container fitting is enabled.

Boolean IsContainerFittingEnabled()

Returns
Boolean true if container fitting is enabled.

SetNumberOfContainerFittingIterations(numIterations)

Set the number of iterations to perform for container fitting. By default, the number of iterations is 0, which always shrinks the text in X direction when it does not fit in Y direction. Setting iterations to a higher count tries to fill the container in both directions, with a possible better effect for higher counts. This method has no effect when container fitting is disabled.

Boolean SetNumberOfContainerFittingIterations(Integer numIterations)

Parameters
numIterationsThe number of iterations
Returns
Boolean true if successful.

GetNumberOfContainerFittingIterations()

Get the number of iterations to perform for container fitting.

Integer GetNumberOfContainerFittingIterations()

Returns
Integer The number of iterations

SetAlignmentUnit(unitX, unitY)

Set the text alignment unit. For the sake of rendering quality, it is often desired to render text using a bitmap font at exact pixel coordinates, so that no blurring occurs due to hardware filtering. For this reason, it is possible to specify both a horizontal and vertical alignment unit, which ensures that all characters are only positioned at locations that are equally dividable by the given unit values. For this to work however, the virtual coordinate system of the camera used to render the text must also be grid-aligned, as the text alignment algorithm only acts on virtual coordinates and not on pixel coordinates!

Boolean SetAlignmentUnit(Number unitX, Number unitY)

Parameters
unitXThe horizontal alignment unit.
unitYThe vertical alignment unit.
Returns
Boolean true if successful.

SetAlignmentUnitX(unitX)

Set the horizontal text alignment unit. See SetAlignmentUnit().

Boolean SetAlignmentUnitX(Number unitX)

Parameters
unitXThe horizontal alignment unit.
Returns
Boolean true if successful.

SetAlignmentUnitY(unitY)

Set the vertical text alignment unit. See SetAlignmentUnit().

Boolean SetAlignmentUnitY(Number unitY)

Parameters
unitYThe vertical alignment unit.
Returns
Boolean true if successful.

GetAlignmentUnitX()

Get the horizontal text alignment unit.

Number GetAlignmentUnitX()

Returns
Number The horizontal alignment unit.

GetAlignmentUnitY()

Get the vertical text alignment unit.

Number GetAlignmentUnitY()

Returns
Number The vertical alignment unit.

SetContainerAlignment(alignmentX, alignmentY)

Set the container alignment. The given alignment values specify how the text container is actually positioned with respect to the node's world position.

Boolean SetContainerAlignment(Murl.IEnums.AlignmentX alignmentX, Murl.IEnums.AlignmentY alignmentY)

Parameters
alignmentXThe horizontal container alignment.
alignmentYThe vertical container alignment.
Returns
Boolean true if successful.

SetContainerAlignmentX(alignmentX)

Set the horizontal container alignment. See SetContainerAlignment().

Boolean SetContainerAlignmentX(Murl.IEnums.AlignmentX alignmentX)

Parameters
alignmentXThe horizontal container alignment.
Returns
Boolean true if successful.

SetContainerAlignmentY(alignmentY)

Set the vertical container alignment. See SetContainerAlignment().

Boolean SetContainerAlignmentY(Murl.IEnums.AlignmentY alignmentY)

Parameters
alignmentYThe vertical container alignment.
Returns
Boolean true if successful.

GetContainerAlignmentX()

Get the horizontal container alignment.

Murl.IEnums.AlignmentX GetContainerAlignmentX()

Returns
Murl.IEnums.AlignmentX The horizontal container alignment.

GetContainerAlignmentY()

Get the vertical container alignment.

Murl.IEnums.AlignmentY GetContainerAlignmentY()

Returns
Murl.IEnums.AlignmentY The vertical container alignment.

SetObjectBoundingMode(modeX, modeY)

Set the object bounding mode. The given values specify how the geometry's bounding volume is calculated, mainly used for automatic alignment via Graph::IAligner nodes. A value of IEnums::OBJECT_BOUNDING_MODE_CONTAINER uses the given container size along the respective axis, and a value of IEnums::OBJECT_BOUNDING_MODE_CONTENTS uses the actual text size. If no explicit container size is given, the actual text size is used for the container size.

Boolean SetObjectBoundingMode(Murl.IEnums.ObjectBoundingMode modeX, Murl.IEnums.ObjectBoundingMode modeY)

Parameters
modeXThe horizontal bounding mode.
modeYThe vertical bounding mode.
Returns
Boolean true if successful.

SetObjectBoundingModeX(modeX)

Set the horizontal object bounding mode. See SetObjectBoundingMode().

Boolean SetObjectBoundingModeX(Murl.IEnums.ObjectBoundingMode modeX)

Parameters
modeXThe horizontal bounding mode.
Returns
Boolean true if successful.

SetObjectBoundingModeY(modeY)

Set the vertical object bounding mode. See SetObjectBoundingMode().

Boolean SetObjectBoundingModeY(Murl.IEnums.ObjectBoundingMode modeY)

Parameters
modeYThe vertical bounding mode.
Returns
Boolean true if successful.

GetObjectBoundingModeX()

Get the horizontal object bounding mode.

Murl.IEnums.ObjectBoundingMode GetObjectBoundingModeX()

Returns
Murl.IEnums.ObjectBoundingMode The horizontal object bounding mode.

GetObjectBoundingModeY()

Get the vertical object bounding mode.

Murl.IEnums.ObjectBoundingMode GetObjectBoundingModeY()

Returns
Murl.IEnums.ObjectBoundingMode The vertical object bounding mode.

SetBorder(borderX, borderY)

Set the horizontal and vertical borders used for alignment.

Boolean SetBorder(Number borderX, Number borderY)

Parameters
borderXThe horizontal border.
borderYThe vertical border.
Returns
Boolean true if successful.

SetBorderX(borderX)

Set the horizontal border used for alignment.

Boolean SetBorderX(Number borderX)

Parameters
borderXThe horizontal border.
Returns
Boolean true if successful.

SetBorderY(borderY)

Set the vertical border used for alignment.

Boolean SetBorderY(Number borderY)

Parameters
borderYThe vertical border.
Returns
Boolean true if successful.

GetBorderX()

Get the horizontal border used for alignment.

Number GetBorderX()

Returns
Number The horizontal border.

GetBorderY()

Get the vertical border used for alignment.

Number GetBorderY()

Returns
Number The vertical border.

SetOffset(offsetX, offsetY)

Set horizontal and vertical offsets used for outline rendering.

Boolean SetOffset(Number offsetX, Number offsetY)

Parameters
offsetXThe horizontal offset.
offsetYThe vertical offset.
Returns
Boolean true if successful.

SetOffsetX(offsetX)

Set the horizontal offset used for outline rendering.

Boolean SetOffsetX(Number offsetX)

Parameters
offsetXThe horizontal offset.
Returns
Boolean true if successful.

SetOffsetY(offsetY)

Set the vertical offset used for outline rendering.

Boolean SetOffsetY(Number offsetY)

Parameters
offsetYThe vertical offset.
Returns
Boolean true if successful.

GetOffsetX()

Get the horizontal offset used for outline rendering.

Number GetOffsetX()

Returns
Number The horizontal offset.

GetOffsetY()

Get the vertical offset used for outline rendering.

Number GetOffsetY()

Returns
Number The vertical offset.

SetPixelFormat(pixelFormat)

Set the underlying texture's actual pixel format for outline fonts.

Boolean SetPixelFormat(Murl.IEnums.PixelFormat pixelFormat)

Parameters
pixelFormatThe pixel format to use.
Returns
Boolean true if successful.

GetPixelFormat()

Get the underlying texture's actual pixel format.

Murl.IEnums.PixelFormat GetPixelFormat()

Returns
Murl.IEnums.PixelFormat The texture's pixel format.

IsCharacterPrintable(utf8Char)

Check if a given UTF8 character sequence is printable.

Boolean IsCharacterPrintable(String utf8Char)

Parameters
utf8CharA String containing the UTF8 character sequence to check.
Returns
Boolean true if the UTF8 character is printable.

SetPrescalingEnabled(enabled)

Enable/disable prescaling if the text geometry is rendering to a texture. See Graph::ITexture::SetPrescalingEnabled().

Boolean SetPrescalingEnabled(Boolean enabled)

Parameters
enabledIf true, prescaling is enabled.
Returns
Boolean true if successful.

IsPrescalingEnabled()

Check if prescaling is enabled.

Boolean IsPrescalingEnabled()

Returns
Boolean true if enabled.

SetNonPowerOfTwoTextureAllowed(allowed)

Allow/disallow the use of a NPOT texture if outline fonts are used.

Boolean SetNonPowerOfTwoTextureAllowed(Boolean allowed)

Parameters
allowedIf true, NPOT textures are allowed.
Returns
Boolean true if successful.

IsNonPowerOfTwoTextureAllowed()

Check if the use of a NPOT texture for outline fonts is allowed.

Boolean IsNonPowerOfTwoTextureAllowed()

Returns
Boolean true if NPOT textures are allowed.