Startup and Asset Management Description This tutorial leads through all required steps to initialize and prepare a Candera application for loading a SceneComposer generated asset and accessing content provided by the asset. Initializing AssetLoader and Animations  AssetLoader For loading assets and accessing content, the application needs to create an instance of an Candera::AssetProvider and Candera::ContentLoader to have them available for later usage. m_contentLoader = &ContentLoader::GetInstance(); m_contentLoader->Init(&m_assetProvider); Animations If Animations are used in the scene, a time dispatcher for dispatching world time to animation players needs to be constructed during initialization. m_animationDispatcher = Animation::AnimationTimeDispatcher::Create (); UpdateSystem* updateSystem = EntitySystem::Get(); if (0 != updateSystem) { UpdateSystem::Handle animationUpdateComponent = updateSystem->CreateComponent(); CANDERA_SUPPRESS_LINT_FOR_SYMBOL(1025, Candera::UpdateDelegate::UpdateWithMilliseconds , "False positive because the template arguments match.") UpdateSystem::Delegate animationUpdateDelegate = UpdateSystem::Delegate::UpdateWithMilliseconds(); result = updateSystem->SetComponentUpdateDelegate(animationUpdateComponent, animationUpdateDelegate) && result; result = updateSystem->AttachComponent(animationUpdateComponent, m_animationDispatcher.GetPointerToSharedInstance()) && result; } #ifdef CANDERA_TRANSITIONS_ENABLED if (0 != m_transitionStrategy) { m_transitionStrategy->SetAnimationTimeDispatcher(m_animationDispatcher); } #endif Initializing 3D DefaultRenderMode  3D DefaultRenderMode The default render mode is kind of a "global" render mode which is applied to all Nodes within a 3D Candera::Scene which have no separate Candera::RenderMode set. Further, if a Candera::Node has its own RenderMode set, still dedicated components can be derived from Candera::DefaultRenderMode - like e.g. CullMode - if the "inheritance bit" in the Node's associated RenderMode is set to true. If RenderMode is defined for a Candera::Camera , the RenderMode of the camera replaces the DefaultRenderMode, temporarily during the camera's render pass. The DefaultRenderMode can be created and manipulated as follows: /* To overwrite the default render mode as specified in scene composer you can create your own render mode. This would have to be set via Renderer::SetDefaultRenderMode(renderMode); */ Candera::MemoryManagement::SharedPointer renderMode = RenderMode::Create (); renderMode->SetWinding(RenderMode::CounterClockWise); renderMode->SetCulling(RenderMode::BackFaceCulling); renderMode->SetDepthWriteEnabled(true); renderMode->SetDepthTestEnabled(true); Apply DefaultRenderMode In SceneComposer the default render mode can be configured in configuration menu - see Render Mode in SceneComposer User Manual In Candera , use the interface Candera::Renderer::SetDefaultRenderMode . When initializing an asset the default render mode in Candera will be replaced by the values from the asset! Loading an Asset  Initializing AssetProvider To initialize Candera::AssetProvider either a Candera::AssetRepository or Candera::AssetConfig has to be specified. AssetRepository Candera::AssetRepository is an abstraction of the actual location of the asset. Currently following implementations are available: Candera::FileAssetRepository for assets in file system Candera::MemoryAssetRepository for assets in memory, e.g. flash memory. Custom AssetRepository implementations are possible. AssetConfig Candera::AssetConfig allows to specify multiple AssetRepository instances, typically for assets that are split with asset shaper and accessed on different locations. The application has to derive from the abstract Candera::AssetConfig to create an AssetConfig that supports the AssetRepository instances according to the specific needs. This AssetConfig can then be used to initialize Candera::AssetProvider : FEATSTD_LOG_INFO("- Initializing asset provider ..."); static UInt32 validationFlags = AssetValidation::Flag() | AssetValidation::Flag() | AssetValidation::Flag(); if (!m_assetProvider.Initialize(&m_assetConfig, validationFlags)) { m_loadError = "Error: Asset initialization and validation failed!"; FEATSTD_LOG_ERROR("%s\n", m_loadError); return false; } Creating a FileAssetRepository Before loading an asset from a file, ensure that the file exists at the given path. Then a Candera::FileAssetRepository can be created using the file path: FileAssetRepository* repo = CANDERA_NEW(FileAssetRepository)(fileName); FEATSTD_DEBUG_ASSERT(repo != 0); If this operation succeeds, the asset repository can be added to an Candera::AssetConfig or specified directly to initialize Candera::AssetProvider . Creating a MemoryAssetRepository To create a Candera::MemoryAssetRepository the start address, where the asset can be found (e.g. the address in flash memory) has to be specified. MemoryAssetRepository* repo = CANDERA_NEW(MemoryAssetRepository)(startMemoryAddress); FEATSTD_DEBUG_ASSERT(repo != 0); If this operation succeeds, the asset repository can be added to an Candera::AssetConfig or specified directly to initialize Candera::AssetProvider . Retrieving AssetDescriptor After initializing the Candera::AssetRepository , the Candera::AssetDescriptor can be retrieved: const AssetDescriptor& assetDescriptor = m_assetProvider.GetAssetDescriptor(); The AssetDescriptor contains information about the asset library file and Candera::AssetNamesList lists of all scenes, animations, displays etc. can be queried. Create Displays and Render Targets It is recommended to check if the asset contains at least one configured display, otherwise no display content will be visible in the application. if (assetDescriptor.GetAssetObjectCount( DisplayLib ) == 0) { m_loadError = "Error: Missing elements.\n Please make sure that there are at least one display and at least one display render target and the cameras are attached to the corresponding render targets."; m_assetProvider.Finalize(); return false; } Next, the displays configured in the assets are created: Int displayId = -1; bool result = true; const AssetDescriptor& assetDescriptor = m_assetProvider.GetAssetDescriptor(); Display* display = 0; Int displayWidth = -1; Int displayHeight = -1; for (AssetDescriptor::AssetIdIterator displayList = assetDescriptor.GetAssetIdIterator( DisplayLib ); displayList.IsValid(); ++displayList) { displayId = m_assetProvider.GetDisplayDataById(*displayList, displayWidth, displayHeight); //check if already created before and destroy display = DevicePackageInterface::GetDisplay(displayId); if(display != 0) { DevicePackageInterface::DestroyDisplay(display); } display = DevicePackageInterface::CreateDisplay(displayId); if (display == 0) { FEATSTD_LOG_ERROR("Could not create display.\n"); result = false; } static_cast(m_displays.Add(display)); // Load display meta information if (result) { if (!m_assetProvider.LoadDisplayProperties(*displayList)) { FEATSTD_LOG_INFO("- Loading of display properties failed"); } } // Upload display if required if (result && upload) { Display::CommonSettings settings; settings.height = displayHeight; settings.width = displayWidth; if (!display->Upload(settings)) { FEATSTD_LOG_ERROR("Could not upload display.\n"); result = false; } } // For simulation displays, set AutoKick disabled if ((display != 0) && (display->ToSimulatedDisplay() != 0)) { display->ToSimulatedDisplay()->SetAutoKickEnabled(false); FEATSTD_LOG_INFO("- AutoKick disabled"); } #ifdef FEATSTD_OS_WIN32 //AppEnvironment::GetInstance().SetWindowPointer(display); #endif } return result; Here is an example how all render targets/layers can be read out of the asset file for further usage (like uploading, swapping, finalizing): GraphicDeviceUnit* gdu = 0; const AssetDescriptor& assetDescriptor = m_assetProvider.GetAssetDescriptor(); Int rtCount = assetDescriptor.GetAssetObjectCount( RenderTargetLib ); FEATSTD_UNUSED(rtCount); FEATSTD_LOG_INFO("Render target lib count = %d", rtCount); #if (defined(CANDERA_3D_ENABLED) && defined(CGIAPP_STATISTICS_OVERLAY_ENABLED)) static bool isRenderStatisticOverlayAttached = false; #endif for (AssetDescriptor::RenderTargetIdIterator gduList = assetDescriptor.GetRenderTargetIdIterator(); gduList.IsValid(); ++gduList) { gdu = m_assetProvider.GetGraphicDeviceUnitById(*gduList); if (gdu != 0) { const Char* gduName = m_assetProvider.GetGraphicDeviceUnitById(*gduList)->GetName(); FEATSTD_UNUSED(gduName); #if (defined(CANDERA_3D_ENABLED) && defined(CGIAPP_STATISTICS_OVERLAY_ENABLED)) Candera::DevicePackageDescriptor::UnitCategory unitCategory = DevicePackageDescriptor::GetUnitCategory(gdu->GetUnitType()); switch (unitCategory) { case DevicePackageDescriptor::DisplayTarget3D: case DevicePackageDescriptor::DisplayTarget2D: case DevicePackageDescriptor::Mixed2D3DDisplayTarget: // attach listener to first valid RT if (!isRenderStatisticOverlayAttached) { Candera::RenderTarget2D* renderTarget = gdu->ToRenderTarget2D(); if (0 != renderTarget) { renderTarget->AddEventListener(m_renderTargetEventListener); isRenderStatisticOverlayAttached = true; } } break; default: //do nothing; break; } #endif FEATSTD_LOG_INFO("GDU name = %s", gduName); if (upload) { //only upload if specified if (gdu->Upload()) { FEATSTD_LOG_INFO("GDU upload sucessful"); } else { FEATSTD_LOG_ERROR("Upload of GDU %s failed\n", gduName); } } static_cast(m_gdus.Add(gdu)); } else { FEATSTD_LOG_INFO("GDU null pointer returned"); } } Creating 3D Scenes from the Asset  Getting 3D Scene List In case that Candera::AssetProvider has successfully loaded an asset file, 3D scenes part of the asset are constructed like in the following example. By means of Candera::AssetDescriptor::GetAssetIdIterator , it is possible to retrieve a list of 3D Scenes: for (AssetDescriptor::AssetIdIterator sceneIdList = assetDescriptor.GetAssetIdIterator( SceneLib ); sceneIdList.IsValid(); ++sceneIdList) { static_cast(sceneList.Add(m_assetProvider.GetSceneById(*sceneIdList)->GetScene()->GetName())); } Loading 3D Scene The following listing shows how a Candera::Scene instance is finally loaded from the asset via Candera::ContentLoader::BuildSceneContext(): // load scene by building the regarding scene context ContentLoader::UploadPolicy uploadPolicy = ContentLoader::NoVramUploadPolicy; if (upload) { uploadPolicy = ContentLoader::DefaultUploadPolicy; } ContentLoader::BuildState buildState = contentLoader->BuildSceneContextById(sceneId, uploadPolicy); // load all packages of the scene without interleaved rendering. while (buildState == ContentLoader::MorePackets) { buildState = contentLoader->BuildSceneContextById(sceneId, uploadPolicy); } if (buildState == ContentLoader::Completed) { sceneContext = contentLoader->GetSceneContextById(sceneId); } else { sceneContext = 0; } The Candera::ContentLoader::DefaultUploadPolicy argument of the BuildSceneContext method forces the ContentLoader to create the scene data in the System RAM and to upload the asset data to VRAM. The upload of the asset data to VRAM can be avoided, if necessary, by using the argument Candera::ContentLoader::NoVramUploadPolicy instead. The setting Candera::DefaultAssetProvider::SetIterativeLoadingEnabled() allows iterative loading of device objects during calls to Candera::ContentLoader::BuildSceneContext(). In combination with Candera::ContentLoader::NoVramUploadPolicy it is possible to load and upload a scene iteratively in background while another scene is rendered. Further, all 3D Widgets related to the given scene can be retrieved from the SceneContext and configured as required. To support animated widgets, the application needs to provide a Candera::Animation::AnimationTimeDispatcher to its widgets, like this: Animation::AnimationTimeDispatcher::SharedPointer animationTimeDispatcher = GetAnimationTimeDispatcher(); WidgetBase* widget = 0; for (bool success = sceneContext-> GetFirstWidget (widget); success; success = sceneContext-> GetNextWidget (widget)) { if (widget != 0) { widget->SetAnimationTimeDispatcher(animationTimeDispatcher); // Register Controller for all GenericEventWidgets ExampleWidgets::CgiEventWidget* gew = Dynamic_Cast(widget); if (gew != 0) { #ifdef USE_STATE_MACHINE // Register Statemachine for Widget Events gew->Register(GenericController::UiEventCallback, 0); #endif // Set input event provider for every widget gew->SetInputEventProvider(GetInputEventProvider()); // FEATSTD_LOG_INFO("* ++ widget registered for Input-Events ...\n"); } } } for (TreeIterator nodeIterator(sceneContext-> GetScene ()); nodeIterator.IsValid(); nodeIterator.Advance(TreeIterator::AdvanceToDescendant)) { CompositeGroup* compositeGroup = Dynamic_Cast(nodeIterator.GetNode()); if (compositeGroup != 0) { for (CompositeGroup::WidgetIterator widgetIterator = compositeGroup->GetWidgetIterator(); widgetIterator.IsValid(); ++widgetIterator) { widget = *widgetIterator; widget->SetAnimationTimeDispatcher(animationTimeDispatcher); } } } Creating 2D Scenes from the Asset  Getting 2D Scene List It is possible to retrieve a list of 2D Scenes from Candera::AssetDescriptor : for (AssetDescriptor::AssetIdIterator scene2DIdList = assetDescriptor.GetAssetIdIterator( Scene2DLib ); scene2DIdList.IsValid(); ++scene2DIdList) { static_cast(sceneList.Add(m_assetProvider.GetScene2DById(*scene2DIdList)->GetScene()->GetName())); } Loading 2D Scene The following listing shows how a Candera::Scene2D instance is finally loaded from the asset: // load scene by building the regarding scene context ContentLoader::UploadPolicy uploadPolicy = ContentLoader::NoVramUploadPolicy; if (upload) { uploadPolicy = ContentLoader::DefaultUploadPolicy; } ContentLoader::BuildState buildState = contentLoader->BuildScene2DContextById(sceneId, uploadPolicy); // load all packages of the scene without interleaved rendering. while (buildState == ContentLoader::MorePackets) { buildState = contentLoader->BuildScene2DContextById(sceneId, uploadPolicy); } if (buildState == ContentLoader::Completed) { sceneContext = contentLoader->GetScene2DContextById(sceneId); } else { sceneContext = 0; } As in the 3D case, the Candera::ContentLoader::DefaultUploadPolicy argument of the BuildScene2DContext method forces the ContentLoader to create the scene data in the System RAM and to upload the asset data to VRAM. The upload of the asset data to VRAM can be avoided, if necessary, using the argument Candera::ContentLoader::NoVramUploadPolicy instead. The setting Candera::DefaultAssetProvider::SetIterativeLoadingEnabled() allows iterative loading of device objects during calls to Candera::ContentLoader::BuildSceneContext(). In combination with Candera::ContentLoader::NoVramUploadPolicy it is possible to load and upload a scene iteratively in background while another scene is rendered. Again, similar to 3D widgets, 2D widgets related to the given scene can be retrieved from the SceneContext. Also in this 2D example the application provides a Candera::Animation::AnimationTimeDispatcher to its 2D widgets: Animation::AnimationTimeDispatcher::SharedPointer animationTimeDispatcher = GetAnimationTimeDispatcher(); WidgetBase* widget = 0; for (bool success = sceneContext-> GetFirstWidget (widget); success; success = sceneContext-> GetNextWidget (widget)) { if (widget != 0) { widget->SetAnimationTimeDispatcher(animationTimeDispatcher); // Register Controller for all GenericEventWidgets ExampleWidgets::CgiEventWidget2D* gew = Dynamic_Cast(widget); if (gew != 0) { #ifdef USE_STATE_MACHINE // Register Statemachine for Widget Events gew->Register(GenericController::UiEventCallback, 0); #endif // Set input event provider for every widget gew->SetInputEventProvider(GetInputEventProvider()); // FEATSTD_LOG_INFO("* ++ widget registered for Input-Events ...\n"); } } } for (TreeIterator nodeIterator(sceneContext-> GetScene ()); nodeIterator.IsValid(); nodeIterator.Advance(TreeIterator::AdvanceToDescendant)) { CompositeGroup2D* compositeGroup = Dynamic_Cast(nodeIterator.GetNode()); if (compositeGroup != 0) { for (CompositeGroup2D::WidgetIterator widgetIterator = compositeGroup->GetWidgetIterator(); widgetIterator.IsValid(); ++widgetIterator) { widget = *widgetIterator; widget->SetAnimationTimeDispatcher(animationTimeDispatcher); } } } Loading Animation an AnimationGroup   Loading Animation As can be seen from application initialization, the application already configured a Candera::AnimationTimeDispatcher. Animations configured in SceneComposer can be loaded from the asset into a Candera::AnimationPlayer and started like following: Animation::AnimationPlayerBase::SharedPointer animationPlayer = m_assetProvider.GetAnimationById(assetId); if (animationPlayer != 0) { static_cast(m_animationDispatcher->AddPlayer(animationPlayer)); if (!m_animationPlayers.Contains(animationPlayer)) { static_cast(m_animationPlayers.Add(animationPlayer)); } if (!animationPlayer->Start()) { FEATSTD_LOG_ERROR(" ERROR: animation player start failed for'%s\n", animationName); } } Loading AnimationGroup Candera::AnimationGroup allows to start a hierarchical group of animations as configured in SceneComposer. The steps are similar besides that all children within the group have to be added to the Candera::AnimationTimeDispatcher, so it is advised to iterate through the tree recursively adding each child. The group can then be started at once: if (animationPlayer->IsTypeOf(Animation::AnimationGroupPlayer::GetTypeId())) { Animation::AnimationGroupPlayer::SharedPointer animationGroupPlayer = Dynamic_Cast(animationPlayer); if (animationGroupPlayer != 0) { AddAnimationGroupChildren(animationGroupPlayer, animationGroupPlayer->GetFirstSuccessor(SharedPointer(0), Animation::AnimationGroupPlayer::WithPrevious)); if (!animationGroupPlayer->Start()) { FEATSTD_LOG_ERROR(" ERROR: animation player group start failed for'%s\n", animationName); } } Selecting a Theme   Retrieving Available Themes The available themes in the asset can be retrieved via Candera::AssetDescriptor : for (AssetDescriptor::AssetIdIterator themeIdList = assetDescriptor.GetAssetIdIterator( ThemeLib ); themeIdList.IsValid(); ++themeIdList) { static_cast(themeList.Add(*themeIdList)); } Selecting a Theme Afterwards one of the available themes can be set to Candera::AssetProvider : Candera::Id themeId = AssetProviderFunctions::GetIdByName(&m_assetProvider, ThemeLib , themeName); m_assetProvider.SetCurrentThemeById(themeId); From now on this theme will be used when loading new scenes. You need to reload the scene explicitly when you change the theme! Loading User Data   User data are raw data of any arbitrary type or format. A SceneComposer asset can be used as a pass-through for such kind of proprietary data to the application. Steps required: Import Raw Data to the SceneComposer solution Assign a numerical asset id like "1" to the data item in SceneComposer, optionally assign a symbolic name for this item Export the asset (also the symbolic names header file is exported) and load it in the application Access the raw data via a ResourceHandle retrieved from Candera::AssetProvider based on the Asset ID(see below) Id jpgId = CDA_LIBRARY_ASSETID(0x01); // Instead, a generated symbolic name could be used ResourceHandle resH = m_assetProvider->OpenRawResourceById(jpgId); Int32 resSize = m_assetProvider->GetResourceSize(resH); const void* dataPointer = m_assetProvider->GetResourceAddress(resH); UInt8* buffer = CANDERA_NEW_ARRAY(UInt8, resSize); UInt32 readBytes = m_assetProvider->ReadResource(resH, buffer, 0, resSize); CANDERA_DEBUG_ASSERT(resSize == readBytes); m_assetProvider->CloseResource(resH); //... CANDERA_DELETE_ARRAY(buffer); Accessing Items via Asset Id  Item Identification: Asset Id instead of String All items in a solution have a type and a name which identifies them in their parent container and a full name which uniquely identifies them in the entire solution. For example, a mesh in a scene could have the full name /Global/Scenes/MyScene/Group:RootNode/Mesh:MyMesh . Before CGI-Studio V3.0.0, for accessing items from an application, the CanderaPath property displayed the string, which uniquely identified this item in the asset library. For the example above, the same mesh would have been accessed from Candera via the name /Scene:Global::Scenes::MyScene/Group:RootNode/Mesh:MyMesh . To improve asset loading performance, CGI-Studio V3.0.0 introduces numerical Ids for accessing items from asset libraries. Using Asset Ids As an example, a bitmap called "cosmosbgBmp" is assigned a symbolic name in a SceneComposer solution: The "Id" field in SceneComposer displays by default "0000000". For this default, SceneComposer will generate a hash value for the Id. In case a custom value greater than '0' is entered in this field, the custom value will be generated instead, which is guaranteed to remain the same permanently, while the generated hash value could change over time. Either during asset export, or explicitly via 'File -> Export Symbolic Names ...' menu, a header file is generated by SceneComposer containing all symbolic names defined in the solution. For the bitmap symbolic names, the export looks like: namespace CgiAssetNames { static const Candera::Id cosmosbgBmp = CDA_LIBRARY_ASSETID(0x0U, 0x11008CU); } //namespace CgiAssetNames To access this bitmap, use the interface Candera::AssetProvider::GetBitmapById : Bitmap::SharedPointer bitmap = Base::GetAssetProvider()->GetBitmapById(CgiAssetNames::cosmosbgBmp); Use the same approach for all other assets like displays, render target, nodes, font and raw data, ... Query Candera Compile Switches   Candera Compile Switches Note that Candera compile switches are documented in Candera Configuration . As an example, in case of DEVICE device, following queries are supported: (DEVICE stands for your device) #if CANDERA_DEVICE==DEVICE ... #endif Similarily: #ifdef CANDERA_DEVICE_DEVICE ... #endif