Data Driven Application

Table of Contents

• Introduction
  • Using the template
• Overview of a Data Driven Application
• GlobalConfig File
• AppInit File
  • FirstSequenceFile
  • BundleFileName
  • FilePathManagerInitFile
  • LocalizationInitFile
  • PackageFileName
• Sequences
• Transitions
• Sample8 Data Driven Application
• Kigs Tools Embedded Inspector and Editor

Introduction

Kigs framework propose a template for Data Driven Application. Data Driven Application allows you to navigate between different screens ( called Sequences ) using mainly XML and/or Lua files. However, the Kigs framework remains a C++ framework and the realization of a complete and complex application will probably require the writing of part of the code in C++.

Using the template

See Getting Started wiki page for details.

To generate a new Data Driven Application, go to kigs/projects folder and launch (double click) CreateNewDDProject.vbs script. Enter a project name in the dialog box and click OK. Add your project to the CMakeFile.txt, then go to kigs/scripts and launch one of the script to generate the desired platform solution.

Overview of a Data Driven Application

A default new Data Driven Application created with the CreateNewDDProject.vbs contains some asset files (data) in kigs\projects\YourProjectName\Ressources folder. A Ressource manager called at build time will process the ressources in this folder based on the rules from the AssetManagerRules.json file.

The main files are :

• AppInit.xml : Contains main window / screen information.
• LaunchScreen.xml : contains the first launched screen ( here a Kigs Logo with fade in/out).
• Screen_Main.xml : contains the second launched screen ( here only a blue screen ).

kigs\projects\YourProjectName\Headers folder contains two header files :

• KigsApplication.h : some defines you generally don't have to edit.
• YourProjectName.h : declaration of the application class.

kigs\projects\YourProjectName\Sources folder contains only one file :

• YourProjectName.cpp : definition of the application class.

After adding new files to Headers or Sources folder, use the scripts in kigs/scripts to generate again the desired platform solution.

If you want to add some assets to your application, you probably want to add them in the Ressources/toPack folder, so they will be packed in a kpkg archive file and moved to the assets folder.

GlobalConfig File

When the application is launched, a GlobalConfig file is searched and if available imported. The global config file name is first search for current platform : GlobalConfig + platform name + .xml

ie : GlobalConfigWin32.xml, GlobalConfigAndroid.xml ...

If not found, "GlobalConfig.xml" is searched.

This file can be used to create application wide instances. This file is not mandatory and is not present in the default application.

AppInit File

AppInit.xml file is mandatory. It is used to initialize Window and RenderingScreen.

Here is the AppInit.xml file used for Sample8 :

<?xml version="1.0"?>
<!-- create application window -->
<Inst N="Sample8" Type="Window">
   <!-- Position.x is from screen left side if positive, centered if -1 and from right side if negative ( and not -1 )
        Position.y is from screen upper side if positive, centered if -1 and from lower side if negative ( and not -1 ) -->
    <Attr N="Position" V="[-1,-1]"/>
	<Attr N="Size" V="[1280,800]"/>
	<Attr N="FullScreen" V="false"/>
	<Attr N="ShowMouseCursor" V="true"/>
	<!-- create global rendering screen ( <=> rendering surface ) -->
	<Inst N="theRenderingScreen" Type="RenderingScreen">
		<Attr N="Size" V="[0,0]"/>
		<!-- virtual screen size if 1280*800 -->
		<Attr N="DesignSize" V="[1280,800]"/>
		<Attr N="BitsPerZ" V="32"/>
		<Attr N="Brightness" V="0"/>
		<Attr N="BackDropColor" V="[0.0,0.0,0.0]"/>
		<Attr N="VSync" V="true"/>
	</Inst>
	<!-- initialize localizations -->
	<Attr T="string" N="LocalizationInitFile" V="InitLoc.json" Dyn="true"/>
</Inst>

Some options can be set through dynamic attributes on AppWindow instance :

FirstSequenceFile

   <Attr T="string" N="FirstSequenceFile" V="FirstSequence.xml" Dyn="true"/>

XML File containing the first sequence to launch ( default is "LaunchScreen.xml" ).

BundleFileName

Bundle file can be used to indicate the path of a file using it's name ( not detailed here ).

   <Attr T="string" N="BundleFileName" V="files.bundle" Dyn="true"/>

FilePathManagerInitFile

File used to init FilePathManager ( to be detailed in a future FilePathManager section ).

   <Attr T="string" N="FilePathManagerInitFile" V="FilePathManager.json" Dyn="true"/>

LocalizationInitFile

Initialization file for Localization manager ( to be detailed in a future Localization manager section ).

   <Attr T="string" N="LocalizationInitFile" V="Localization.json" Dyn="true"/>

PackageFileName

Load given package file. ( to be detailed in a future CorePackage section ).

   <Attr T="string" N="PackageFileName" V="package.kpkg" Dyn="true"/>

Sequences

