# Candera V3.0.4

Release Date: June 08, 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\_0\_4.

# Candera Engine 3D

#### Texture Level of Detail Parameters

The [Texture](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_texture.html "Texture encapsulates a TextureImage and a set of attributes specifying how it is applied to a vertex'...") class now supports setting a level of detail bias (offset or base level) as well as a lower and upper limit for the level of detail value. These are new parameters available in OpenGL ES 3.0 or higher, which allow control over which mipmap levels are sampled. The parameters are set through the RenderDevice class.

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

</div></div></div>#### MSAA Offscreen Render Targets

Framebuffer objects now support setting the MsaaSamples property. If the device supports OpenGL ES 3.0 or higher, setting the property to anything larger than 1 will enable multisample anti-aliasing with the given number of samples for that framebuffer object.

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

</div></div></div>#### NPOT Textures

NPOT (Non-Power-Of-Two) Textures are supported with OpenGL ES 3.0 API.

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

</div></div></div>#### Vertex Geometry Modifier

[VertexGeometry](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vertex_geometry.html "The VertexGeometry holds all vertex data of a mesh. VertexGeometry may be used also for multiple Vert...") objects can be modified using the new class [VertexGeometryModifier](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vertex_geometry_modifier.html "In conjunction with a VertexAccessor, the VertexGeometryModifier helps to effectively modify VertexGe...") in conjuction with a [VertexAccessor](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vertex_accessor.html).

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

</div></div></div>#### Occlusion Culling Camera Render Strategy

On OpenGL ES 3.0 platforms this camera render strategy uses hardware occlusion culling to improve performance. It only reaches its full potential when objects have been sorted front to back and occluded objects consist of lots of vertices, have expensive shaders, or both.

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

</div></div></div>#### Render Order Performance Improvements

Nodes that are to be added to the default render order bins - Opaque and Transparent - are now added to these bins directly without expensive string comparisons in the Find function. The Find function was also modified to check the references of the default bin names before the string compares are done. Additionally a copy constructor was implemented for the RenderOrderBin class, allowing improvement of the copy constructor of [RenderOrder](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order.html "Defines the order(sequence) in which nodes are rendered. Collaborates with Renderer. Must cover functional correctness (translucent/transparent objects after opaque/solid objects) as well as optimization-related orderings (sorting by state, defining a background bin for rendering without depth checks). Nodes are assigned to bins; all nodes in an "earlier" bin are rendered before all nodes in a "later" bin. Two default bins are defined and must not be deleted. The opaque bin, which is sorted from front to back (DistanceToCameraOrderCriterion), and the transparent bin, which is sorted from back to front (ReverseDistanceToCameraOrderCriterion). If a Node has no specific assignment to a render order bin, it will be automatically assigned by Candera either to opaque or transparent bin, according to its RenderMode::IsAlphaBlendingEnabled setting.").

---

# Candera Engine 2D

#### Removed limitation of 256 layers for photoshop export/import

