#########
Instances
#########

The HOOPS Luminate scene graph supports instancing. An instance can be obtained that way:

.. include:: /tasks/ta_ca/ta_ca_scenegraph/tk_creating_an_instanced_shape.rst

Instances are key elements in many scene graphs as they're generally stored once in memory. However, there are exceptions to this general behavior, mainly for performance reasons, that are detailed here: :doc:`/book/subjects/bk_analyzingperf`.


**************************************
Identifying Instances in a Scene Graph
**************************************

One of the issues that arise with instances is that the address of a given shape object does not let you uniquely identify an instance of a shape. To be able to uniquely identify an instance of a shape, the full path from the root of the scene graph down to the instanced shape is needed. In the :doc:`/tasks/ta_ca/ta_ca_scenegraph/tk_creating_an_instanced_shape` task quoted above, the first instance is uniquely identified by path #ABD and the second one by path #ACD.

HOOPS Luminate uses the ``RED::ShapePath`` object to deal with instances. For instance, a picking operation done using ``RED::IWindow::FramePicking`` will return ``RED::ShapePath`` instances uniquely identifying all picked objects.


******************************
Instancing and Physical Lights
******************************

If an instanced mesh is used as a light emitter mesh using ``RED::IPhysicalLightShape::SetEmitter``, then as many lights as the number of instances of that mesh will be created. A physical light should not be instanced by itself as this will create redundant lights with duplicate positions, all using the same emitter mesh.

Therefore, the solution is to instance the mesh which is chosen once as a light emitter.


*****************
Instance Counters
*****************

It may be interesting for an application to identify instances at the time of the rendering. There's a HOOPS Luminate mechanism to pursue this objective: this is the "instance counter callback", that can be defined using ``RED::IViewpoint::SetInstanceCounterCallback``. A dedicated tutorial on this topic is available here: :doc:`/tutorials/workflows/wf_realtime/wf_using_instance_counters`.