Tessellation for markups. More...

Modules

 Bitmasks for A3DTessMarkupData tessellation
 
 Extra data types for A3DTessMarkupData tessellation
 
 Bitmasks for markup options
 
 Masks for encoding font keys
 

Data Structures

struct  A3DTessMarkupData
 TessMarkupData structure. More...
 

Functions

A3DStatus A3DTessMarkupCreate (const A3DTessMarkupData *pData, A3DTessMarkup **ppTess)
 Creates an A3DTessMarkup entity from an A3DTessMarkupData structure. More...
 
A3DStatus A3DTessMarkupGet (const A3DTessMarkup *pTess, A3DTessMarkupData *pData)
 Populates the A3DTessMarkupData structure. More...
 

Detailed Description

Tessellation for markups.

Entity type is kA3DTypeTessMarkup.

The tessellation uses two arrays: one for the codes and another for the coordinates. The codes array describes the type of contents in tessellation (the entities). The coordinates array contains point coordinates and other floating point values used by the entities. The coordinates array is specified in the A3DTessBaseData structure.

Each entity occupies at least two codes. The first code contains the entity type and the number of specific codes. The second code contains the number of doubles (coordinates) for the entity. The doubles (coordinates) are in the coordinates array of the A3DTessBaseData structure.

Explanation of the first code:

Use one of the following masks to identify the entity type with the first code:

If none of these masks are set, the entity is a polyline.

kA3DMarkupIsMatrix must not be set if kA3DMarkupIsExtraData is set and kA3DMarkupExtraDataType represents the type of entity only if kA3DMarkupIsExtraData is set.
The kA3DMarkupIntegerMask mask represents the number of codes that refers to the entity (inner codes).
kA3DMarkupIsMatrix and kA3DMarkupIsExtraData are booleans; whereas, kA3DMarkupExtraDataType is an integer.
The other bits should be set to zero.

See Bitmasks for A3DTessMarkupData tessellation and Extra data types for A3DTessMarkupData tessellation for more details.

Explanation of the second code:

The second code is the number of doubles needed by the entity. Each time the first double of block refers to updated position within BaseData Coord array: starting from 0 if reading a matrix first and next double value to read will be at Coord[16].

The following table describes the inner codes and doubles that can be defined for each entity. It also describes the extra data type number.

Entity              Extra data type   Number of inner codes     Number of doubles
---------------------------------------------------------------------------------------------
Polyline            none              0                         number of points * 3
Matrix mode[1]      none              0 or number in block      0 or number in block
Pattern                0              3 + number of loops       number of points in loops * 3
Picture                1              1                         0
Triangles              2              0                         number of triangles * 9
Quads                  3              0                         number of quads * 12
Face view mode[1]      6              0 or number in block      0 or number in block
Frame draw mode[1]     7              0 or number in block      0 or number in block
Fixed size mode[1]     8              0 or number in block      0 or number in block
Symbol                 9              1                         3
Cylinder              10              0                         3
Color                 11              1                         0
Line stipple[2]       12              0 or 1                    0
Font                  13              2                         0
Text                  14              1                         2
Points                15              0                         number of points * 3
Polygon               16              0                         number of points * 3
Line width[2]         17              0                         0 or 1

See A3D_ENCODE_EXTRA_DATA macro to encode extra data.

About Blocks

Blocks are defined by face view, frame draw, fixed size, and matrix modes (indicated by [1]). Each block is surrounded by the corresponding entity. At the start of a block, the entity modifies the state (style, current transformation matrix, ...). Then this state is restored at the end of the block. For example, a matrix mode starts by defining a matrix (which will multiply the current transformation matrix), draws some entities, and ends with another matrix mode entity for indicating the end of the mode.

[1] The face view, frame draw, fixed size, and matrix modes start with the corresponding entity and end with the same entity; therefore, they define blocks. The starting entity has a non-zero number of inner codes. It represents the number of codes until the end of the block, excluding the 2 mandatory codes for each entity. The same rule applies to the doubles. The ending entity has 0 inner codes and 0 doubles. The use of this number is to easily skip a block when reading tessellation. To treat the content of a block, the numbers to use are as follows:

