Origin

2D Scene Graph and Nodes 

Chapters

Example Solutions

Back to the top menu

2D Scenes and Nodes

Scene Graph

The 2D scene graph is a tree structure which organizes nodes of type Candera::Node2D. The root of each scene graph has to be a node of type Candera::Scene2D. All nodes of type Candera::Node2D can hold sub nodes added by Candera::Node2D::AddChild().

Nodes of type Candera::RenderNode are representing content which has to be rendered to the target, e.g. text or a bitmap. At least one node of type Candera::Camera2D which is the link to the render target (e.g. a display) has to be part of the scene graph.

RenderNode

Only nodes of type RenderNode are considered during rendering. Each render node requires a list of effects (effect chain) which implements the visual representation of that node. Each render node has a depth value as parameter which defines the order of rendering (z-order). Higher value means background, lower value means foreground.

Transformations

The functionality to define the local coordinate system is derived from Candera::Transformable2D and consists of following components:

This information is always relative to its parent node. Changing one of these parameters affects the presentation of all child nodes. If for example a node is rotated, all child nodes are rotated accordingly. Each nodes rotation, translation (position) and scale values are combined in one transformation matrix which is multiplied with the parent nodes transformation matrix.

Back to the Chapter menu

2D Node Transformations 

2D Node Manipulation Example

To illustrate basic node transformation operations, the NodeManipulationWidget_2D and the DisplayPositionWidget2D part of the Tutorial Widgets cand be used. An usage example for NodeManipulationWidget_2D can be seen in NodeManipulationSolution_2D solution provided in the content folder of cgi_studio_player.

Please consider:

Translations

Once the NodeManipulationWidget_2D is linked with a node from the static scene tree and enabled, the position coordinates can be set in the Player for this property to change the position.

            // Set node position
            m_node->SetPosition(m_position);    // set absolute node position
            // End Set node position

            // Translate node
            m_node->Translate(m_translate);     // translate actual node position
            // End Translate node

Rotations

Similar to translation, rotation can also be applied via Candera::Transformable2D::Rotate or Candera::Transformable2D::SetRotation.

            // Rotate node
            m_node->Rotate(m_rotate);
            // End Rotate node

Scaling

Again there is also a Candera::Transformable2D::Scale and Candera::Transformable::SetScale method.

            // Scale node
            m_node->Scale(m_scale);
            // End Scale node

Pivot Point

It is possible to change your pivot point with the Candera::Transformable2D::TranslatePivotPoint (or Candera::Transformable2D::SetPivotPoint) method. The pivot point can be used to define e.g. the rotation point that the node should rotate around. It affects the scaling too.

How to get the screen space coordinates of a node

With the DisplayPositionWidget2D you can retrieve the screen coordinates of an associated node. Please consider that a node and a camera have to be selected in the widget. In the solution the widget is disabled by default, so if you want to see an output of your display position, you need to enable it. To get the screen space coordinates of an associated node, you simply need to add the render target position of your node to the window position.

Back to the Chapter menu

2D Effects 

Description

Candera2D renders content exclusively by pieces of code which are named effects. Effects represent semantic functionality which considers hardware and driver capabilities.

Chapters

Example Solution

2D Effect Types

Effects can be distinguished in three types of operations:

The effect types can be linked together so that they resemble an Effect Chain. An effect chain consists of one brush effect, zero to n InPlace effects and one blend effect.

Combined Effects

A Combined Effect is a single effect which represents a whole sequence of other effects in an effect chain. For example, if you want to render bitmap data with an alpha function, there usually is a combined effect which represents the Brush Effect and the Blend Effect in one single object.

This single object can take the advantage to perform operation in a single step as the external interfaces (pixel data) can be replaced internally by setting options in the native rendering API.

Refer to Candera::CombinedEffect2D about which CombinedEffects are supported by Candera.

Combined Effects Examples

An example of various effects and how they are configured can be seen in 2DCombinedEffects solution from cgi_studio_player/content/Tutorials/03_SceneGraphAndNodes.

Bitmap Effects

In order to render an image, a BitmapNode with one of the following effects must be set in a 2D scene:

