![]() |
Murl Engine Lua Addon API
Version 1.0 beta
|
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:
To display a given text using an embedded outline font, the following settings are needed:
To display a given text using a system font, the following settings are needed:
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.
Murl.Graph.IDrawable
Murl.Graph.IText
Murl.Graph.IScalable
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()
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()
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)
numReserved | The number of characters to reserve. |
Get the number of characters currently reserved.
Integer GetNumberOfReservedCharacters()
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)
sizeX | The horizontal size of the text container. |
sizeY | The vertical size of the text container. |
Set the text node's horizontal container size. See SetContainerSize().
Boolean SetContainerSizeX(Number sizeX)
sizeX | The horizontal size of the text container. |
Set the text node's vertical container size. See SetContainerSize().
Boolean SetContainerSizeY(Number sizeY)
sizeY | The vertical size of the text container. |
Get the text node's horizontal container size.
Number GetContainerSizeX()
Get the text node's vertical container size.
Number GetContainerSizeY()
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)
enabled | If true, autofitting is enabled. |
Check if container fitting is enabled.
Boolean IsContainerFittingEnabled()
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)
unitX | The horizontal alignment unit. |
unitY | The vertical alignment unit. |
Set the horizontal text alignment unit. See SetAlignmentUnit().
Boolean SetAlignmentUnitX(Number unitX)
unitX | The horizontal alignment unit. |
Set the vertical text alignment unit. See SetAlignmentUnit().
Boolean SetAlignmentUnitY(Number unitY)
unitY | The vertical alignment unit. |
Get the horizontal text alignment unit.
Number GetAlignmentUnitX()
Get the vertical text alignment unit.
Number GetAlignmentUnitY()
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)
alignmentX | The horizontal container alignment. |
alignmentY | The vertical container alignment. |
Set the horizontal container alignment. See SetContainerAlignment().
Boolean SetContainerAlignmentX(Murl.IEnums.AlignmentX alignmentX)
alignmentX | The horizontal container alignment. |
Set the vertical container alignment. See SetContainerAlignment().
Boolean SetContainerAlignmentY(Murl.IEnums.AlignmentY alignmentY)
alignmentY | The vertical container alignment. |
Get the horizontal container alignment.
Murl.IEnums.AlignmentX GetContainerAlignmentX()
Get the vertical container alignment.
Murl.IEnums.AlignmentY GetContainerAlignmentY()
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)
modeX | The horizontal bounding mode. |
modeY | The vertical bounding mode. |
Set the horizontal object bounding mode. See SetObjectBoundingMode().
Boolean SetObjectBoundingModeX(Murl.IEnums.ObjectBoundingMode modeX)
modeX | The horizontal bounding mode. |
Set the vertical object bounding mode. See SetObjectBoundingMode().
Boolean SetObjectBoundingModeY(Murl.IEnums.ObjectBoundingMode modeY)
modeY | The vertical bounding mode. |
Get the horizontal object bounding mode.
Murl.IEnums.ObjectBoundingMode GetObjectBoundingModeX()
Get the vertical object bounding mode.
Murl.IEnums.ObjectBoundingMode GetObjectBoundingModeY()
Set the horizontal and vertical borders used for alignment.
Boolean SetBorder(Number borderX, Number borderY)
borderX | The horizontal border. |
borderY | The vertical border. |
Set the horizontal border used for alignment.
Boolean SetBorderX(Number borderX)
borderX | The horizontal border. |
Set the vertical border used for alignment.
Boolean SetBorderY(Number borderY)
borderY | The vertical border. |
Get the horizontal border used for alignment.
Number GetBorderX()
Get the vertical border used for alignment.
Number GetBorderY()
Set horizontal and vertical offsets used for outline rendering.
Boolean SetOffset(Number offsetX, Number offsetY)
offsetX | The horizontal offset. |
offsetY | The vertical offset. |
Set the horizontal offset used for outline rendering.
Boolean SetOffsetX(Number offsetX)
offsetX | The horizontal offset. |
Set the vertical offset used for outline rendering.
Boolean SetOffsetY(Number offsetY)
offsetY | The vertical offset. |
Get the horizontal offset used for outline rendering.
Number GetOffsetX()
Get the vertical offset used for outline rendering.
Number GetOffsetY()
Set the underlying texture's actual pixel format for outline fonts.
Boolean SetPixelFormat(Murl.IEnums.PixelFormat pixelFormat)
pixelFormat | The pixel format to use. |
Get the underlying texture's actual pixel format.
Murl.IEnums.PixelFormat GetPixelFormat()
Check if a given UTF8 character sequence is printable.
Boolean IsCharacterPrintable(String utf8Char)
utf8Char | A String containing the UTF8 character sequence to check. |
Enable/disable prescaling if the text geometry is rendering to a texture. See Graph::ITexture::SetPrescalingEnabled().
Boolean SetPrescalingEnabled(Boolean enabled)
enabled | If true, prescaling is enabled. |
Check if prescaling is enabled.
Boolean IsPrescalingEnabled()
Allow/disallow the use of a NPOT texture if outline fonts are used.
Boolean SetNonPowerOfTwoTextureAllowed(Boolean allowed)
allowed | If true, NPOT textures are allowed. |
Check if the use of a NPOT texture for outline fonts is allowed.
Boolean IsNonPowerOfTwoTextureAllowed()