CGI Studio 3.0.0

• Candera V3.0.0
• Overview
• Candera Engine 3D
• Candera Engine 2D
• Candera Base
• Candera System
• Candera Device
• Candera AssetLoader
• Text Engine
• Candera V3.0.0 Migration Guide
• Courier V3.0.0
• FeatStd V3.0.0
• FeatStd CMake Switches
• FeatStd Diagnostics
• FeatStd Memory Management
• FeatStd Memory Pool
• FeatStd Monitor
• FeatStd Util
• SceneComposer V3.0.0
• Candera Related Features
• SceneComposer Usability Improvements
• SceneComposer Known Issues
• Import from Photoshop

Candera V3.0.0

Overview

Release Info

Interface Changes

Migration Guide and Backwards Compatibility

In CGI Studio V3.0.0, deprecated interfaces from CGI Studio V2.10.0 can still be used to a large extent, while deprecation functions for interfaces from releases before V2.10.0 have been removed completely.

Refer to:

Candera Engine 3D

OpenGL ES 3.0 Support

RenderDevice for OpenGL ES 3.0

In order to support OpenGL ES 3.0 a new RenderDevice.cpp has been added, which implements RenderDevice.h with OpenGL ES 3.0 functions. Additionally GlInclude.h, GlTraceMapper and GlTypeMapper have been adapted to support the split of one RenderDevice into several ones for multiple GLES versions. GlTraces are now all displayed under Gles device (instead of Gles20).

For current device packages OpenGL ES 2.0 is still used. If it is supported by a device, usage of OpenGL ES 3.0 can easily be configured in Device.cmake. Simply include Common/OpenGLES30 instead of Common/OpenGLES20 and add the following line to the CMake file.

CgiAddDefinitions( -DCGIDEVICE_OPENGLES_30 )

Synchronization for OpenGL ES 3.0

The OpenGL ES 3.0 render device uses core OpenGL ES 3.0 fences for synchronization, instead of EGL extension EGL_KHR_fence_sync.

OpenGL ES 3.0 Support for Linux OpenGLAdapter

OpenGLAdapter for Linux hosts now also supports OpenGL ES 3.0 interface (based on GLX and OpenGL 3.0).

OpenGL ES 3.0 ETC2/EAC Texture Compression

OpenGL ES 3.0 introduces ETC2/EAC texture compression as part of the core standard. This enables all OpenGL ES 3.0 capable devices to reduce VRAM and memory bandwidth usage per texture at unnoticeable reduction of image quality, allowing either higher framerates or more and bigger textures used simultaneously.

Candera now supports this feature in the OpenGL ES 3.0 render device. For this purpose Bitmap class has been changed (see Changes in Bitmap Enumerations). The new Bitmap::PixelFormat enumerator has to be used for texture uploading.

See also:

Cloning Interface

In accordance to basic Unified Cloning Interface, the following changes have been applied to the affected classes in Candera 3D:

The cloning interface was applied to:

Special considerations:

Deep Cloning Interface

In accordance to basic Tree Cloning Strategies, the following support is provided for deep cloning in 3D as follows:

CompositeGroup

CompositeGroup is a new Node type that is usually created by AssetLoader and which contain:

Picking Test: Consistent Behavior for deep and flat Picking

In both cases Node::IsPickIntersectingGeometry only returns true for a tested node if it is hit by the intersection ray AND Node::IsEffectiveIntersectionTestEnabled is true.

DeviceObject Listener

DeviceObject now supports adding listeners that are notified before and after the object is uploaded and unloaded and before it is destroyed.

Upload to Multiple Contexts

Device Objects of a Node (and its descendants) can be uploaded to all render target contexts belonging to the cameras the nodes are in scope of.

ExternalTextureImage

Added ExternalTextureImage which is a texture image that allows wrapping external created native texture objects.

Car Paint Shaders added

The following reference shaders have been added:

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.

Cloning Interface

In accordance to basic Unified Cloning Interface, the following changes have been applied to the affected classes in Candera Engine 2D:

The cloning interface was applied to:

Special considerations:

Deep Cloning Interface

In accordance to basic Tree Cloning Strategies, the following support is provided for deep cloning in 2D as follows:

CompositeGroup2D

CompositeGroup is a new Node2D type that is usually created by AssetLoader and which contain:

SharedPointer: Deprecated '...Ptr' types

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