For the above effects, the following properties can be set to obtain different rendering results:

An example of Bitmap effects with different properties is shown below:

Candera::BitmapBrushColorBlend is a combined effect between Candera::BitmapBrushBlend and Candera::BitmapBrushColor. The properties of this effect sum up the properties of the other two. The values for the properties for Candera::BitmapBrushColorBlend used in the example, for left most, centre and right most images, are:

Text Effects

In order to render text, a TextNode with one of the following effects must be set in a 2D scene:

Text, TextColor and Style properties can be set for the above effects. The Font of the text must be set for the Style property.

For Candera::TextBrushBlend , the properties Color Blend Factor and Operation and Alpha Blend Factor and Operation can also be set to obtain different rendering results.

An example of Candera::TextBrushBlend and related properties is shown below:

Brush Effects

The following effects can be used with a RenderNode in a 2D scene:

Fill Color must be set for the above effects.

For Candera::SolidColorBrushBlend, the properties Color Blend Factor and Operation and Alpha Blend Factor and Operation can also be set to obtain different rendering results.

An example of Candera::SolidColorBrushBlend and related properties is shown below:

Mask Effects

As the name suggests, Mask effects allows masking different areas of a given image by applying a mask image with transparent areas.

The following effects can be used with a BitmapNode:

For the above effects, the following properties must be set:

An example of mask effects is presented below:

Left most image has no Mask Node set, therefore the BitmapNode associated with the effect is used. The image from the center has Mask Node set to a RenderNode with Rotation property = -50. Thus, the mask also appears rotated. Right most image has Mask Node set to a RenderNode with different values for Scale property (x= 0,5 ; y = 0,5). Thus, the mask also appears smaller.

The properties Color Blend Factor and Operation and Alpha Blend Factor and Operation can also be set to obtain different rendering results.

Manipulating an Effect on a Render Node

To illustrate effect manipulation operations, the NodeManipulationWidget_2D part of the Tutorial Widgets in combination with the NodeManipulationSolution_2D provided in the content folder of cgi_studio_player can be used.

The type Candera::RenderNode defines a node that shall be rendered. Each render node requires an effect chain, which implements the visual representation of the node.

The following properties manipulate a Candera::SolidColorBrushBlend effect on a render node (this is a already combined effect with brush, inplace and blend):

Manipulating an Effect

First the selected render node (which comes with type Candera::Node2D by the CDAProperty) is casted to a Candera::RenderNode.

    // Cast Node2D to RenderNode
    m_renderNode = Dynamic_Cast<RenderNode*>(node);
    // End Cast Node2D to RenderNode

Next the first effect of the selected render node of type Candera::Effect2D is casted to Candera::SolidColorBrushBlend to get access to specialised properties.

    // Get and cast first effect of render node
    Effect2D* effect2D = node->GetEffect(0);
    SolidColorBrushBlend* effect = Dynamic_Cast<SolidColorBrushBlend*> (effect2D);
    // End Get and cast first effect of render node

Now properties of the effect can be set.

        // Set solid color
        SolidColorBrush& brush = effect->GetSolidColorBrush();
        brush.Color() = m_color;
        // End Set solid color

        // Set fill area
        brush.Size() = m_rect;
        // End Set fill area

The effect should be updated each time a property is changed. A good place for updating the effect might be the widget Update method.

        // Update effect
        static_cast<void>(effect->Update());
        // End Update effect

Arbitrary properties on arbitrary effects can be manipulated the same way.

How to Integrate a Custom Combined Effect into SceneComposer

Integrate a custom effect to Candera and SceneComposer

For DEVICE that would mean to modify cgi_studio_candera/src/CanderaPlatform/Device/DEVICE/2D/DEVICEEffectLibrary.cpp, so that the new effect implementation is included and the Effect2DLibrary MetaInfo is extended by the new effect. (DEVICE stands for your specific device)

How to create a combination of two effects

There are several effects which can be combined to a new effect. How to combine two effects to a new one is shown in Candera::GlBitmapBrushColorMaskBlend implementation.

