class RED::ITextShape

This interface defines the way to display texts on screen. More...

#include <REDITextShape.h>

Inherits: IREDObject.

Public functions:

virtual RED_RCAddRotatedAndScaledString ( const RED::String & iString, const RED::Vector3 & iAnchor, float iAngle, const RED::Vector3 & iScale, RED::TEXT_ATTACH_POS iAttachPos, const RED::State & iState ) = 0
virtual RED_RCAddRotatedString ( const RED::String & iString, const RED::Vector3 & iAnchor, float iAngle, RED::TEXT_ATTACH_POS iAttachPos, const RED::State & iState ) = 0
virtual RED_RCAddString ( const RED::String & iString, const RED::Vector3 & iAnchor, RED::TEXT_ATTACH_POS iAttachPos, const RED::State & iState ) = 0
virtual RED_RCClearStrings ( const RED::State & iState ) = 0
virtual RED_RCCopyFrom ( const RED::Object & iText, const RED::State & iState, int iSrcStateNumber = -1 ) = 0
virtual RED_RCGetAnchor ( RED::Vector3 & oAnchor, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetAngle ( float & oAngle, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetAttachPosition ( RED::TEXT_ATTACH_POS & oAttachPos, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetColor ( RED::Color & oColor, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetDepth ( float & oDepth, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetFont ( RED::Object *& oFont, int iStateNumber = -1 ) const = 0
virtual RED_RCGetScale ( RED::Vector3 & oScale, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetString ( RED::String & oString, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetStringBox ( float & oLeft, float & oRight, float & oBottom, float & oTop, int iStringNumber, int iStateNumber = -1 ) const = 0
virtual RED_RCGetStringsCount ( int & oStringsCount, int iStateNumber = -1 ) const = 0
virtual RED_RCRemoveString ( int iNumber, const RED::State & iState ) = 0
virtual RED_RCSetAnchor ( int iStringNumber, const RED::Vector3 & iAnchor, const RED::State & iState ) = 0
virtual RED_RCSetAngle ( int iStringNumber, float iAngle, const RED::State & iState ) = 0
virtual RED_RCSetAttachPosition ( int iStringNumber, RED::TEXT_ATTACH_POS iAttachPos, const RED::State & iState ) = 0
virtual RED_RCSetColor ( int iStringNumber, const RED::Color & iColor, const RED::State & iState ) = 0
virtual RED_RCSetDepth ( int iStringNumber, float iDepth, const RED::State & iState ) = 0
virtual RED_RCSetFont ( RED::Object * iFont, const RED::State & iState ) = 0
virtual RED_RCSetScale ( int iStringNumber, const RED::Vector3 & iScale, const RED::State & iState ) = 0
virtual RED_RCSetString ( int iStringNumber, const RED::String & iString, const RED::State & iState ) = 0

Public static functions:

static RED::CIDGetClassID ( )

Detailed description:

This interface defines the way to display texts on screen.

This interface exposes services to draw texts on screen. This interface is implemented by the CID_REDTextShape object instance that can be created from the RED::Factory.

RED::String objects are stored by the shape, are rendered using the shape's material. The appareance of strings is defined by the font of the shape (RED::ITextShape::SetFont). A text shape will not appear on screen if it has no font defined.

The RED::BoundingSphere of a text is limited to the sphere enclosing all anchoring points of strings in the shape. This because depending on the kind of text being displayed, the text geometry may be dynamic. So if a shape has a single string, if it's anchor point is outside the screen, the whole string will disappear after clipping.

See documentation on texts here: Text shapes, and a tutorial on practical text implementation here Displaying texts.

Refer to the documentation of the RED::IFont class to learn more on the setup of fonts for the display of texts and on text geometries resulting of using the various font types.

The orientation of text strings is either:

The axis system of a string in a text shape.

The coordinate system of the string is the model space of the shape. Therefore, adding a parent transform shape above the text shape will transform all strings positions.

Functions documentation

public virtual RED_RC RED::ITextShape::AddRotatedAndScaledString(const RED::String &iString,
const RED::Vector3 &iAnchor,
floatiAngle,
const RED::Vector3 &iScale,
RED::TEXT_ATTACH_POSiAttachPos,
const RED::State &iState
) = 0

Adds a string to the shape with a rotation angle and a scaling.

Adds a string to the list of strings displayed by this shape. Compared to the RED::ITextShape::AddString method, this one adds a rotation and a scaling component to the string, enabling it to be turned around its attach position.
Note that all texts but RED::FNT_BITMAP texts can be rotated and scaled using this method. Noticeably, RED::FNT_TEXTURE texts can be rotated and scaled without suffering from any performance penalty during the rendering.

Bounding boxes enclosing each string character are calculated by this call. This operation can take some time for characters that have not been displayed on screen yet.

Parameters:

iString:Added text.
iAnchor:Text string anchoring position.
iAngle:Angle of rotation of the string. The rotation occurs in the (X,Y) plane of the string object space. The angle is expressed in radians.
iScale:Scaling factor applied to the string. The scaling is centered at the string anchoring point.
iAttachPos:String vs anchor attachment position.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::AddRotatedString(const RED::String &iString,
const RED::Vector3 &iAnchor,
floatiAngle,
RED::TEXT_ATTACH_POSiAttachPos,
const RED::State &iState
) = 0

Adds a string to the shape with a rotation angle.

Adds a string to the list of strings displayed by this shape. Compared to the RED::ITextShape::AddString method, this one adds a rotation component to the string, enabling it to be turned around its attach position.
Note that all texts but RED::FNT_BITMAP texts can be rotated using this method. Noticeably, RED::FNT_TEXTURE texts can be rotated and this does not change the performance of the rendering.

Bounding boxes enclosing each string character are calculated by this call. This operation can take some time for characters that have not been displayed on screen yet.

Parameters:

iString:Added text.
iAnchor:Text string anchoring position.
iAngle:Angle of rotation of the string. The rotation occurs in the (X,Y) plane of the string object space. The angle is expressed in radians.
iAttachPos:String vs anchor attachment position.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::AddString(const RED::String &iString,
const RED::Vector3 &iAnchor,
RED::TEXT_ATTACH_POSiAttachPos,
const RED::State &iState
) = 0

Adds a string to the shape.

Adds a string to the list of strings displayed by this shape. Each string has a spatial anchoring position that'll define where it'll be rendered on screen. The position of the string versus it's anchoring position is specified by the iAttachPos parameter.

Bounding boxes enclosing each string character are calculated by this call. This operation can take some time for characters that have not been displayed on screen yet.

Parameters:

iString:Added text.
iAnchor:Text string anchoring position.
iAttachPos:String vs anchor attachment position.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has fail,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::ClearStrings(const RED::State &iState) = 0

Removes all strings from the shape.

Parameters:

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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::CopyFrom(const RED::Object &iText,
const RED::State &iState,
intiSrcStateNumber = -1
) = 0

Copies the content of a RED::ITextShape instance to the current object.

This method will work for only two instances of the same concrete class.

Parameters:

iText:Reference to the object to copy from.
iState:Current transaction.
iSrcStateNumber:State from which the source text must be copied.

Returns:

RED_OK on success,
RED_BAD_PARAM if 'iText' and this are from different classes, or if 'iSrcStateNumber' is invalid,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL for any other error.
public virtual RED_RC RED::ITextShape::GetAnchor(RED::Vector3 &oAnchor,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the i-th string anchor position.

Parameters:

oAnchor:The returned string anchoring position.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK is the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetAngle(float &oAngle,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the i-th string rotation angle.

Parameters:

oAngle:The returned string angle value.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK is the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetAttachPosition(RED::TEXT_ATTACH_POS &oAttachPos,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the attachment position of the string.

This method returns the attachment position of the string relatively to its anchoring point.

Parameters:

oAttachPos:String attachment position.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetColor(RED::Color &oColor,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the custom color of a string.

See the SetColor method for details on the custom color setup.

Parameters:

oColor:The current custom color for the string. The value returned is RED::Color::UNDEFINED if the string has no custom color set.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetDepth(float &oDepth,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the custom depth of a string.

See the SetDepth method for details on the custom depth setup.

Parameters:

oDepth:The current custom depth for the string. The value returned is FLT_MAX if the string has no custom depth set.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetFont(RED::Object *&oFont,
intiStateNumber = -1
)const = 0

Gets the shape's font.

Parameters:

oFont:Returned shape's font. NULL if the shape has no assigned font yet.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetScale(RED::Vector3 &oScale,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the i-th string scale.

Parameters:

oScale:The returned string scale value.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK is the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetString(RED::String &oString,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the i-th shape string.

Parameters:

oString:Accessed string.
iStringNumber:Queried string number.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::GetStringBox(float &oLeft,
float &oRight,
float &oBottom,
float &oTop,
intiStringNumber,
intiStateNumber = -1
)const = 0

Gets the bounding box of a string.

This method returns the bounding box of a string. This is an AABB of the box in the local axis coordinate system of the shape that is returned by the call. The string anchoring, attachment position and rotation angles are all managed by the method.

Parameters:

oLeft:Left boundary of the text box.
oRight:Right boundary of the text box.
oBottomBottom boundary of the text box.
oTop:Top boundary of the text box.
iStringNumber:The string box to calculate and return.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL if the shape has no valid font.
public virtual RED_RC RED::ITextShape::GetStringsCount(int &oStringsCount,
intiStateNumber = -1
)const = 0

Gets the number of strings in the shape.

Parameters:

oStringsCount:The number of strings in the shape.
iStateNumber:Queried state number.

Returns:

RED_OK if the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter.
public virtual RED_RC RED::ITextShape::RemoveString(intiNumber,
const RED::State &iState
) = 0

Removes a string from the shape.

Parameters:

iNumber:String position in the shape's list.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetAnchor(intiStringNumber,
const RED::Vector3 &iAnchor,
const RED::State &iState
) = 0

Edits the anchor position of the i-th string.

Parameters:

iStringNumber:Modified string number.
iAnchor:New anchor position.
iState:Current transaction parameter.

Returns:

RED_OK when the operation has succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetAngle(intiStringNumber,
floatiAngle,
const RED::State &iState
) = 0

Edits the angle of the i-th string.

Parameters:

iStringNumber:Modified string number.
iAngle:New angle value.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetAttachPosition(intiStringNumber,
RED::TEXT_ATTACH_POSiAttachPos,
const RED::State &iState
) = 0

Edits the attachment position of the i-th string.

Parameters:

iStringNumber:Modified string number.
iAttachPos:New attachment position.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetColor(intiStringNumber,
const RED::Color &iColor,
const RED::State &iState
) = 0

Overwrites the color material value of a string.

This method sets a custom color value to use with the string. This is only used for texts strings that are rendered using textured fonts (RED::FNT_TEXTURE) and using a RED::RenderShaderText. This kind of custom custom value is mainly used for string batching in drafting environments.

Parameters:

iStringNumber:Modified string number.
iColor:The color value to use for the string.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetDepth(intiStringNumber,
floatiDepth,
const RED::State &iState
) = 0

Overwrites the z-buffer rendering value of a string.

This method sets a custom depth value to use with the string. This is only used for texts strings that are rendered using textured fonts (RED::FNT_TEXTURE) and using a RED::RenderShaderText. This kind of custom depth value is mainly used by custom depth sorting algorithms in drafting environments.

Parameters:

iStringNumber:Modified string number.
iDepth:The depth value to return from the pixel shader, instead of the regular depth value resulting of the rasterization of the text quads. The value should be in [0.0f,1.0f] for the final string to be visible. However, an out-of-bound value can be assigned.
iState:Current transaction parameter.

Returns:

RED_OK when the operation succeeded,
RED_BAD_PARAM if the method has received an invalid parameter,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetFont(RED::Object *iFont,
const RED::State &iState
) = 0

Sets the shape's font.

Sets the font that'll be used for the rendering of the shape's strings. 'iFont' is created using RED::IResourceManager::CreateFont.

If the text shape is already using a font, then 'iFont's render mode must be identical to the render mode of the previous font of the text shape. For example, a font rendered using triangle texts can't be switched to be rendered using textured texts.

Parameters:

iFont:New font for the shape's rendering.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_SCG_FONT_RENDER_MODE_CHANGE_ERROR if the font's render mode has been changed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetScale(intiStringNumber,
const RED::Vector3 &iScale,
const RED::State &iState
) = 0

Edits the scaling of the i-th string.

Parameters:

iStringNumber:Modified string number.
iScale:New scaling value.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.
public virtual RED_RC RED::ITextShape::SetString(intiStringNumber,
const RED::String &iString,
const RED::State &iState
) = 0

Edits the contents of the i-th string.

Bounding boxes enclosing each string character are calculated by this call. This operation can take some time for characters that have not been displayed on screen yet.

Parameters:

iStringNumber:Modified string number.
iString:New string value.
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 a transaction error has been found,
RED_ALLOC_FAILURE if an internal allocation has failed,
RED_FAIL otherwise.