# Candera Engine 2D

#### Deterministic Render Order

In the past, RenderNodes with the same depth value have been rendered in an order which was dependent on the point of time the node has been added to the scene. The result was that in SceneComposer the render order could look different as when

 loading the scene from the asset on target.

The new implementation ensures that the render order of nodes with the same depth value is defined by the position within the scene tree. Nodes which appear on top of the scene tree (as shown in SceneComposer) are rendered before nodes that are located on the bottom of the scene tree. Therefore the render order is always the same during design on host (SceneComposer) and on target.

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

</div></div></div>#### Cloning Interface

In accordance to basic [Unified Cloning Interface](https://doc316en.candera.eu/link/977#bkmrk-unified-cloning-inte), the following changes have been applied to the affected classes in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") Engine 2D:

<div class="contents" id="bkmrk-cloneself%28cloneopera"><div class="contents"><div class="textblock">- CloneSelf(CloneOperation) protected interface was removed.
- Clone(TraverseOperation, CloneOperation) has become deprecated.
- Copy constructor lost the optional CloneOperation argument.
- Clone() const function was added.

</div></div></div>The cloning interface was applied to:

<div class="contents" id="bkmrk-node2d-and-its-desce"><div class="contents"><div class="textblock">- [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.") and its descendants: [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..."), [CompositeGroup2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group2_d.html "CompositeGroup2D is a Group2D that allows direct access to a number of descendants, called 'anchor points'."), [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."), [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..."), [Scene2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_scene2_d.html "The class Scene2D represents a top level scene graph node. Multiple scenes are allowed. A scene can not be part of any other scene.").
- [Effect2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_effect2_d.html "Base class for all 2D effects which can be added to a 2D RenderNode.") and [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 ...") already define the interface appropriately.

</div></div></div>Special considerations:

<div class="contents" id="bkmrk-general.-descendants"><div class="contents"><div class="textblock">- General. Descendants of [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...") implement deprecated "Node2D\* Clone(Traversing) const" and "Node2D Clone(TraverseOperation, CloneOperation) const" for backward compatibility.
- [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..."). [Camera2DRenderStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera2_d_render_strategy.html "The abstract class Camera2DRenderStrategy is intended to be derived in order to tell the Renderer2D...") and RenderTarget2D are not linked to the clone anymore.
- [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."). [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 ...") is copied during deep node cloning. Because of this [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.") handles the destruction of [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 ...") upon disposing the node.
- [Scene2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_scene2_d.html "The class Scene2D represents a top level scene graph node. Multiple scenes are allowed. A scene can not be part of any other scene."). [Scene2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_scene2_d.html "The class Scene2D represents a top level scene graph node. Multiple scenes are allowed. A scene can not be part of any other scene.") may be cloned. [Scene2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_scene2_d.html "The class Scene2D represents a top level scene graph node. Multiple scenes are allowed. A scene can not be part of any other scene.") render order is not cloned, as it doesn't support different render order bins.

</div></div></div>##### Deep Cloning Interface

In accordance to basic [Tree Cloning Strategies](https://doc316en.candera.eu/link/977#bkmrk-unified-cloning-inte), the following support is provided for deep cloning in 2D as follows:

<div class="contents" id="bkmrk-treecloner2d-is-a-sp"><div class="contents"><div class="textblock">- TreeCloner2D is a specialization for the 2D scene tree of [TreeClonerBase](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_tree_cloner_base.html "This class clones scene subtrees.").
- [DeepNode2DCloneStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_deep_node2_d_clone_strategy.html "This is the default clone strategy for deep cloning.") provides a generic node strategy that clones the delegates the cloning of derived Nodes to specialized strategies.
- [DeepCompositeGroup2DCloneStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_deep_composite_group2_d_clone_strategy.html "This is the default clone strategy for deep cloning composite groups. See DeepNode2DCloneStrategy for...") resolves node binding by use of TreeMatch2D.
- [DeepRenderNodeCloneStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_deep_render_node_clone_strategy.html "This is the default clone strategy for deep cloning render nodes. See DeepNode2DCloneStrategy for rul...") resolves the sharing of effects by use of a map.
- [DeepTreeCloner2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_deep_tree_cloner2_d.html "This class creates deep clones scene subtrees.") is a wrapper of [DeepNode2DCloneStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_deep_node2_d_clone_strategy.html "This is the default clone strategy for deep cloning.") that provides an interface similar to TreeCloner2D.

---

</div></div></div>#### CompositeGroup2D

[CompositeGroup](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group.html "CompositeGroup is a Group that allows direct access to a number of descendants, called 'anchor points...") is a new [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.") type that is usually created by AssetLoader and which contain:

<div class="contents" id="bkmrk-a-list-of-anchorpoin"><div class="contents"><div class="textblock">- a list of AnchorPoints: descendants of the [CompositeGroup2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group2_d.html "CompositeGroup2D is a Group2D that allows direct access to a number of descendants, called 'anchor points'.") that can be accessed directly from the [CompositeGroup2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group2_d.html "CompositeGroup2D is a Group2D that allows direct access to a number of descendants, called 'anchor points'.") instance.
- a list of Widgets that act on any node within the [CompositeGroup2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group2_d.html "CompositeGroup2D is a Group2D that allows direct access to a number of descendants, called 'anchor points'.") subtree.
- a list of AnimationPlayers that act on any node within the [CompositeGroup2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_composite_group2_d.html "CompositeGroup2D is a Group2D that allows direct access to a number of descendants, called 'anchor points'.") subtree.

---

</div></div></div>#### SharedPointer: Deprecated '...Ptr' types

All effect Ptr types like e.g. BitmapBrushPtr are marked as deprecated. Please use e.g. BitmapBrush::SharedPointer instead.

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

</div></div></div>#### Deprecated BaseEffect2DPropertySetter

BaseEffect2DPropertySetter and its derivate classes became deprecated. [Effect2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_effect2_d.html "Base class for all 2D effects which can be added to a 2D RenderNode.") objects, as other objects with attached MetaInfo, can already animate their properties using built-in PropertyMetaInfo AnimationPropertySetters, with an improved performance.

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

</div></div></div>#### AnimationPropertySetters Namespace Correction

All AnimationPropertySetters residing in `<cgi_studio_candera>/src/Candera/Engine2D/AnimationPropertySetters` have been moved from the *[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]")* to the *Candera::Animation* namespace. The following classes are affected by this change:

<div class="contents" id="bkmrk-alphanode2dpropertys"><div class="contents"><div class="textblock">- [AlphaNode2DPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_alpha_node2_d_property_setter.html)
- [BaseNode2DPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_base_node2_d_property_setter.html)
- [BaseTransformable2DPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_base_transformable2_d_property_setter.html)
- [BaseTransformable2DRelativePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_base_transformable2_d_relative_property_setter.html)
- BaseEffect2DPropertySetter
- Effect2DFloatPropertySetter
- [RenderingEnabledNode2DPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_rendering_enabled_node2_d_property_setter.html)
- [Transformable2DRelativeRotatePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_rotate_property_setter.html)
- [Transformable2DRelativeScalePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_scale_property_setter.html)
- [Transformable2DRelativeScaleXPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_scale_x_property_setter.html)
- [Transformable2DRelativeScaleYPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_scale_y_property_setter.html)
- [Transformable2DRelativeTranslatePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_translate_property_setter.html)
- [Transformable2DRelativeTranslateXPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_translate_x_property_setter.html)
- [Transformable2DRelativeTranslateYPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_relative_translate_y_property_setter.html)
- [Transformable2DRotatePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_rotate_property_setter.html)
- [Transformable2DScalePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_scale_property_setter.html)
- [Transformable2DScaleXPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_scale_x_property_setter.html)
- [Transformable2DScaleYPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_scale_y_property_setter.html)
- [Transformable2DTranslatePropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_translate_property_setter.html)
- [Transformable2DTranslateXPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_translate_x_property_setter.html)
- [Transformable2DTranslateYPropertySetter](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_animation_1_1_transformable2_d_translate_y_property_setter.html)

<dl class="note"></dl></div></div></div><p class="callout info">Moved classes are still accessible via the Candera namespace in CGI-Studio 3.0.0 but these deprecated interfaces will be removed in the next release.</p>

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

</div></div></div>#### Candera2D Bitmap MipMap Flag

Candera2D internally uses MipMapping for Bitmaps, as long as OpenGL is used to render. Whereas this measure typically improves image quality, MipMaps consume ~1/3 more memory and might bear side effects (interpolation between MipMap levels may produce artifacts). Therefore a MipMapEnabled flag has been added.

<div class="contents" id="bkmrk-see-also%3A-candera%3A%3Ab"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>Candera::Bitmap::SetMipMappingEnabled() and Candera::Bitmap::IsMipMappingEnabled().</dd></dl>---

</div></div></div>#### Camera2D Viewport Transformation functions moved

Viewport transformation functions have been moved from [Candera::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...") to new class [Candera::Math2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_math2_d.html "The Math2D class for 2D transformation and helper functions."). Picking in 2D considers window offset.

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

</div></div></div>#### Reduced size of members

To reduce heap usage some elements in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") 2D have been reduced in size:

<div class="contents" id="bkmrk-the-camera-sequence-"><div class="contents"><div class="textblock">- The camera sequence number from 32 to 16 bit, <dl class="see"><dt>**See also:**</dt><dd>[Candera::Camera2D::SetSequenceNumber(Int16 sequenceNumber)](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_camera2_d.html#a86f661bc6f4dd115e9e13a2f9efb0291)</dd></dl>
- The bitmap width and height from 32 to 16 bit, <dl class="see"><dt>**See also:**</dt><dd>[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...")</dd></dl>
- The child count 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.") from 32 to 16 bit, <dl class="see"><dt>**See also:**</dt><dd>[Candera::Node2D::GetChildCount()](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_node2_d.html#aa3c00fa2c52103b48c400b13c1bd47ae)</dd></dl>

---

</div></div></div>#### DeviceObject2D listener.

[DeviceObject2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_device_object2_d.html "DeviceObject2D is the pure abstract base class for all objects which are able to upload or unload its...") now supports adding listeners that are notified before and after the object is uploaded and unloaded and before it is destroyied.

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

</div></div></div>#### Layout Rectangle

The Layout is no longer done based on bounding rectangle. Instead, [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.") has a new property, layout rectangle. Bouding rectangle is used for picking and dirty area management. Computed layout and bounding rectangle are based on affect layout and bounding rectangle, respectively.

<div class="contents" id="bkmrk-see-also%3A-node2d%3A%3Ase"><div class="contents"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>Node2D::SetLayoutingRectangle() and [Candera::Effect2D::GetLayoutingRectangle()](http://dev.doc.cgistudio.at/APILINK/group___effects2_d.html#gafa31c551c09efb1c6ccfb9540e34e1ac). [Candera::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.") uses new [Layout](http://dev.doc.cgistudio.at/APILINK/group___layout.html "Layout features.") Rectangle instead of Bounding Rectangle for layout.</dd></dl></div></div></div>[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...") and TextBrushCaches compute their Layout Rectangle based on Text Cursor Position. MaximumSize property of [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...") has been replaced by [CacheArea](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_brush.html#a8bd385827d4edfd56dbfd8a0b4eb5fde). Bounding Box and Cache Size have been decoupled from Layout. To retrieve the height of a [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...") with ConstantHeight use GetLayoutingRectangle, and for ActualHeight use GetBoundingRectangle.

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

</div></div></div>#### Renderer2DListener

A [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.") allows to listen to Renderer-Events in Candera2D like in [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") 3D with [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.").

---