.. _group__a3d__tessmarkup:

########################
Tessellation for Markups
########################

Tessellation for markups.

Entity type is :c:enumerator:`~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 :c:struct:`~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 :c:struct:`~A3DTessBaseData`\ structure.


Explanation of the first code:
==============================

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


- :c:macro:`~kA3DMarkupIsMatrix`\ denotes a matrix.
- :c:macro:`~kA3DMarkupIsExtraData`\ indicates other entities (extra data).
- :c:macro:`~kA3DMarkupExtraDataType`\ is the type of extra data.

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

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

See :ref:`Bitmasks for A3DTessMarkupData tessellation <group__a3d__tessmarkupflags>`\ and :ref:`Extra data types for A3DTessMarkupData tessellation <group__a3d__tessmarkupextradata>`\ 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 :c:macro:`~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 process 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 :c:macro:`~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 processing 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:


- First column shows the mandatory codes and the inner codes
- Second column shows the doubles

**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 :c:struct:`~A3DGraphVPicturePatternData`\ type. The pattern identifier is obtained by invoking the :c:func:`~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 :c:func:`~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 :c:func:`~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 :c:struct:`~A3DFontKeyData`\ structure. To create the :c:struct:`~A3DFontKeyData`\ structure, invoke the :c:func:`~A3DGlobalFontKeyCreate`\ function.

The font style, size indexes, and attributes are encoded into a single code by using the bitmasks in :ref:`Masks for encoding font keys <group__a3d__tessmarkupfontkeydef>`\ . See :ref:`Fonts <group__a3d__fonts>`\ .

**Text**

This entity defines a text string to be rendered with the current font (defined by :c:struct:`~A3DFontData`\ entity).


   :ref:`Fonts <group__a3d__fonts>`



::

   Codes                             Doubles
   --------------------------------------------------------------------------------
   1                                 W
   2                                 H
   index of text

The index of text refers to the zero-based text index in :c:member:`A3DTessMarkupData::m_ppcTexts <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 :c:func:`~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:


- :c:func:`~A3DGlobalInsertGraphDottingPattern`
- :c:func:`~A3DGlobalInsertGraphHatchingPattern`
- :c:func:`~A3DGlobalInsertGraphSolidPattern`
- :c:func:`~A3DGlobalInsertGraphVPicturePattern`


**Returns**


   ``A3D_SUCCESS``\ on success, or an error code on failure


.. rst-class:: kind-group kind-topic

.. rubric:: Topics
   :class: kind-group-title


.. rst-class:: api-xref-list


* :ref:`Bitmasks for A3DTessMarkupData tessellation <group__a3d__tessmarkupflags>`
* :ref:`Extra data types for A3DTessMarkupData tessellation <group__a3d__tessmarkupextradata>`
* :ref:`Bitmasks for markup options <group__a3d__tessmarkupdef>`
* :ref:`Masks for encoding font keys <group__a3d__tessmarkupfontkeydef>`

.. rst-class:: kind-group kind-record

.. rubric:: Structures
   :class: kind-group-title


.. rst-class:: api-xref-list


* :c:struct:`~A3DTessMarkupData`

.. rst-class:: kind-group kind-function

.. rubric:: Functions
   :class: kind-group-title


.. rst-class:: api-xref-list


* :c:func:`~A3DTessMarkupGet`
* :c:func:`~A3DTessMarkupCreate`

.. toctree::
   :maxdepth: 1
   :hidden:

   a3d_tessmarkupflags
   a3d_tessmarkupextradata
   a3d_tessmarkupdef
   a3d_tessmarkupfontkeydef
   ../structures/A3DTessMarkupData
   ../functions/A3DTessMarkupGet
   ../functions/A3DTessMarkupCreate