Deprecated BaseEffect2DPropertySetter

BaseEffect2DPropertySetter and its derivate classes became deprecated. Effect2D objects, as other objects with attached MetaInfo, can already animate their properties using built-in PropertyMetaInfo AnimationPropertySetters, with an improved performance.

AnimationPropertySetters Namespace Correction

All AnimationPropertySetters residing in <cgi_studio_candera>/src/Candera/Engine2D/AnimationPropertySetters have been moved from the Candera to the Candera::Animation namespace. The following classes are affected by this change:

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.

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.

Camera2D Viewport Transformation functions moved

Viewport transformation functions have been moved from Candera::Camera2D to new class Candera::Math2D. Picking in 2D considers window offset.

Reduced size of members

To reduce heap usage some elements in Candera 2D have been reduced in size:

DeviceObject2D listener.

DeviceObject2D now supports adding listeners that are notified before and after the object is uploaded and unloaded and before it is destroyied.

Layout Rectangle

The Layout is no longer done based on bounding rectangle. Instead, Node2D 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.

TextBrush and TextBrushCaches compute their Layout Rectangle based on Text Cursor Position. MaximumSize property of TextBrush has been replaced by CacheArea. Bounding Box and Cache Size have been decoupled from Layout. To retrieve the height of a TextBrush with ConstantHeight use GetLayoutingRectangle, and for ActualHeight use GetBoundingRectangle.

Renderer2DListener

A Renderer2DListener allows to listen to Renderer-Events in Candera2D like in Candera 3D with RendererListener.

Candera Base

Camera Groups

CameraGroup is a container that groups cameras from multiple scenes. CameraGroup has an arbitrary number of 2D and/or 3D cameras from different scenes and it is used by applications to easily access and change camera settings uniformly, e.g. in transitions.

Unified Cloning Interface

Base classes implement a virtual "Clone() const" method, which is overridden in all children. "Clone() const" builds a new instance of the class using the copy constructor. Copy constructors are protected for use only in derived copy constructors. Copying via assignment operator is prohibited, as it could cause problems, like orphaned nodes, memory leaks or dangling pointers. Assignment operators are thus private.

Cloning is shallow, with only shared pointers and constant character pointers being copied. All other coupling via pointers is broken for the clones.

For more complex cloning see Tree Cloner and Tree Cloning Strategies.

Tree Cloner

TreeClonerBase is provided for cloning trees. The default clone strategy is to call the Clone interface on each node, and build the clone tree with the same node pattern as the original tree. For deeper cloning, TreeClonerBase supports attaching a TreeCloneStrategy. This TreeCloneStrategy is typically aware of different types of nodes, and delegates to other strategies.

Tree Cloning Strategies

The deep cloning strategies respect the following rules:

Bitmap as SharedPointer

Instances of class Bitmap can only be created by calling static method Bitmap::Create() which returns a SharedPointer.

All interfaces have been changed to pass the shared pointer and the corresponding disposer function has been removed from the interfaces.

Old interface (example):

void BitmapImage2D::SetBitmap(Bitmap* bitmap, BitmapDisposerFn disposerFn);

New interface (example):

void BitmapImage2D::SetBitmap(Bitmap::SharedPointer bitmap);

Changes in Bitmap Enumerations

Until now, Bitmap class described the organization of the pixels with the enumerators Bitmap::Format and Bitmap::Type.

With introducing OpenGL ES 3.0 ETC2/EAC Texture Compression, it came up that the bitmap description was not suitable for describing compressed images (which have a format descriptor, but no type descriptor). Another problem was that the Bitmap class allowed invalid combinations of Format and Type, e.g. Bitmap::Format::RgbFormat (3 components) and UnsignedShort4444Type (4 components).

In order to enable compressed bitmaps and to avoid invalid combinations the enumerator Bitmap::PixelFormat has been introduced, here Format and Type have been merged to valid enumeration items, while the ETC2/EAC items have been added.

For this reason Bitmap::Format and Bitmap::Type have become deprecated. Of course it is still possible to use custom formats.

Shared Pointer Concept in Animation Framework

Objects of the following classes can only be created by calling static method Create() which returns a SharedPointer:

All interfaces have been changed to pass the shared pointer and the corresponding disposer function has been removed from the interfaces.

Old interface (example):

void AnimationPlayer::SetController(AnimationController* controller, DisposerFn disposerFn = 0);

New interface (example):

