3D Scene Design

• 3D Nodes
• Node Attachments
• 3D Scene Editor
• Vertex Buffer Editor
• Shader Configuration

3D Nodes

3D Toolbox

The Toolbox for 3D scenes provides the following items:

Create 3D Nodes

Following items can be used to create a new node in the scene graph:

3D Nodes

Canvas Nodes

12	Canvas: A node which acts as a surface. Read more... Candera::Canvas
13	CanvasGroup: A node which can contain other canvas nodes. Read more... Candera::CanvasGroup
14	CanvasSprite: A node which represents a solid object, offering the possibility to render a texture, a flat colored rectangle or other visual effects. Read more... Candera::CanvasSprite
15	CanvasText: A node which facilitates displaying text on Canvas. Candera::CanvasText

Create a new 3D node by drag & drop

New scene nodes are named like the item type, for more than one item suffixed with a number.

Refer to the Properties panel for inspecting all properties specific for the type of node. Tooltips are available to explain the purpose of the property. Refer also to the Properties Overview listing the Tooltip descriptions.

Light

Types of Light

Different kinds of light sources are available:

1 Ambient Light

Ambient light illuminates the scene from all directions. The light intensity is the same everywhere in the scene.
Position and direction of an ambient light source have no effect.

2 Directional Light

Directional light corresponds to sunlight in the real world. Illuminates all objects in the scene from the same direction, and with a constant intensity.
Position and attenuation of a directional light source have no effect.

3 Point Light

Point light casts equal omnidirectional illumination from the position of the light source. The intensity of light coming from a point light source can diminish with distance.
The direction of a point light has no effect.

4 Spot Light

Spot light casts a light cone from a position centered around a direction.
A spot light has both: a direction and a position.

Light Properties

Please refer to section Light Gizmos for more details on how to edit lights by using gizmos.

Light properties that can be edited from the Properties panel (Some properties are only applicable depending on the selected light type):

Light properties that can be edited in ShaderParamSetter:

Camera

Refer to the Properties panel for inspecting all properties specific for a 3D camera.
Tooltips are available to explain the purpose of the property.

Please refer to section Camera Manipulation for details on how to manipulate cameras.

Camera Render Strategy

Camera, Reflection camera and LeftEye/RightEye (StereoCamera) objects have a property (available in Properties panel) called "RenderStrategy" that only affects the processing of that camera and its nodes.

Per default "none" is selected as camera render strategy, which means the nodes will be rendered inside a render pass according to the defined render order.

Benchmark Render Strategy

Select "Benchmark" as render strategy to split a render call into several passes.

In a render pass, only that part of the scene graph is rendered, which node's benchmarks are beyond a given threshold. In the next render call, rendering will resume at the previous stop point, until it is complete.

Two properties are relevant to achieve this behavior:

 Occlusion Culling

Select "Occlusion Culling" as render strategy to have a new property available in property grid: QueryType.

The render strategy uses a dynamic property (QueryProperty) per node to determine if an occlusion query should be issued or not. It also stores the query result for that node in that property.

Reflection Camera

Reflection camera is a special item in the Toolbox that can be added in scenes only under camera nodes using drag & drop.

The camera will have some modified properties after adding a reflection camera on it. After the reflection camera is removed, the camera may still have some modified properties which have been previously required for the reflection camera.

Configure the properties "Mirror Plane Direction" and "Mirror Plane Distance" to visualize the reflection plane.

The reflection will not be rendered in predefined views (Perspective, Orthogonal). Depending on the desired visual effect, set the proper values for the properties: IsColorClearEnabled and SequenceNumber.

Camera Render Strategy

Both Camera and Reflection camera objects have a property (available in Properties panel) called "CameraRenderStrategy" that only affects the processing of that camera and its nodes.

Per default "none" is selected as camera render strategy, which means the nodes will be rendered inside a render pass according to the defined render order.

Stereo Camera

To use the StereoCamera object two Camera objects have to be assigned as the left and the right eye. Only cameras that have no parent, or their parent is the StereoCamera itself, are allowed to be set as eyes. If they have no parent, they'll automatically get assigned as children of this StereoCamera. On these cameras position, lookAtVector, upVector and the projection get set automatically with respect to the StereoCamera objects setting.

A StereoCamera object is available in the Toolbox. In order to use it, the user should drag it on a scene. After this first step, a StereoCamera object will become available in the Scene Tree.

A LeftEye camera and a RightEye camera will be assigned to the StereoCamera. The LeftEye camera and the RightEye camera may be configured from the properties panel as any other camera. The properties specific for the StereoCamera may be configured from the Properties panel that is available when the StereoCamera is selected. Those are:

Eye separation controls the interaxial offset of the two Camera objects positions relative to the StereoCamera's position. Here for both camera's the position is set to half of the separation in +X and -X direction.

Convergence distance is the distance from the camera to the plane on which both projections would produce the same image, and therefore no parallax occurs.

Without a special designed hardware the only possibility to check the Stereoscopy on SceneComposer is to link every Eye Camera to a different Render Target. For instance, it is possible to associate the LeftEye with a Left Render Target and the RightEye with a Right Render Target. The association of any Eye Camera should be done by following the usual two steps:

Both Render Targets are expected to be kept grouped under the same Display as it can be noticed in the image above.

Stereo Camera Side by Side

One of the Stereoscopic Camera configurations is the so called "side by side" (SBS) configuration. This type of configuration is based on display that combines the left and right eye images into a single image by squeezing the two together horizontally.

To facilitate the creation of SBS configuration, SceneComposer provides a built in configuration that can be used.

First drag and drop a Stereoscopic Camera from the Toolbox in a 3D scene. Second, right click on the Stereo Camera in the Scene Tree. Select "Camera Side-by-Side Configuration" from the context menu.

