#############################
Controlling Material Batching
#############################

This is an advanced topic in HOOPS Luminate. Before starting plying with the methods for batch control, please make sure that you're familiar with all the :doc:`/book/subjects/bk_ap/bk_ap_hardware_display_performances` stuff.

HOOPS Luminate uses hardware batching to reduce the number of OpenGL state changes that occur during a draw. This increases performances a lot. That's why shapes that contain small objects are internally aggregated together into larger batches that can then be rendered as a whole, using less rendering calls, for a better performances. The calling application does not see this processing.

Then, if the application just modifies a small shape that contain let's say a dozen of vertices, HOOPS Luminate will make sure that only that portion of a dozen vertices will be updated in the GPU video memory for the batch in which the shape is stored. This is detailed further in the doc :doc:`/book/subjects/bk_ap/bk_ap_modifying_engine_data`.

But, if we have large meshes, or very large meshes, this system does not handle the partial edition of the meshes contents. Sometimes in a large mesh that represents a lot of application primitives at once (this arise often in the 2D world, or for simulation streaming needs) we need to just update a small part of the mesh. The process is similar to the one described above, except that we only have one shape and that we're updating only a sub section of that shape data.

HOOPS Luminate delivers an API to handle these low level updates. This is the material batching API, accessible directly from the ``RED::IMaterial`` interface.


Sub Array Update in a Batch
===========================

The ``RED::IMaterial::AddBatchArrays`` is used to define what's called "batched arrays" in HOOPS Luminate. These batched arrays are uniquely instanced, and are meant to be used with a ``RED::IMeshShape::SetSharedArrays`` call. Once declared, partial updates of these arrays can be declared using ``RED::IMaterial::AddBatchSubArrayUpdate``.

The same mechanism can be used for a sub update of indices: ``RED::IMaterial::AddBatchIndices`` plus ``RED::IMaterial::AddBatchSubArrayUpdate``.
