.. _group__a3d__entity__reference:

################
Entity Reference
################

Creates and accesses references to other PRC entities. 


   2.0



Entity type is :c:enumerator:`~kA3DTypeMiscEntityReference`\ .

An :c:type:`~A3DMiscEntityReference` references an entity containing structure data, representation items, topology data, markup data or scene display data. All of these entities can be referenced from other entities. For example, the :c:type:`~A3DAsmProductOccurrence` entity (:ref:`Product Occurrence <group__a3d__productoccurrence>`\ ) can include an :c:type:`~A3DMiscEntityReference` entity that references another product occurrence. In another example, an :c:type:`~A3DAsmFilter` entity (:ref:`Filter Module <group__a3d__filter>`\ ) can include an entity filter for which multiple :c:type:`~A3DMiscEntityReference` entities specify the entities to be inclusively or exclusively filtered.

The :c:type:`~A3DMiscEntityReference` can supply modifiers that affect the referenced entity nominal definition. All entity references can include a coordinate system, which is applied to the referenced item. Topology entity references can also include global index items, such as color and texture.

To create references for non-topological entities listed in :ref:`Referenceable Non-Topological Entities <group__a3d__eligibleforreference>`\ , perform these steps: 


1. Create an :c:struct:`~A3DMiscEntityReferenceData` structure that references the non-topological entity. 
2. Set the coordinate system transformation in the :c:struct:`~A3DMiscEntityReferenceData` structure as needed.  
3. Create an :c:type:`~A3DMiscEntityReference` that references the :c:struct:`~A3DMiscEntityReferenceData` structure. 

To create references for topological entities listed in :ref:`Referenceable Topological Entities <group__a3d__eligiblefortopologicalreference>`\ , perform these steps: 


1. Create an :c:struct:`~A3DMiscReferenceOnTopologyData` structure that references the topological entity. 
2. Set global index items in the :c:struct:`~A3DMiscReferenceOnTopologyData` structure as needed.  
3. Create an :c:type:`~A3DMiscReferenceOnTopology` entity, providing the :c:struct:`~A3DMiscReferenceOnTopologyData` structure. 
4. Create an :c:struct:`~A3DMiscEntityReferenceData` structure that references the :c:type:`~A3DMiscReferenceOnTopology` entity. 
5. Set the coordinate system transformation in the :c:struct:`~A3DMiscEntityReferenceData` structure as needed.  
6. Create an :c:type:`~A3DMiscEntityReference` that references the :c:struct:`~A3DMiscEntityReferenceData` structure. 

See the referenceable types in the modules :ref:`Referenceable Non-Topological Entities <group__a3d__eligibleforreference>` and :ref:`Referenceable Topological Entities <group__a3d__eligiblefortopologicalreference>`\ . 

**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:`Reference on Topology/Tessellation <group__a3d__reference__on__topo>`
* :ref:`Referenceable Non-Topological Entities <group__a3d__eligibleforreference>`
* :ref:`Referenceable Topological Entities <group__a3d__eligiblefortopologicalreference>`
* :ref:`Reference on coordinate system subcomponent <group__a3d__reference__on__csys__sub__cmpnt>`

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

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


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


* :c:struct:`~A3DMiscEntityReferenceData`

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

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


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


* :c:func:`~A3DMiscEntityReferenceGet`
* :c:func:`~A3DMiscEntityReferenceCreate`
* :c:func:`~A3DMiscEntityReferenceSet`

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

   a3d_reference_on_topo
   a3d_eligibleforreference
   a3d_eligiblefortopologicalreference
   a3d_reference_on_csys_sub_cmpnt
   ../structures/A3DMiscEntityReferenceData
   ../functions/A3DMiscEntityReferenceGet
   ../functions/A3DMiscEntityReferenceCreate
   ../functions/A3DMiscEntityReferenceSet