If a RenderTarget already includes cameras, you can not choose it. So, remove cameras in the RenderTarget and select "Camera Side-by-Side Configuration" menu to be appeared its dialog. After a display and a render target are created, select the Render Target. After this step click "OK".

In the Render Targets panel both "eyes" associated with the Stereo Camera will be displayed.

Sky Box

One of the most spectacular types of environment mapping is the so called "sky box". This type of mapping gives the user the feeling of immersion into a large environment. The name is related with one of its first usages into pc games industry, especially in relationship with clouds and sky projected into a 3D level of a computer game.

It is possible to create this type of virtual environment by using the SkyBoxMesh from toolbox. Associated with a camera, this mesh will be placed on every renderization on the same position as camera's position. When a skybox is attached to a camera, any of the clear color properties will not be taken into consideration.

The sky box should only be seen if the active camera is the same one with that camera to which the sky box is attached.

Usually you need to specify only texture to show skybox (CubeMap Texture). And you do not need to specify VertexBuffer and Shader. But if you want to specify your own SkyBoxMesh:

Planar Shadow

To configure it the following steps have to be taken:

The AlignmentNode property exposes Candera's automatic alignment behavior. When the alignment node is set, Candera automatically aligns the shadow plane to the alignment node (which usually is the shadow receiver).

Related with the planar shadow there are many other important aspects:

Morphing Mesh

Shape Morphing

Shape Morphing allows a smooth transition from an origin 3D model shape into a destination shape at runtime, e.g. to change a cube to a sphere. In contrast to model blending a single shape is rendered at every point in time which actually forms the morphed model. This model supports virtually all features of regular models.

CGI Studio supports not only a single shape being morphed into another but allows contributing multiple models to the resulting shape. The degree of contribution of a single model to the result is controlled by "morph weight" attribute of the regarding model.

Morphing of multiple models can be used for various fancy effects such as 'chaotic' vertex movement, explosion effects, and simple particle effects.

Technical Background

Geometries (vertex buffer) of different shapes supposed to be morphed are combined into a special, single vertex buffer for "Morphing Mesh" nodes including all vertex buffer attributes such as position, normals, texture coordinates per original vertex. This combined vertex buffer is uploaded to GPU, the regarding vertex attributes can be accessed in vertex shader. Uniforms applied to vertex shader during rendering by Candera include morphing weights for all contributing shapes. The vertex shader calculates the vertex attributes of the resulting shape by adding all regarding vertex attributes of single shapes multiplied by morphing weight.

For example, the vertex position is calculated in vertex shader as

Vertex Position = Vertex Position 0 * Morph Weight 0 + Vertex Position 1 * Morph Weight 1;

Other vertex attributes that are subject to morphing calculation are normals, bi-normals, and in special cases, texture coordinates. This calculation moves the vertices between the corner points of the model according to their morph weight.

If color or textures are subject of morphing as well, the resulting color needs to be calculated in an according fragment shader considering morph weights.

Prerequisites

3D models need to be prepared for shape morphing. For each "corner" shape, a single model needs to be provided. All models contributing to a morphed shape need to have homologous vertices. This means that all models must have the same number of vertices and the vertices must "semantically correlate". For instance a vertex of model 1 addressed by a certain index is located in a front face. The vertex of model 2 with the same index need to be located on the corresponding front face of the second model, and not, e.g. on a back-side face.

Create a MorphingMesh

To create a MorphingMesh at least one .fbx file has to be imported. Choose "Import > Import Resources..." from the menu. This will open the "Import Resources" dialog. Browse to your FBX file an click [ Open ] to import the file.

To import the FBX file in Import dialog click "Select Files..." button.

 Configuring shape morphing in SceneComposer:

Configure Morphing Weights

In order to get the desired morphing effect, select the morphing mesh in the right side of the Scene Tree panel and set the weight of each morphing mesh item in the Properties panel accordingly.

By default, after creating morphing mesh items, the morph weight of the first item is set to 1.00, while morph weights for all other items are set to 0.00.

Wireframe Line Width

Morphing Shader

The reference shaders for morphing:

support morphing between maximal 2 vertex buffers.

Level of Detail (LOD)

With Level of Detail, 3D render performance can be improved by using low polygon models for far away objects and high polygon models only for objects near to the camera.

Create a LodNode

Using the level of details concept in SceneComposer:

Configure Lod Levels

Each child of a LodNode must be associated to a specific LodLevel by configuring following properties:

While the index is given by the order of the LodNode children in the scene graph, lower and upper bound can be configured either in the Properties panel or in the "Configure Level of Detail" dialog. For this, use the context menu item "Configure Level of Detail" on the selected LodNode in Scene Tree panel:

First of all, the "Level of Detail" dialog allows to specify the Lower Bound and the Upper Bound for any child part of the LodNode.

The same operation can be done in the Properties panel, whenever a LodNod child is selected in the Scene Tree panel:

Configure LodNode

Select the LodNode in the Scene Tree panel to edit the following LoD node properties in the Properties panel:

The preview type property can be edited in the Level of Detail Configuration dialog, too.

Discrete LoD Render Strategy

Select "Discrete" for the Level of Detail render strategy to configure a stepwise transition between the several Lod levels.

After choosing "DistanceToCamera" Lod criterion, the LoD level will be switched depending on the distance of the LodNode to the camera.

Blend Lod Render Strategy

Select "Blend" for the Level of Detail render strategy to configure a smooth alpha blending transition between the several Lod levels. In this case, following additional properties can be specified:

Again, after choosing "DistanceToCamera" Lod criterion, the LoD level will be switched depending on the distance of the LoDNode to the camera.

Canvas

Canvas is a node that acts as a surface which allows the user to introduce 2D content in a 3D scene. Canvas nodes can have appearances, just like normal 3D nodes so the user can achieve complex visual effects by using appropriate shaders, materials and textures.

