# Candera Engine 3D

#### Shader Uniform Cache Handles

If a shader uses more than a single uniform, a [Shader::UniformCacheHandle](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_shader_1_1_uniform_cache_handle.html) is the fastest way to access uniform locations. After a uniform cache accessor was registered in a shader with an array of uniforms to be accessed, the resulting uniform cache handle can be used to retrieve uniform locations in constant time. It does not matter if the uniform is an auto or a custom uniform. [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") uses this mechanism to get rid of uniform location related (string) compares.

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock">---

</div></div></div>#### Render Order Criterion

The [RenderOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html "The abstract class RenderOrderCriterion defines an interface to prepare the order criterion values (i...") class extends the [OrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_order_criterion.html "Abstract class OrderCriterion defines an interface that compares two Nodes according to a specific so...") class to enable the user to control preparation and sorting of render order bins. By default it is now used to skip sorting if the order of the bin has not changed since the last pass.

If an [OrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_order_criterion.html "Abstract class OrderCriterion defines an interface that compares two Nodes according to a specific so...") was assigned to the RenderOrderBin, everything is processed as usual. If a [RenderOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html "The abstract class RenderOrderCriterion defines an interface to prepare the order criterion values (i...") was assigned to the RenderOrderBin, RenderOrderBin::Sort calls [RenderOrderCriterion::PrepareRenderOrderCriterionValues](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html#a1ca15c7d53060d12c3d813f865c1fe3f), [RenderOrderCriterion::HasOrderChanged](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html#a32901dc1173db834fe70dc38554fb87e), and depending on the result of the previous function, [RenderOrderCriterion::Sort](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html#abb577bf04c4079c7aff1bfdc5aad9027).  
Using the new interface enables the user to have more control over how sorting is performed, and if sorting needs to be performed at all.

Candera's [DistanceToCameraOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_distance_to_camera_order_criterion.html "class DistanceToCameraOrderCriterion compares two Node's distances to the camera. A render order bin ..."), [ReverseDistanceToCameraOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_reverse_distance_to_camera_order_criterion.html "class ReverseDistanceToCameraOrderCriterion compares two Node's distances to the camera. A render order bin using ReverseDistanceToCameraOrderCriterion can sort its Nodes from "Back to Front" according to selected distance function. ("), [RankOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_rank_order_criterion.html "class RankOrderCriterion compares two Node's render order ranks, whereas lower render order rank is b..."), as well as [RenderStateOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_state_order_criterion.html) have all been changed to use the new [RenderOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html "The abstract class RenderOrderCriterion defines an interface to prepare the order criterion values (i...") interface.

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock">---

</div></div></div>#### Batch Order Criterion

The [BatchOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_batch_order_criterion.html "class BatchOrderCriterion produces a render order that contains batches of nodes with equal propertie...") is a [RenderOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html "The abstract class RenderOrderCriterion defines an interface to prepare the order criterion values (i...") implementation that sorts bins by either VertexBuffer+Shader+RenderMode+Distance to camera, or by VertexBuffer+Appearance+Distance to camera to increase drawcall batching (i.e. implicit geometry instancing) rates. It also takes advantage of the new [RenderOrderCriterion](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order_criterion.html "The abstract class RenderOrderCriterion defines an interface to prepare the order criterion values (i...") feature to only sort bins when the order has changed.

<div class="contents" id="bkmrk--1"><div class="contents"><div class="textblock">---

</div></div></div>#### Extended Geometry Instancing Support

Classes derived from [CameraRenderStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera_render_strategy.html "The abstract class CameraRenderStrategy is intended to be derived in order to tell the Renderer...") can now utilize implicit geometry instancing (i.e. drawcall batching) by passing a flag to its base class. The [BreakNodeCameraRenderStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_break_node_camera_render_strategy.html "The BreakNodeCameraRenderStrategy is an implementation of the abstract class CameraRenderStrategy. The rendering of the nodes is done until it reaches a node that is in the list of break nodes (See function AddBreakNode).") has been updated to use it by default.

The [PointSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html "PointSprite represents a GL point primitive. The size (glPointSize) of the point is calculated by def...") class is now recognized as being batchable, i.e. point sprites will automatically be picked up by drawcall batching (geometry instancing) if possible.

<div class="contents" id="bkmrk--2"><div class="contents"><div class="textblock">---

</div></div></div>#### Render Order Usage Change

The render order was previously associated with the [Scene](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_scene.html "The class Scene represents a top level scene graph node. Multiple Scenes are allowed. A Scene can not be part of any other Scene. To render a Scene, at least one Camera must be part of this Scene and the Camera must have rendering enabled. A Scene can have more than one Camera. Note: Lights added to a Scene apply for that Scene only and do not affect 3D objects in any other Scene."). With this version it has been moved to the [Camera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera.html "A Camera provides Modelview and Projection matrices. Camera is a Transformable.* The eye point is set..."). Every camera requires its own render order now. This was done to be able to skip sorting of previously sorted render order bins.

The following functions were declared deprecated:

```
    void Scene::SetRenderOrder(AbstractRenderOrder* renderOrder);
    AbstractRenderOrder* Scene::GetRenderOrder();
    const AbstractRenderOrder* Scene::GetRenderOrder() const;
```

<div class="contents" id="bkmrk--3"><div class="contents"><div class="textblock"><div class="fragment">  
</div>---

</div></div></div>#### PointSprite Interface and Behavior Changes

Point sprites share a single vertex buffer now, unless a custom vertex buffer is set for an instance of a point sprite by the user. Therefore [PointSprite::GetVertexBuffer()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html#a7fbaf650d1c5962126f89b56d212cbe3) returns a const pointer in order to avoid alteration of the shared vertex buffer. The color of a point sprite is now determined by the diffuse color of the material to establish consistent usage of the auto uniform that was used by the point sprite shader. [GenericShaderParamSetter::SetPointSpriteActivationEnabled()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#a4d750620676762a10934f6d3643fef18) must be set to true, when using it with a [PointSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html "PointSprite represents a GL point primitive. The size (glPointSize) of the point is calculated by def...").

The following functions were deprecated:

```
    void PointSprite::SetColor(const <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behaviors_control.html#ggae7abc816df647d0ecbc280480fefb788a6d1d4da086e381cb2c5a5ce6a2513ebd">Color</a>& color);
    const <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behaviors_control.html#ggae7abc816df647d0ecbc280480fefb788a6d1d4da086e381cb2c5a5ce6a2513ebd">Color</a>& PointSprite::GetColor() const;
```

<div class="contents" id="bkmrk--4"><div class="contents"><div class="textblock"><div class="fragment">  
</div>---

</div></div></div>#### MorphingMesh Changes

Just like the [PointSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html "PointSprite represents a GL point primitive. The size (glPointSize) of the point is calculated by def..."), the [MorphingMesh](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_morphing_mesh.html "MorphingMesh is a Mesh that stores weight values for morphing, and activates them as uniforms at rend...") was changed to establish consistent usage of its auto uniform. Therefore [GenericShaderParamSetter::SetMorphingMeshActivationEnabled()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#ad9c026d2cf45f51a7ce74b0a7a4fcff6) must be set to true, when using it with a [MorphingMesh](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_morphing_mesh.html "MorphingMesh is a Mesh that stores weight values for morphing, and activates them as uniforms at rend...").

<div class="contents" id="bkmrk--5"><div class="contents"><div class="textblock">---

</div></div></div>#### GenericShaderParamSetter Changes

The [GenericShaderParamSetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html "GenericShaderParamSetter bundles uniform shader parameters that are calculated by Candera...") now handles the auto uniforms of the [PointSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html "PointSprite represents a GL point primitive. The size (glPointSize) of the point is calculated by def...") and the [MorphingMesh](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_morphing_mesh.html "MorphingMesh is a Mesh that stores weight values for morphing, and activates them as uniforms at rend...").

The following functions were added, and must be used in conjunction with point sprites and morphing meshes:

```
    bool <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#a2104b2ebd267cef812cb9d34cc419c69">GenericShaderParamSetter::IsMorphingMeshActivationEnabled</a>() const;
    void <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#ad9c026d2cf45f51a7ce74b0a7a4fcff6">GenericShaderParamSetter::SetMorphingMeshActivationEnabled</a>(bool enableMorphingMeshActivation);
    bool <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#aefd2c0fb2f2fdbc53e63ec850787d927">GenericShaderParamSetter::IsPointSpriteActivationEnabled</a>() const;
    void <a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_generic_shader_param_setter.html#a4d750620676762a10934f6d3643fef18">GenericShaderParamSetter::SetPointSpriteActivationEnabled</a>(bool enablePointSpriteActivation);
```

<div class="contents" id="bkmrk--6"><div class="contents"><div class="textblock"><div class="fragment">  
</div>---

</div></div></div>#### Renderer Statistics Improvements

[Renderer::Statistics](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer_1_1_statistics.html) now also exposes the total number of queries and occlusion query results for the last render pass.

<div class="contents" id="bkmrk--7"><div class="contents"><div class="textblock">---

</div></div></div>#### Generation of index buffers update.

[Math3D::CreateVertexBufferWithIndexGenerated](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math3_d.html#aab1ad47fa732605f9f06fececc1463bd) is now extended with an argument specifying the minimum size of one index (8, 16 or 32 bit).

---