# CGI Studio 3.2.1

# Candera V3.2.1

Release Date: June 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\_1.

# Candera/FeatStd CMake Build System Changes

<div class="contents" id="bkmrk-v3.2.0-v3.2.1-cander"><div class="contents"><div class="textblock"><table border="1" class="doxtable" style="border-collapse: collapse; width: 800px;"><tbody><tr><th>**V3.2.0**</th><th>**V3.2.1**</th></tr><tr><td>CANDERA\_MONITOR\_CUSTOM\_EXPERIMENTS</td><td>MONITOR\_CANDERA\_CUSTOM\_EXPERIMENTS</td></tr><tr><td>CANDERA\_PERFORMANCE\_RECORDER\_DISABLED   
<dl class="note"><dd>  
</dd></dl><p class="callout info">logic has been inverted.</p>

</td><td>MONITOR\_CANDERA\_PERFORMANCE\_RECORDER\_ENABLED</td></tr><tr><td>MONITOR\_OMIT\_OPENGL\_RECORDING   
<dl class="note"><dd>   
</dd></dl><dl class="note"><dd><p class="callout info">logic has been inverted.  
Flag were not part of CMake in previous versions.</p>

</dd></dl></td><td>MONITOR\_RECORDING\_OPENGL\_ENABLED</td></tr><tr><td>MONITOR\_OMIT\_2D\_CALLS\_RECORDING   
<dl class="note"><dd>   
</dd></dl><dl class="note"><dd><p class="callout info">logic has been inverted.  
Flag were not part of CMake in previous versions.</p>

</dd></dl></td><td>MONITOR\_RECORDING\_2D\_CALLS\_ENABLED</td></tr><tr><td>CANDERA\_PERFMON\_BUFFERSIZE   
<dl class="note"><dd>  
</dd></dl><p class="callout info">logic has been inverted.  
Flag were not part of CMake in previous versions.</p>

**See also:**