Mode                      Number of inner codes          Number of doubles
--------------------------------------------------------------------------------
Face view (starting)      0                              3
Face view (ending)        0                              0
Frame draw (starting)     0                              3
Frame draw (ending)       0                              0
Fixed size (starting)     0                              3
Fixed size (ending)       0                              0
Matrix (starting)         0                              16
Matrix (ending)           0                              0

For example: matrix mode

        --+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--
Codes     |  |M1|16|C |C |C |C |C |C |C |C |C |C |C |M2|0 |
        --+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--

M1 code is kA3DMarkupIsMatrix (0 additional code), which is the same as M2. This example shows the codes for defining a matrix mode. The M1 code defines the beginning of the matrix mode, and the M2 code defines the closing of that mode. The number of doubles for the M1 code is 16. After that, some entities are drawn (the Cs) and the M2 code defines the end of the matrix mode. The M2 code has 0 codes and 0 doubles because it is only reverting back to the initial matrix.

[2] The line stipple and line width modes operate identically to [1], but the numbers correspond to the entity only and not to the block. This is because the treatment of those can be more easily omitted than for the previous ones. For line stipple mode, the number of inner codes denotes the start (1) or the end (0) of the block. For line width mode, the number of doubles denotes the start (1) or the end (0) of the block.

Explanation of each entity:

The array for each entity is organized as described here:

Polyline

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 X
number of points * 3              Y
                                  Z

There is a (x,y,z) triplet for each point of the polyline.

Triangles

A list of triangles.

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 X
number of triangles * 9           Y
                                  Z

There is a (x,y,z) triplet for each point of the triangle list.

Quads

A list of quads.

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 X
number of quads * 12              Y
                                  Z

There is a (x,y,z) triplet for each point of the quad list.

Polygon

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 X
number of points * 3              Y
                                  Z

There is a (x,y,z) triplet for each point of the polygon.

Points

A list of points.

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 X
number of points * 3              Y
                                  Z

There is a (x,y,z) triplet for each point.

Face view mode

In this mode, all the drawing entities are parallel to the screen (billboard). The point given in the doubles corresponds to the origin of the new coordinate system in which we draw parallel to the screen.

Codes                             Doubles
--------------------------------------------------------------------------------
0 or number in block              X
0 or number in block              Y
                                  Z

Frame draw mode

In this mode, all the drawing entities are given in 2D space. The point given in the doubles corresponds to a 3D point projected onto the screen giving origin of 2D coordinate system in which we draw in 2D (viewport).

Codes                             Doubles
--------------------------------------------------------------------------------
0 or number in block              X
0 or number in block              Y
                                  Z

Fixed size mode

In this mode, all the drawing entities are drawn at a fixed size, independent of the zoom setting. The point given in the doubles corresponds to the origin of the new coordinate system in which we draw at fixed size.

Codes                             Doubles
--------------------------------------------------------------------------------
0 or number in block              X
0 or number in block              Y
                                  Z

Matrix mode

In this mode, all the drawing entities are transformed by the current transformation matrix multiplied by the matrix given in the doubles. At the end of the mode, the previously active transformation matrix is restored.

Codes                             Doubles
--------------------------------------------------------------------------------
0 or number in block              a(1,1)
0 or number in block              a(2,1)
                                  a(3,1)
                                  a(4,1)
                                  a(1,2)
                                  a(2,2)
                                  ...
                                  a(3,4)
                                  a(4,4)

Symbol

The point given in the doubles corresponds to the position of the symbol in 3D.

Codes                             Doubles
--------------------------------------------------------------------------------
1                                 X
3                                 Y
id of pattern                     Z

The pattern is an A3DGraphVPicturePatternData type. The pattern identifier is obtained by invoking the A3DGlobalInsertGraphVPicturePattern function.

Color

This entity defines a color that will be effective until a new one is defined.