void AnimationPlayer::SetController(AnimationController::SharedPointer controller);

TreeTraverserBase for 'const' Traversing

Interface of template class TreeTraverserBase has been changed to use only Traverse() and ProcessNode(). TraverseConst() and ProcessConstNode() have been removed. This ensures type safe const correct usage but enforce all const-traverser implementations to be changed. Const traversers have to be defined the following way:

class MyTraverser : public TreeTraverserBase<const Node> {
    protected:
        virtual TraverserAction ProcessNode(const Node& node)
        {
        ...
        }
};

Candera::Animation Namespace extension

Classes and Types located in <cgi_studio_candera>/src/Candera/EngineBase/Animation which formerly belonged to the Candera namespace were reassigned to the Candera::Animation namespace.

Affected classes/types:

Moved classes and types are still accessible via the Candera namespace in CGI-Studio 3.0.0 but these deprecated interfaces will be removed in the next release.

CanderaObject becomes DynamicPropertyHost

CanderaObject inherits from DynamicPropertyHost. Objects previously inheriting from DynamicPropertyHost now inherit from CanderaObject. ApplicationData is deprecated. The DynamicPropertyHost allows to attach multiple application data objects.

Candera System

Property Validation

A new macro CdaValidityTest allows the definition of a validation function for Widget, Effect2D and Gdu properties. In case of failed validation the property will be highlighted in SceneComposer property list and an error message will be displayed.

Candera Device

Automatic Context Resource Pools

Context resource pools are created automatically, and assigned automatically to Device objects. If all objects attached to a display share a context resource pool, the display is associated to the context resource pool. Otherwise, the display has a null context resource pool. The interface for replacing context resource pools on the display is deprecated. So is the interface for manually creating context resource pools.

Layout Rectangle of Effects

Effect2D has an interface to compute the layout rectangle. Layout rectangle is the same as bounding rectangle for non-text effects. For text effects the layout rectangle is given by CursorTextMeasureContext, and bounding rectangle is given by GlyphTextMeasureContext. ActualHight parameter of TextBrush has been removed. Text is now always constant aligned. Applications need to compensate for this parameter by moving the pivot of the node by the offset of the bounding rectangle.

RenderTarget Auto Clearing

Added auto clear flag (RenderTarget::SetAutoClearEnabled and RenderTarget::IsAutoClearEnabled) to Candera::RenderTarget2D / Candera::RenderTarget3D. This flag, unlike the auto swap, does not alter the clear setting of the Camera/Camera2D, but assures that the RenderTarget is cleared automatically before the first camera renders.

Further changes in detail:

Warping Orientation

The orientation of the display to use during warping can be set on the Display.

Warping Image Bounds

In previous versions the warped image was not restricted to bitmap image bounds. The function Display::SetWarpImageBounds() has to be invoked before function Display::SetWarpMatrix() is called.

GraphicDeviceUnit Name

A name may be attached to a Graphic Device Unit.

Candera AssetLoader

AssetDescriptor

AssetContext class has become deprecated and its functionality is taken by the new AssetDescriptor class.

Old Interface:

Candera::DefaultAssetProvider* provider = m_assetProvider;
Candera::AssetContext* assetContext = provider->GetAssetContext();
if (assetContext != 0) {
    for (Int i = 0; i < assetContext->GetAnimationCount(); i++) {
        const Candera::Char* animation = assetContext->GetAnimationName(i);
        //Use animation name
    }
}

New Interface in 3.0.0:

Candera::DefaultAssetProvider* provider = m_assetProvider;
for (Candera::AssetDescriptor::AssetIdIterator animationIdIterator =  provider->GetAssetDescriptor().GetAssetIdIterator(AnimationLib); animationIdIterator.IsValid(); ++animationIdIterator) {
    //use animation AssetId: *animationIdIterator
    //or use animation name: provider->GetNameById(AnimationLib, *animationIdIterator, 0)
}

AssetId

AssetId is a unique binary identifier that should be used to retrieve objects from the asset though the AssetProvider interface. AssetIds are supposed to replace the identification of objects by their name/path.

AssetIds should not be hard coded, but referenced through Symbolic Names. For more information see Accessing Items via AssetId. AssetIds can also be retrieved via the AssetDescriptor class iterators as shown in the AssetDescriptor example above.

Old Interface:

