Display Configuration

• Add a new Display
• Add a new Render Target
• Link a Camera to a Render Target
• Default Render Target
• Manage Render Targets
• Smart Scene/Camera Preview
• Rendering Order
• Display Renderer Statistics
• CGI Studio HMI Rotation

Add a new Display

Add display

There are two options available on how to add a new display:

Go to "Platform" > "New Display" in the menu bar or go to the Render Targets panel, right click on the Displays node and select "New Display".

"New Display" Menu

 "Render Targets" panel  

Specify the desired display name and display id in the "Add New Display" dialog:

 "Add New Display" Dialog  

Set the desired resolution of the display via Properties panel by editing ResolutionX and ResolutionY.

Properties Panel of Display  

A display can be deleted in the "Render Targets" panel. Right click on the display and select the "Delete" option from the context menu or press the Delete key.

Add a new Render Target

Add Render Target

A render target is an abstraction of a rendering surface. In the field of 3D computer graphics, it is a feature of modern graphics processing units (GPUs) that allows a 3D scene to be rendered to an intermediate memory buffer, or Render Target Texture (RTT). It can then be manipulated by shaders in order to apply additional effects to the final image before displaying it.

As mentioned before, there are two types of render targets:

• Display Render Targets: They address the rendering in a native surface of the graphic device.
• Texture Render Targets: They represent textures which can be used in the scene to render into them. 

A new render target can be added using one of the following possibilities:

Go to "Platform" > "New Render Target" in the menu bar or go to the Render Targets panel, right click on a node under the display and select "New Render Target" from the context menu.

Set the following items in the Add New Render Target dialog box and click [ OK ] to create a new Render Target.

(1)	Top input field	The location where the Render Target is saved in Solution Explorer
(2)	Name	The Render Target Name
(3)	Description	The Render Target Description
(4)	Annotations	The Render Target Annotations
(5)	URI	The Render Target URI
(6)	Export Always	If enabled, the Render Target selected at the time of asset generation is always exported to the asset.
(7)	Render Target Template	The Render Target template
(8)	Display	The display that is linked to the Render Target

The types available depend on the SceneComposer platform of a given solution, respectively of the feature set of the Candera Device specified by the platform.

The newly added render target can have the properties listed in the table below set in the Properties panel. The properties of the display render targets "Width", "Height" and "X", "Y" coordinates have to be configured with appropriate values that can be changed via Properties panel. The displays and the display render targets associated can be seen in the Render targets panel.

Section	Property name	Description
Render Target	Render Target Template	The Render Target template Select the Render Target template from the following: Hybrid 2D/3D Window Surface Hybrid 2D/3D Off-Screen Surface Software Layer For details, please refer to Cameras and Render Targets.
	Display	The Display that is linked to the Render Target This property can only be set when Render Target Template = Hybrid 2D/3D Window Surface.
	Owner	Hybrid 2D/3D Off-Screen Surface: Surface owner Software Layer: Software Layer owner This property can only be set when the Render Target Template is set to Hybrid 2D/3D Window Surface or Software Layer.
	Type	The Render Target type
	Auto Swap	If enabled, the buffer will be automatically swapped (switched to new drawing) once all cameras linked to the Render Target have completed drawing.
	Auto Clear	If enabled, the relevant buffers (color, depth, and stencil buffers) are automatically cleared before a rendering operation to a Render Target is performed. The depth buffer is cleared with "1.0" values.
	Is Default	If enabled, it will be set as the default Render Target. For details, please refer to Default Render Target.
	Orientation	Rotation angle of the rendered image (0°/90°/180°/270°) For details, please refer to Rotate Display Preview.
	ClearMode	A ClearMode item used to clear the buffer associated with a 3D Render Target. For instructions on how to create a ClearMode item, see ClearMode.
	ClearMode2D	Color to clear the color buffer of a 2D Render Target

The properties in the Edting Utilities section vary depending on the Render Target Template selected.

Render Target Template: Hybrid 2D/3D Window Surface Edting Utilities section properties:

