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.

Back to the menu

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);

Back to the menu

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 menu