# CGI Studio 3.1.1

# Candera V3.1.1

Release Date: November 3, 2015  
  
To keep backwards compatibility for any interface change in the public API the old interface has been kept and marked as deprecated. The deprecated interfaces will be removed in future versions. Compiler warnings will be generated when using a deprecated interface through the usage of Candera Macro CANDERA\_DEPRECATED\_3\_1\_1.

# 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).

---

# Candera Engine 2D

#### TextNode2D and TextNode2DLayouter

[TextNode2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d.html "TextNode2D is a RenderNode that renders text using the attached BitmapBrush effect.") is a [RenderNode](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_node.html "RenderNode is a 2D node that links to an effect chain. Therefore this is the only type of 2D node whi...") specialized for text rendering. A [TextNode2DLayouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d_layouter.html "Base Layouter for TextNode2D nodes.") needs to be attached to the node for text layout. The DefaultTextNode2DLayouter implements horizontal or vertical truncation for correct text layout inside given or computed area. [TextNode2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d.html "TextNode2D is a RenderNode that renders text using the attached BitmapBrush effect.") requires a [BitmapBrush](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_brush.html "Output an image. The image is transformed to the space of the current node, but no pixel transformati...") effect for text rendering and one [TextNodeRenderer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node_renderer.html "Base class for text to Image2D generation strategies.") object for generating correct images to be rendered. Four [TextNodeRenderer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node_renderer.html "Base class for text to Image2D generation strategies.") implementations are available in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"), each corresponding to one CacheType option in the existing [TextBrush](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_brush.html "Output alpha only glyph data. A color may be specified, which is applied to the color channels...") rendering concept.

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

</div></div></div>#### SkipNode functionality to Camera2DRenderStrategy

SkipNode action was added to [Camera2DRenderStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera2_d_render_strategy.html "The abstract class Camera2DRenderStrategy is intended to be derived in order to tell the Renderer2D...") to tell the [Renderer2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d.html "The class Renderer2D represents the unique Candera 2D render interface to the application. Each render call shall be triggered via the Renderer2D interface.") to proceed with rendering, but skip current node.

---

# Candera Base

#### TextureImage to Image2D Adaptor

An adaptor class TextureImageToImage2DAdaptor was added to enable using a [TextureImage](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_texture_image.html "Abstract base class for Texture images.A texture image mainly encapsulates a texture handle in VRAM a...") (3D only) as an [Image2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_image2_d.html "Image2D encapsulates a surface handle which is retrieved when uploading an image."). The TextureImageToImage2DAdaptor class implements [Image2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_image2_d.html "Image2D encapsulates a surface handle which is retrieved when uploading an image.") interfaces and can therefore be used directly with a corresponding effect.

This can for instance be used to make the DirectTextureImage functionality available in 2D scenes.

Example Usage:

```
TextureImageToImage2DAdaptor::SharedPointer image = <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___c_o_u_r_i_e_r___v_i_s_u_a_l_i_z_a_t_i_o_n.html#ggaf0e93dc4242f607c3c8d13dafd036af9aaabfa5309af24986d3111a092449f857">TextureImageToImage2DAdaptor::Create</a>();
image->SetTextureImage(texture, pixelFormat);
image->Upload();
```

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

</div></div></div>#### Default layout alignment change

The default value for horizontal and vertical layout alignment was modified from HCenter and VCenter to HStretch and VStretch.

---

# Candera Device

#### Shared Sampler Objects

On OpenGL ES 3.0 Platforms texture sampling parameters is decoupled from texture information using sampler objects. The benefit is that multiple textures may share the same sampling parameters and therefore a sampler object. A sampler object can be bound to a texture unit in a single draw call, eliminating the need to set all sampling parameters such as filter mode, wrap mode or anisotropy separately per frame.