Section	Property name	Description
Edting Utilities	Preview Border Scope	Preview borders for the targeted Render Target Available in Global Preferences. None: Border is hidden Global: Border based on global coordinates Local: Border based on local coordinates
	Preview Border Color	Preview border color for the target Render Target Available in Global Preferences.
	Width	Render target width (horizontal pixels) If this value is "-1", it is calculated from the Display value.
	Height	Render target height (vertical pixels) If this value is "-1", it is calculated from the Display value.
	X	The position of the Render Target along the X axis (horizontal direction) in the display linked to the Render Target
	Y	The position of the Render Target along the Y axis (vertical direction) in the display linked to the Render Target
	Layer	Window Surface Layer ID When there are multiple render targets, you can set the rendering order.The higher the number, the higher the layer will be. Bottom layer: Layer = 0 Middle layer: Layer = 1 Top layer: Layer = 2 The number of layers supported varies by device. Also, Window Surfaces with the same layer ID cannot be uploaded at the same time. For details, please refer to Multiple Render Targets.
	BlendMode	Blend mode BlendModeStandard: A common blend mode that represents transparency based on the alpha value of the source pixel. BlendModePreMultiplied: Performs blending as if the source pixel is already multiplied by the alpha value. BlendModeOff: Blending disabled For details, please refer to Blend Modes.
	AntiAliasingSampleBuffers	Number of sample buffers to use for anti-aliasing
	AntiAliasingMultiSamplingFactor	Minimum number of samples to use for multi-sample buffers used for anti-aliasing
	MaxSwapInterval	Maximum swap interval Set when using EGL settings. If this value is "-1", the maximum swap interval is not limited.
	MinSwapInterval	Minimum swap interval Set when using EGL settings. If this value is "-1", the minimum swap interval is not limited.
	SwapInterval	Swap Interval Applies to the Window Surface. The initial value is "1". If the value is "0", the buffer swap is not synchronized with the video frame, and the swap is performed as soon as rendering is completed. If the value is "1" or more, the buffer swap is performed every time the vertical synchronization signal (V-sync) is received the number of times specified by the value.
	RedSize	The number of bits for the Red color in the color buffer.
	GreenSize	The number of bits for the Green color in the color buffer.
	BlueSize	The number of bits for the Blue color in the color buffer.
	AlphaSize	The number of bits for the Alpha in the color buffer.
	Conformant	Set this property to enabled if Render Target is OpenGL ES compliant.
	DepthSize	Number of bits in the depth buffer
	StencilSize	Number of bits in the stencil buffer
	BufferPreservedBit	If enabled, Render Target contents are preserved after buffer swapping, potentially improving performance by reducing GPU strain when only a portion of the screen changes.

Render Target Template：Hybrid 2D/3D Off-Screen Surface Edting Utilities section properties:

Section	Property Name	Description
Edting Utilities	Preview Border Scope	Preview borders for the targeted Render Target Available in Global Preferences. None: Border is hidden Global: Border based on global coordinates Local: Border based on local coordinates
	Preview Border Color	Preview border color for the target Render Target Available in Global Preferences.
	ColorFormat	Color buffer format
	DepthFormat	Depth buffer format
	StencilFormat	Stencil buffer format
	ExternalColorTexture	Attaches an external color buffer to a Render Target.
	ExternalDepthBuffer	Attaches an external depth buffer to a Render Target.
	ExternalStencilBuffer	Attaches an external stencil buffer to a Render Target.
	Width	Render target width (horizontal pixels) If this value is "-1", it is calculated from the Display value.
	Height	Render target height (vertical pixels) If this value is "-1", it is calculated from the Display value.
	MsaaSamples	MSAA (Multisample Anti-Aliasing) Sample Count For details, please refer to Multisample Anti-Aliasing Offscreen Render Targets.

Render Target Template：Software Layer Edting Utilities section properties:

