######
Layers
######

Up to version 24.4.0, a *layer* was simply a logical group of objects.
It only contained a name and an ID.

These regrouped objects were not required to be related in any way, and an entity could only be linked to one layer, by specifying its layer indice on the :cpp:struct:`A3DGraphicsData` structure.

Since version 24.5.0, :cpp:struct:`the layer object type <A3DAsmLayerData>` has been extended with a note field and a display status.
Moreover, since an entity can now be linked to several layers, a layer also maintains a list of referenced entities.

Typical Contents And Usages
===========================

Layers in a part file can include features like sketches, extrusions, holes, datum planes, axes, surfaces and annotations that belong to that specific part.

Layers help in controlling the visibility and selectability of features within a part.
They can be used to simplify the part model view, focus on specific features, and prevent accidental modifications.

Common applications include:

* Organizing different types of features (e.g., all holes on one layer, all datum planes on another).
* Managing complex parts with many features by grouping related features together.
* Controlling the display of reference geometry and construction elements separately from the solid geometry.

API Overview
============

A :cpp:struct:`layer entity <A3DAsmLayerData>` is structured as follows:

.. code-block:: c

   typedef struct
   {
        A3DUns16                     m_usStructSize;
        A3DUTF8Char                  m_pcLayerName;
        A3DUns32                     m_uiLayerID; // Layer ID
        A3DUTF8Char*                 m_pcNote;               
        A3DMiscEntityReference**     m_ppReferenceEntities;
        A3DUns32                     m_uiReferenceEntitiesSize;
        A3DELayerDisplayStatus       m_eDisplayStatus;
   } A3DAsmLayerData;

Field :cpp:member:`~A3DAsmLayerData::m_uiLayerID` is the layer ID coming from the source internal format (e.g. Creo layer ID).

Field :cpp:member:`~A3DAsmLayerData::m_pcNote` is a null-terminated UTF-8 string which may add some description to this layer.

The field :cpp:member:`~A3DAsmLayerData::m_ppReferenceEntities` is an array of links to entities referenced by this layer (if the layer explicitly knows them).
Its size is :cpp:member:`~A3DAsmLayerData::m_uiReferenceEntitiesSize`.

Each link directly references a geometric entity or construction geometry participating in a feature element.

.. important:: 

   An empty array doesn't necessary mean that this layer is empty.
   In this case, you need to check the layerIndex field of an entity to know if it's referenced by a layer.

The :cpp:member:`~A3DAsmLayerData::m_eDisplayStatus` field is an enumerator specifying its display status:

  * `kA3DLayerDisplayShow` layer is shown
  * `kA3DLayerDisplayHide` layer is hidden
  * `kA3DLayerDisplayIsolate` layer is isolated
  * `kA3DLayerDisplayUnknown` layer display status is unknown

`kA3DLayerDisplayIsolate` status means that only this layer is visible.

Getting Layer List
==================

Throughout the HOOPS Exchange API, a layer list can be obtained from any instance of :struct:`A3DAsmProductOccurrenceData` containing layers:

.. code-block:: c

   A3DVoid ReadLayers(const A3DAsmProductOccurrenceData* pPO)
   {
      for(A3DUns32 ui = 0 ; ui < pPO->m_uiLayersSize ; ++ui)
      {
         A3DAsmLayerData sData = A3D_MAKE_DATA(A3DAsmLayerData);
         A3DAsmLayerGet(pPO->m_ppLayers[ui], &sData);

         // sData ready
		 // ...
		 
		 // Free allocated memory
		 A3DAsmLayerGet(A3D_NULL_HANDLE, &sData);
      }
   }