Canvas, CanvasGroup, CanvasSprite and Canvas Text (placed under the "Canvas Nodes" section of the Toolbox) behave like normal nodes when it comes to transformations and selection. Bounding box will be rendered for each of them. They can be translated, rotated, scaled. Canvas acts as a surface. CanvasGroup nodes, CanvasSprite nodes and Canvas Text nodes can be inserted into it.

For each Canvas object, a new editing camera is added in the scene camera list and becomes available in "Canvas" category. This camera can be selected and exhibits a special behavior: is automatically oriented towards the canvas, regardless of canvas transformations, so that the Canvas and its children will always appear like they would be viewed from a "Front" camera. A Canvas camera provides an orthographic projection.

Canvas Sprite

CanvasSprite is a node that represents a solid object, offering the possibility to render a texture, a flat colored rectangle or other visual effects, depending on its appearance configuration.

Four new shaders will be available in the default solution for configuring the CanvasSprite:

A new uniform setter template will be available in the default solution for configuring CanvasSprite: CanvasTransShaderParamSetter.

Canvas Text

Canvas Text is a node that allows the creation of 2D texts on a Canvas in a 3D scene. When Canvas Text node is selected, specific properties become available in the Properties panel.

In this way the text can be set as desired.

The Canvas automatically batches Canvas Texts together to minimize the amount of draw calls. To achieve high batching rates, it is crucial that the user shares Appearances, Render Order Ranks, Render Order Bins, and Scope Masks between Canvas Texts as much as possible. Only Canvas Texts with the same properties can be batched together.

Some of the most important Canvas Text properties are the following:

Alignment: The text has a property for horizontal alignment. This property aligns the text within Text::Size. If no Text::Size is set, the Layout::Size is used. The layout has a horizontal and vertical layout alignment property which is used to align the ‘block’ of the measured text within the Layout::Size. The defined layout alignment can be propagated to the text alignment when the text alignment is set to ‘Auto’.
Otherwise, it is possible to right align the text within Text::Size but left align this block of right aligned text within Layout::Size. The properties will be inverted if the layout direction is set to ‘right to left’.

Word wrap and truncation: Both properties prepare a text for use cases in which they do not fit into a size. Therefore, enabling one of them forces the text to fit into the provided smallest size (Layout::Size or Text::Size).

For many other details see the chapter Canvas Text - Size Property.

Canvas Text Outline

By using this feature, it is possible to use shader effects such as Outline on any canvas text node on a 3D scene. This property allows the user to add an outline on any canvas text on a 3D scene.

To use the "Canvas Text Outline" feature, it is mandatory to use an Appearance Collection that has set "RefTransColor_RefColorTexAlpha" as shader.

In order to obtain such a collection, first, in "Solution Explorer" copy the "CanvasText" appearance collection which can be found in "References > SCL:ConstructionKit > Resources > Appearances > CanvasText" from "Templates" into your solution. After this step, in "Solution Explorer" rename the copied "CanvasText" appearance collection (e.g.: "AppearanceCollectionWithOutlineShader") then in Properties select the "CanvasText" tab and under the "Appearance" section set "RefTransColor_RefColorTexAlphaOutline" as shader program.

From now on it is possible to use this appearance collection to set an outlined canvas text. The color and width properties are available under "Shader parameters" section (see the image above). To see how this works, first, when "AppearanceCollectionWithOutlineShader" is selected in "Solution Explorer", modify the u_outline Color as follows: X=1.00/Y=0.00/Z=1.00/W=1.00 then set the u_outline Width to be "4". Create a 3D scene and in it drag and drop from Toolbox a Canvas node with a Canvas Text in it. In Scene Tree select the "CanvasText" node and drag and drop on it - from "Solution Explorer" - the "AppearanceCollectionWithOutlineShader". In Scene Tree select again the "CanvasText" node then in Properties modify the "Outline Width" to be at least 1 or 2.

In this way the outline of the text can be set as desired.

Canvas Layouter

The functionality of 3D Layout for canvas nodes is similar with that of the layouters known from SceneComposer 2D scenes. By using this feature a Canvas Group is able to align its nodes (group, sprite, or text) according to the configured layouter.

It's not possible to animate the same property for parent and child nodes. Group nodes are resolved and all properties are applied on their child nodes. Either animate the parent group property or the child properties.

The settings for this feature can be done through a category with the same name available in the Properties panel. To access it, first, a Canvas Group - included in a Canvas - has to be selected:

By using this feature a Canvas Group is able to align its nodes - group, sprite, or text - according to the configured layouter. The available layout types are identical with those used for the 2D layouters:

Baseline Layouter

The layout type "Baseline" realizes a stacked laying out in the horizontal direction. It behaves similar to the Horizontal Stack Layouter. The major difference consists in its given reference: it aligns the objects to a line instead of aligning them to the client area. The main purpose of this layouter is to align different sizes formatted texts along the same baseline. For instance, if the center is chosen for alignment, the baseline of the text will be aligned to the given line (= baseline offset). The order of the elements is given by the order of the child nodes within the layouted group.

Configure the Baseline Layouter by following these steps:

  

Grid Layouter

In a Grid layout, every node part of the layouted canvas group is assigned to a cell of the grid. A Grid Layout Editor is available to configure the grid and to arrange nodes in the grid's cells by drag & drop operation.

 Configuring the Grid Layouter:

Optional: Use the buttons "+","-" to configure the desired number of rows and columns in the "Grid layout editor" dialog, if not done already in the Properties panel.

 Arrange the nodes of the group in the grid's cells by drag & drop operation.

Configure width and height for rows and columns by editing the values on the border of the grid. Values within the range [0...1] are considered as percentages and values greater than 1 as dimensions.

Confirm the layouter configuration by pressing the "OK" button of the dialog "Grid layout editor".