Candera::DefaultAssetProvider* provider = m_assetProvider;
Bitmap::SharedPointer bitmap = provider->GetBitmap(bitmapName);            

New Interface in 3.0.0:

Candera::DefaultAssetProvider* provider = m_assetProvider;
 //copy AssetId directly from SceneComposer, but better use specified symbolic name or retrieve it via AssetIdIterator
AssetId assetId = CDA_LIBRARY_ASSETID(0x0, 0x100);
Bitmap::SharedPointer bitmap = provider->GetBitmapById(assetId);

Text Engine

Text Alignment

Enumeration type TextAlignment has been replaced by new enum types HorizontalAlignment and VerticalAlignment.

Integrated FreeType 2.5

The following new options are available for configuration from CMake:

RgbColor deprecated

The class Candera::TextRendering::RgbColor has been deprecated. Candera::Color shall be used instead.

Text Measure Context

TextRenderer::GetBoundingRectangle is deprecated. Instead TextMeasureContext is available to provide similar functionality, in a more configurable manner. GlyphTextMeasureContext is a class provided to emulate the behavior of GetBoundingRectangle for ActualHeight alignment parameter. The rectangle returned by this class may be offset from the text position. To have the same alignment as before when rendering the text, the inverse of this offset needs to be applied. CursorTextMeasureContext is a class provided to emulate the behavior of GetBoundingRectangle for ConstantHeight alignment parameter. The rectangle returned by this class does not usually have an offset and it contains the final advancement of the cursor. From the two rectangles, all values returned by GetBoundingRectangle may be computed.

Candera V3.0.0 Migration Guide

Following a guide how to uprade application code from V2.10.0 to V3.0.0 Candera Interfaces.

Besides interface changes, also the build system has been changed significantly in V3.0.0:

Regular Expression Search and Replace Patterns

Migration Guide for Backward Compatible Interface Changes

This page provides an overview about interface changes between Candera V2.10.0 and Candera V3.0.0, which are backward compatible.

Interface Changes with Deprecations

These changes do not require immediate adaptation of existing code. Although deprecated interfaces are still accessible, consider switching to the new interfaces as the deprecated interfaces will be removed with the next release.

Leading
Middle
Trailing

HLeft
HCenter
HRight

VTop
VCenter
VBottom

BitmapBrushPtr

BitmapBrush::SharedPointer

class MyTraverser : public TreeTraverserBase<Node> {
    protected:
        virtual TraverserAction ProcessConstNode(const Node& node)
        {
        ...
        }
};

class MyTraverser : public TreeTraverserBase<const Node> {
    protected:
        virtual TraverserAction ProcessNode(const Node& node)
        {
        ...
        }
};

Candera::DefaultAssetProvider* provider = m_assetProvider;
Candera::AssetContext* assetContext = provider->GetAssetContext();
if (assetContext != 0) {
    for (Int i = 0; i < assetContext->GetAnimationCount(); i++) {
        const Candera::Char* animation = assetContext->GetAnimationName(i);
        //Use animation name
    }
}