Section	Property Name	Description
Edting Utilities	Preview Border Scope	Preview borders for the targeted Render Target Available in Global Preferences. None: Border is hidden Global: Border based on global coordinates Local: Border based on local coordinates
	Preview Border Color	Preview border color for the target Render Target Available in Global Preferences.
	ColorFormat	Color buffer format
	DepthFormat	Depth buffer format
	StencilFormat	Stencil buffer format
	ExternalColorTexture	Attaches an external color buffer to a Render Target.
	ExternalDepthBuffer	Attaches an external depth buffer to a Render Target.
	ExternalStencilBuffer	Attaches an external stencil buffer to a Render Target.
	Width	Render target width (horizontal pixels)
	Height	Render target height (vertical pixels)
	X	The position of the Render Target along the X axis (horizontal direction) in the Render Target's owner (drawing area).
	Y	The position of the Render Target along the Y axis (vertical direction) in the Render Target's owner (drawing area).
	Layer	Software Layer ID When a Software Layer is made up of multiple layers, you can set the rendering order. The higher the number, the higher the layer.
	BlendMode	Blend mode For details, please refer to Blend Modes.
	ConstantAlpha	Alpha (transparency) applied to the entire Software Layer
	BufferCount	Number of buffers used by the Software Layer SoftwareLayerSingleBuffered SoftwareLayerDoubleBuffered
	Enabled	Enable (show)/disable (hide) Software Layers
	CompositionCamera	CompositionCamera The drawing of each layer in the Software Layer is used by the Composition Camera to generate the final display image. For details please refer to Software Layers.
	BorderEnabled	Show/Hide Layer Borders Each Software Layer is separated by a one-pixel border.

Please refer to the Candera API Documentation to learn about device-specific render target properties: 
Candera::RenderTarget

Every new created render target could be enabled or disabled by ticking the checkbox. When deactivating/activating a render target by unchecking/checking the checkbox, 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.

A render target can be deleted using the context menu option "Delete" in the Render Targets panel.

---

Configure Render Target

Configure a Display Render Target

In the "Render Targets" panel, the Display Render Targets are organized in the DisplayRenderTargets collection of a Display node. 
New display render targets will be listed under this category.

Configure a Texture Render Target

Rendering to a texture is simple on one hand, but on the other hand it is powerful and enables numerous special effects. It is an extension to rendering to a surface. 
Usually, for a texture render target, the texture render target properties "Width" and "Height" must be configured according to the required size of the texture.

To use a texture render target as a texture, SceneComposer allows selecting a texture render target in the "Choose Item" dialogs, whenever a texture shall be selected during composing a scene.

Clear Mode Item

The "Clear Mode" item can be created via "Solution Explorer" panel by using the context menu option ("Add" > "New Item"). In this way, all its specific properties ("Clear Color", "Enable Color Write", "Enable Depth Clear" and "Enable Stencil Clear") are related with just one item instead of being included among many other properties of every render target. If there are many render targets which are referencing the same clear mode item, it is enough to modify just one time the desired property rather than modifying every of them.

After the creation of a "Clear Mode" item, it can be used after being referenced from a specific Render Target. This operation can be done by using the "Clear Mode" property available in the "Properties" panel associated with any available render target.

If a ClearMode is a associated to a RenderTarget, the RenderTarget is cleared using that clearmode before any of the attached cameras renders to it.

Clear Mode Property
See also: Candera::ClearMode

---

Link a Camera to a Render Target

Link a Camera to a Render Target

There are two options on how to create a link between a camera and a render target:

• Camera to render target: Drag the camera in the Scene Tree panel and drop it on the desired render target in the Render Targets panel.
• Render target to camera: Drag a render target in the Render Targets panel and drop it on the desired camera in the Scene Tree panel. 

Existing links will be overridden by a new drag and drop operation.

Render Targets Panel with Camera enabled  

A camera can be associated to exactly one render target at a moment. 
A render target can be associated to one or more cameras, hence one or more cameras can use the same render target as output target.

---

Render Target Swapping

Once all cameras are finished with rendering their content onto a render target, the render target must be swapped. There are two options to ensure this:

• Enable the "Enable Swapping" property of exactly one camera linked to the render target. In case of more cameras, take the camera with the highest sequence numbers, so only the last camera linked to a render target will trigger the swap of the render target buffers.
• If no camera has "Enable Swapping" property enabled, the application must take care to swap the buffers during the render loop correctly. 

"Enable Swapping" property of Camera  

