Building Player, Widgets, and SCHost

• Introduction
• Building CGI Panel
• Building Player and Widgets
• Activating Additional Behaviors for Player
• Building SCHost for SceneComposer
• Customizing Widgetset Generation
• BehaviorSet Library with Behavior Set Parts
• Candera Version Validation
• Using Player on 64 bit Systems
• Debugging Hints
• Used Behaviors Plugin

Introduction

CGI Studio provides an integrated development environment based on Visual Studio for widget and application layer development, located at:

In the cgi_studio_player directory, 4 different projects are defined:

The following pages explain how to build these components.

Building CGI Panel

The CGI Panel is a C# project which provides a graphical interface which supports the control of scenes and animations by managing the flow of the Player. 

Building CGI Panel

Usually there is no need to build the CGI Panel on your own, since the executable is already provided for the Player build environment - refer to either:

Building CGI Panel

For building a new CGI Panel, refer to the following steps:

This solution allows the customer to extend the windows UI control of the Player.

Actually, the C# Panel is responsible for providing the following Player control panel:

For additional information regarding CGI Panel User Interface please take a look at CGI Panel User Interface - Overview.

Upon opening a specific asset library, the CGI Panel will attach to a Player for asset loading and content display. The next section explains how to create the application.

Building Player and Widgets

Building Player and Widgets

The Player executable used by CGI Panel collects following components:

Build output will be named according to the Candera device platform configuration.

For example if you build for your device on host simulation, the following executable will be created:

Load Assets in Player

After starting CGIPanel.exe from this location, you will be able to load assets generated for host simulation with the Player. For building the Player, refer to following steps:

If CGIPanel pops up but the asset content is not shown use the File->Attach menu to connect the panel to the Player. 

Activating Additional Behaviors for Player

To include the behaviors part of CGI Studio in the Player, simple enable the CMake option CGIAPP_ENABLE_ADDITIONAL_BEHAVIORS before generating the CGI Application solution with CMake.

The CMake option CGIAPP_ADDITIONAL_BEHAVIOR_PATH is already preconfigured to include widgets part of <cgi-studio-root>/cgi_studio_player/src/Behaviors/AdditionalBehaviorsPaths.txt.

Following projects will be created in the solution with above cmake configuration:

Building SCHost for SceneComposer

To make the same set of widgets available for SceneComposer, as they are for the Player, a new SCHost.dll needs to be created and deployed to SceneComposer. 

That's the reason why the SCHostDll project is part of the C++ Player.sln, because this way the widget set configuration for the Player is identical to the one for SCHost.dll .

However, in difference to the Player, SceneComposer requires a specific set of Candera static libraries to link together with the widgets part of the solution. These specific libraries are created as part of the compilation process and collected into a library names SCHostLib.lib. The corresponding Visual Studio project is named SCHostLib.
When the SCHostDll project is built, SCHostLib.lib will be linked together with the widgets and the Candera Device lib part of the solution into the SCHostDll.dll library.

To automatically copy the generated SCHostDll.dll to your SceneComposer executable location as SCHost.dll after the build, take care to set the following CMake variable:

SCHost and Memory Pools

As memory pools are introduced in FeatStd V1.2.0 resp. V1.1.0.3, and an SCHost build using this feature is not binary compatible to a build not using memory pools, a new restriction is added for building SCHost.dll:

As a consequence, the build system for cgi_studio_dev will not add the SCHost project when Memory Pools are enabled.

Customizing Widgetset Generation

Customizing Widgetset Generation

For adding your own behaviors and widgets to the default widget set, it is required to specify them in the widget set definition (WidgetSet.cpp), which is finally accessed by SceneComposer to provide all exported behaviors and widgets in the user interface.

The Candera CMake build system automatically generates this widget set definition (WidgetSet.cpp), so it is only required to provide behavior and widget implementations at any location and to specify this additional behavior and widget location for CMake.

This chapter explains how the widget set generation works.

Specifying Widget Set (WidgetSet.cpp)

The main widget set is a project to generate a library containing definitions for all behaviors and widgets to be used. Behavior and widget implementations can be part of other libraries which of course also need to be linked together with the widget set definition.

Refer to the CMake configuration of the Player demo widget set:

Refer to the following example from the Player behaviors:

# Declare widget set class files
set(WidgetSet_SRC
    ${PRV_CGI_GENERATED_CANDERA_DIR}/WidgetSet.cpp
)
source_group("WidgetSet" FILES ${WidgetSet_SRC})

# Declare behavior set class files
set(BehaviorSet_SRC
    ${PRV_CGI_GENERATED_CANDERA_DIR}/WidgetSet.cpp
)
source_group("BehaviorSet" FILES ${BehaviorSet_SRC})


# Register widget set
CgiAddWidgetSet(PRV_WIDGET_TARGET_NAME_WIDGETSET WidgetsSet ${WidgetSet_SRC})

# Register behavior set
CgiAddWidgetSet(PRV_WIDGET_TARGET_NAME_WIDGETSET BehaviorSet ${BehaviorSet_SRC})