For the new effect Candera::GlBitmapBrushColorMaskBlend you need a combination of Candera::BitmapBrushColorBlend and Candera::GlBitmapBrushMaskBlend. Create and implement the new effect analogous to Candera::GlBitmapBrushMaskBlend. Now apply following changes:

Back to the Chapter menu

2D Scene Graph Dynamics 

Description

Usually all required nodes are already specified and preconfigured via SceneComposer, so in most cases it won't be necessary to make any adaptations within the scene graph loaded from an asset at runtime.

However, some use cases might require such adaptations. This tutorial covers the most common means to manipulate the scene graph structure dynamically.

Chapters

Example Solution

Adding and Removing 2D Nodes

Scene Graph Dynamics 2D Example

There are some differences between a 2D and a 3D scene graph. This chapter will explain the differences in detail.

For 2D scene graph dynamics, the following examples can be used:

Adding and Removing 2D Nodes

In the widget a RenderNode with text is created and added/removed to/from the 2D scene graph. For adding and removing 2D nodes on the scene graph the following properties can be used:

        CdaProperty(AddToNode, Candera::Node2D*, GetAddToNode, SetAddToNode)
            CdaDescription("Node2D, where a new TextNode shall be added to")
            CdaCategory("Adding and Removing 2D Nodes")
        CdaPropertyEnd()

        CdaProperty(TextNodeFont, Candera::TextRendering::Font, GetTextNodeFont, SetTextNodeFont)
            CdaDescription("Truetype Font of the new TextNode")
            CdaCategory("Adding and Removing 2D Nodes")
        CdaPropertyEnd()

        CdaProperty(AddTextNode, bool, GetAddTextNode, SetAddTextNode)
            CdaDescription("If AddTextNode is enabled, a new TextNode with selected TextNodeFont will be added to the selected AddToNode property. If disabled the new TextNode will be removed.")
            CdaCategory("Adding and Removing 2D Nodes")
        CdaPropertyEnd()

Creating a new Text Node

To display a new text, a new RenderNode is created with a Candera::TextBrushBlend effect.

Candera::TextBrushBlend::Create creates a shared pointer of type Candera::TextBrushBlend, on which properties like text, font and color are set. Then the RenderNode is created and the effect is added.

        Candera::MemoryManagement::SharedPointer<Candera::TextBrushBlend> brush = Candera::TextBrushBlend::Create();
        Candera::MemoryManagement::SharedPointer<Candera::TextRendering::SharedStyle> style = Candera::TextRendering::SharedStyle::Create();

        brush.GetSharedInstance().GetTextBrush().Text().Set("Node Added", 0);
        brush.GetSharedInstance().GetTextBrush().Color().Set(m_ColorTurquoise);

        style.GetSharedInstance().SetDefaultFont(m_font);
        brush.GetSharedInstance().GetTextBrush().Style().Set(style);

        //create and init new RenderNode
        m_addedNode = RenderNode::Create();
        m_addedNode->SetName("AddedNode");
        static_cast<void>(m_addedNode->AddEffect(brush.GetPointerToSharedInstance()));
        m_addedNode->SetPosition(Vector2(259.0F, 296.0F));

Adding Text Node to Scene Graph

Next the text node is uploaded to VRAM and appended to the selected node.

        static_cast<void>(m_addedNode->Upload());
        static_cast<void>(m_addToNode->AddChild(m_addedNode));

Removing and Destructing Text Node

A 2D node can be removed by calling Candera::Node2D::RemoveChild. This is also described in the 3D part of this chapter (see Removing and destructing the Billboard). For removing and completely destructing the node, following code is used:

        static_cast<void>(m_addedNode->Unload());
        m_addedNode->Dispose();
        m_addedNode = 0;

The text node is unloaded from VRAM. The method Candera::Node2D::Dispose removes the node from its parent and frees the resources.

Replacing a 2D Effect

Replacing an Effect

In the SceneGraphDynamicsWidget_2D example, the effect of a Candera::RenderNode can be either replaced by a Candera::SolidColorBrushBlend or a Candera::BitmapBrushBlend effect. Of course the same procedure works for Text effects.