Candera::DefaultAssetProvider* provider = m_assetProvider;
for (Candera::AssetDescriptor::AssetIdIterator animationIdIterator =  
        provider->GetAssetDescriptor().GetAssetIdIterator(AnimationLib);
        animationIdIterator.IsValid(); ++animationIdIterator) {
    //use animation AssetId: *animationIdIterator
    //or use animation name: provider->GetNameById(AnimationLib, *animationIdIterator, 0)}

Bitmap::SharedPointer bitmap= Base::GetAssetProvider()->GetBitmap("MyModule#Imports#Models#myBmp");

#include "MyAssets.h"
Bitmap::SharedPointer bitmap = Base::GetAssetProvider()->GetBitmapById(CgiAssetNames::myBmp);

Candera::InterpolationStrategy* interpolationStrategy =
       Candera::LinearInterpolationStrategy::Create();

Animation::InterpolationStrategy::SharedPointer interpolationStrategy =
       Animation::LinearInterpolationStrategy::Create();

using namespace CgiWidgetLibrary;

Node* clone = node->Clone();

Node* clone = node->Clone(Node::Flat);

Node* clone = node->Clone();

Node* clone = node->Clone(Node::Deep);

Node* clone = TreeCloner().CreateClone(*node);

Node2D* clone = node->Clone();

Node2D* clone = node->Clone(Node2D::Flat);

Node2D* clone = node->Clone(TraverseFlat, CloneShallow);

Node2D* clone = node->Clone();

UInt8* pixels = GetBitmapDataFromArbitrarySource(); //exemplary
Bitmap* bitmap = &Bitmap(128, 128, 
    Bitmap::RgbaFormat, Bitmap::UnsignedByteType,
    Bitmap::PackAlignment1, pixels, 0,
    true, true);

UInt8* pixels = GetBitmapDataFromArbitrarySource(); //exemplary
Bitmap* bitmap = &Bitmap(128, 128, 
    Bitmap::RgbaUnsignedBytePixelFormat,
    Bitmap::PackAlignment1, pixels, 0,0,
    true, true);

bound = textRenderer.GetBoudingRectangle(layoutingOptions, shapingOptions, textProperties,
                        MeasuringOptions(ExcludeFinalAdvance, ActualTransversalSize));

GlyphTextMeasureContext context;
textRenderer.Render(context, layoutingOptions, shapingOptions, textProperties);
bound = context.GetTextRectangle();

bound = textRenderer.GetBoudingRectangle(layoutingOptions, shapingOptions, textProperties,
                        MeasuringOptions(IncludeFinalAdvance, ActualTransversalSize));

CursorTextMeasureContext cursorContext;
GlyphTextMeasureContext glyphContext;
glyphContext.SetNextContext(&cursorContext);
textRenderer.Render(glyphContext, layoutingOptions, shapingOptions, textProperties);
glyphBound = glyphContext.GetTextRectangle();
cursorBound = cursorContext.GetTextRectangle();
bound = Rectangle(
    glyphBound.GetLeft(),
    glyphBound.GetTop(),
    Math::Maximum(
        cursorBound.GetWidth() - glyphBound.GetLeft(),
        glyphBound.GetWidth()),
    glyphBound.GetHeight());

bound = textRenderer.GetBoudingRectangle(layoutingOptions, shapingOptions, textProperties, 
                        MeasuringOptions(IncludeFinalAdvance, ContantTransversalSize));

CursorTextMeasureContext cursorContext;
GlyphTextMeasureContext glyphContext;
glyphContext.SetNextContext(&cursorContext);
textRenderer.Render(glyphContext, layoutingOptions, shapingOptions, textProperties);
glyphBound = glyphContext.GetTextRectangle();
cursorBound = cursorContext.GetTextRectangle();
bound = Rectangle(
    glyphBound.GetLeft(),
    cursorBound.GetTop(),
    glyphBound.GetWidth()),
    cursorBound.GetHeight());

bound = textRenderer.GetBoudingRectangle(layoutingOptions, shapingOptions, textProperties, 
                        MeasuringOptions(IncludeFinalAdvance, ContantTransversalSize));

CursorTextMeasureContext cursorContext;
GlyphTextMeasureContext glyphContext;
glyphContext.SetNextContext(&cursorContext);
textRenderer.Render(glyphContext, layoutingOptions, shapingOptions, textProperties);
glyphBound = glyphContext.GetTextRectangle();
cursorBound = cursorContext.GetTextRectangle();
bound = Rectangle(
    glyphBound.GetLeft(),
    cursorBound.GetTop(),
    Math::Maximum(
        cursorBound.GetWidth() - glyphBound.GetLeft(),
        glyphBound.GetWidth()),
    cursorBound.GetHeight());

Extended Interfaces

These changes extend existing interfaces by adding new functionality and do not require any adaptation of existing code. However, custom implementations may be replaced by these library functions.

Node* clone = node->Clone();
DeepNodeCloneStrategy cloneStrategy;
DeepNodeCloneStrategy::Pair pair(node, clone);
cloneStrategy.Execute(pair, pair);

Node* clone = DeepTreeCloner().CreateClone(*node);

TreeCloner treeCloner;
DeepNodeCloneStrategy cloneStrategy;
treeCloner.SetNodeCloneStrategy(&cloneStrategy);
Node* clone = treeCloner.CreateClone(*node);

Header File Relocations

In CGI Studio 2.x, some functionality had been moved from Candera into FeatStd, keeping redirection macros and header files for backward compatibility. In CGI Studio 3.0.0, redirection code has been removed to a large extent. Following is an overview about macros and header files that will be removed.

Candera/System/Diagnostics Cleanup

To ensure backward compatibility, macros and files formerly located in Candera/System/Diagnostics can still be accessed in CGI-Studio V3.0.0 . Please be aware that this access will be removed with the next release.

