ITextShape
Functions
Detailed Description
-
class ITextShape : public RED::IREDObject
This interface defines the way to display texts on screen.
@related Text Shapes, class RED::IShape, class RED::IFont, Displaying Texts
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: \ref bk_sg_text_shapes, and a tutorial on practical text implementation here \ref wf_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:
Aligned with the screen if the text is using a RED::FNT_BITMAP type of font.
Positioned in the 3d model according to the image below for all other font types:
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.
Public Functions
-
virtual RED_RC 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.
-
virtual RED_RC GetFont(RED::Object *&oFont, int iStateNumber = -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.
-
virtual RED_RC AddString(const RED::String &iString, const RED::Vector3 &iAnchor, RED::TEXT_ATTACH_POS iAttachPos, 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.
-
virtual RED_RC AddRotatedString(const RED::String &iString, const RED::Vector3 &iAnchor, float iAngle, RED::TEXT_ATTACH_POS iAttachPos, 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.
-
virtual RED_RC AddRotatedAndScaledString(const RED::String &iString, const RED::Vector3 &iAnchor, float iAngle, const RED::Vector3 &iScale, RED::TEXT_ATTACH_POS iAttachPos, 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.
-
virtual RED_RC InsertStringsFrom(const RED::Object *iSource, const RED::State &iState) = 0
Inserts all strings from iSource into this.
This method adds all strings contained in iSource into this. If iSource uses the same font as this then the operation will copy strings bounding boxes stored in iSource, otherwise it’ll recalculate them.
- Parameters
iSource – Source RED::ITextShape to source strings to add from.
iState – The current transaction.
- Returns
RED_OK if the method has succeeded,
RED_BAD_PARAM if iSource is NULL or not a
RED::ITextShape,
RED_WORKFLOW_ERROR if a transaction error has been found,
RED_ALLOC_FAILURE if a memory allocation has failed,
RED_FAIL otherwise.
-
virtual RED_RC RemoveString(int iNumber, 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.
-
virtual RED_RC 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.
-
virtual RED_RC GetStringsCount(int &oStringsCount, int iStateNumber = -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.
-
virtual RED_RC GetString(RED::String &oString, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetAnchor(RED::Vector3 &oAnchor, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetAngle(float &oAngle, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetScale(RED::Vector3 &oScale, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetAttachPosition(RED::TEXT_ATTACH_POS &oAttachPos, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetDepth(float &oDepth, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC GetColor(RED::Color &oColor, int iStringNumber, int iStateNumber = -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.
-
virtual RED_RC SetString(int iStringNumber, 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.
-
virtual RED_RC SetAnchor(int iStringNumber, 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.
-
virtual RED_RC SetAngle(int iStringNumber, float iAngle, 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.
-
virtual RED_RC SetScale(int iStringNumber, 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.
-
virtual RED_RC SetAttachPosition(int iStringNumber, RED::TEXT_ATTACH_POS iAttachPos, 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.
-
virtual RED_RC SetDepth(int iStringNumber, float iDepth, 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.
-
virtual RED_RC SetColor(int iStringNumber, 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.
-
virtual RED_RC CopyFrom(const RED::Object &iText, const RED::State &iState, int iSrcStateNumber = -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.
-
virtual RED_RC GetStringBox(float &oLeft, float &oRight, float &oBottom, float &oTop, int iStringNumber, int iStateNumber = -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.
oBottom – Bottom 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.