Call the Do-Layout command using the shortcut keys "Ctrl+L" or from the "Edit" > "Do-Layout" menu.

Overlay Layouter

The layout type "Overlay" arranges the objects by laying out them on top of each other or by aligning the nodes according to their general layout properties. The order of the elements is given by the order of the child nodes within the layouted group.

Configuring the Overlay Layouter:

Stack Layouter

The layout type "Stack" realizes a stacked laying out either in horizontal or vertical direction. The order of the stack elements is given by the order of the child nodes within the layouted group.

Configuring the Stack Layouter:

DockPanel Layouter

The "DockPanel" layout provides a layout area within it is possible to arrange canvas child elements around the edge of the screen based on four direction: Top, Bottom, Left, and Right.

This type of layout arranges the elements by laying out them in the remaining space after the previous element was set. To dock an element to the center of the panel, it must be the last child of the panel.

Configure the DockPanel Layouter by following these steps:

Node Attachments

Node Attachments Toolbox

Create 3D Node Attachments

A node can have an appearance attached, having up to four children. Following items from the Toolbox can be used to configure attachments for 3D nodes:

Create a new attachment by drag & drop an attachment type from the Toolbox on the desired 3D node in the Scene Tree panel.

Apply Appearance Template to Multiple Nodes

It is possible to apply an attachment to multiple nodes at once: When all the desired nodes are selected, drag and drop the attachment on the multi-selected nodes.

Render Mode

Configure Render Mode

If no "Render Mode" is associated to an object, SCHost will automatically apply the values set in the Default render mode configuration (the default render mode). Otherwise, if a render mode instance already exists on a specific node, note the following:

In the Properties panel, the RenderMode properties provide a checkbox on the left side with two states:

If the property value is set to Inherited, the property will be read only and the value will be taken from the DefaultRenderMode (Configuration > Default Render Mode). Only if the checkbox is unchecked (meaning that the property does not inherit from the default render mode configuration) the property will be editable.

Cube Map Texture

Cube Mapping

Cube mapping is one of the most spectacular types of the so called environment mapping. In SceneComposer this type of mapping can be done by using the CubeMapTexture from the Toolbox. First, a mesh and a collection of six images of a cubical environment map have to be imported. The mesh will be dragged in a 3D scene. The Appearance has to be contained:

CubeMapTexture supports up to 16 slots on ES3.0 builds and up to 8 on ES2.0 builds (each slot maps to u_CubeMapTextureN).

The main feature that has to be used is CubeMapTexture which has to be dragged and set as texture. Six specific properties will become available for this type of texture: Positive X Image / Negative X Image / Positive Y Image / Negative Y Image / Positive Z Image and Negative Z Image. Any of the imported images has to correspond to one of these properties.

Any model can be placed inside the environment (in our case, a cube) and set as a reflective map. One of the best examples is to place a sphere inside the cube environment and to use the RefTransCubeMapReflection_RefCubeMapTex shader. The setting of the properties will be almost the same as in the Cube mapping case. The UniformSetter properties which have to be enabled are ModelMatrix4, NormalModelMatrix3 and ModelViewProjectionMatrix4. The same six images can be used for the sphere as six textures displayed as an unfolded cube.

By placing the sphere in an environment some complex and spectacular scenes can be created.

Render Order Bins

Render Order Bins are containers for items to sort them for rendering.

For a detailed description of the Candera Render Order concept, refer to Application and Widget Development Tutorial.

The Render Order Bins collection is displayed in the RenderOrderBins Panel. It can be enabled by choosing "View - Scene - Render Order Bins" menu option.

There are two predefined Render Order Bins: Opaque and Transparent. Per default, all objects part of a scene are sorted into that bins according to their render attributes. Both default bins are protected, meaning that they are under control of Candera and cannot be deleted.

Configure a New Render Order Bin

To specify a non-default render order, create a new Render Order Bin by drag & drop from the Toolbox into the RenderOrderBins collection.

In order to check the "BatchOrderCriterion" the following steps should be followed:

See also:

Node Attachment Templates

SceneComposer allows saving any node attachment (Appearance, Material, Render Mode or Texture) as a template to enable reuse for other nodes. Templates are also listed in the Templates panel.

Save as Template

Select a node which contains an appearance, material, render mode, or texture in the Scene Tree and save the selected node attachment as a template with the context menu item "Save as Template".

Alternatively directly select the node attachment in the right side of the Scene Tree and use the regarding context menu item to save the selected attachment as template:

In the "Add New Template" dialog, specify the template location and template name. Tick the checkbox "Is Instance Sharing Enabled" to allow sharing of a template instance across several nodes (refer to the chapter Shared Node Attachments for more details).

The new template will be displayed in the Templates panel. This panel contains all node attachment templates grouped by type:

---

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. For instance, if the object is a button used in an interface, we can suppose that the only properties which have to be modified by the user are "Font", "Text" and "Status". But if the appearance of the object has many other properties, it could be overwhelming for the user to understand exactly which properties have to be modified to get the desired result. So, it is easy understandable why is necessary to provide a concept which will allow replacing a node attachment with an object which exposes only some properties of a regular node attachment.

This 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). In this way, the goal mentioned above - the user will be able to see and modify just the exposed properties - is fulfilled.

When a template object is created from an existing appearance attached to a node, in the "Add New Template" dialog an Is Encapsulated check-box becomes available. If this check-box is enabled, all the properties associated with the template will not be visible for the user in the properties panel when the template will be used. Only the "Generic" category of properties will be available in the Properties panel.

If the user needs only some of encapsulated properties to be visible, this operation should be done by righting click on the template which has all the properties encapsulated. From the context menu the "Configure Properties" should be chosen. The "Configure Properties" dialog provides the possibility to select which encapsulated properties will become visible in the Properties panel. This operation could be done by using the "IsChecked" boxes available in the dialog. When a template with exposed properties is used, all the properties will become visible in the "Public Properties" category of the Properties panel.