In [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") the usage of sampler objects is implicit and hidden from the user. The RenderDevice will determine which textures can share a sampler object and will bind them accordingly. Sampler objects can be shared if the MinLod and MaxLod parameters are left at their default values, to utilize the full potential of sampler objects it is beneficial if the other sampler parameters MaxAnisotropy, WrapMode, MipMapFilter, MagnificationFilter and MinificationFilter are the same for as many textures as possible. The LodBias parameter has no effect on sampler objects as it is a texture parameter only.

A new value recorder id was added for CGI Studio Analyzer to track the number of sampler objects that are created: ValueRecId::SamplerObjectCount. The value represents the number of sampler objects created across all contexts.

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

</div></div></div>#### DirectTextureImage Alpha Format

The newest iMX6 drivers support setting an 8 bit alpha format on DirectTextureImage. The format FormatAlpha has been added.

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

</div></div></div>#### Added check for custom Bitmap Format

A check for custom bitmap format has been added to [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") class. The new function is used by [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") RenderDevice to check the bitmap format before Upload is attempted.

<div class="contents" id="bkmrk-see-also%3A-bitmap%3A%3Ais"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Bitmap::IsCustomPixelFormat](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html#a253f397539c2db04a4ddbb2f81222906)</dd></dl>---

</div></div></div>#### Bitmap size computation

As different platforms support different bitmap formats, the size of the pixel array for a bitmap, in VRAM, is platform dependent. To provide a more accurate value for this size the following modifications were made:

<div class="contents" id="bkmrk-new-renderdevice%3A%3Age"><div class="contents"><div class="textblock">- new RenderDevice::GetSize and RenderDevice2D::GetSize methods were added. This method receives a [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") parameter and returns the size of its pixel array in VRAM.

- new [BitmapImage2D::GetSize](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html#a9fc7ba644b8d15448549d3bf86319a82) method was added. This method returns the estimated value of the video memory used by the bitmap.

- the possibility to explicitly specify a size for a [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") within the constructor was preserved. However, the automatic computation of the size, if default value 0 is used with the constructor, was removed. Now, if default value 0 is used for the *size* parameter in constructor, [Bitmap::GetSize](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html#a06c7059065362c807cf48a52279e90fc) method returns 0. If a value is set for *size* parameter, the [Bitmap::GetSize](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html#a06c7059065362c807cf48a52279e90fc) method returns this value.

---

</div></div></div>#### New draw methods for RenderTarget class

New RenderTarget::SafeBeginDraw, RenderTarget::SafeEndDraw and RenderTarget::GetActiveRenderTarget methods have been added.

SafeBeginDraw and SafeEndDraw are used to store the active render target during RenderTarget::BeginDraw / RenderTarget::EndDraw sequence. A pointer to the active RenderTarget is set on a SafeBeginDraw call and reset to 0 on a SafeEndDraw call.

The stored render target can be further retrieve using RenderTarget::GetActiveRenderTarget method.

As the current active render target is further used in the internal implementation of [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"), it is recommended to change calls of BeginDraw and EndDraw to calls of SafeBeginDraw and SafeEndDraw.

---

# Migration Guide

Following an overview about interface changes between [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.0 and [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.1.

<div class="contents" id="bkmrk-description-candera-"><div class="textblock"><table class="doxtable" style="width: 100%;"><tbody><tr><th style="width: 44.7477%;">**Description**</th><th style="width: 29.9124%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.0**</th><th style="width: 25.3399%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.1**

</th></tr><tr><td style="width: 44.7477%;">Render Device deprecated texture parameter functions are replaced with a single function.</td><td style="width: 29.9124%;">RenderDevice::SetTextureLodMode  
RenderDevice::SetTextureFilter  
RenderDevice::SetTextureWrapMode</td><td style="width: 25.3399%;">RenderDevice::ActivateTexture

</td></tr><tr><td style="width: 44.7477%;">[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.") deprecated funtions are replaced with [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...") functions (Note: Every [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...") requires its own RenderOrder!)</td><td style="width: 29.9124%;">Scene::SetRenderOrder  
Scene::GetRenderOrder</td><td style="width: 25.3399%;">[Camera::SetRenderOrder](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera.html#ac04b157f871bc3c6d5874549e3f88057)  
[Camera::GetRenderOrder](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera.html#a9c87d86273969e6debc6347eba4425bf)

</td></tr><tr><td style="width: 44.7477%;">[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...") deprecated functions are replaced by using the corresponding functions of the PointSprite's [Material](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_material.html "The class Material describes the color attributes of an object's surface and is primarily used for li...")</td><td style="width: 29.9124%;">PointSprite::SetColor  
PointSprite::GetColor</td><td style="width: 25.3399%;">[Material::SetDiffuse](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_material.html#ac34c9a69521f4c7679b023d94fb800bc)  
[Material::GetDiffuse](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_material.html#a2738be952a792729e68b636d8ef292fe)

</td></tr><tr><td style="width: 44.7477%;">PointSprites share a single [VertexBuffer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vertex_buffer.html "The VertexBuffer encapsulates the attributes of an uploaded VertexGeometry. It holds the actual handl...") by default to facilitate drawcall batching. Custom VertexBuffers can still be set, but getting the [VertexBuffer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vertex_buffer.html "The VertexBuffer encapsulates the attributes of an uploaded VertexGeometry. It holds the actual handl...") returns a const pointer now.</td><td style="width: 29.9124%;">VertexBuffer\* [PointSprite::GetVertexBuffer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html#a7fbaf650d1c5962126f89b56d212cbe3)</td><td style="width: 25.3399%;">const VertexBuffer\* [PointSprite::GetVertexBuffer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_point_sprite.html#a7fbaf650d1c5962126f89b56d212cbe3)

</td></tr></tbody></table>

</div></div>---

# Courier V3.1.1

<span style="color:rgb(34,34,34);font-size:1.666em;font-weight:400;">3.1.1-1 New interface for handling the scope mask of Courier::Messages</span>

A fix was made for the scope mask feature of Courier::Messages to distinguish between the original scope mask of the view and the effective mask of the view, which takes into account the scope mask of its children.

With the fix, the interface of [Courier::View](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view.html) class has been modified in the following way:

<div class="contents" id="bkmrk-courier%3A%3Aview%3A%3Aoncha"><div class="contents"><div class="textblock">- Courier::View::OnChangeScopeMask was made deprecated;

- New method [Courier::View::SetScopeMask](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view.html#a767a6178726c21a0cf406c9f8bb6e04c) was added; this can be used to set the actual scope mask of the view;

- New method [Courier::View::GetEffectiveScopeMask](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view.html#a661d8436c828dde77e1858817ef5cb37) was added; this can be used to retrieve the effective scope mask of the view. The effective scope mask of the view is composed internally, from the actual scope mask and the scope mask of the children of the view;

- New method [Courier::View::OnScopeMaskChanged](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view.html#a4e4a8ce6f87eabe1dbc5f7245f6722d3 "Creates the effective scope mask of the view, by applying a logical OR on the actual scope mask of th...") was added. This is called every time the effective scope mask of the view or its actual scope mask gets changed.

</div></div></div>Interface of [Courier::FrameworkWidget](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_framework_widget.html) has also been changed:

<div class="contents" id="bkmrk-new-method-courier%3A%3A"><div class="textblock">- new method [Courier::FrameworkWidget::OnScopeMaskChanged](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_framework_widget.html#ac213bb6b25bf48a6ba0c13ef207baa6c "Notifies the parent view of changes in the scope mask.") was added also. This must be called every time the scope mask of the widgets changes ( i.e. on a CustomWidget::SetScopeMask method).

</div></div>---

# FeatStd V3.1.1

# FeatStd CMake Switches

#### New CMake switch to enable / disable glGetError and eglGetError calls

A new CMake switch, FEATSTD\_GLERRORS\_AND\_EGLERRORS\_ENABLED, has been added. This enables calls to glGetError and eglGetError functions in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"). By default this is set to OFF for Release builds and to ON for other builds.

---

# SceneComposer V3.1.1

# Candera Related Features

#### Display Renderer Statistics

The Renderer Statistics structure keeps track of per pass data that is relevant to the User. This includes statistics about the metrics of:

<div class="contents" id="bkmrk-draw-calls-uniform-c"><div class="contents"><div class="textblock">- Draw Calls
- Uniform Calls
- Vertices
- Indices
- Batched Draw Calls
- Occlusion Queries (available on OpenGL ES 3.0 API only)
- Visible Draw Calls (available on OpenGL ES 3.0 API only)
- Invisible Draw Calls (available on OpenGL ES 3.0 API only)

</div></div></div>This information is presented to the user in a dedicated panel which can be made visible through the "Render Statistic" menu item from the "View" menu. The panel will be displayed by default in the top right region of the SceneComposer user interface. This panel can be moved in any other area, also (Mantis 6037).

<div class="contents" id="bkmrk-see-also%3A-display-re"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Display Renderer Statistics](https://doc316en.candera.eu/link/7#bkmrk-page-title)</span> in SceneComposer User Manual
- [Candera::Renderer](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html "The class Renderer represents the unique Candera render interface to the application. Each render call an base of Candera shall be triggered via the Renderer interface.")

</dd></dl>---

</div></div></div>#### Candera Feature Geometry Instancing

With Geometry Instancing Meshes having the same appearance can be rendered with one draw call.

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock"><dl class="note"></dl>  
</div></div></div><p class="callout info">This feature has no visual effect, but it can be observed through Render Statistics.</p>

**See also:**

<div class="contents" id="bkmrk-display-renderer-sta-0"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[Display Renderer Statistics](https://doc316en.candera.eu/link/7#bkmrk-page-title)</span> in SceneComposer User Manual
- <span style="color: rgb(230, 126, 35);">[Drawcall Batching by implicit Geometry Instancing](https://doc316en.candera.eu/link/919#bkmrk-drawcall-batching-by)</span> in SceneComposer User Manual

---

</div></div></div>#### Support for BatchOrderCriterion

A new sorting criterion was introduced for render order bins: BatchOrderCriterion (Mantis 6030). BatchOrderCriterion produces a render order containing series of nodes that can then be batched by the Renderer to maximize usage of Geometry Instancing. BatchOrderCriterion has 2 modes of operation:

<div class="contents" id="bkmrk-sortbyshaderandrende"><div class="contents"><div class="textblock">- SortbyShaderandRenderMode
- SortbyAppearance

<dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Configure a New Render Order Bin](https://doc316en.candera.eu/link/132#bkmrk-configure-a-new-rend)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Occlusion Culling

A new camera render strategy was introduced: OcclusionCulling. When OcclusionCulling render strategy is selected, a new property becomes available in property grid: QueryType.

Default value of QueryType (in case of occlusion culling render strategy) was changed to AnySamplePassedConservative. "Occlusion Culling" Render Strategy option is no longer available on platforms with OpenGL ES API different than 3.0 (Mantis 6059).

<div class="contents" id="bkmrk-see-also%3A-occlusion-"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Occlusion Culling](https://doc316en.candera.eu/link/130#bkmrk-%C2%A0occlusion-culling-0)</span> in SceneComposer User Manual
- <span style="color: rgb(230, 126, 35);">[Candera Engine 3D](https://doc316en.candera.eu/link/919#bkmrk-page-title)</span> in SceneComposer User Manual
- [Candera::OcclusionCullingCameraRenderStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_occlusion_culling_camera_render_strategy.html "The class OcclusionCullingCameraRenderStrategy is an implementation of the abstract class CameraRende...")

</dd></dl>---

</div></div></div>#### Integrate Candera TextNode

For this version we provide a basic implementation: TextNode will be integrated as a new node type, and not as a replacement (full migrations - solution conversions - will not be possible).

**Manipulation &amp; rendering**

SceneComposer will provide a new 2D node type: TextNode2D. Properties of the new objects:

<div class="contents" id="bkmrk-%22text%22---specifies-t"><div class="contents"><div class="textblock">- "Text" - specifies the text to be rendered
- "Style" - specifies the style to be used for rendering
- "Renderer" - specifies the renderer used by the text node
- "Text Laying Out Enabled" - enable additional laying out properties

</div></div></div>The TextNode2D will be associated with a BitmapBrushColorBlend effect. The TextNode element in the "Toolbox" panel will create a TextNode2D object having a BitmapBrushColorBlend effect when it will be dragged into the "Scene Editor". Relationship with Translator plugin: the Text property can be edited by Translator plugin.

**Photoshop export**

Photoshop exporter will export the text layers as TextNode2D objects. TextNode2D objects having BitmapBrushColorBlend effects will be exported instead of RenderNode2D having TextBrushBlend effects. Instead of setting BoundingRectangle property, Size (laying out property) shall be set on TextNode.

Point text is converted to paragraph text upon export. This ensures the bounding rectangle is exported properly and the text has the same position as in Photoshop with pixel accuracy. Alignment support has also been discussed with [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") team, the text will be aligned properly regardless of "Text Laying Out" being enabled.

**Solution migration (conversion)**

SceneComposer does not offer a conversion from RenderNode2D to TextNode2D.

---

# SceneComposer Usability Improvements

#### Adapt SceneComposer to Extended GenericShaderParamSetter

IsPointSpriteActivationEnabled and IsMorphingMeshActivationEnabled flags were added in UniformSetter. When a uniform setter is dragged over a pointsprite or morphing mesh, the corresponding flag will be activated accordingly. Also, the new default solutions contain specialized uniform setters for morphing meshes and pointsprites which are assigned by default.

The uniforms setters on which auto activation is not enabled, from older solutions, must be updated by the user.

Color property of PointSprite object was removed. Instead, a material must be assigned to the PointSprite and the diffuse component will specify the desired color (Mantis 5896).

<div class="contents" id="bkmrk-see-also%3A-shader-par"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Shader Parameters](https://doc316en.candera.eu/link/146#bkmrk-shader-parameters%C2%A0)</span> in SceneComposer User Manual
- <span style="color: rgb(230, 126, 35);">[Generic ShaderParamSetter](https://doc316en.candera.eu/link/146#bkmrk-generic-shaderparams)</span> in SceneComposer User Manual
- <span style="color: rgb(230, 126, 35);">[Default Shader Configuration](https://doc316en.candera.eu/link/146#bkmrk-default-shader-confi)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Vertex Buffer 24 bit Index Export

VertexBuffers can now be converted to indexed buffers of various index sizes (8bit, 16bit or 32 bit index). BufferType configuration property (which had 2 options: ArrayBuffer and IndexBuffer) was removed. "Is Indexed" property was added. If enabled, the vertex buffer will be converted to an index array buffer, by selecting the optimal index size. Therefore, depending on vertex count, an 8bit, 16bit or 32bit index buffer will be created. BufferType property in AssetData section will specify the effective buffer type (Mantis 5408).

<div class="contents" id="bkmrk-see-also%3A-vertex-buf"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Vertex Buffer Editor](https://doc316en.candera.eu/link/136#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Context Menu inside "Generate Asset" View

Inside "Generate Asset Library" the options "Select, Expand All and Collapse All" are available for every item right clicked inside "Scene Tree" side of the view (Mantis 5958).

<div class="contents" id="bkmrk-see-also%3A-generate-a"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Generate Asset Library](https://doc316en.candera.eu/link/87#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Browsing through Tabs

A button was added at the end of the tab row. By using it, the user has the possibility to browse through all the tabs from this panel, even if they are not visible (Mantis 5320).

<div class="contents" id="bkmrk-see-also%3A-scenecompo"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- SceneComposer GUI in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Device Capability

"3D Render API" device capability info was added in "SCHost Information" dialog (Mantis 6215).

<div class="contents" id="bkmrk-see-also%3A-schost-inf"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[SCHost Information](https://doc316en.candera.eu/link/34#bkmrk-page-title)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### Minor Improvements

<div class="contents" id="bkmrk-adapt-bitmap-profile"><div class="textblock">- **Adapt Bitmap Profile** The name of RgbFloatingPoint9E5FPixelFormat was changed to RgbFloatingPoint9E5PixelFormat (Mantis 6057).
- **Default Size.** The deafult size of the text in TextNode is 14px instead of 0px as it was until now (Mantis 5961).
- **Drag-drop Multiselected Items.** The user is able to drag-drop multiselected elements from different folders into another one (Mantis 5611).
- **Switched Properties.** From now on the "Style" property is displayed under the "Text" property, in the Properties panel of a "TextNode" (Mantis 6144).
- **Default New Solution.** When a new solution is created on iMX6 platform, the default value for "Solution Template" should be "Base Solution OpenGLES 3.0" (Mantis 6106).
- **Deactivated Button.** The "Generate" button, from "Generate Asset Library" view, will be disabled if the path for the "Asset File" is invalid (Mantis 5904).

</div></div>---

# SceneComposer Known Issues

<div class="contents" id="bkmrk-render-statistics-ar"><div class="textblock">- Render Statistics are not reset when opening a new solution if there is no display or if nothing is rendered on it.

</div></div>---