Header files from Candera/Systems/Diagnostics which only represented redirections to files located in FeatStd should no longer be used.
Please use respective files in FeatStd/Diagnostics and the namespace Featstd::Diagnostics instead.

Similarly, all macros contained in files located in Candera/System/Diagnostics which only served as redirection to macros located in FeatStd should not be used any more.

Migration Guide for Breaking Interface Changes

These changes are incompatible with earlier versions of Candera and will require immediate adaptation of existing code.

Interface Changes without Deprecations

AnimationController* animController = AnimationController::Create();
AnimationTimeDispatcher* animDispatcher = AnimationTimeDispatcher::Create();
InterpolationStrategy* interpolationStrategy = SplineInterpolationStrategy::Create();
BackEaseFunction backEase;

AnimationController::SharedPointer animController = AnimationController::Create();
AnimationTimeDispatcher::SharedPointer animDispatcher = AnimationTimeDispatcher::Create();
InterpolationStrategy::SharedPointer interpolationStrategy = SplineInterpolationStrategy::Create();
BackEaseFunction::SharedPointer backEase = BackEaseFunction::Create();

Candera::Transformable2DTranslateYPropertySetter transitionPS();
Candera::MaterialPropertySetter materialPS();

Candera::Transformable2DTranslateYPropertySetter::SharedPointer transitionPS = Transformable2DTranslateYPropertySetter::Create();
Candera::MaterialPropertySetter::SharedPointer materialPS = MaterialPropertySetter::Create();

Bitmap* bmp = CANDERA_NEW(...);
CANDERA_DELETE(bmp);
bmp = 0;

Bitmap::SharedPointer bmp = Bitmap::Create(...);
// no manual destruction
// no need to set to zero / NULL

Bitmap bitmap(...);

Bitmap::SharedPointer bitmap = Bitmap::Create(...);

BitmapTextureImage textureImage = BitmapTextureImage::Create();
Bitmap bitmap = CANDERA_NEW(Bitmap)(...);
textureImage->SetBitmap(bitmap, 0);

BitmapTextureImage textureImage = BitmapTextureImage::Create();
Bitmap::SharedPointer bitmap = Bitmap::Create(...);
textureImage->SetBitmap(bitmap);

Header File Relocations

In CGI Studio 2.x, some functionality had been moved from Candera into FeatStd, keeping redirection macros and header files for backward compatibility. In CGI Studio 3.0.0, redirection code has been removed to a large extent. Following is an overview about removed macros and header files.

CanderaPlatform/OS Cleanup

Candera TimePlatform

Candera/FeatStd Build System Changes

Library Changes

Candera base feature libraries have been joined into the new common library called Candera.lib. The following libraries from CGI-Studio V2.x no longer exist separately:

CMake Switch Name Modification

The names of almost all CMake switches used in CGI-Studio V2.x have been revised to improve effect and feature association. The feature name now reflects, to which component the feature belongs to.

Please be aware, that even though the CMake Switch names and preprocessor defines from CGI-Studio V2.x still work in CGI-Studio V3.0.0, this backward compatibility is going to be removed with the next release.

Candera CMake Switch Changes

FeatStd CMake Switch Changes

Regular Expression Search and Replace Patterns

The following Regular Expression Search & Replace patterns may be used to quickly apply changes to existing source code. They aim at fixing many (breaking) changes introduced with the new version of Candera. However, as simple text replacement with regular expressions is used, corrections which resulted from applying these patterns may be incorrect in some situations. Therefore, the patterns are just provided as-is in the hope that they may be useful for code migration.

To apply the patterns Notepad++ or any other compatible Regular Expression Search & Replace tool can be used. When using Notepad++ please make sure to select the search method "Regular expression" and check "Match case".

Patterns for Fixing Breaking Changes

Patterns for fixing backward compatible changes

Courier V3.0.0

3.0.0-1 Courier CMake Switches

3.0.0-2 Data Binding Changes

The following changes have been made:

3.0.0-3 Visualization Changes

The following changes have been made:

3.0.0-4 AddOns Changes

The following changes have been made:

FeatStd V3.0.0

FeatStd CMake Switches

FeatStd Diagnostics

MemoryAppender added

MemoryAppender is added which allows logging events to a buffer in memory.

FeatStd Memory Management

Removed Sharing Object