Return and parameters type for [Node2D::SetRenderOrderRank](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#a44f043fe18c7a3f946983e9dbdea1852), [Node2D::GetRenderOrderRank](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#a335694d84284ef00aa0f0f3079c389c3) and [Node2D::GetEffectiveRenderOrderRank](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#a6b23bd4be5a0d2c3f1ddac20cc86d830) have been changed from Int8 and Int16 to Int.

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

</div></div></div>#### LayoutingRectangle and BoundingBox calculation

LayoutingRectangle and BoundingBox are always computed from the first effect in the chain, if it is or contains a brush. If an effect is a combined effect it forwards the call to it's contained brush effect.

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

</div></div></div>#### Added Computation of Perspective Warped Bounding Rectangle

A method for computing perspective warped bounding rectangle has been added to [Math2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math2_d.html "The Math2D class for 2D transformation and helper functions.") class.

<div class="contents" id="bkmrk-see-also%3A-math2d%3A%3Age"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Math2D::GetSurfaceAlignedPerspectiveBoundingRectangle()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math2_d.html#ab420fa8b9b18313426cdec621e970b3a).</dd></dl></div></div>---

# Candera Base

#### Enums in DynamicProperties namespace renamed

The enumerations DynamicProperties::PropertyFlags::Enum and DynamicProperties::PropertyType::Enum were renamed to DynamicProperties::PropertyFlags and DynamicProperties::PropertyType. Additionally, the Generic PropertyType was renamed to GenericType.

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

</div></div></div>#### Added 9 OpenGL ES3.0 texture formats

The following OpenGL ES 3.0 formats have been added to [Candera::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...")

<div class="contents" id="bkmrk-bitmap%3A%3Apixelformat-"><div class="contents"><div class="textblock"><table class="doxtable" style="width: 100%;"><tbody><tr><td style="width: 33.2509%;">**[Bitmap::PixelFormat](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html#a0028006b9fd5b6e630bc6aca572603cb)**</td><td style="width: 13.1026%;">**Bits per pixel**</td><td style="width: 12.6065%;">**[Renderable](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderable.html "The class Renderable can serve as a base for nodes that can be recognized and rendered by the Rendere...")**</td><td style="width: 41.1636%;">**Description**</td></tr><tr><td style="width: 33.2509%;">EacCompressedUnsignedRPixelFormat</td><td style="width: 13.1026%;">4</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Compressed single channel unsigned alpha format</td></tr><tr><td style="width: 33.2509%;">EacCompressedSignedRPixelFormat</td><td style="width: 13.1026%;">4</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Compressed single channel signed alpha format (can preserve 0 exactly)</td></tr><tr><td style="width: 33.2509%;">EacCompressedUnsignedRGPixelFormat</td><td style="width: 13.1026%;">8</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Compressed two channel unsigned luminance alpha format</td></tr><tr><td style="width: 33.2509%;">EacCompressedSignedRGPixelFormat</td><td style="width: 13.1026%;">8</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Compressed two channel signed luminance alpha format (can preserve 0 exactly)</td></tr><tr><td style="width: 33.2509%;">SrgbUnsignedBytePixelFormat</td><td style="width: 13.1026%;">24</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">sRGB</td></tr><tr><td style="width: 33.2509%;">SrgbaUnsignedBytePixelFormat</td><td style="width: 13.1026%;">32</td><td style="width: 12.6065%;">X</td><td style="width: 41.1636%;">sRGBA</td></tr><tr><td style="width: 33.2509%;">RgbFloatingPointR11G11B10PixelFormat</td><td style="width: 13.1026%;">32</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Floating point format with 5 bit exponent and 5/6 bit mantissa</td></tr><tr><td style="width: 33.2509%;">RgbFloatingPoint9E5FPixelFormat</td><td style="width: 13.1026%;">32</td><td style="width: 12.6065%;">  
</td><td style="width: 41.1636%;">Floating point format with shared 5 bit exponent and 9 bit mantissa</td></tr><tr><td style="width: 33.2509%;">RgbaUnsignedIntRev10A2PixelFormat</td><td style="width: 13.1026%;">32</td><td style="width: 12.6065%;">X</td><td style="width: 41.1636%;">RGBA with 10 bit per rgb, 2 bit alpha</td></tr></tbody></table>

</div></div></div>*[Renderable](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderable.html "The class Renderable can serve as a base for nodes that can be recognized and rendered by the Rendere...")* means that the format can also be used as a render target.

Compressed single channel alpha formats deliver the best visual quality for transparency of all compressed formats using alpha. E.g., if the quality of transparency in a compressed texture is lacking, a combination of a compressed rgb texture together with a compressed single channel alpha texture should be favored over an uncompressed texture, since the 2 compressed textures still need less memory and bandwidth than an uncompressed one.

---

# Candera System

#### Dynamic\_Cast

Dynamic\_Cast that uses pointer type as typename replaces the DynamicCast function that uses the referenced type as typename.

---

# Candera Device

#### CLUT Bitmap Format

A new bitmap format, CLUT(color lookup table), has been added. This format offers compression by replacing the full RGB image with a palette having a limited number of entries and a color table which will contains references to the lookup index. In SceneComposer, the platform specific converter can be used to do the conversion of the bitmap into an indexed color format.

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

</div></div></div>#### Added support for native invalid values for EGL display, surface and context types

Previous versions of [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") Device Package do not allow null values for EGL display, surface and context types. To overcome this limitation, support for native invalid values for EGL display, surface and context types has been added.

For this, three preprocessor defines were added in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"):

<div class="contents" id="bkmrk-invalid_native_egl_c"><div class="contents"><div class="textblock">- INVALID\_NATIVE\_EGL\_CONTEXT
- INVALID\_NATIVE\_EGL\_DISPLAY
- INVALID\_NATIVE\_EGL\_WINDOW

</div></div></div>In order to add custom invalid values for EGL display, surface and context types, one must override this defines with the desired values. For this, a header file must be created which first undefines and then defines the desired invalid values for INVALID\_NATIVE\_EGL\_CONTEXT, INVALID\_NATIVE\_EGL\_DISPLAY and INVALID\_NATIVE\_EGL\_WINDOW. *EglInvalidValues.h* is the default header file used by [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") which can serve as a template for creating custom header files. In order to be take into account, this custom header file must be specified using the new CMake variable NATIVE\_EGL\_INVALID\_VALUES\_HEADER when the project is configured.

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

</div></div></div>#### 3DRendererAPI string

Candera::DevicePackageDescriptor::RenderDevice3DCapabilities structure has been extened with a string that specifies the 3D render engine API that it is used by the current or the target device.

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

</div></div></div>#### Context caching

When RenderStateCaching is enabled, native calls to context activation (e.g. eglMakeCurrent) have to be avoided, because they will unsynchronize the cache. Activation of contexts can still be done via activation of [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") objects like: RenderTarget, ContextResourcePool or GduContext.

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

</div></div></div>#### Perspective Viewport in 2D

The 2D Render Device has been enhanced to support setting a viewport used for perspective warping. This method can be used on platforms supporting such 2.5D effects.

<div class="contents" id="bkmrk-see-also%3A-renderdevi"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>RenderDevice2D::SetPerspectiveViewport()</dd></dl></div></div>---

# TextEngine

#### Added new event triggered before bliting each glyph bitmap

A new method [TextRendering::TextLayoutStrategy::OnGlyphProcessing](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_text_layout_strategy.html#a0ed82950c1cebd975ffbb5372b4fc477) has been added which is triggered before bliting each glyph bitmap. Default implementation has been added to keep backwards compatibility. This offers the possibility to skip the bliting of a glyph bitmap if needed. For this, also the [TextRendering::TextLayoutStrategy::Action](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_text_layout_strategy.html#a1e3dab4e7de13366fbef6604f5a3dc38 "Action taken by the text renderer after an event is processed.") enumeration has beed extended with a new *Break* value.

---

# Migration Guide

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

<div class="contents" id="bkmrk-description-candera-"><div class="textblock"><table class="doxtable" style="width: 140.741%;"><tbody><tr><th style="width: 13.3504%;">**Description**</th><th style="width: 33.7448%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.0.3**</th><th style="width: 52.9048%;">**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.0.4**</th></tr><tr><td style="width: 13.3504%;">Dynamic\_Cast</td><td style="width: 33.7448%;">```
DerivedObject* derivedPtr = DynamicCast<DerivedObject>(basePtr);
DerivedObject::SharedPointer derivedPtr = DynamicCast<BaseObject>(basePtr);
```

</td><td style="width: 52.9048%;">```
DerivedObject* derivedPtr = Dynamic_Cast<DerivedObject*>(basePtr);
DerivedObject::SharedPointer derivedPtr = Dynamic_Cast<BaseObject::SharedPointer>(basePtr);
```

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

</div></div>---