To replace the effect in the example, the following properties can be used:

        CdaProperty(NodeToChange, Candera::Node2D* , GetNodeToChange, SetNodeToChange)
            CdaDescription("Select a RenderNode which effect should be exchanged")
            CdaCategory("Replacing a 2D Effect")
        CdaPropertyEnd()

        CdaProperty(ChangeEffect, bool, GetChangeEffect, SetChangeEffect)
            CdaDescription("Change effect of selected NodeToChange. Set either a SolidColorBrushAlphaBlend (enabled) or BitmapBrushAlphaBlend effect (disabled).")
            CdaCategory("Replacing a 2D Effect")
        CdaPropertyEnd()

Creating a Color Effect

First a new effect is created by creating an instance of Candera::SolidColorBrushBlend.

        Candera::SolidColorBrushBlend::SharedPointer brush = Candera::SolidColorBrushBlend::Create();
        brush->GetSolidColorBrush().Size().Set(m_Rect);
        brush->GetSolidColorBrush().Color().Set(m_ColorBlue);
        brush->GetBlendEffect().SetBlendMode(RenderDevice2D::SourceAlpha, RenderDevice2D::InverseSourceAlpha, RenderDevice2D::Add);

Adding Replacing Effect

Once the effect is created it can be added to the render node. In the following code snippet the selected NodeToChange is casted to a Candera::RenderNode (for this a RenderNode must be selected, otherwise the cast will fail). The first effect of the node is removed via its reference and the new created effect added.

    RenderNode* rn = Dynamic_Cast<RenderNode*>(m_nodeToChange);
    if (rn == 0) {
        return;
    }

    static_cast<void>(rn->Unload());

    //remove old effect
    Effect2D* oldEffect = rn->GetEffect(0);
    static_cast<void>(rn->RemoveEffect(oldEffect));

    //add new effect
    static_cast<void>(rn->AddEffect(effect));
    static_cast<void>(rn->Upload());

Creating a Bitmap Effect

Creating a Candera::BitmapBrushBlend effect is similar to creating other effects (see Creating a Color Effect). Just apply other properties.

        Candera::MemoryManagement::SharedPointer<Candera::BitmapBrushBlend> brush = Candera::BitmapBrushBlend::Create();
        Bitmap::SharedPointer bitmap = Base::GetAssetProvider()->GetBitmapById(CgiAssetNames::cosmosbgBmp);
        if (m_image != 0) {
            static_cast<void>(m_image->SetBitmap(bitmap));
        }
        brush.GetSharedInstance().GetBitmapBrush().Image().Set(m_image);
        brush.GetSharedInstance().GetBlendEffect().SetBlendMode(RenderDevice2D::SourceAlpha, RenderDevice2D::InverseSourceAlpha, RenderDevice2D::Add);

Cloning 2D Nodes 

Cloning 2D nodes is equivalent to cloning of 3D nodes. In accordance to Tree Cloning Strategies, the following support is provided for deep cloning:

Refer to

as well as the example for cloning 3D nodes:

Back to the Chapter menu

Camera / Viewport 

The following example shows the interaction between scene and camera. The objects are placed relatively to the scene origin (which is the root node). The camera defines the view to that scene by defining also a position relative to the scene.

The view port dimensions (width and height) relate to the area on the render target the camera is painting on.

Back to the Chapter menu

2D Layout 

Description

In a typical user interface users need to distribute screen space to different elements. If the size of elements is dynamic, it's desired that the screen space distribution is done automatically based on the contents's natural size. To enable easy arrangement of elements, Candera2D supports layout functionalities.

Chapters

Example Solution

Candera::GridLayouter 

Introduction

Basically, in SceneComposer for each Candera::Group2D a Candera::Layouter can be attached. The attached layouter defines the arrangements of the group's children.

Cell Spanning

Candera::GridLayouter provides a feature that allows joining of adjacent columns and rows into a larger single cell.

Cells can be joined horizontally, vertically or both. In order to achieve this, you must specify Row Span and Column Span properties for elements inside a Candera::GridLayouter:

Example