The outdated and orphaned file SharingObject.h has been removed.

Retain Count atomic and uncopyable

The retain count of shared objects - enabled by macro "FEATSTD_SHARED_POINTER_DECLARATION" - has been made atomic to make increments and decrements thread-safe. Additionally the retain count has been made uncopyable to avoid copying the retain count when cloning shared objects.

FeatStd Memory Pool

Enforce Initialization of BackingHeap

Initialization of BackingHeap (MallocBackingHeap) is enforced. BackingHeap initializations are reference counted and missing initialization will assert. This is to detect missing initialization early, even if MallocBackingHeap does not require Init (but switching to other BackingHeap will cause crashes then). A new parameter in BackingHeap::Destroy() / MallocBackingHeap::Destroy() forces the destruction of the heap (even if init counter is larger 1).

FeatStd Monitor

Monitor module migrated from Candera

The Candera module CanderaMonitor has been migrated to FeatStd.

FeatStd Util

String Ids for translatable Text

A new class TextId has been added for accessing translatable texts from a string.

SceneComposer V3.0.0

Candera Related Features

Array Editor

Array properties are now supported for dynamic items (widget, effect, render target and layouter). Special editors are available in properties panel for changing the value.

See also:

Candera Driven Validation

A new feature was added which enables Candera engine to validate the content from SceneComposer. For each dynamic property of widgets, effects, render targets or layouters, Candera engine can generate a problem message (error or warning). This message is displayed in the problems panel and also as a tooltip in the properties panel for the item on which the property is set.

If an item has properties with Error problems, the asset is not generated for it.

See also:

Camera Groups

The purpose of this work package is to support the creation of camera groups and to offer extended support for display visualization by enabling/disabling camera groups. In Candera, a CameraGroups is a class containing a list of Camera2D and Camera3D objects.

The camera groups were added and they allow the user to group together cameras from the entire solution. The camera groups are displays in a tab or the render targets explorer panel.

Widgets can be associated to camera groups (widget property of type CameraGroup* is supported). However, the widget should not modify the state of the camera group (shall not add or remove cameras)

See also:

Composite Animations

The Composite Animation was Removed. An animation can now contain animated properties for composites and scenes (they can also be mixed).

See also:

Clear Mode

A new item of type "Clear Mode" can be created in SceneComposer and referenced from any render target.

See also:

Items AssetId

All items in a solution have a type and a name which identifies them in their parent container and a full name which uniquely identifies them in the entire solution (for example a mesh in a scene could have the full name /Global/Scenes/MyScene/Group:RootNode/Mesh:MyMesh).

Similar to the full name which identifies the items in the solution, for Candera there is a CanderaPath which uniquely identifies an item in an asset file (for example the mesh mentioned above will be referenced in Candera using the path /Scene:Global::Scenes::MyScene/Group:RootNode/Mesh:MyMesh). Such a string will have to be stored in the asset library for animations or widgets which reference scene nodes. Also it will be processed every time the scene is loaded.

Candera does not have the concept of solution folders, so in order to distinguish between items with the same name but located in different solution folders the CanderaName property of the items contain also the name of the folders (for example the scene /Global/Scenes/MyScene will have the CanderaName Global::Scenes::MyScene).

To improve the performance we introduced another way to identify items using numerical Ids instead of strings.

See also:

EGL Context Sharing

A Context Resource Pool (CRP) is used to share resources among different Context Providers. It allows grouping of render targets and associated device objects (Shaders, Texture Images, Vertex Buffers, etc.) in a common pool.

Each platform has some rules and restrictions related to CRPs, for example on some platform multiple displays can share the same CRP, while on some other platform a CRP is required for each Window Surface. SceneComposer displays the relationship between CRPs, Displays, Window Surfaces and Frame Buffer Objects in the Render Target Explorer panel (main view and an additional CRP view). Depending on the platform, the texture render targets (frame buffer objects) may have an Owner property of type render target reference or CRP.

If the type of the Owner property is render target reference, the owner must be a display render target (window surface).

If the type of the Owner property is CRP (integer value in SceneComposer), the possible values will be obtained from the available displays.

If the Owner property is available for a render target but it is not set by the user, the render target will be considered orphan.

See also:

BitmapFormat and BitmapType

These properties were made obsolete and their value were merged into PixelFormat which contains only the valid combinations of the former properties.

SceneComposer Usability Improvements

Reusable Solution Library