<dl class="see"><dd><span style="color: rgb(230, 126, 35);">[FeatStd CMake Switches](https://doc316en.candera.eu/link/885#bkmrk-page-title)</span></dd></dl></td><td>MONITOR\_CANDERA\_PERF\_RECORD\_BUFFER\_SIZE</td></tr></tbody></table>

</div></div></div>Existing monitor settings have been moved from code to CMake settings:

<div class="contents" id="bkmrk-name-description-pos"><div class="contents"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse; width: 800px; border-width: 1px; border-spacing: 0px; height: 83.1393px;" width="1150"><tbody><tr bgcolor="#d4d4d4" style="height: 27.7131px;"><th style="width: 302.641px; border-width: 1px; padding: 5px; height: 27.7131px;">**Name**</th><th style="width: 358.641px; border-width: 1px; padding: 5px; height: 27.7131px;">**Description**</th><th style="width: 147.719px; border-width: 1px; padding: 5px; height: 27.7131px;">**Possible values**</th></tr><tr style="height: 27.7131px;"><td style="width: 302.641px; border-width: 1px; padding: 5px; height: 27.7131px;">MONITOR\_RECORDING\_OPENGL\_ENABLED</td><td style="width: 358.641px; border-width: 1px; padding: 5px; height: 27.7131px;">Enables or disables OpenGL monitor recordings.</td><td style="width: 147.719px; border-width: 1px; padding: 5px; height: 27.7131px;">ON/OFF</td></tr><tr style="height: 27.7131px;"><td style="width: 302.641px; border-width: 1px; padding: 5px; height: 27.7131px;">MONITOR\_RECORDING\_2D\_CALLS\_ENABLED</td><td style="width: 358.641px; border-width: 1px; padding: 5px; height: 27.7131px;">Enables or disables monitoring of 2D driver calls.</td><td style="width: 147.719px; border-width: 1px; padding: 5px; height: 27.7131px;">ON/OFF</td></tr></tbody></table>

</div></div></div>New CMake variable was added for Candera2D layout clipping:

<div class="contents" id="bkmrk-name-description-pos-0"><div class="contents"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse; width: 800px; height: 76.3907px; border-width: 1px; border-spacing: 0px;" width="1150"><tbody><tr bgcolor="#d4d4d4" style="height: 29.7969px;"><th style="width: 269.656px; height: 29.7969px; border-width: 1px; padding: 5px;">**Name**</th><th style="width: 397.656px; height: 29.7969px; border-width: 1px; padding: 5px;">**Description**</th><th style="width: 141.688px; height: 29.7969px; border-width: 1px; padding: 5px;">**Possible values**</th></tr><tr style="height: 46.5938px;"><td style="width: 269.656px; height: 46.5938px; border-width: 1px; padding: 5px;">CANDERA\_LAYOUT\_CLIPPING\_ENABLED</td><td style="width: 397.656px; height: 46.5938px; border-width: 1px; padding: 5px;">Defines whether Candera2D layout clipping (setting a clipping rectangle for every render node) is enabled or not.</td><td style="border-width: 1px; padding: 5px;">ON/OFF</td></tr></tbody></table>

---

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

# Candera Engine 3D

#### New Functions in Renderer

[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.") has new functions to activate and deactivate a camera ([Renderer::ActivateCamera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#a877ebbcf0c736d86fd13cb24a0eac593), [Renderer::DeactivateCamera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#aaf7f7ac9ec4402c24c70bcd04fd0bfa1)), to activate a clear mode (Renderer::ActivateClearMode), and scissor (Renderer::ActivateScissor).

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

</div></div></div>#### Dirty Area Management

[Renderer::RenderCamera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#a10dbe66b15c60f44cce3aaccd38d2ee5) now accepts a rectangle as the parameter that defines a dirty area. A dirty area denotes an area on the screen or render target in which the content has changed, thus only this area requires updating by the [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."). The dirty area rectangle parameter defaults to the full size of the screen or render target. If the user provides his own dirty area rectangle, only this area will be cleared and drawn to. Objects whose bounding rectangle is outside the dirty area will be skipped. Generally speaking, the smaller the dirty area, the smaller the bandwidth required for clearing and drawing, and the more objects can be skipped.

This feature also adds the properties [Renderer::Statistics::CulledNodesUsingDirtyAreaScissor](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer_1_1_statistics.html#a15baae47c2e48398d527823f402b0e93 "Number of nodes culled due to their bounding box being outside the dirty area.") and [Renderer::Statistics::AverageDirtyAreaFactor](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer_1_1_statistics.html#a2ef679fb55bffe7c2a42e36924779ee0 "Average dirty area factor (dirty area / renderTarget area) in the range of (0..1]."). CulledNodesUsingDirtyAreaScissor denotes the number of objects that could be skipped by the [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.") due to their bounding rectangle being outside the dirty area. AverageDirtyAreaFactor denotes the average dirty area divided by the size of the screen or render target. E.g. a factor of 0.8 means that the average dirty area accumulated since the last [Renderer::Statistics::Reset](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer_1_1_statistics.html#abb63e5922adbe34593df495ed2694294) is 80% of the size of the screen or render target. The bigger the factor, the less performance improvement can be expected. Under some circumstances, which depends on the actual content being used, performance can even decrease. Therefore always profile this feature to see if your content benefits from it or not.

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

</div></div></div>#### New Renderer::Statistics properties

[Renderer::Statistics](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer_1_1_statistics.html) now also exposes the number of color buffer, depth buffer, and stencil buffer clears, as well as the number of nodes that were culled due to using a dirty area, and the ratio of the average dirty area to its screen/render target area.

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

</div></div></div>#### CanvasGroup::TranslatePivot renamed

[CanvasGroup::TranslatePivot](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_group.html#a593b45667010200bd4e35f75dbaf182d) has been renamed to [CanvasGroup::TranslatePivot2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_canvas_group.html#a029decdb2d21ed93464b08e81547922e).

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

</div></div></div>#### PlanarShadow::GetId and SetId renamed

[PlanarShadow::GetId](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_candera_object.html#a8f0f015836c983726e590472024816aa) has been renamed to [PlanarShadow::GetStencilBufferId](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_planar_shadow.html#abdfe7d5274e03d6b40c42e483c5a8c97). In the same manner also [PlanarShadow::SetStencilBufferId](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_planar_shadow.html#a4c748372ea9c301632bd0a2af9a20a34).

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

</div></div></div>#### Camera Look-At Node

A new feature allows to set a look-at node for a camera. If such a node is set the camera will always look at that node.

<div class="contents" id="bkmrk-see-also%3A-camera%3A%3Ase"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Camera::SetLookAtNode](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera.html#a53b1e4854b4c8b15369b82facb560c07).</dd></dl>---

</div></div></div>#### Normalize Rectangle from Render Target Space

A new function to normalize a given rectangle from the render target space has been added.

<div class="contents" id="bkmrk-see-also%3A-math3d%3A%3Ano"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Math3D::NormalizeRectangle()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math3_d.html#a5acae572700c94a5e8e898d71addb30f).</dd></dl></div></div>---

# Candera Engine 2D

#### Dirty Area Management

[Renderer2D::RenderCamera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d.html#a44c76b6ec44f705ed78d71ca4f05b66b) now accepts a rectangle as the parameter that defines a dirty area. A dirty area denotes an area on the screen or render target in which the content has changed, thus only this area requires updating by the [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."). The dirty area rectangle parameter defaults to the full size of the screen or render target. If the user provides his own dirty area rectangle, only this area will be cleared and drawn to. Objects whose bounding rectangle is outside the dirty area will be skipped. Generally speaking, the smaller the dirty area, the smaller the bandwidth required for clearing and drawing, and the more objects can be skipped.

This feature also adds the properties [Renderer2D::Statistics::BlitsCulled](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer2_d_1_1_statistics.html#a9c5d631131c9cf9f5b46c9fbd116a9a2 "Number of Blits that were culled, thus not submitted to the RenderDevice2D.") and [Renderer2D::Statistics::AverageDirtyAreaFactor](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer2_d_1_1_statistics.html#a1c7caace88e576ed72ff8d3aa9d9086f "Average dirty area factor (dirty area / renderTarget area) in the range of (0..1]."). BlitsCulled denotes the number of objects that could be skipped by the [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.") due to their bounding rectangle being outside the dirty area. AverageDirtyAreaFactor denotes the average dirty area divided by the size of the screen or render target. E.g. a factor of 0.8 means that the average dirty area accumulated since the last [Renderer2D::Statistics::Reset](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer2_d_1_1_statistics.html#ac6f3f3b0a5ea14d2de26f4bd348c2c0c) is 80% of the size of the screen or render target. The bigger the factor, the less performance improvement can be expected. Under some circumstances, which depends on the actual content being used, performance can even decrease. Therefore always profile this feature to see if your content benefits from it or not.

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

</div></div></div>#### Renderer2D::Statistics

[Renderer2D::Statistics](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_renderer2_d_1_1_statistics.html) provides information on how many blits and clears were submitted to the RenderDevice2D in the process of executing [Renderer2D::RenderCamera](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d.html#a44c76b6ec44f705ed78d71ca4f05b66b) or [Renderer2D::RenderAllCameras](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d.html#aebe992159ee6bc5406b5c0feba870bb4). Furthermore the statistics keep track of how many blits could be culled by 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."), as well as the ratio of the average dirty area to its screen/render target area.

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

</div></div>

# Candera Scripting

#### New Lua Functions

Two new Lua functions have been added in this version:

<div class="contents" id="bkmrk-candera.setenabled-c"><div class="contents"><div class="textblock">- [Candera.SetEnabled](http://dev.doc.cgistudio.at/APILINK/group___lua_binding_general_functions.html#CanderaLuaSetEnabled)
- [Candera.IsEnabled](http://dev.doc.cgistudio.at/APILINK/group___lua_binding_general_functions.html#CanderaLuaIsEnabled)

---

</div></div></div>#### New Script Callbacks.

This version adds 5 new Callbacks:

<div class="contents" id="bkmrk-awake-ondestroy-onen"><div class="textblock">- [Awake](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html#LuaTutorialFunctionsCalledByCandera)
- [OnDestroy](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html#LuaTutorialFunctionsCalledByCandera)
- [OnEnable](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html#LuaTutorialFunctionsCalledByCandera)
- [OnDisable](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html#LuaTutorialFunctionsCalledByCandera)
- [LateUpdate](http://dev.doc.cgistudio.at/APILINK/group___lua_tutorial.html#LuaTutorialFunctionsCalledByCandera)

</div></div>---

# Candera System

#### New EntityComponentSystem Function

Components from the EntityComponentSystem now have a function to see if the component is attached to an entity (Component::IsAttached). [Rectangle](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_rectangle.html "Represents a rectangle.") now has a set function (Rectangle::Set).

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

</div></div></div>#### New MetaInfo Macro

A new CdaDeprecated macro has been added to make a MetaInfoBase object deprecated. This was further used to deprecate all [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...") effects.

---

# Candera Device

#### Performance Recorder for WaitSync added

Monitor instrumentation has been added for WaitSync methods of Render Targets. Timings of WaitSync will be measured for Analyzer usage.

<div class="contents" id="bkmrk-see-also%3A-candera%3A%3As"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>Candera::Synchronizable::WaitSync</dd></dl>---

</div></div></div>#### Extended PlatformDescrition structure

A new field of PlatformDescription defines whether the platform uses a Window Manager.

---

# Candera Globalization

#### Threadsafe Globalization

The CanderaGlobalization classes have been enhanced for thread-safety. Especially [Candera::Globalization::CultureChangeListener](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_culture_change_listener.html) now handles [Candera::Globalization::CultureChangeListener::OnCultureChanged](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_culture_change_listener.html#ad34d13c0afad927f5448437087da15f5) notification in a thread safe way.

<div class="contents" id="bkmrk-see-also%3A-candera%3A%3Ag"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Candera::Globalization::CultureChangeListener::Obtain](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_culture_change_listener.html#a3ba3d6ef80d584acede70b5759613020) and [Candera::Globalization::CultureChangeListener::Release](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_globalization_1_1_culture_change_listener.html#a9dcdde7c3e6c98fb572efebbdf7f5218).</dd></dl></div></div>---

# TextEngine

#### Extended GlyphCacheAccess

[TextRendering::GlyphCacheAccess](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_glyph_cache_access.html "GlyphCacheAccess is responsible with providing an interface to the caching system, by which to store cached bitmaps. The caching system works by creating a new instance of each bitmap for each GlyphCacheAccess object, so each class extending this interface should behave like a singleton.") interface was extended with a function that should check if a glyph is valid in current context, even if cached. If the GlyphCacheAccess implementation returns false on this method, the glyph caching system will recall TextRendering::GlyphCacheAccess::Create and will replace the cached item with the one provided by the new call. Create function is extended with a parameter representing the old cached item for reference.

---

# Migration Guide

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

<div class="contents" id="bkmrk-description-candera-"><div class="textblock"><table class="doxtable"><tbody><tr><th>**Description**</th><th>**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.2.0**</th><th>**[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") V3.2.1**

</th></tr><tr><td>Activating [ClearMode](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_clear_mode.html "Describes how a viewport is cleared. The color buffer may be cleared using a given color...") moved to [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.")</td><td>[ClearMode::Activate()](http://dev.doc.cgistudio.at/APILINK/group___c_o_u_r_i_e_r___t_r_a_n_s_i_t_i_o_n_s.html#gga5d0c24bca24009c53c455ef2e77ff2caa2ef10430976350af6e16142bd380932c)</td><td>Renderer::ActivateClearMode(const ClearMode\*)

</td></tr><tr><td>Activating [ClearMode](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_clear_mode.html "Describes how a viewport is cleared. The color buffer may be cleared using a given color...") via [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...") moved to [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.")</td><td>ClearMode::Activate(const Camera&amp;)</td><td>Renderer::ActivateClearMode(const Camera&amp;)

</td></tr><tr><td>Setting a shader uniform moved to [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.")</td><td>RenderDevice::SetUniform(Handle, const Char\*, const void\*, Shader::UniformType, UInt)</td><td>Renderer::SetUniform(Handle, const Char\*, const void\*, Shader::UniformType, UInt)

</td></tr><tr><td>Submitting a drawcall moved to [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.")</td><td>RenderDevice::DrawVertexBufffer(const VertexBuffer&amp;)</td><td>Renderer::Draw(const VertexBuffer&amp;)

</td></tr><tr><td>Submitting an instanced drawcall moved to [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.")</td><td>RenderDevice::DrawInstancedVertexBuffer(const VertexBuffer&amp;, UInt32)</td><td>[Renderer::Draw(const VertexBuffer&amp;, UInt)](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer.html#aee4c9a181d71f8358cc9984d487ab275)

</td></tr><tr><td>Setting the transformation matrix moved to [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.")</td><td>RenderDevice2D::SetTransformationMatrix(ContextHandle2D, SurfaceType, const Matrix3x2&amp;)</td><td>Renderer2D::SetTransformationMatrix(ContextHandle2D, SurfaceType, const Matrix3x2&amp;)

</td></tr><tr><td>Blit moved to [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.")</td><td>RenderDevice2D::Blit(ContextHandle2D)</td><td>Renderer2D::Blit(ContextHandle2D)

</td></tr><tr><td>Clear moved to [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.")</td><td>RenderDevice2D::Clear(ContextHandle2D, Float, Float, Float, Float)</td><td>[Renderer2D::Clear(ContextHandle2D, Float, Float, Float, Float)](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_renderer2_d.html#aad0af8d8d6fb588579acfd1724481e5f)

</td></tr><tr><td>Implementation of GlyphCacheAccess::Create</td><td>UInt8\* CustomGlyphCache::Create(const GlyphBitmap &amp;bitmap) { Create and return new item based on bitmap }</td><td>UInt8\* CustomGlyphCache::Create(const GlyphBitmap &amp;bitmap, UInt8\* cacheItem) { Create or update the cacheItem and return it. }

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

</div></div>---

# 64 Bit Support

Support for building with **64 bit** has been **added**. Please note that **32 bit** builds are **no longer supported**. In order to obtain a 64 bit build, one has to configure the build to use a 64 bit compiler. This can be done during CMake configuration. This configuration step can be performed during CMake setup. For users with Visual Studio versions earlier than Visual Studio 2019 (version 16), make sure to select 'x64' as the optional platform for the generator during CMake configuration.  
  
Doing this will automatically enable the CMake variable FEATSTD\_64BIT\_PLATFORM which is further used in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]").

Two new types have been introduced for unsigned and signed integers which extend to the correct size when used in a 64 bit system. These are **FeatStd::SizeType** and **FeatStd::OffsetType** (equivalent to std::size\_t type and std::ptrdiff\_t types).

<p class="callout info">The API has been adapted at various locations to use FeatStd::SizeType and FeatStd::OffsetType instead of integer types. Application code using a previous version will be compatible due to implicit integer conversion. Please take care on compiler warnings related to type conversions, alignment casts and signed/unsigned comparisons.</p>

---

# Courier V3.2.1

#### Foundation Changes

Time stamp and Source ID have been added to the Touch Message and the Touch Info.

<div class="contents" id="bkmrk-see-also%3A-courier%3A%3At"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>Courier::TouchMsg::SetTimeStamp(), Courier::TouchMsg::SetSourceId() and [Courier::TouchInfo](http://dev.doc.cgistudio.at/APILINK/struct_courier_1_1_touch_info.html).</dd></dl>---

</div></div></div>#### Visualization Changes

<div class="contents" id="bkmrk-renderjob-strategies"><div class="contents"><div class="textblock">- Renderjob Strategies introduced
- Create View by View ID
- Dirty Area Management

</div></div></div>#### Renderjob Strategies introduced

A new class [Courier::RenderJobStrategy](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_render_job_strategy.html) has been introduced which is used to sort the RenderJobs. The default sort criterias are:

<div class="contents" id="bkmrk-offscreen-render-job"><div class="contents"><div class="textblock">1. offscreen render jobs before Display render jobs.
2. 2d render jobs before 3d render jobs
3. clear render jobs before normal view render jobs
4. lower camera sequence number before higher camera sequence number For custom sort criteria simply derive from RenderJobStrategy and use the Renderer::SetRenderJobStrategy. The [Courier::Renderer](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_renderer.html) will use the [Courier::RenderJobStrategy](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_render_job_strategy.html) and utilize also the [Courier::Gdu::RenderState](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_gdu.html#a3c9d7d4efdf92e862618111cba1172d5) structure.

</div></div></div>#### Create View by View ID

The class [Courier::ViewFactory](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view_factory.html) has been enhanced by a method [Courier::ViewFactory::Create](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view_factory.html#ad421b5ee9235b39354662940f3e2082a) which creates a View object identified by its View id. Used by [Courier::ViewHandler](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view_handler.html) class.

#### Dirty Area Management

##### Dirty Area Management in Widgets

The easiest way for a widget developer is to simply call the Invalidate method of the [Courier::FrameworkWidget](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_framework_widget.html) whenever the scene tree has been changed (structure and setting changes). By default this will lead to an invalidation of the associated view with a dirty area that marks the complete area as dirty.

The [Courier](http://dev.doc.cgistudio.at/APILINK/namespace_courier.html) dirty area management enables widget developers to overwrite that Invalidate method. To provide an out-of-the-box dirty area based implementation a base widget is recommended that takes the bounding rectangle (2D) resp. bounding box (3D) before the change and uses it as source for the dirty area of the current frame.

The bounding rectangle/box has first to be transformed into the view space of the camera.

##### Scene Dependencies

Invalidation dependencies have been extended by an optional dirty area. This enables the application developer to limit invalidation dependencies to dirty areas. Dependent on the size of the dirty area invalidation of a view in a small area no longer leads to an invalidation of the complete chain of invalidation dependencies.

The only change required on application side to limit invalidation dependencies is to provide a dirty area as small as possible when calling Invalidate. If this is already handled by a common widget base class, see next section, no additional changes are required.

##### Widget Changes

A common base class for 2D and 3D is already provided which overwrites the following method:

<div class="contents" id="bkmrk-see-also%3A-courier%3A%3Af"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>[Courier::FrameworkWidget::Invalidate](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_framework_widget.html#a40c3fcf4c499f73e8e9156bef1f78a79 "Invalidates the parent view.")</dd></dl></div></div></div>If the optional dirtyArea parameter is not set, the bounding rectangle (in 2D) resp. the bounding box (in 3D) of the attached node is taken as dirty area. This base class is called BaseSampleWidget, which can be found in "&lt;cgi\_studio\_root&gt;/cgi\_studio\_cit/src/CitApps/CitDemoApp/Widget".

For default dirty area management all widgets need to be derived from this widget class.

In case that the bounding rectangle/box is not sufficient for correct invalidation, the widget itself has to provide a corresponding dirty area via the FrameworkWidget::Invalidate method. In this case it is also up to the widget to take care of correct invalidation of the old dirty area.

##### Camera View Space Transformation

In case an own dirty area is provided, the widget first has to transform its specific dirty area into the camera view space before calling Invalidate. This is done by multiplying the world transformation matrix of the attached node with the view matrix of the camera, as done in the following code snippet:

```
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_matrix3x2.html" title="Representation of a 3x2 Matrix used for 2d transformations.">Candera::Matrix3x2</a> worldTransformation = node->GetWorldTransform();
cameraDirtyArea.Transform(worldTransformation * camera->GetViewMatrix()); // transform dirty area to view space
```

The camera can either be added to the widget via an own property or be retrieved from the parent view in the following way:

```
Courier::ViewScene2D::CameraPtrVector& cameras = GetParentView()->ToViewScene2D()->GetCameraPtrVector();
```

In case that a scene contains more than one camera the transformation of the dirty area has to be done for each camera.

<div class="contents" id="bkmrk-see-also%3A-basesample"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>BaseSampleWidget::Invalidate implementation as a reference.</dd></dl></div></div>---

# FeatStd V3.2.1

# FeatStd CMake Switches

<div class="contents" id="bkmrk-v3.2.0-v3.2.1-featst"><div class="contents"><div class="textblock"><table border="1" class="doxtable" style="border-collapse: collapse; width: 100%;"><tbody><tr><th>**V3.2.0**</th><th>**V3.2.1**</th></tr><tr><td>FEATSTD\_MONITOR\_TYPE</td><td>MONITOR\_COM\_TYPE</td></tr><tr><td>FEATSTD\_MONITOR\_BLOCK\_UNTIL\_CONNECT</td><td>MONITOR\_BLOCK\_UNTIL\_CONNECT</td></tr><tr><td>FEATSTD\_MONITOR\_TCPIP\_PORT</td><td>MONITOR\_TCPIP\_PORT</td></tr><tr><td>FEATSTD\_MONITOR\_TCPIP\_ADDRESS</td><td>MONITOR\_TCPIP\_ADDRESS</td></tr><tr><td>FEATSTD\_MONITOR\_TCPIP\_STACK\_ENABLED</td><td>MONITOR\_TCPIP\_STACK\_ENABLED</td></tr><tr><td>FEATSTD\_MONITOR\_SERIALPORT\_BAUDRATE</td><td>MONITOR\_SERIALPORT\_BAUDRATE</td></tr><tr><td>FEATSTD\_MONITOR\_SERIALPORT\_ADDRESS</td><td>MONITOR\_SERIALPORT\_ADDRESS</td></tr><tr><td>PERFORMANCE\_RECORDER\_GENERATION\_DIR</td><td>MONITOR\_CANDERA\_PERFORMANCE\_RECORDER\_GENERATION\_DIR</td></tr><tr><td>PERFORMANCE\_RECORDER\_TEMPLATE\_DIR</td><td>MONITOR\_CANDERA\_PERFORMANCE\_RECORDER\_TEMPLATE\_DIR</td></tr></tbody></table>

</div></div></div>Existing monitor settings have been moved from code to CMake settings:

<p class="callout info">These flags are marked as advanced and should only be changed if the current settings have side effects.</p>

<div class="contents" id="bkmrk-name-description-pos"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="width: 100%;"><tbody><tr bgcolor="#d4d4d4"><th style="width: 30.2832%;">**Name**</th><th style="width: 52.0406%;">**Description**</th><th style="width: 17.6761%;">**Possible values**</th></tr><tr><td style="width: 30.2832%;">MONITOR\_CANDERA\_PERF\_RECORD\_BUFFER\_SIZE</td><td style="width: 52.0406%;">Defines the buffer size on target which is used for performance log tracing.  
When only perf-log streaming is used, it can use a smaller buffer.  
4000 as size can be enough then. The effective minimum requirement depends on the amount of recorders.</td><td style="width: 17.6761%;">positive integer</td></tr><tr><td style="width: 30.2832%;">MONITOR\_CANDERA\_PERF\_RECORD\_STRID\_BUFFER\_SIZE</td><td style="width: 52.0406%;">Defines the maximum of stored strings that can be sent (performance logs)  
with an id to reduce payload.</td><td style="width: 17.6761%;">positive integer</td></tr><tr><td style="width: 30.2832%;">MONITOR\_CANDERA\_PERF\_RECORD\_STRING\_SIZE</td><td style="width: 52.0406%;">Defines the maximum length of a single string that can be sent (performance logs).</td><td style="width: 17.6761%;">positive integer</td></tr></tbody></table>

</div></div>---

# FeatStd Monitor

#### Non-blocking connection setup

The monitor supports non-blocking connection setup now. CGIAnalyzer and target can be connected any time now.

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

</div></div></div>#### Performance logs: Payload reduction

The payload of performance logs are reduced to approx. 36 percentage of previous version. The buffer for streaming can be smaller now due to restructuring the sent data. Using the recording only functionality can store more recordings within the same buffer. The amount of recordings traced is defined by the size of buffer. Changes to the buffer size can be done by changing the CMake flag MONITOR\_CANDERA\_PERF\_RECORD\_BUFFER\_SIZE.

<div class="contents" id="bkmrk-see-also%3A-featstd-cm"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd><span style="color: rgb(230, 126, 35);">[FeatStd CMake Switches](https://doc316en.candera.eu/link/885#bkmrk-page-title)</span> for the changed CMake feature flag related to Monitor functionality.</dd></dl></div></div>---

# FeatStd Platform

#### 64 Bit Support

Support for building with 64 bit has been added. In order to obtain a 64 bit build, one has to configure the build to use a 64 bit compiler. Doing this will automatically enable the CMake variable FEATSTD\_64BIT\_PLATFORM which is further used in FeatStd. If a 32 bit compiler is used, the CMake variable FEATSTD\_32BIT\_PLATFORM will be enabled automatically.

Two new types have been introduced for unsigned and signed integers which extend to the correct size when used in a 64 bit system or a 32 bit system. These are **FeatStd::SizeType** and **FeatStd::OffsetType** (equivalent to std::size\_t type and std::ptrdiff\_t types).

<p class="callout info">The API has been adapted at various locations to use FeatStd::SizeType and FeatStd::OffsetType instead of integer types. Application code using a previous version will be compatible due to implicit integer conversion. Please take care on compiler warnings related to type conversions, alignment casts and signed/unsigned comparisons.</p>

---

# FeatStd Util

#### Thread safe String

The [FeatStd::String](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_string.html) class has been enhanced by a method [String::GetCriticalSection](http://dev.doc.cgistudio.at/APILINK/class_feat_std_1_1_string.html#a52f64553ae443fd990eaafe85995f1a6) which can be used to protect the internal c-string from modification by other threads.

<p class="callout info">The feature is only available when CMake flag FEATSTD\_THREADSAFETY\_ENABLED is enabled.</p>

---

# Analyzer V3.2.1

# Scene Analyzer

#### Loading Performance Logs

A streamed performance log can be loaded after pressing pause now.   
Opening performance logs of older versions is supported now.

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

</div></div></div>#### Dashboard functionality

The dashboard can load more than the default value recorders (CpuLoad, GpuLoad, MemoryUsage) now. Drag'n'Drop a graph to show multiple value-recorders in one graph is possible now.  
Graphs with no content are no longer shown.

---

# Communication

Stabilized the connection and solved crashes (hang up) when pressing stop button.  
Requests for communication port uses own scheduler now. This results in better reactivity and a more stabilized connection.  
Adaptions made to support non-blocking connection setup.

<div class="contents" id="bkmrk-see-also%3A-featstd-mo"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd><span style="color: rgb(230, 126, 35);">[FeatStd Monitor](https://doc316en.candera.eu/link/886#bkmrk-page-title)</span></dd></dl></div></div>---

# SceneComposer V3.2.1

# Requirements

#### Requirements

Starting with this version, the .NET 4.5.2 is needed in order to run SceneComposer (Mantis 6824).

---

# SceneComposer Usability Improvements

#### Solution Conversion from TextEffects to TextNode2D

A new option "Replace Old Text Nodes" was added in the context menu for all scenes, composites and folders containing scenes or composites. This will enable the user to replace the TextNode-TextBrushEffect pairs with the new TextNode2D-BitmapBrushBlendEffect pairs (Mantis 6173 &amp; 6820).

<div class="contents" id="bkmrk-see-also%3A-solution-c"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Solution Conversion from TextEffects to TextNode2D](https://doc316en.candera.eu/link/147#bkmrk-solution-conversion-)</span> in SceneComposer User Manual

</dd></dl>---

</div></div></div>#### TextNode2D Layout Rework

New properties were added for the TextNode: TextAlignment, LineSpacing and Trimming. A new category called "Text Layout" was added. This includes the properties noted before and also MultiLine and WordWrap. All the properties from this category are visible only if Enable Text Layout is checked. If it is unchecked, the default values of the properties will determine in which way the text is rendered (Mantis 6682 &amp; 6820).

Photoshop exporter now exports the new layout properties. The Y position of the imported TextNode2D is now calculated for each font to achieve &lt;1 px accuracy.

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

</dd></dl>---

</div></div></div>#### Logging Assebly &amp; Plugin Versions

SceneComposer now writes in the log file the version of .dlls and .exe files located in SceneComposer's directory. For .dlls and .exes that .NET assemblies that can be loaded, the assembly version will be written. or the other, the file version (Mantis 4761).

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

</dd></dl>---

</div></div></div>#### Enable Automatic Import

A new option was added in Preferences and in Automatic Imports configuration to enable/disable the feature (Mantis 6443).

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

</dd></dl>---

</div></div></div>#### Scripts Creation &amp; Execution

When a new script is created, the script is automatically loaded in the "Script Editor" if visible (Mantis 6854).

The execution of any available script is possible by using the control interface (Play, Pause, Resume, Stop) (Mantis 6529).

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

</dd></dl>---

</div></div></div>#### Sorting "Solution Explorer" Folders &amp; Items

In the Solution Explorer panel all the folders and items will be sorted only for presentation. They will be sorted alphabetically, folders first, items after. New data will always be appended to internal list. Sorting for SCML file will not be made anymore In this way, the modification of the SCML file will be avoided (Mantis 4761).

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

</div></div></div>#### "About" Dialogue

Many times it is necessary to copy the version and the revision number of SceneComposer. A new feature allows the user to copy this piece of information directly from the "About" dialogue (Mantis 6513).

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

</div></div></div>#### Other Changes

<div class="contents" id="bkmrk-converted-solutions-"><div class="contents"><div class="textblock">- Converted solutions to 3.1.1 do not contain the new specialized uniform setters. When converting a solution from an older version, a check will be made whether the Uniform Setter Templates are up to date. If the values for the shader param uniforms were updated in the latest version of the solution template, the uniforms in the converted solution will be updated. If new uniforms were added, they will be added also in the converted solution (Mantis 6131).

- Point Sprite objects from previous versions are not visible after conversion to the 3.2.1 version. The default shader config will be copied from the latest base solution template (Mantis 6936).

---

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

<div class="contents" id="bkmrk-alignement-schost-wa"><div class="textblock">- **Alignement** SCHost was aligned with candera type changes for 64bit support (Mantis 6822).
- **3D Sources** SCHost solution does no longer include sources for 3D if CANDERA\_3D\_ENABLED is not activated. The same is available for 2D.
- **Renamed Button** The "Cancel" button from "Rules Editor" dialog was renamed into "Close" (Mantis 6536).
- **Removed Context Menu Option** The "Rename" context menu option of a transition rule is not necessary. The option was removed (Mantis 6537).
- **Shows More Items** SceneComposer shows more than 5 items as "Recent Solutions" (Mantis 6684).
- **Display Window** Double click on a display in the "Render Targets" panel opens the display window (Mantis 6634).
- **Categories Ordered by Name** In ToolBox, all categories are ordered by name and placed before the elements without a category (Mantis 6638).
- **Log File** The application (SceneComposer) logs the version of all dependent assemblies AND plugins in the log file (Mantis 6823).
- **Import Fonts** The possibility to import fonts was added in the "Text Style Palette" panel, in order to improve the usability (Mantis 5974).
- **Fonts Name** Fonts are now imported using the font name instead of the file name (Mantis 5817).
- **Piece of Information** The user is informed that there are elements which are based on templates and the references will be lost after converting (Mantis 6820).
- **Camera** Scene 2D Editor camera is now reset to fit the objects in the scene instead of a preset default position and zoom (Mantis 6825).

</div></div>---

# Photoshop Exporter

#### Photoshop Exporter

<div class="contents" id="bkmrk-due-to-the-recommend"><div class="contents"><div class="textblock">- Due to the recommendation to create documents with a 72 DPI resolution, the conversion will be done implicitly without any confirmation from the user. In this way, unexpected behavior which may be caused by internally conversion to 72 DPI will be avoided. The exporter scripts requires the resolution of the document to be 72 DPI in order to correctly compute and report the values of some properties of the layers. However, the working document is not affected, because the export (and the conversion) is performed on a copy of it (Mantis 6647 &amp; Mantis 6795).

- Trimming is no longer done on layers with transparent areas. The whole layer bounds are taken from Photoshop.

- The position of the fonts is now calculated on export/import with little differences from the original (Mantis 6802 &amp; 6646).

- Photoshop exporter now exports text with the appropriate effect for Amber platform (Mantis 6821).

</div></div></div>**Known Issues**

<div class="contents" id="bkmrk-photoshop-character-"><div class="textblock">- Photoshop character tracking is not supported, warning has been added in the export log.

- The Photoshop Stroke layer style is not supported in SceneComposer.

</div></div>---