In case no swapping is done, the display will remain black. 
In case more than one swapping is done during a render pass, the display will flicker.

---

Additional Info about Rendering

This section explains the render loop performed by SCHost for the Scene Editor part of SceneComposer. For each frame, the following procedure is executed:

Displays are cleared (all the render targets are cleared) - due to specific requirements.

All cameras are rendered in the order specified by the camera property "Sequence Number". A camera is rendered only if it is explicitly enabled in the Render Targets panel.

Active Camera Rendering:

• 3D: Active camera attached to scene render panel is about to be rendered. 
  > If the camera has any ReflectionCamera children, they will be placed in a list along with the active camera. 
  > The list is sorted considering the Sequence Number property of the cameras. 
  > All the cameras in the list are rendered. 
  > The scene render panel render target is swapped.
• 2D: Active camera attached to scene render panel is rendered. 

Scene Rendered on a Configured Display  

Zoom Display Preview:

In some particular situations, the user could need an option to switch back to 100% of a display if its size has been modified. Consequently, the possibility to zoom in Display Preview through options in the context menu of the view is available. In the context menu which can be opened by right click anywhere in the display, eight given values are available: 200%, 175%, 150%, 125%, 100%, 75%, 50%, and 25%.

Context Menu with Zoom Options on a Preview Display  

---

Rotate Display Preview:

This function is used to rotate the orientation of the display preview to match the orientation of the target device (landscape/portrait). The CGI Player also has a similar function. See "Rotate" for details.

The display preview can be rotated in the below two ways.

• Set the rotation angle (0°/90°/180°/270°) from the context menu of the display preview.
• Set the rotation angle (0°/90°/180°/270°) from the Orientation property of the render target. This setting also applies to the rotation angle of the CGI Player.

Default Render Target

The default render target is the render target that new cameras are attached to by default. Visually, the default render target is identifiable by the "(default)" text near it's name or by the "Is Default" property which is checked. Also, its tooltip displays additional information.

Default Render Target Example  

The default render target works with Camera, Reflection Camera and Stereo Camera.

---

Manually Setting

Setting the default render target can be done in one of the following ways:

• via context command using the "Set As Default Render Target" option
• by enabling the property "Is Default" from the Property panel
• via [ Solutions Options > Default Render Target Configuration ] window 

---

Automatically Setting

The default render target is set automatically in one of the following two situations:

• when adding a new render target if there is no other
• when deleting the current default render target, if another one is available

---

Manage Render Targets

Manage Render Targets dialog allows you to view and edit the various settings of the render targets included in solution.

Open the Manage Render Targets dialog

The Manage Render Targets dialog can be opened in two ways:

• From the [ Platform > Manage Render Targets… ] menu on the menu bar
• The context menu of any render target in the Render Targets panel

Manage Render Targets dialog details

(1)	Create Render Target	Create a new Render Target.
(2)	Delete Render Target	Delete a Render Target.
(3)	Search	If multiple Render Targets are set, you can enter a search term to narrow the number of results.
(4)	Render Target list	A list of Render Targets included in the solution is displayed. (If a search term is set, only Render Targets that correspond to the search results are displayed.)
(5)	Annotations	The Render Target Annotations
(6)	URI	The Render Target URI
(7)	Export Always	If enabled, the Render Target selected at the time of asset generation is always exported to the asset.
(8)	Render Target Template	The Render Target type
(9)	Display	The display that is linked to the Render Target

---

Smart Scene/Camera Preview

Smart Scene/Camera Preview

It is possible to enable/disable camera visualization into the display(s) based on scenes. Depending (offscreen) cameras are automatically activated. The actions are offered via context menu on the camera, render target, display objects, and scenes. This option is available for the user via the following context menus:

1. Scene - Render in display (menu having children items):

• Enable all cameras
• Disable all cameras

"Render in Display" Option in the Scene's Context Menu  

2. Camera - Render in display (menu item having children items):

• Render only this camera - clears all cameras and enables only this camera
• Render all except this camera

"Render in Display" Option in the Camera's Context Menu  

3. Display - Render in display (menu having children items):

• Enable all cameras
• Disable all cameras

