####################
Tessellation Example
####################

***************************************************************
Creating a Tessellation Entity for Representing Faceted Objects
***************************************************************

This section explains how to add tessellation base data to an existing representation item for a theoretical STL file.
The process is broken into two main parts: creating the root base data, and creating the tessellation facet data.

*********************************
Create the Tessellation Base Data
*********************************

.. rubric:: Step 1

Create a :struct:`A3DTessBaseData` structure and set its member values to represent the facets.
The following explanation assumes facets are defined as triangles, although you could define facets having more than three points.

* `m_uiCoordSize`. Set this member to the number of coordinates required to represent all facets in the object.
  This value is calculated as `9 * facetSize`. The 9 multiplier is the number of points in each facet (3) times the number of coordinates in each point (3). The `facetSize` variable represents the number of facets in the object.
* `m_pdCoords`. Set this member to an array of N `A3DDouble` entries, where N is the value calculated for the `m_uiCoordSize` member.

.. rubric:: Step 2

Add coordinates for each vertex of each facet to the array referenced by the `m_pdCoords` member.
The X, Y, and Z coordinates for each vertex are represented as sequential entries in the array, as shown in this example:

.. code-block:: c

   sTessBaseData.m_pdCoords[j++] = x;
   sTessBaseData.m_pdCoords[j++] = y;
   sTessBaseData.m_pdCoords[j++] = z;

**********************************
Create the Tessellation Facet Data
**********************************

.. rubric:: Step 1

Create an :struct:`A3DTess3DData` structure and set its members to represent the facet normals:

* `m_uiNormalSize`. Set this member to the size of the array required to represent the normals for all facets in the objects. This is calculated as `3 * facetSize`. The 3 multiplier is the number of coordinates to represent each vector.
* `m_pdNormals`. Set this member to an array of N `A3DDouble` entries, where N is the value calculated for the `m_uiNormalSize` member.
* `m_uiTriangulatedIndexSize` . Set this member to the number of entries required to represent the indices associated with each facet in the objects. Each facet can have one to four indices that reference texture coordinates, one index that references a facet normal, and three indices that reference vertices. Normals are read from the `m_pdNormals` array, and textures are read from the `m_pdTextureCoords` array.
* `m_puiTriangulatedindices`. Set this member to an array of N `A3DUns32` entries, where N is the number of entries in the `m_uiTriangulatedIndexSize` member. This array contains the indices of the points (`m_pdCoords`), normals (`m_pdNormals`), and texture arrays for each face's triangulated representation. The entries in this array correspond to the contents in the `A3DTessFaceData` entity.

.. rubric:: Step 2

Add the indices for each facet, considering the number of entries to represent each facet.
Each facet contains the following sequential representations in this array:

* (Optional) Index of the first texture in the array referenced by the `m_pdTextureCoords` member. This entry can be followed by three more entries for additional texture indices.
* Index of the facet normal in the array referenced by the `m_pdNormals` member.
* Index of the first facet vertex in the array referenced by the `m_pdCoords` member.
* Index of the second facet vertex in the array referenced by the `m_pdCoords` member.
* Index of the third facet vertex in the array referenced by the `m_pdCoords` member.

In the following example for STL data, `facetSize` is set to 0 for the first facet represented by the array and to 1 for the second facet in the array.

.. code-block:: c

   sTess3DData.m_puiTriangulatedindices[4 * facetSize] = i;
   sTess3DData.m_puiTriangulatedindices[4 * facetSize + 1] = j;
   sTess3DData.m_puiTriangulatedindices[4 * facetSize+2] = j + 3;
   sTess3DData.m_puiTriangulatedindices[4 * facetSize+3] = j + 6;

.. rubric:: Step 3

.. code-block:: c

   sTess3DData.m_pdNormals[i++] = x;
   sTess3DData.m_pdNormals[i++] = y;
   sTess3DData.m_pdNormals[i++] = z;

.. rubric:: Step 4

For each face, create an `A3DTessFaceData` entity and set its member values as follows:

* `m_usUsedEntitiesFlags` . Set this member to an enumeration that specifies the entities used in the current face tessellation. For example, the `kA3DTessFaceDataTriangleOneNormal` enumeration specifies that the face data is a triangle with a single normal facet.
* `m_uiSizesTriangulatedSize` . Set this member to the number of entries in the array referenced by the `m_puiSizesTriangulated` member.
* `m_puiSizesTriangulated` . Set this value to the repetition sequence applied to the `m_usUsedEntitiesFlags` member. A single entry with a value of 1 indicates that the first flag in `m_usUsedEntitiesFlags` applies to all face data.
* `m_uiStartTriangulated` . Set this value to the starting index for the wire in the array of point indices of the `A3DTess3DData` entity.

.. rubric:: Step 5

Set the `A3DTess3DData` structure's `m_psFaceTessData` member to reference an array that in turn references each face that applied to the facets.
Set the `m_uiFaceTessSize` member to the number of faces in this array.

.. rubric:: Step 6

Create the tessellation entity by invoking the `A3DTess3DCreate` function, providing the location of the `A3DTess3DData` structure as the first argument and the location of the `A3DTess3D` pointer as the second argument.

.. code-block:: c

   A3DTess3D* pTess3D = NULL;
   A3DTess3DCreate(&sTess3DData, &pTess3D);

.. rubric:: Step 7

Package the tessellation base data with in the `A3DTess3D` entity by invoking the `A3DTessBaseSet` function.

.. code-block:: c

   A3DTessBaseSet(&pTess3D, &sTessBaseData);

.. rubric:: Step 8

Add the `A3DTess3D` data to a representation item.

The complete code sample can be found :download:`here </_assets/create_tess_entity.c>`;.
The code creates an A3D tessellation entity from a file that conforms to the STL format.
It packages this entity with a poly B-rep model representation item.
STL is a file format native to the stereolithography CAD software created by 3D Systems.

etting_tessellation