Sequences can be seen as different section of the application. A video game application for example, can have a splash screen, then an introduction screen, then a menu screen giving access to a parameter screen, the game itself and a credit screen... Each of those will be a sequence (or several sequences) in a Kigs Data Driven application.

Simple sequences can only be defined by a UI2DLayer. Here is the default splash screen :

<?xml version="1.0"?>
<Inst N="UILayerBump" T="UI2DLayer">
	<Attr N="Size" V="[1280,800]"/>
	<Attr N="Priority" V="0"/>
	<Attr N="RenderingScreen" V="RenderingScreen:theRenderingScreen"/>
	<Inst N="Bump" T="UIItem">
		<Attr N="Size" V="[1280,800]"/>
		<Attr N="Opacity" V="0.0"/>
		<Attr N="Dock" V="[0.500000,0.50000]"/>
		<Attr N="Anchor" V="[0.500000,0.50000]"/>
		<Inst N="Logo" T="UIImage">
			<Attr N="TextureName" V="Logo.png"/>
			<Attr N="Size" V="[1280,800]"/>
			<Attr N="Priority" V="50"/>
			<Attr N="Dock" V="[0.500000,0.50000]"/>
			<Attr N="Anchor" V="[0.500000,0.50000]"/>
			<Attr N="KeepRatio" V="false"/>
		</Inst>
	</Inst>
	<Inst N="FadeIn_Launcher" T="CoreSequenceLauncher">
		<Attr N="StartOnFirstUpdate" V="true"/>
		<Attr N="Sequence">
                <![CDATA[{
                "Fade":[
                        {"Linear1D":[0.5,-16,0,"/theRenderingScreen->Brightness",0]},
                        { "Wait" : [  0.1 ] },
                        { "Notification" :  [ 0 , "StackSequence", "Screen_Main.xml" ] }
                       ]
                }
                ]]>
	</Attr>
  </Inst>
</Inst>

More complex sequences are generally defined as DataDrivenSequence.

A DataDrivenSequence can have several UI2DLayer and/or Scene3D children, and manage transition between sequences.

Transitions

DataDrivenTransition can be added to DataDrivenSequence to determine transition effect when going from one sequence to another.

Here is a simple "fade to black the previous sequence, then fade from black to the current sequence transition :

<Inst N="transition" T="DataDrivenTransition">
   <Attr N="PreviousAnim">
   <![CDATA[{
      "Fade":[
      {"Linear1D":[0.5,0,-16,"/theRenderingScreen->Brightness",0]},
      { "SetValue1D" : [0.0,0.0,"Show" ]}
      ]
   }
   ]]>
   </Attr>
   <Attr N="NextAnim">
   <![CDATA[{
      "Fade":[
      { "SetValue1D" : [0.0,0.0,"Show" ]},
      { "Wait" : [  0.5 ] },
      { "SetValue1D" : [0.0,1.0,"Show" ]},
      {"Linear1D":[0.5,-16,0,"/theRenderingScreen->Brightness",0]},
      { "Notification" :  [ 0 , "InitScreen" ] }
      ]
   }
   ]]>
   </Attr>
</Inst>

Sample8 Data Driven Application

The Sample8 Data Driven Application C++ code is exactly the same as the template Data Driven Application. Everything is done in XML / JSON / lua files in the asset folder.

After splash screen, first sequence is composed of a 3D scene and a UI2DLayer with some buttons.

A node with an attached spot light is animated :

<Ref P="Node3D:Light" DontAddAsSon="true">
    <!-- Ask this Node3D to be "pivot" controled --> 
    <Upgrd N="PivotUp"/>
    <!-- the pivot is set in global coordinates --> 
    <Attr N="IsGlobal" V="true"/>
    <!-- around z axis --> 
    <Attr N="PivotAxis" V="[0.000000,0.000000,1.000000]"/>
    <!-- animate pivot angle with an infinite loop --> 
    <Inst Name="animateLightPos" Type="CoreSequenceLauncher">
        <Attr N="Sequence"><![CDATA[
                            {"animateLightPos":[
			    {"DoWhile":[1,
				           {"Linear1D":[4,0,6.28,"Angle"]} ]}
			    ]}
			    ]]>
	</Attr>
	<!-- animation sequence starts directly -->
	<Attr N="StartOnFirstUpdate" V="true" />
    </Inst>	
</Ref>

A second sequence can be launched by pressing localized "Next" button :

Kigs Tools Embedded Inspector and Editor

When compiled in Debug or ReleaseTools mode, an embedded instance inspector / editor is available by pressing CTRL + F1 keys.

You can inspect all CoreModifiable instances in the application, search them using the Hierarchy / filter text input.

For example, go to the online Sample8 version, press CTRL+F1, then in the Filter input type "button", then click on "camup_btn" in the list and look at all the button attributes in the "Attributes" window. You can then play with the size, position, color... of the button.

Find all the sample code from this wiki section in Sample8 project (browse the code)