"Render in Display" Option in the Display's Context Menu  

4. RenderTarget - Render in display (menu having children items):

• Enable all cameras
• Disable all cameras

"Render in Display" Option in the Render Target's Context Menu  

Dependent cameras are 2D and 3D cameras which render in off-screen RenderTargets and the offscreen RenderTarget is used in a 3D scene as texture (e.g. billboard). 

---

Rendering Order

Rendering Order

The order in which the rendering occurs in SceneComposer follows the next rules:

1. All the widgets from the active scene get updated;
2. All the 2D cameras are rendered: all the cameras are sorted by following the sequence number; all the cameras are rendered on associated surfaces;
3. All the 3D cameras are rendered: all the cameras are sorted by following the sequence number; all the cameras are rendered on associated surfaces;
4. Active camera and all reflection cameras (if existing) are rendered on Scene Editor panel: a) The active camera is added on a list of cameras; b) On the same list all the "reflection camera" children type are added; c) The list is sorted by following the sequence number; d) The cameras from the list are rendered on Scene Editor panel. 

Buffer Swapping Rules (available for both 2D and 3D)

Usually, the last camera (based on the sequence number) that is rendered on a surface performs a buffer swap (being the latest camera, the frame is completely updated so it can be displayed).

Clearing rules:

• 2D: a) Scissoring not active: cameras clear the surface on the region which is indicated by the viewport b) Scissoring active: cameras clear the surface on the region which is indicated by the scissoring rectangle
• 3D: the cameras clear the surfaces inside the region created by the scissor box (when scissoring is enabled). By default, the scissor box is equivalent with the whole surface (-0, 0, 1, 1). In conformity with OpenGL specifications, the viewport does not affect the clearing region (this is a driver dependent rule). 

---

Display Renderer Statistics

Add display

Render Statistics inform the user about current performance indicators during rendering. Therefore they are of major help when trying to identify performance bottlenecks. This information is presented to the user in a dedicated panel which can be made visible through the "Render Statistics" menu item from the "View" menu.

"Render Statistics" Menu  

The panel will be displayed by default in the top right region of the SceneComposer user interface. Also this panel can be moved in any other area.

"Render Statistics" panel  

The Renderer Statistics structure keeps track of per pass data that is relevant to the user. This includes statistics about the metrics of:

• Draw Calls
  
• Uniform Calls
• Vertices
• Indices
• ColorBufferClears
• DepthBufferClears
• StencilBufferClears
• AverageDirtyAreaFactor
• CulledNodesUsingDirtyAreaScissor
• Uniform Buffer Updates
• Pixcel buffer mappings
• Render Camera Calls
  
• Occlusion Queries (available on OpenGL ES 3.0 API only)
• Visible Draw Calls (available on OpenGL ES 3.0 API only)
• Invisible Draw Calls (available on OpenGL ES 3.0 API only) 
  

Some specific pieces of information are the following:

2D:

• Uploaded BitmapImages
• Total Uploaded BitmapImages
• Render Camera2D Calls

3D:

• Uploaded Textures (incl. breakdown to BitmapTextureImages, CubeMapTextureImages, DirectTextureImages)
• Total Uploaded Textures (incl. breakdown to BitmapTextureImages, CubeMapTextureImages, DirectTextureImages)
• Uploaded Shader Programs
• Total Uploaded Shader Programs
• Uploaded VertexBuffers
• Total Uploaded VertexBuffers
• Render Camera Calls 
  

The numbers shown in the statistic accumulate a typical render pass conducted by RenderAllCameras. The user can disable or enable cameras and render targets within the RenderTarget panel to sum up and view statistics for only those selected items. To gather statistics, three basic conditions have to be fulfilled. First, the display has to be set active. Second, the "Enable Rendering" property of any camera has to be checked. Third, the camera(s) should have the rendering enabled.

This selection is already available, see the panels RenderTargets/RenderTargetView or RenderTargets/CameraGroupView. The render statistics dialog may display values which are different than zero on some platforms, even if there is no camera configured to render. This may happen, for example, on iMX6 platform, because of the software layers rendering simulation.

