# Candera V3.1.0

Release Date: July 23, 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\_0.

# Candera Engine 3D

#### Occlusion Culling

This new feature allows to disable rendering of the objects when they are not currently seen by the camera because they are obscured by other objects. Occlusion culling becomes enabled when the render strategy for camera is set to [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..."). During the rendering, all nodes initialized by the strategy will issue occlusion queries. If query results are available from the previous frame, they are evaluated and all nodes deemed occluded will have their bounding box rendered invisibly instead of the node itself. Visible nodes, or nodes not having a QueryProperty attached, will be rendered as usual. A new query to determine visibility for the next frame will be issued regardless the result of the previous query.

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

</div></div></div>#### Drawcall Batching by implicit Geometry Instancing

On OpenGL ES3.0 platforms, Candera's renderer automatically batches draw calls of nodes where possible, and issues a single instanced draw call per batch (Geometry Instancing) instead of submitting an individual draw call per node.

To trigger draw call batching, the following prerequisites must be met:

<div class="contents" id="bkmrk-an-instance-able-sha"><div class="contents"><div class="textblock">- an instance-able shader must be used, and the corresponding [Candera::Shader](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_shader.html "The class Shader is an Appearance component representing a graphical processing unit (GPU) program...") object must have its maximum instance count set accordingly.
- nodes must share the vertex buffer, shader, textures, and render mode
- nodes must not use multi-pass appearances
- nodes must not use object-space lighting

</div></div></div>If prerequisites are not met, nodes will be rendered individually.

In order to achieve good batching rates, nodes should be sorted by shader, or grouped together using a separate camera to guarantee sequenced submission to the renderer.

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

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

[Renderer::GetStatistics()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#aba9718ac603dcf728e3082221e31a810) provides information on how many draw calls, instanced draw calls, instances, vertices, indices, uniforms and SetUniform() calls were submitted to the RenderDevice in the process of executing [Renderer::RenderCamera()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#a10dbe66b15c60f44cce3aaccd38d2ee5) or [Renderer::RenderAllCameras()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#aed822ba1d66620f2d1e794973e30f354).

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

</div></div></div>#### CameraRenderStrategy enhanced

[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...") has been enhanced with a new choice "SkipNode" for [CameraRenderStrategy::RenderPassAction](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera_render_strategy.html#a4eb1d70fe3fcbb2f0a6283346ab95662). The interface has been enhanced with [CameraRenderStrategy::SetRenderPassCompleted()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera_render_strategy.html#ac22d46f3c3b622f9fa2c1dc1587cc1e1) and [CameraRenderStrategy::Render()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera_render_strategy.html#a05ddc6a449c932537b89354fb5afd16a).

---

# Candera Engine 2D

#### Animation Property Setter for SnapToDevicePixel

A new animation property setter has been added to animate the "SnapToDevicePixel" property.

<div class="contents" id="bkmrk-see-also%3A-animation%3A"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Animation::SnapToDevicePixelEnabled2DPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_snap_to_device_pixel_enabled2_d_property_setter.html "A PropertySetter that sets the "SnapToDevicePixel" property of a Node2D.")</dd></dl></div></div>---

# Candera System

#### Localization

Interface for Internal::LocalizableStringData and Internal::ParameterizedLocalizableStringData has been changed.

Overloaded placement operators *new* and *delete* have been replaced by Internal::LocalizableStringData::Create and Internal::ParameterizedLocalizableStringData::Create methods.

These were introduced to better handle the allocation and creation of new instances. As the default placement *new* operator is used within the implementation of Create methods, the matching operator *delete(void\* pMem, void\*)* had to be added also.

---

# Candera Device

#### DirectTextureImage External Buffers and New Formats

DirectTextureImage now supports application defined buffers to be provided for the texture data, as well as additionally supporting the 32 bit unpacked formats RGBA and BGRA.

This functionality can be used by setting the logical and/or physical address properties of DirectTextureImage using DirectTextureImage::SetLogicalAddress and DirectTextureImage::SetPhysicalAddress. The default behaviour of DirectTextureImage, where the buffers are allocated by the driver, is used if these properties are set to the default values. The addresses should be provided as a pointer array of four pointers in the case of logical addresses. Depending on the format, one or more pointers to provided buffers should be set and unused pointers in the array set to 0. In the case of physical addresses, these should be provided as an array of unsigned integers, where unused addresses are set to ~0U.

An additional function [DirectTextureImage::Invalidate()](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#ggaf0e93dc4242f607c3c8d13dafd036af9a7e58b417e215e88881554ef892d19906) has been added to the DirectTextureImage which should be called if the data in the provided buffers was modified.

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

</div></div></div>#### OpenGlEs20 Device Package

[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") OpenGlEs20 Device Package has been added.

This is a generic device which supports 2Dover3D and takes device specific / native configuration from a Device Configuration Factory. Main purpose is quick setup of new OpenGL ES based platforms for evaluation or benchmarking.

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

</div></div></div>#### Render API String in 3D Capabilities

DevicePackageDescriptor::RenderDevice3DCapabilities has been enhanced by a string indicating the render API, e.g. "OpenGL ES 3.0".

---

# Candera AssetLoader

#### Maximum Bitmap Glyph Size

[AssetDescriptor](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_descriptor.html "Descriptor of the loaded asset.") provides a new interface for obtaining the maximum size of the glyphs of all the fonts in the asset. The maximum size can be used to optimally initialize the decompression buffer of the TextEngine.

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

</div></div></div>#### Initial Value of BitmapImage2D MemoryPool

AssetLoader automatically assigns the value BitmapImage2D::MemoryPool::FlashMemory during reading [BitmapImage2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html "Supplies an Image2D interface to a Bitmap.") instances from asset if the asset repository is directly addressable (e.g. in Flash).

<div class="contents" id="bkmrk-see-also%3A-bitmapimag"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[BitmapImage2D::SetMemoryPool()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html#add4cad3cf3c032375a7785481721123f)</dd></dl></div></div>---

# Candera Globalization

#### Custom Localizer Support

CMake feature switch CANDERA\_CUSTOM\_LOCALIZER\_ENABLED has been introduced to enable the use of a custom localizer. In case this flag is enabled (along with CANDERA\_GLOBALIZATION\_ENABLED), the DefaultLocalizer which loads LanguagePacks from assets will be disabled.

Furthermore the interface to set or get a Localizer in GlobalizationCultureManager class has been changed to SharedPointer instead of pointer.

Additional information on how to set up a custom localizer can be found here: <span style="color: rgb(230, 126, 35);">[Custom Localizer Support](https://doc316en.candera.eu/link/488#bkmrk-page-title)</span>

---

# TextEngine

#### Bitmap Font Sizes

[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...") fonts have now an interface to acquire information on available sizes.

<div class="contents" id="bkmrk-see-also%3A-textrender"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>TextRendering::BitmapFont::BmFont::GetEffectiveFontSize()</dd><dd>TextRendering::BitmapFont::BmFont::GetFontSizeCount()</dd><dd>TextRendering::BitmapFont::BmFont::GetPossibleFontSize()</dd></dl></div></div>---

# SCHost.dll

#### Source File Relocation

SCHost.dll source files **SCHost.h** and **dllmain.cpp** are no longer provided separately in *cgi\_studio\_courier* and *cgi\_studio\_dev*.  
Instead, these files are now located in *cgi\_studio\_schost/src/SCHost*.

---

# Migration Guide

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

<div class="contents" id="bkmrk-description-candera-"><div class="textblock"><table class="doxtable" style="width: 240.741%;"><tbody><tr><th style="width: 22.4969%;">**Description**</th><th style="width: 34.2245%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.0.4**</th><th style="width: 43.2785%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.0**</th></tr><tr><td style="width: 22.4969%;">Deprecated DynamicPropertyHost::BrowseableForDescendants, replaced with BrowsableForDescendants</td><td style="width: 34.2245%;">```
            DynamicPropertyHost::BrowseableForDescendants
```

</td><td style="width: 43.2785%;">```
            DynamicPropertyHost::BrowsableForDescendants
```

</td></tr><tr><td style="width: 22.4969%;">Getter for Localizer changed to SharedPointer</td><td style="width: 34.2245%;">```
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_globalization_culture_manager.html#a6e17a180e7192514132f4ff8220b40f9">Globalization::GlobalizationCultureManager::GetInstance</a>().SetLocalizer(&Globalization::Internal::DefaultLocalizer::GetInstance());
```

</td><td style="width: 43.2785%;">```
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_globalization_culture_manager.html#a6e17a180e7192514132f4ff8220b40f9">Globalization::GlobalizationCultureManager::GetInstance</a>().SetLocalizer(Globalization::Localizer::SharedPointer(&Globalization::Internal::DefaultLocalizer::GetInstance()));
```

</td></tr><tr><td style="width: 22.4969%;">Setter for Localizer changed to SharedPointer</td><td style="width: 34.2245%;">```
Localizer* localizer = GlobalizationCultureManager::GetInstance().GetLocalizer();
if (localizer != 0) {
...
```

</td><td style="width: 43.2785%;">```
Localizer::SharedPointer localizer = GlobalizationCultureManager::GetInstance().GetLocalizer();
if (!localizer.PointsToNull()) {
...
```

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

</div></div>---