The Layout2DSolution provided in the content folder of cgi_studio_player gives an example how the 2D layout can be applied in SceneComposer. This section gives just a brief overview on layout features and shows how it looks like.

In the example on the outermost group, a Candera::GridLayouter with 6 rows and 3 columns is defined.

All child nodes, here a bunch of bitmap-, text- and solid-nodes, are arranged along the grid. Each inner grid element can set various dynamic properties which define its size and alignment inside a grid cell.

Layouters can be nested. The outer grid contains a inner grid and two inner stack layouters (Candera::StackLayouter).

The example consists of a grid layouter with fixed size 1280 x 756 px.

The bitmaps in the left column have different alignments (Top-Left, Centered, Bottom-Right). In the inner grid 9 bitmaps are scaled down (by the stretching property) to a fixed element size.

Cell Spanning Example

In the example, below a Candera::GridLayouter with 5 rows and 4 columns defined is used to exemplify how cell spanning is working:

See also:

Candera::BaseLineLayouter 

Introduction

Candera::BaseLineLayouter behaves similar to a Horizontal StackLayouter but instead of aligning the objects to the client area of the Layouter, it aligns them to a line.

The idea is to be able to align text with different sizes in different ways.

Example

The Layout2DSolution provided in the content folder of cgi_studio_player gives an example how the 2D BaseLineLayouter can be applied in SceneComposer.

The baseline can be either fixed or automatic. The automatic baseline is configured such that all the children fit from the top of the client area.

See also:

Candera::OverlayLayouter 

Introduction

A Candera::OverlayLayouter is a container that layouts enfolded nodes by overlaying them in same place in a sorted sequence. With this layouter, elements can be arranged that they fulfill a given area and lay on top of one another.

Example

The Layout2DSolution provided in the content folder of cgi_studio_player gives an example how the OverlayLayouter can be applied in SceneComposer. Some important use cases are:

See also:

Candera::DockPanelLayouter 

Introduction

The Candera::DockPanelLayouter provides an easy docking of elements to the left, right, top, bottom or center of the panel. To dock an element to the center of the panel, it must be the last child of the panel.

Example

The Layout2DSolution provided in the content folder of cgi_studio_player gives an example how the DockPanelLayouter can be applied in SceneComposer.

See also:

Automatic Resize Depending on Content 

Introduction

This tutorial will show how to create resizable dialog popups using a hierarchy of groups and different kind of nodes (bitmap, solid color and text) arranged specifically using layouters.

Examples

Resizable Dialog Using Grid Layouter 

Example Using Grid Layouter

For this example the dialog elements are arranged using Grid and Overlay layouts.

Group Hierarchy

Create the parent group for the pop-up and name it GridDialog. Create another two groups (Background and Content) and add them as children of GridDialog group.

Layout Configuration

Set the layout for each group as shown in the image below:

Configure the column width and row height:

In SceneComposer this can be achieved in the "Grid Layout Editor" (right click on the Background group and select "Configure Layout").

Adding Nodes

The Background group should be populated with bitmap or solid color nodes with the following settings:

The Content group might be filled with one or more nodes of any type, as desired:

Result

After putting everything together the dialog will look as above:

Resizable Dialog Using DockPanel Layouter 

Example Using DockPanel Layouter

For this example the dialog elements are arranged using DockPanel and Overlay layouts.

Group Hierarchy

Create the following structure of groups:

Layout Configuration

Set the layout for each group as shown in the image below:

Adding Nodes

The children groups of Background should be populated with bitmap or solid color nodes with the following settings:

The Content group should be configured as explained in the previous chapter for the dialog based on grid layout with the only difference that the text node will be replaced with a bitmap. Please see the Content group part from the Adding Nodes section.

Result

After putting everything together the dialog will look as above:

Back to the Chapter menu

Candera 2D Listener 

Applications can receive notifications on scene graph events. Therefore implement a listener, which defines hooks to receive those notifications.
Following listener interfaces are provided in Candera 2D:

Example Listener Implementation

Refer to Using Animation Callback Functions for an example how to implement and use an Animation listener.

Back to the Chapter menu