To see how the Geometry Instancing feature works, the user has the opportunity to observe its functionality through Render Statistics. The next steps will be followed: 
(To perform these steps, you need a system that supports OpenGL ES 3.0.)

• Open/create an OpenGL ES 3.0 Solution like 3D Basic Solution;
• Import an .fbx object;
• Create a 3D scene containing the object and a camera (do not activate occlusion culling render strategy);
• Create a display, a render target and set the camera to render on the display;
• Add shader with instancing support (ex: RefTransLight1Inst_RefColorTex ) to the appearance;
• Add UniformSetter to the appearance;
• Set either "Lights Activation" to false or "Light Coordinate Space" to World on the UniformSetter;
• Save its appearance collection as a template and enable Instance Sharing;
• Drag the newly created template back on the mesh;
• Clone the object a few times;
• At this point each Cube must have a shared Appearance with a shader that supports instancing and a uniform setter;
• Enable the Render Statistics Panel; 
  
• If Geometry Instancing IS NOT working then Draw Calls will be "N", Instanced Draw Calls will be "0" and Instances will be "0" (where "N" is the number of identical meshes); 
  
• If Geometry Instancing IS working then Draw Calls will be "1", Instanced Draw Calls will be "1", Instances will be "N" (where "N" is the number of identical meshes). 
  

Geometry Instancing through "Render Statistics" panel  

If CANDERA_RENDER_STATE_CACHING_ENABLED and CANDERA_DETAIL_STATISTICS_ENABLED are set to true, additional information about Render State Cache Effectivity is available.

• Render State Cache Hits informs about the number of OpenGL state changes that were saved because the value was already cached. 
  
• Render State Cache Misses informs about the number of OpenGL state changes that had to be executed because the new value was not in the cache. 
  
• With these values the Render State Cache Hit Rate can be calculated, where 100% would mean no state changes. 
  

These values are visible either in the Render Statistics Overlay of the Player, the Render Statistics Panel in SceneComposer (only for applicable properties) or directly accessible from the API.

Render Statistic Overlay  

---

CGI Studio HMI Rotation

It might occur that a hardware display that is designed for landscape mode (horizontal orientation) is installed into an environment where it is actually used in portrait mode (vertical orientation). This would mean, the designers and programmers would have to create the HMI rotated by 90° and arch their neck whenever they want to check if it looks fine.

To support tricky usecases like that, CGI Studio Scene Composer offers a convenient HMI rotation feature that goes far beyond this particular case. The user can design and program his HMI the way it will finally be displayed. The necessary rotation will be added separately. You can configure to rotate the HMI by 0° (default), 90°, 180° or 270° clockwise.

Example and Configuration

In the following example configuration we will simulate the usecase from above: a display that is designed for landscape mode will be used in portrait mode.

1. Create a Scene Composer solution with a 2D scene  (you can e.g. use the empty solution provided on the Scene Composer's Start Up screen).

2. Configure the Display for landscape mode.

3. Configure the Render Target to be rotated by 90° clockwise.

4. Add 2 TextNodes to the scene by dragging 2 them from the Toolbox to the Scene Editor or Scene Tree Panel.

5. Move the TextNodes apart in the Scene Editor so that they are clearly visible. Then change their Text property in the Properties Panel to "Top Left" and "Bottom Right".

6. Open the Display preview through the menu "View - Display - Display (0)".

7. You can see that the Display's orientation is still landscape. We have to physically rotate the display by 270°. This is like rotating the physical hardware device that is in front of you. To do this, right click into the display window and choose "Rotate 270°".

The Display window will display your HMI as intended. You can now reposition the TextNode "Bottom Right" to the bottom right and the configuration example is done.

Rotation in Player

Save the solution configured in the steps above and start the player hitting the Play button of the "Generate and Play" option from the Toolbar.

This will open the player and the Display will be in landscape mode.

The display of the Player can be rotated as well using the corresponding icons in the CGI Panel's toolbar.

When configuring a display rotation of 270° clockwise for the Player (same as we did for the display in Scene Composer), the Display will be oriented correctly again. The current configuration of the display's rotation will be displayed in the Player's title bar.