# Candera V3.2.0

Release Date: February 2016  
  
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\_2\_0.

# Candera/FeatStd CMake Build System Changes

#### i.MX6 Custom Driver Includes

With the newest board support packages the drivers are available together with the other includes and libraries required when cross-compiling for the i.MX6. Therefore, it is now no longer required to specify custom driver include and library paths. The CGIDEVICE\_CUSTOM\_PATHS CMake parameter has been removed, together with the CGIDEVICE\_TARGET\_IMX6\_DRIVER\_PATH\_INCLUDE and CGIDEVICE\_TARGET\_IMX6\_DRIVER\_PATH\_LIB parameters. Ensure that the driver includes and libraries are available in the sysroot specified for cross-compilation.

---

# Candera Engine 3D

#### 2D Composition in 3D using Canvas Objects.

New node types have been added to the 3D scene graph, namely [CanvasSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_canvas_sprite.html) and [CanvasGroup](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_canvas_group.html). Both offer means to realize 2D items in 3D space. These canvas objects are transformable in their local XY plane. [CanvasSprite](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_canvas_sprite.html) reacts on the size of the set texture and offers means to provide a pivot offset, such that rotations or scale is done around this pivot point. With these objects 2D planes containing several 2D elements can be defined, but even be transformed in 3D space. Using an orthographic even pixel exact positioning is possible.

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

</div></div></div>#### RendererListener Camera Hook