The main goal of a shareable component library (SCL) solution is to make all the resources from a particular SCS solution available to be used in other solutions. SceneComposer provides the possibility to reuse any part from a solution that is exported as a SCL.

See also:

Appearance Wrapper

In some circumstances it could be necessary to expose for the user just those properties which should be modified to get a desired setting of an object. The Appearance Wrapper feature allows to expose only some properties of an appearance attached to a node or the properties pertaining to its containments (material, render node, shader, uniform setter, texture).

See also:

Shader Details

Shader requirements are now available in SceneComposer. This includes the number of lights, materials and textures. They are displayed in a new tab "Details" in the Property Grid, when a shader program is selected. The tab also contains the available attributes and uniforms.

See also:

Problem Viewer Extensions

Due to the huge quantity of informations which can be displayed on the Problems browser, it is possible to suppress warnings or messages solely related to imported content.

To get focused on problems related to SceneComposer solution configuration, many changes were made related to problem management:

See also:

Bitmap Usage Validation

Custom formats available for each bitmap converter will have an additional property to specify for which engine are they supported (Candera2D, Candera3D, Mixed). This information is displayed in the properties panel of the BitmapProfile used by the Bitmap (see property CanderaModelType). During validation of the solution, if CanderaModelType of the bitmap profile used by the bitmap does not match the texture, effect, widget, a warning will be displayed (Mantis 4461).

See also:

Activate Referenced Items

The possibility to activate items referenced through paths has been added. The Activate button will load the item in the property grid and in others panels linked to the type of the item (Mantis 4621).

See also:

Uniform Auto Activation

Uniform setters contain some flags used to enable the activation of various auto uniforms (camera position, lights, material, texture, etc.) which are defined in shader programs.

A new property was added to uniform setters:

See also:

Multi Materials Import from FBX

This feature enables the user to import FBX objects that have multiple materials (Multi/Sub object) associated to the geometry (For example different polygons are associated different materials). As Candera does not support multi-material objects, an object that has a multi-material is split into separate objects in which the polygons share the same material. Therefore, such an object will be imported as a group containing the sub-meshes that sum up to the FBX object.

See also:

Auto-hide in Selected Panels

Auto-hide is offered in selected panels, similar to VisualStudio. Also available are the following options: Float, Dock as Tabbed Document, Hide and Close.

See also:

Perspective Support

It is now possible to save a new perspective layout, which will be based on the current perspective. Also the possibility to delete, to export and to import a perspective was added.

See also:

Scene Templates

Scene templates are now supported in SceneComposer. A scene created by the user can be made template by checking its IsTemplate property. The dialogue used to create new scenes was modified to allow the user to select an existing template or import.

See also:

Import Fonts Button

A new "Import Fonts" button was added in the Text Style Palette section from the Solution Options ("File" > "Solution Options"). If there are no fonts already imported, the user can import any available fonts by using the "Import Fonts" button which is placed on the upper-right corner of the Text Style Palette section.

See also:

Support for Display and Device Meta-Info

Display is now a dynamic item and has dynamic properties (like widget, render target, effect and layouter properties). Device Package is a new dynamic item which is displayed as the root element in the Render Target Explorer panel.

See also:

Render Target Preview

Preview functionality for render targets has been extended: when deactivating/activating a render target - by unchecking/checking the checkbox - in order to disable/enable the preview of it, the render target gets also unloaded/uploaded. Therefore, one can make use of several WindowSurfaceRenderTarget objects having the same layer by activating only one of them - the others will not be uploaded (Mantis 3935).

See also:

Import KTX Image Format

A new image format - "Khronos Texture" (.ktx) - can be imported and used in SceneComposer.

See also:

Global Cameras Rendering Order

The global cameras rendering order changed. The rendering sequence for 2D and 3D cameras is:

See also:

Minor Improvements

SceneComposer Known Issues

Import from Photoshop

Photoshop Import/Export

From Candera 2.10 to 3.0, TextBrush was changed in that:

SceneComposer accomodates these changing by:

Import Names Validation

This change was done due to misalignments between SceneComposer's name validation rules and name validation rules implemented in importers and PhotoshopExporter. The PhotoshopExporter script's name validation rules were very restrictive, replacing commonly used characters (even spaces) with underscore. The attempt was to get PhotoshopExporter's naming validation as close as possible to SceneComposer's ones.

Photoshop Known Issues