Use a Template

Use a template by dragging it from the Templates panel and dropping it on the desired parent in the Scene Tree:

It's possible to apply the same template to many multi-selected nodes at once. After all the desired nodes are selected, drag and drop the template on the multi-selected nodes.

The template will replace the existing node attachment by an item linked to the template. In case the template allows instance sharing, the Shared Instance Id used for the node is displayed in brackets.

Edit a Node Attachment Template

Edit a node attachment template in the Properties panel after selecting a template in the Solution Explorer panel or in the Templates panel.

Any change in the template will be reflected in all the nodes using it.

Shared Node Attachments

Shared node attachments refer to instances of appearances, materials, render modes, or textures which are being shared between nodes.

There are several options:

Prevent sharing of a template:
Disable the property "Is Instance Sharing Enabled" of the node attachment template. In this case, each time such a template is applied to a node, a new instance of the template will be created for this node.

Share exactly one instance of a template:
Enable the property "Is Instance Sharing Enabled" of the node attachment template and use only the default value "0" for the node attachment property "Shared Instance Id". In this case, each time such a template is applied to a node, the same template instance will be shared among all nodes.

Share more than one instance of a template:
Enable the property "Is Instance Sharing Enabled" of the node attachment template and specify as much distinct values for "Shared Instance Id" as instances are required.

Enable Instance Sharing

Whenever a new node attachment is created and about to be shared, enable the property "Is Instance Sharing Enabled":

This property can be also set in the Properties panel after selecting an existing template from the Templates panel.

Specify Shared Instance Ids

Node attachments from scenes which are linked to templates having "Is Instance Sharing Enabled" set to true will get a new property "Shared Instance Id" to indicate which shared instance of the node attachment to use:

Edit Shared Instance Ids:

The Instance Id of a node attachment can be edited in the Properties panel of the node attachment.

For an overview of all nodes using a shared node attachment template, use the Instance Id Editor from the context menu of the node attachment template:

Refer to the Node Attachments Optimization Wizard for optimizing existing scenes regarding node attachments. It is possible to export a .csv file with all the shared items by using the "Export to CSV" button which can be seen in the figure above.

Node Attachment Optimization

SceneComposer provides a wizard to automatically detect node attachments which could be replaced by shared node attachments templates. It is possible to create new node attachment templates, which can be used for the optimization, if no proper node attachment templates exist yet. Selected node attachment candidates can be replaced by shared node attachment templates by the wizard.

Invoke Node Attachment Optimization Wizard

Invoke the node attachment optimization wizard from the context menu of any folder in Solution Explorer panel, or from a scene in the Scene Tree:

In the Node Attachment Optimization Wizard, select either the entire solution, or a specific scene or location within the solution as root location for the wizard. Further, the type of node attachments to optimize can be selected.

Press the "Next" button to start optimization analysis for the first type of node attachment.

Optimization Analysis Results

During optimization analysis, the wizard detects all nodes with identical properties regarding the selected type of node attachment, and suggests proper node attachment templates to share between those nodes.

As a result of the analysis, the wizard provides a list of node attachment template candidates, which could be shared among several nodes, as well as the number of nodes which would benefit from sharing the same template.

If no proper node attachment template candidate exists yet, the nodes which could share their attachments are listed under the name "( Empty )".

Select "Include already optimized" to include node attachments that have been previously optimized in the list.

Apply Node Attachment Optimizations

Select the node attachment sharing candidates you want to optimize by

Now all fields to apply the optimization are editable:

In the list below, specify which nodes should share the given node attachment template. The numbers displayed in the right side of each node represents the SharedInstanceId to be used.

Apply the changes by pressing the "Apply changes" button from the upper right corner of the wizard dialog.

Repeat the optimization for all node attachment types which have been selected in the initial wizard step:

Appearance Editor

The Appearance Editor offers a visual editing and comparison mode for several appearances.

Go to "View" > "Editors" > "Appearance Editor" to activate the Appearance Editor panel. Drag and drop node attachment templates from the Templates panel to the Appearance Editor:

Each of the node attachment template displayed in the Appearance Editor can be selected and then edited using the Properties panel. All changes applied in the Properties panel will be reflected in the Appearance Editor.

It is possible to apply the same appearance to many multi-selected nodes at once. After all the desired nodes are selected, drag and drop the appearance on the multi-selected nodes.

3D Scene Editor

The "Scene Editor" is the main panel of the application in which scenes and animations are displayed ("render view"). It is the only panel that cannot be closed.

This page describes the five types of interactions that are possible with the render view.
See Also : 3D Editing Helpers 

---

General

By default, only one Scene Editor is displayed (Scene Editor (0) only). You can display up to four Scene Editors (Scene Editor (0) to (4)) as needed. You can show or hide them from the menu bar [ View > Editors > Scene Editor ].

• Scene Editor menu on the Menu Bar
  
  
  
  
• The [ Display Scene Editor ] icon on the toolbar
  
  

  When you click the [ Display Scene Editor ] icon, four icons will appear for toggling the visibility of the Scene Editor. Please refer to the table below for details on each icon.

  	The Scene Editor (0) is displayed.
  	The Scene Editors (0) and (1) are displayed.
  	Scene Editors (0) through (2) are displayed.
  	Scene Editors (0) through (3) are displayed.

  When a display setting not listed in the table above is applied in the Scene Editor menu on the Menu Bar, the [ Display Scene Editor ] icon will display "Custom".
  
  

Displaying multiple Scene Editors is useful when you want to check a 3D model from multiple directions at the same time.

Additionally, scene editors (1) to (3) support floating display. By using floating display, you can display any scene editor on a separate display.

If the displayed Scene (or Control) is updated, it will be reflected in all Scene Editors.