# Declare default widget directories (include here all your subdirectories 
# containing behavior and/or widget implementations
include(${CGISTUDIO_BEHAVIORSET_CMAKE_INCLUDE})
if (CGIAPP_ENABLE_ADDITIONAL_WIDGETS)
    if ((EXISTS "${CGIAPP_ADDITIONAL_WIDGET_PATH}"))
        CgiAddAdditionalWidgets(${CGIAPP_ADDITIONAL_WIDGET_PATH} "Widgets_CgiStudioWidgetsLib")
    endif()
endif()



if (CGIAPP_ENABLE_ADDITIONAL_BEHAVIORS)
    if ((EXISTS "${CGIAPP_ADDITIONAL_BEHAVIOR_PATH}"))
        CgiGetCurrentDir(PRV_CUR_DIR)
        CgiAddAdditionalBehaviors(${CGIAPP_ADDITIONAL_BEHAVIOR_PATH} "ControlBehaviors")
    endif()
endif()
#add to WidgetSet.cpp
    
if (CGIAPP_ENABLE_TUTORIAL)    
    source_group(PRV_ALL_SRCS FILES ${PRV_CGIAPP_TUTORIALWIDGET_SUBDIRS})
    CgiCollectListedFiles(PRV_ALL_SRCS "" "" LIST ${PRV_CGIAPP_TUTORIALWIDGET_SUBDIRS})
    CgiFetchHeaderFiles("Widgets_Tutorial" "${PRV_CGIAPP_TUTORIALWIDGET_SUBDIRS}")
endif(CGIAPP_ENABLE_TUTORIAL)



source_group(PRV_ALL_SRCS FILES ${PRV_CGIAPP_BEHAVIORS_SUBDIRS})
CgiCollectListedFiles(PRV_ALL_SRCS "" "" LIST ${PRV_CGIAPP_BEHAVIORS_SUBDIRS})
#CgiFetchHeaderFiles("Behaviors_Examples" "${PRV_CGIAPP_BEHAVIORS_SUBDIRS}")
CgiFetchBehaviorsHeaderFiles("Behaviors_Examples" "${PRV_CGIAPP_BEHAVIORS_SUBDIRS}

In this example, following projects will be created in the solution:

Adding Widget Sets

If other locations than in the example above shall be included for widget set generation, following steps are required:

The project will contain a sub project for the generated widget set, a sub project for the main widget set, and further sub projects for each additional widget location specified in AdditionalBehaviorsPaths.txt and/or AdditionalWidgetsPaths.txt.

BehaviorSet Library with Behavior Set Parts

With the new CMake environment, a new CMake Flag CANDERA_DEPRECATED_WIDGETSET_ENABLED is available (Default setting is ON). When this flag is turned OFF, then instead of a single file "WidgetSet.cpp", several files are generated for every Widget or Behavior library.

This might resolve known issues with too many symbols generated during compilation of single "WidgetSet.cpp" file.

Candera Version Validation

To ensure, that an application like the Player always refers to the proper Candera version, following CMake configurations can be used:

<CANDERA_DIR>/CgiStudioCanderaConfig.cmake: This file specifies the actual version of Candera, e.g.:

 set(CGI_CANDERA_VERSION "3.12.0.0") 

Accordingly, proper Candera build defines will be generated, accessible for applications via <CANDERA_DIR>/src/Candera/CanderaVersion.h

<CGI-Player_DIR>/src/CgiStudioPrereqs.txt: This file is an example how an application will request a specific Candera version:

 set(CGI_CANDERA_VERSION_REQUIRED "3.12.0.0") 

<CGI-Player_DIR>/cmake/cgiapp_cmake_common.cmake: This cmake file contains an example how an application can detect a Candera folder matching a specific Candera version (via cmake find_package command).

Using Player on 64 bit Systems

For Player, the CMake project generator should be of type Win64 (e.g. Visual Studio 15 2017 Win64) and it should be built with the "COURIER_PLATFORM_CONFIG" setting set to "x64". This is the only way to build a SCHost.dll that can be used in SceneComposer　

Debugging Hints

Debugging Player

For debugging the Player set "Player" as startup project in the Player solution and start debugging.

With CMake, the required Debugging configurations are preconfigured as following:

 

Debugging Widget Life Cycle in SceneComposer

For debugging widgets used in SceneComposer please execute the following steps:

Set:

Used Behaviors Plugin

The "Used Behaviors Plugin" extracts the type names of all Behaviors referenced in a solution.
At asset generation time, it generates a CMake file as given in the plugin configuration.

When configuring a build with CMake, there is a new option "CONTROLS_PLUGIN_CONFIGURATION_ENABLED".

This option is hidden, when "COURIER_ADD_SCHOST_PROJECT" flag is set to ON.

When the option "CONTROLS_PLUGIN_CONFIGURATION_ENABLED" is turned on, then another option "CONTROLS_USED_BEHAVIORS_CONFIG_PATH" is exposed, which must be set to the file as configured in the plugin.

Then the build is configured by CMake to only contain the Behaviors referenced in the solution, and some base behaviors and functionality, which is always required.