M3dgraText

See also

User Guide:

3D graphics lists Annotating the 3D display

Reference:

M3dgeoInquire M3dgraArc M3dgraControl M3dgraInquire MthrAlloc

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

3dplanefit.cpp
m3dgra.cpp
m3dgra.cs
m3dgra.vb

Function Map

- List3dgraId

- ParentLabel

Table:

For specifying the parent label

- Text

Table:

For specifying the string

- Matrix3dgeoId

Table:

For specifying the transformation matrix object identifier

- Options

Table:

For specifying extra options

- ControlFlag

Return value

Compilation information

Synopsis

Add a text graphic to a 3D graphics list.

Syntax

MIL_INT64 M3dgraText(

MIL_ID List3dgraId,	//in
MIL_INT64 ParentLabel,	//in
MIL_CONST_TEXT_PTR Text,	//in
MIL_ID Matrix3dgeoId,	//in
MIL_INT64 Options,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function adds a text graphic to the specified 3D graphics list, allowing you to, for example, view the text graphic on a 3D display.

You must specify the label of the 3D graphic, in the 3D graphics list, to use as the parent of the text graphic. When the text graphic is added to the 3D graphics list's tree structure, it is added as a child under the specified parent. If the 3D graphics list is empty, the text graphic's parent must be the root node.

The text graphic has its own coordinate system that represents the text's position and orientation with respect to its parent's coordinate system. The text is justified at its coordinate system's origin, and is written in the direction of its coordinate system's X-axis, by default, facing the direction of the Z-axis. By default, the text is top- and left-aligned, so the top-left corner of the text is positioned at its coordinate system's origin. You can set the text's position and orientation using the Matrix3dgeoId parameter.

You can set the text's font and size using M3dgraControl with M_FONT and M_FONT_SIZE.

To modify or inquire 3D graphics list settings, use M3dgraControl() or M3dgraInquire(), respectively.

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same MIL 3D graphics list (List3dgraId) without using an M_MUTEX object, as long as all the other parameters of the concurrent calls do not also share data.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

List3dgraId

Specifies the identifier of the 3D graphics list in which to add the text graphic.

ParentLabel

Specifies the label of the parent of the text graphic in the 3D graphics list.

For specifying the parent label
Value	Description
M_DEFAULT	Same as M_ROOT_NODE.
M_ROOT_NODE	Specifies the top-most node of the 3D graphics list.
Value >= 0	Specifies the label of the parent of the text graphic in the 3D graphics list. Label 0 is the 3D graphics list's root node. (summarize) Specifies the label of the parent of the text graphic in the 3D graphics list. (more details...)

Text

Specifies the address of the string containing the text that must be shown in the text graphic.

For specifying the string
Value	Description
MIL_TEXT("String") ¹	Specifies the address of the null-terminated (\0) ASCII string that must be shown in the text graphic. There is no restriction on the length of the string. (summarize) Specifies the address of the null-terminated (\0) ASCII string that must be shown in the text graphic. (more details...)

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

Matrix3dgeoId

Specifies the identifier of the transformation matrix that defines the text graphic's position and orientation with respect to its parent's coordinate system.

For specifying the transformation matrix object identifier
Value	Description
M_DEFAULT	Same as M_IDENTITY_MATRIX.
M_IDENTITY_MATRIX	Specifies the identity matrix. This means that the text graphic's position and orientation is the same as the position and orientation of its parent's coordinate system. (summarize) Specifies the identity matrix. (more details...)
MIL transformation matrix object identifier	Specifies the identifier of the transformation matrix that defines the text graphic's position and rotation with respect to its parent's coordinate system. The transformation matrix must be of type M_RIGID. (summarize) Specifies the identifier of the transformation matrix that defines the text graphic's position and rotation with respect to its parent's coordinate system. (more details...)

Options

Specifies extra options for the appearance of the text graphic.

For specifying extra options
Value	Description
M_DEFAULT	Specifies that the text is written in the direction of the text graphic's coordinate system's X-axis, and that the text faces the direction of the Z-axis of the text graphic's coordinate system. (summarize) Specifies that the text is written in the direction of the text graphic's coordinate system's X-axis, and that the text faces the direction of the Z-axis of the text graphic's coordinate system. (more details...)
M_FLIP	Specifies that the text is mirrored across the X-axis. The text faces the direction of the negative Z-axis of the text graphic's coordinate system. (summarize) Specifies that the text is mirrored across the X-axis. (more details...)

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Return value

Returns the label of the text graphic added to the 3D graphics list.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3d.lib.
DLL	Requires mil.dll; mil3d.dll.