---

The following is an explanation of the scene editor tool icons.

Camera Manipulation 

The Camera combo box provides following camera views for a 3D scene:

Orthogonal Cameras:

Scene Camera View

The Aspect Ratio and the Aspect Autofit properties are available for Camera 3D. If the Aspect Autofit property is set to true (when the checkbox available for Aspect Ratio property is checked), the aspect of the camera will be calculated based on the width and height of the render target. Otherwise, if the checkbox available for Aspect Ratio is left unchecked, the aspect of the camera will be calculated based on the resolution of the display.

Camera Panning and Zooming

The scene content displayed in the Scene Editor can be modified like this:

Enable panning and zooming also for scene cameras with a preference option:

Orient Camera to Selected Object

Sometimes it is quite difficult to locate in a 3D scene a new added object. This feature provides new control to active camera: orienting it to a selected object.

First select the object in the Scene Tree. After this the "Perspective" camera will be oriented towards the selected object, by pressing the "O" key. The position of the camera remains unchanged; the only thing that changes is its orientation. The reference of the orientation is the geometric center (or "centroid") of the selected object.

Rotate Perspective Camera around Selected Object

The object can be seen from different angles by rotating the Perspective Camera around a selected object. After the desired object is selected in the Scene Tree, the camera can rotate around it by holding down the Ctrl key and using Rotate camera.

Camera Look-At Node

When this property is set the camera is automatically oriented towards the look-at-node. Up direction and look-at direction are not shown anymore in property grid. Look-at direction is discarded.

Camera Preview Thumbnail

Even though the current selected camera is the Perspective camera, it is possible to see the content displayed by another camera in the thumbnail available in property grid. If the camera is not associated to a render target, the preview will be done on a fixed size virtual render target surface:

If the camera is associated to a render target, the preview will be generated:

The camera preview thumbnail will be displayed in the property grid by selecting the camera whose perspective should be viewed in the Scene Tree.

Reset Camera

Use the "Reset Camera" button left to the Camera combo box to reset the selected view to the default location and orientation.

Camera Sequence Editor 

When many cameras are associated to the same Render Target, editing of the camera sequence can be done in two different ways. The first one is done by following these four steps:

The second way to edit the sequence of all cameras associated with the same Render Target is based on the usage of button "Go to Camera Sequence Editor view" which is placed in the Render Targets panel right to the Search field.

When this button is selected, a window with all the cameras from the entire solution is displayed. The filter button "Show only associated cameras" on the left allows to filter just those cameras which are associated to a render target. In the list displayed, every camera has an associated field where the sequence number can be edited.

Unfiltered list in Sequence Camera view:

Filtered list in Sequence Camera view:

Context Resource Pool 

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.

The Context Resource Pool is accessible via Render Targets panel by using the specific button as can be seen in the image below.

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. The Owner property is available in the Properties panel (see the image below).

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.

Camera Group 

Camera group feature offers extended support for display visualization. They can be added in a camera group to allow the user to enable or disable any of them (solution with many cameras).

How to create a "CameraGroup":

After creating a CameraGroup, it will be visible in the "Camera Group Explorer View". A camera group is a flat list of camera groups identified by a unique name.

Any camera from any scene can be dragged from the Scene Tree inside the group.

Another way to add a camera to the group is by using the context menu: right click on a camera and select the "Add Camera To Camera Group" option.

Any camera inside the group can be locked or unlocked, enabled or disabled. Initially, all newly added cameras are ordered alphabetically. It is possible to change this order manually by dragging the cameras in the desired position.

When a camera is a added into a Camera Group it will become a member of an array where all the other cameras are included. If one of those cameras added into a Camera Group is removed, the "Delete Items" panel will become available and the user will have the possibility to use the "Remove Array Item" resolution. In this way, the selected camera will be removed from the array of cameras contained by the Camera Group.

Camera Gizmos 

For a camera object the following properties can also be edited by using gizmos, not only from the Properties panel:

LookAtVector

Editing is done by click-and-drag the front of the camera as it can be seen in the image bellow and the current look at vector will be rotated by a free rotation alt-azimuthally model, using both X and Y mouse movement.

Up Direction

Editing is done by click-and-drag the ring around the camera body (which is highlighted with yellow when selected). The current up-vector will be rotated around the world looking-at direction, obtaining a "rolling" effect considering the Y mouse movement.

Projection

For Perspective view a wireframe frustum is provided, constructed to suggest fov,znear and zfar; for Orthographic view a wireframe rectangular prism is provided, constructed to suggest width, height, znear, zfar; for Generic projection no impersonator is provided.

Light Gizmos 

For a light object the following properties can also be edited by using gizmos, not only from the Properties panel:

Direction

Editing is done by click-and-drag on the direction arrow. The direction vector will be rotated by a free rotation alt-azimuthally model, using both X and Y mouse movement.

Range

For light of type Point the range is suggested by a set of n concentric circles laid at an exponential step (1, 2, 4, 8, etc.). For light of type Spot the range is suggested by the length of the wireframe cone. Editing (spot and point) is done by click-and-drag on the centered light source object (yellow sphere) and the range value will be modified using a combination of X and Y movement.

Spot Exponent

Editing is done by click-and-drag on the top part of the spot cone (as it can be seen in the image bellow), and the spot exponent is modified using Y movements (up movement increases the value of property spot exponent and down movement decreases it).

Spot Angle

A wireframe cone is provided and the editing is done by click-and-drag on the cone, the spot exponent value is modified using a combination of Y movements.

Picking and Transforming Items 

In the Scene Editor, an item can be picked by clicking on it. After picking, the bounding box of the item is displayed together with the XY axes, and it is selected in the "Scene Tree" panel:

Interaction Modes: Selection, Edit the margin of objects inside a layout, Translate, Rotate, Scale

