.. _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