A new hook is defined for [RendererListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer_listener.html "A RendererListener defines hooks that are called before or after a Node is rendered.") - [RendererListener::OnCameraPostRender](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer_listener.html#abe297d3569d880cddd3d37ec961fc9ff) that is called after a camera has been rendered.

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

</div></div></div>#### Node intersection in Screen Coordinates

An interface has been added to compute whether a node intersects with a pick in screen coordinates - [Math3D::IsPickIntersectingGeometry](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math3_d.html#a995cc49799841f830cf104addb6e5943).

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

</div></div></div>#### Added MemoryPool property to TextureImage

[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...") class has now a memory pool property which indicates where to store the image data for rendering. This property may be ignored on RenderDevices that only support uploading to VideoRam.

---

# Candera Engine 2D

#### 2D Node Render Benchmark Property

New methods have been added for getting/setting of render measure value of [Node2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html "The class Node2D is an abstract base class for all 2D scene graph nodes."): [Node2D::SetRenderBenchmark](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#a90f229b2b18275b21ed1e87ba3cb3fd3) and [Node2D::GetRenderBenchmark](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#aeb4d7e3764ab886e1b65c8c3fe5c01be). These values are used by a camera render strategy and the rendering of the nodes is done until the sum of these render benchmark values exceed a defined threshold.

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

</div></div></div>#### Renderer2DListener Camera Hook

A new hook is defined for [Renderer2DListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d_listener.html "A Renderer2DListener defines hooks that are called before and after a Node is rendered.") - [Renderer2DListener::OnCameraPostRender](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d_listener.html#a141a35238594252d9c3f80b8f131ad7e) that is called after a camera has been rendered.

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

</div></div></div>#### GridLayouter Cell Spanning

A new feature has been added to [GridLayouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html "GridLayouter arranges its elements in a grid. The amount of rows and columns for the grid must be spe...") that allows merging of adjacent columns and/or rows into larger single cells. Two new properties are defined in this case for each element inside a [GridLayouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html "GridLayouter arranges its elements in a grid. The amount of rows and columns for the grid must be spe..."), **RowSpan** and **ColumnSpan**, which can be accessed by corresponding getter/setter methods: [GridLayouter::SetRowSpan](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html#aa9faa97b01d2b51e73b8d81f2edd3857), [GridLayouter::GetRowSpan](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html#a8b41b6d564eb8d8417ba318bcbd1f073) and respectively [GridLayouter::SetColumnSpan](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html#a2ad9c7c394035fada0198a0981b8ee54), [GridLayouter::GetColumnSpan](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_grid_layouter.html#a52a7e7f858439fa7db55c958578a19b6).

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

</div></div></div>#### 2D Scene Graph support

CGIAnalyzer supports 2D [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.") Graphs now.

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

</div></div></div>#### BitmapImage2D::MemoryPool changed

Enumeration values available for [BitmapImage2D::MemoryPool](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html#aa0f832d09bd521bdf64f34831155fa5c) have been modified to BitmapImage2D::MemoryPool::VideoMemory and BitmapImage2D::MemoryPool::ClientMemory. The previous values SystemMemory and FlashMemory are now deprecated.

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

</div></div></div>#### Node2D::LayoutingRectangle deprecated

The dynamic property Node2D::LayoutingRectangle has been deprecated. The only use for this parameter was to allow layouting of text in a uniform way with images. This was made obsolete by the introduction of [TextNode2DLayouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d_layouter.html "Base Layouter for TextNode2D nodes."). The funcitonality introduced by this property has been moved to the layouter, as follows:

For controlling the size of the layout rectangle, one shall use the dynamic property Node2D::Size (accessible via [Layouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_layouter.html "A non-zero padding applies space inside the element layout's width and height. The values can be set ...")::\*Size\*) For controlling the position of the layout rectangle, one shall use the dynamic property Node2D::Margin (accessible via [Layouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_layouter.html "A non-zero padding applies space inside the element layout's width and height. The values can be set ...")::\*Margin\*) For computing the layout rectangle, a generic interface is available as Layouter::GetComputedLayoutRectangle. This is also available in a non-generic flavour as: [Node2D::GetComputedBoundingRectangle](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#a47334bfe51bb9a7289994087195f3fb4) for nodes that don't display text and [TextNode2D::GetLayoutTextRectangle](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d.html#a08ea9bb95c74eaba7f7ef28132f35384) for text.

---

# Candera Base

#### Event Listener

This version introduces the foundation for a new event/listener system based on two classes, <span style="color: rgb(230, 126, 35);">[Implementing the event handlers of IEventListener](https://doc316en.candera.eu/link/189#bkmrk-implementing-the-eve)</span> and [EventListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_event_listener.html). The motivation for this is to reduce the amount of virtual functions, reduce code needed for predefined event listeners as well as to improve extensibility of existing events. Events are passed to a single OnEvent function which should use [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") RTTI to differentiate between event types and call concrete non-virtual handling functions. [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") will not provide implementations of listeners, only interfaces, further reducing code size.

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

</div></div></div>#### Specializations for StringBufferAppender added

Specializations for the FeatStd::StringBufferAppender::Append method have been added for all [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") types used with DataType:

<div class="contents" id="bkmrk-margin-layouter-%2A-ho"><div class="textblock">- [Margin](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_margin.html "A non-zero margin applies space outside the element layout's width and height. The values can be set ...")
- [Layouter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_layouter.html "A non-zero padding applies space inside the element layout's width and height. The values can be set ...") \*
- HorizontalAlignment
- VerticalAlignment
- [Color](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_color.html "Represents a color by its red-, green-, blue- and alpha-value. Provides color arithmetic functions an...")
- [Rectangle](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_rectangle.html "Represents a rectangle.")
- [Vector2](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vector2.html "The default Vector2 class.")
- [Vector3](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_vector3.html "The default Vector3 class.")
- [TextRendering::Font](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_font.html "Defines a specific font face and size.")
- SharedPointer&lt;[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.")&gt;
- [Node2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html "The class Node2D is an abstract base class for all 2D scene graph nodes.") \*
- [Camera2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera2_d.html "A camera defines the view to the scene. At least one Camera2D has to be added to a 2D scene graph and...") \*
- [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...") \*
- [Group2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_group2_d.html "The class Group2D is a scene graph node that stores a set of nodes as its children. The parent-child relationship between groups and nodes is bidirectional. Whereas a group can hold a group of nodes, a node can at most have one parent at a time. Cycles are prohibited. Changing the groups transformation or alpha value affects the children nodes of the group.") \*
- [Node](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node.html "The class Node is an abstract base class for all scene graph nodes. Each Node defines a local coordin...") \*
- SharedPointer&lt;[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...")&gt;
- [Group](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_group.html "The class Group is a scene graph node that stores a set of Nodes as its children. The parent-child re...") \*
- [Mesh](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_mesh.html "The class Mesh represents a three-dimensional rigid body object defined by polygons. The Mesh's polygonal surface is defined by its VertexBuffer. Each Mesh must have exactly one Appearance set, in order to specify how the Mesh geometry is rendered.") \*
- [Light](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_light.html "A Node that represents different kinds of light sources. Light sources are used to determine the colo...") \*
- [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...") \*
- RenderDevice2D::BlendFactor
- RenderDevice2D::BlendOperation
- RenderDevice2D::Filter
- RenderDevice2D::MipMapFilter

</div></div>---

# Candera Scripting

This version introduces a scripting language agnostic [base component system](http://dev.doc.cgistudio.at/APILINK/group___scripting.html), as well as an implementation that binds the [Lua scripting language to Candera](http://dev.doc.cgistudio.at/APILINK/group___lua_binding.html). For an introduction to Lua scripting in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"), refer to [this section](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html).

---

# Candera System

#### Entity Component System

This version offers an [entity component system](http://dev.doc.cgistudio.at/APILINK/group___entity_component_system.html) to facilitate development using the entity component programming paradigm. An entity component system is a model to attach data (components) to objects (entities). It provides fast iteration over data at the cost of slightly higher setup and teardown times. Entities do not contain components as members, so Entity derived classes do not increase the size of your objects. This approach lends itself to data oriented programming, and is an alternative to, not a substitute for, object oriented programming.

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

</div></div></div>#### SharedPtrProperty::Set(T\* value) deprecated

The method SharedPtrProperty::Set(T\* value) has been deprecated. Widgets/Applications should use [SharedPtrProperty::Set(const TPtr&amp; value)](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_shared_ptr_property.html#aaf5c60e3a803ff07119aaec898742d45) instead.

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

</div></div></div>#### 2D and Custom Experiments added

Global Experiment "Ignore Draw Calls" is available for 2D applications. Custom Experiments allow self-constructed Experiments which can be (de-)activated by CGIAnalyzer. These experiments are based on function pointers allowing more functionality and a wider range of usages.

---

# Candera Device

No changes.

---

# Candera Transitions

This version introduces a basic transition framework to [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") to allow activation and deactivation of nodes or scenes using configurable transition fragments based on a set of rules and a request. Currently only fading and switching is supported. For details on how to use the transition framework please refer to PID\_app\_dev\_tutorial\_11 on how to use the framework as well as the documentation of the [Transitions::TransitionStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_transitions_1_1_transition_strategy.html), which lies at the core of the framework.

---

# TextEngine

#### Support for TTC (True Type Font Container)

Support for TTC (True Type Font Container) has been added to [TextRendering::Font](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_font.html "Defines a specific font face and size.") and [TextRendering::FontStore](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_font_store.html "FontStore is an abstract interface to retrieve font data The font store defines unique descriptor id ...") classes. The single fonts inside a collection can be accessed by specifying a Face Index.

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

</div></div></div>#### Internal Namespace for Font Engine Integrations

The namespaces of the Font Engine integrations - "FreeType" and "BitmapFont" - have been changed to "Internal".

---

# Migration Guide

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

<div class="contents" id="bkmrk-description-candera-"><div class="contents"><div class="textblock"><table class="doxtable" style="width: 121.605%;"><tbody><tr><th style="width: 21.3774%;">Description</th><th style="width: 30.0441%;">[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.1.1</th><th style="width: 48.5785%;">[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.2.0

</th></tr><tr><td style="width: 21.3774%;">[BitmapImage2D::MemoryPool](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html#aa0f832d09bd521bdf64f34831155fa5c) enumeration changed</td><td style="width: 30.0441%;">```
            bitmapImage2D->SetMemoryPool(BitmapImage2D::SystemMemory);
            bitmapImage2D->SetMemoryPool(BitmapImage2D::FlashMemory);
```

</td><td style="width: 48.5785%;">```
            bitmapImage2D->SetMemoryPool(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap_image2_d.html#aa0f832d09bd521bdf64f34831155fa5cab8a66ac13e0d466639f78b13c063a6bf" title="The buffer is in client memory.">BitmapImage2D::ClientMemory</a>);
```

</td></tr><tr><td style="width: 21.3774%;">Deprecated SharedPtrProperty::Set(T\* value), replaced with [SharedPtrProperty::Set(const TPtr&amp; value)](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_shared_ptr_property.html#aaf5c60e3a803ff07119aaec898742d45).</td><td style="width: 30.0441%;">```
            Image2D* image;
            m_image.Set(image);
```

</td><td style="width: 48.5785%;">```
            SharedPtrProperty<Image2D> image;
            m_image.Set(image);
```

</td></tr><tr><td style="width: 21.3774%;">Face Index introduced for TTC (True Type Font Container) support.</td><td style="width: 30.0441%;">```
            UInt8 faceId = fontStore->GetDescriptorId("Vera");
```

</td><td style="width: 48.5785%;">```
            UInt8 faceId = fontStore->GetDescriptorId("Vera", 0);
```

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

---

</div></div></div>