These interaction modes are available for 3D scenes in the Toolbar:

Select

When the button "Select" is enabled, the selected object will be highlighted in the Scene Editor but can't be transformed.

Edit the margin of objects inside a layout

For more information about this, please refer to Adorners.

Translate

In this mode, a translation gizmo is represented by an axis coordinate system, having three arrows handles pointing in the directions of the corresponding axis (x, y, or z). For combined operations (translate xy, xz, ..), more rectangle handles positioned on the center and aligned to the corresponding axis combination are provided. Editing is done by click-and-drag a specific arrow handle or a specific rectangle handle.

For translation mode three options are available:

Rotate

In this mode, a rotation gizmo is represented by a set of circles, each corresponding to a plane (xy, xz, yz). Editing is done by click-and-drag a specific circle.

Usually the object is freely rotated except the situations when the rotation angle is close to a fixed angle controlled by a tolerance. The tolerance defines the range between two multiple values where the object can freely rotate without being snapped.

Edit the object with a fixed angle by enabling this option using the button placed near active rendering button.

In Translate mode, another feature is the "Translation System" that allows choosing between Parent and View reference system. When Parent system is selected, the reference system is the coordinate system of the scene. Otherwise, the reference system is the coordinate system of the selected object. In both cases, the object can be moved by using the arrow keys.

Scale

In this mode, a scale gizmo is represented in a similar way as the translation gizmo. For the combined operations (xy, xz, yz), rectangle handles are provided. For the combined (xyz) mode, a sphere handle is provided (located in the center of the gizmo). Editing is done by click-and-drag a specific arrow, a specific rectangle or the sphere.

Move the mouse while pressing left mouse button to translate, rotate, or scale the selected object in the render view. The modification of the properties is also reflected in the "Properties" panel for the selected item.

Editing Aids

Move from a selected element to another one by using the Tab key. First in the Scene Editor an element would be selected by Left click on it. After this all the elements placed at the same level (in the same group) can be selected by using the Tab key.

After the selection is done, it is possible to tab all the selected elements situated at the same level. By using the Shift key + Tab all the elements can be selected in an ascendant order.

Another possibility is to tab selected elements on the same (visual) ray. This option can be done by holding down the Left key and then use the Tab key. To get the ascendant direction the same combination is available: Shift key + Tab (when the Left mouse button is holding down).

Move Elements with Arrows Keys

Any element can be moved/scaled/rotated by using arrows. After the selection of the object use the Left, Right, Up and Down arrows to get the desired results.

Unselect an Item

The camera cannot be manipulated and vice versa when an item is selected.

Unselect an item by hitting the Esc key.

Please refer to section 3D Editing Helpers for further information.

Navigation Panel 

SceneComposer provides a navigation panel which allows the user to manipulate the predefined perspective and orthogonal cameras using gizmos.

Vertex Buffer Editor

Imported Geometry can be managed and configured in either ArrayBuffer or IndexBuffer format, depending on its Geometry Topology. ArrayBuffer offers higher rendering performance (cache efficiency and sequential read) but consumes more memory since vertices cannot be shared.

To configure these two types of Vertex Buffer elements, select the vertex buffer in the Solution Explorer, and then configure the VertexGeometry (vertex attribute statuses) within the [Vertex Buffer] category in the [Properties] panel.

Within the Vertex Buffer, each Property Item has a status of Imported (available), Removed (deleted), Regenerated/Generated (added), or Missing (not set). All selected Float32-type vertex attributes within the vertex buffer can be converted to Float16 if necessary, with convertible patterns indicated in parentheses.

When [Is Indexed] is enabled, the vertex buffer can be converted to an index array buffer by selecting the optimal index size. Depending on the vertex count, 8-bit, 16-bit, or 32-bit index buffers will be generated, and a valid buffer type can be specified via the BufferType property in the AssetData section.

When importing a glTF file that contains positions, UVs, and normals but lacks tangents, tangents will be automatically generated using the MikkTSpace algorithm. With MikkTSpace support in the Vertex Buffer Editor, the “Generated MikkTSpace” and “Regenerated MikkTSpace” options can now be selected for the Tangent and BiNormal Property Items, improving rendering quality when applying normal maps and ensuring consistency across tools.

The editable items are listed in the table below.

Normal	When attribute is not included: Missing, Generated (Float16), Generated (Float32) When attribute is included: Imported (Float32), Imported (Float32 => Float16), Regenerated (Float16), Regenerated (Float32), Removed
BiNormal/Tangent	When attribute is not included: Missing, Generated MikkTSpace (Float16), Generated MikkTSpace (Float32), Generated (Float16), Generated (Float32) When attribute is included: Imported (Float32), Imported (Float32 => Float16), Regenerated MikkTSpace (Float16), Regenerated MikkTSpace (Float32), Regenerated (Float16), Regenerated (Float32), Removed

The selectable items in the [Properties] panel vary depending on whether the imported file contains the respective vertex attributes.

If the import data and the property settings do not match, an error message will appear in the Output Panel. As with other properties, the settings can be reset using the arrow button on the left of each property (Please refer to the figure below). When settings are changed, values such as Vertex Stride, Vertex Count, and Vertex Format are updated and reflected within the [Vertex Buffer] category in the Properties panel.

Shader Configuration

The Solution option allows for Default Shader Configurations.

Add a New Vertex or Fragment Shader

Shaders are software programs that include instructions on how the graphics processing unit (GPU) should render certain images on the screen. A shader program consists of two types of shaders:

There are following options to create a new (empty) shader, which can later be combined into appropriate shader pairs or programs.

Use the "Shader" > "New shader" menu option

In the Shaders panel, use the context menu option "New Shader" of any node within the "Shaders" category:

In the "Add New Shader" dialog, specify the shader location, shader name, and shader type.

After creating the shaders, the shader instructions need to be added in the Shader Editor.