Codes                             Doubles
--------------------------------------------------------------------------------
1
0
id of color

Color identifier is obtained by invoking the A3DGlobalInsertGraphRgbColor function.

Line stipple mode

This entity defines the style that will be effective inside the block.

Codes                             Doubles
--------------------------------------------------------------------------------
0 or 1
0
id of style

The first code is 1 for beginning the block and 0 for ending the block. The style identifier is obtained by invoking the A3DGlobalInsertGraphStyle function.

Font

This entity defines the font used for the Text entity (described next).

Codes                             Doubles
--------------------------------------------------------------------------------
2
0
family index
style index/size index/attributes

The indexes and the attributes are taken from the A3DFontKeyData structure. To create the A3DFontKeyData structure, invoke the A3DGlobalFontKeyCreate function.

The font style, size indexes, and attributes are encoded into a single code by using the bitmasks in Masks for encoding font keys. See Fonts.

Text

This entity defines a text string to be rendered with the current font (defined by A3DFontData entity).

See also
Fonts
Codes                             Doubles
--------------------------------------------------------------------------------
1                                 W
2                                 H
index of text

The index of text refers to the zero-based text index in A3DTessMarkupData::m_ppcTexts.
The W and H correspond to the width and height (respectively) of text in real display coordinates.

Line width mode

This entity defines the line width that will be effective inside the block.

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 W
0 or 1

The number of doubles is 1 for beginning the block and 0 for ending the block. The W double is the line width to use in the block. There is no W double when ending the block.

Cylinder

Codes                             Doubles
--------------------------------------------------------------------------------
0                                 Base radius
3                                 Top radius
                                  Height

The cylinder is positioned by a matrix mode, oriented with Z axis, base at Z = 0 and top at Z = Height.

Picture

This entity defines a picture positioned at the current position.

Codes                             Doubles
--------------------------------------------------------------------------------
1
0
id of picture

Picture identifier is obtained by invoking the A3DGlobalInsertGraphPicture function.

Pattern

Codes                             Doubles
--------------------------------------------------------------------------------
3 + number of loops               X
number of points in loops * 3     Y
id of pattern                     Z
filled mode
behavior
number of points for loop 1
...
number of points for loop n

The filled mode is one of these values: 0=OR, 1=AND, or 2=XOR. The behavior is a bit field, with the 0x1 bit specifying whether to ignore the view transformation. If true, the pattern is not transformed by the current view transformation. The other bits should be set to zero. There is a (x,y,z) triplet for each point of loops, sequentially.

Pattern identifier is created by invoking one of the following functions:

Function Documentation

◆ A3DTessMarkupGet()

A3DStatus A3DTessMarkupGet ( const A3DTessMarkup pTess,
A3DTessMarkupData pData 
)

Populates the A3DTessMarkupData structure.

Version
2.0
Returns
A3D_SUCCESS in case of success or an error code
Return values
A3D_INITIALIZE_NOT_CALLED
A3D_INVALID_DATA_STRUCT_SIZE
A3D_INVALID_DATA_STRUCT_NULL
A3D_INVALID_ENTITY_NULL
A3D_INVALID_ENTITY_TYPE
A3D_SUCCESS

◆ A3DTessMarkupCreate()

A3DStatus A3DTessMarkupCreate ( const A3DTessMarkupData pData,
A3DTessMarkup **  ppTess 
)

Creates an A3DTessMarkup entity from an A3DTessMarkupData structure.

Version
2.0
Returns
A3D_SUCCESS in case of success or an error code
Return values
A3D_INITIALIZE_NOT_CALLED
A3D_INVALID_DATA_STRUCT_SIZE
A3D_INVALID_DATA_STRUCT_NULL
A3D_INVALID_ENTITY_NULL
A3D_INVALID_ENTITY_TYPE
A3D_TESSMARKUP_HAS_INVALID_FONTKEY
A3D_TESSMARKUP_HAS_INVALID_TEXT_INDEX
A3D_SUCCESS