Import Vertex and Fragment Shaders

It is also possible to import already existing shaders.
For information about how to import a Vertex or Fragment shader please refer to section How to Import Resources.

Add a New Shader Program 

Fragment and vertex shaders are combined into shader pairs or programs which can then be applied to node appearances.

Create a new shader program:

Use the "Shader" > "New Shader Program" menu option.

Use the context menu option "New Shader Program" of any node within the shader program category from the Shaders panel.

Specify location and name and the desired shader pair consisting of one fragment shader and one vertex shader in the dialog "Add New Shader Program".

Tick the "Export Always" checkbox to always include the shader program to the generated assets.

Shader Editor 

Edit shaders in the "Shader Editor". Use the menu option "View" > "Editors" > "Shader Editor" to make the panel visible.

Open shaders in Shader Editor for editing:

The selected shader(s) are displayed in the Shader Editor panel (in both cases) like this:

Shader requirements - including the number of lights, materials and textures - are displayed in a tab in the Property Grid when a shader program is selected. The tab also contains the available attributes and uniforms.

On OpenGL ES 3.0 targets, up to 16 texture units are supported (CANDERA_MAX_TEXTURE_UNIT_COUNT = 16). On OpenGL ES 2.0, 8 texture units are guaranteed unless ES extensions are enabled.

Shader Editor Features

The context menu of the Shader Editor provides "Cut", "Copy", "Paste", "Delete", "Select All" functions for editing shader instructions:

On pressing [Ctrl+ Space bar], a list with helper functions is available for shader programming:

Compile the edited shader using the platform's shader compiler

The compilation result is reported in the "Shader Compiler Errors" panel. This can be opened via menu item "View" > "Shader Compiler Errors".

For further information please refer to section Compile Shaders.

Compile Shaders 

The compilation result can be seen in the "Problems Browser" panel. For further information please refer to section Problems Browser.

After successful shader compilation, a regarding message is displayed.

Shader Parameters 

SceneComposer offers the necessary support to define shader parameters for uniform and attribute values. For every shader, Candera supplies a list of uniforms and their corresponding types. Uniforms are set via UniformSetters.

When a shader is edited in the Shader Editor panel and new uniforms are created, those uniforms will only be listed in the Shader Parameters section of the node properties after successful shader compilation.

If the shader program is faulty (e.g. compile error), the previously retrieved uniforms are presented in read-only mode.

Instanceable Shaders 

Instanceable shaders are integrated into SceneComposer. They have "Inst" in their names and are special shaders used for instanced draw.

When using an instance-able shader, uniforms that are declared as arrays in the shader, will not be exposed as an array in the SceneComposer view. Instead it has to be exposed as a single value.

When an instanceable shader is selected, the property grid will display the Max Instance Count value (represents the maximum number of element that the shader can render in a batch render).

Instanceable shader validations. In an instanceable shader, the following shall hold true:

List of auto-uniforms that must not be declared as arrays in instanceable shaders:

• "u_Light[0].intensity", // intensity
• "u_Light[1].intensity", // intensity
• "u_Light[2].intensity", // intensity
• "u_Light[3].intensity", // intensity
• "u_Light[4].intensity", // intensity
• "u_Light[5].intensity", // intensity
• "u_Light[6].intensity", // intensity
• "u_Light[7].intensity", // intensity

Shader Consistency Checker 

Shader Consistency Checker refers to validations of the shader params (attributes and uniforms defined in shaders) based on some rules. Most shader param problems are reported for appearances of nodes after checking the vertex buffer of the mesh versus the shader program referenced by the appearance versus the uniform setter of the appearance.

Generic ShaderParamSetter 

Generate special effects by using a uniform setter associated to a given node in a 3D scene. This can be done by realizing a correspondence between the configuration proper to the UniformSetter and all the parameters of the available shaders.

To get the desired effect, first, the UniformSetter from the Toolbox should be dragged in the the Scene extra-Tree over the node's Appearance.

A relationship between the semantics of the UniformSetter and all the properties of the shader should be established. The semantics of the UniformSetter contain specific values that could be activated/deactivated in direct relationship with the shader. In In [ Solution Option >Default Shader Params ] from the menu bar allows to change the default names of all these values specific for the semantics of the UniformSetter.

For example, if under an appearance template we have a RefTransLight2SphereMap_RefColorTex shader, as a first step it is necessary to open the Shader Editor panel and search all the uniforms required by this shader.

As a second step, configure the semantic of the UniformSetter in order to create a correspondence between the shader required uniforms and enabled Uniforms in the generic UniformSetter category in the Properties panel.

Find all the semantic uniform values of the RefTransLight1SphereMap_RefColorTex shader in the Shader Editor.

Enable Auto Activation Property

There is an option to avoid the detailed (i.e. manual) setting of the uniform setters by using the auto activation property. This is possible after the setting of the "Enable uniform setter auto activation" property in the Solution Option panel (section "General Configuration"). If this setting is used and the "Auto activation scope" property is set global, the "Enable auto activation" property will become active and all the activation flags will be determined when the asset is generated based on the auto uniforms which are defined in the shader program.

After this operation, a check box with the same name will become available in the Properties panel. This property specifies if the auto activation of the flags should be enabled based on the global values stored in the solution properties or locally in this item.

---

Multi-Pass Effect Configuration

Another way of getting complex effects is combining multiple appearances. The fact that there are multiple appearances attached on the same node implies that the node is rendered with each appearance at a time. All the appearances are rendered sequentially.

For example, if two different appearances associated at the same node after the UniformSetters of the first appearance are set, the second appearance should be set. Every appearance can be configured by using its own properties panel. However, it is possible to see both appearances in the general Properties panel as different tags of it.

Clone, Rename, Delete a Shader 

Use the context menu of a shader program in the Shaders panel to trigger one of the following options: