Kigs Framework Introduction (8/8) - 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
• Already Published in this Series
• History

Introduction

Kigs framework proposes a template for Data Driven Applications. Data Driven Applications allow 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 development of a complete and complex application will probably require the writing of part of the code in C++.

Here is an example of a more complex Data Driven Application based on the Kigs framework:

Fun with YouTube Data API v3 (Public Data) and Kigs Framework

Using the Template

See Kigs framework GitHub 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 scripts 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 (default is a Kigs Logo with fade in/out)
• Screen_Main.xml: contains the second launched screen (default is 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 using: GlobalConfig + platform name + .xml.

i.e.,: 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. There's no GlobalConfig file in Sample8 example.

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 Window 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 its name (not detailed here).

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

FilePathManagerInitFile

File used to init FilePathManager (not detailed here).

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

LocalizationInitFile

Initialization file for localization manager (not detailed here, but Sample8 manages some localizations).

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

PackageFileName

Load given package file (not detailed here).

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

Sequences

Sequences can be seen as different sections 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 sequence can only be defined by a UI2DLayer. Here is the default splash screen:

<?xml version="1.0"?>
<Inst N="UILayer" T="UI2DLayer">
    <Attr N="Size" V="[1280,800]"/>
    <Attr N="Priority" V="0"/>
    <Attr N="RenderingScreen" V="RenderingScreen:theRenderingScreen"/>
    <Inst N="Interface" 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.

Here is a Sample8 first sequence (after splash screen) Screen_Main.xml.

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 assets folder.

After splash screen, the 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).

Already Published in this Series

1. Kigs Framework Introduction (1/8) - Overview
2. Kigs Framework Introduction (2/8) - CoreModifiable
3. Kigs Framework Introduction (3/8) - Attributes
4. Kigs Framework Introduction (4/8) - Methods
5. Kigs Framework Introduction (5/8) - CoreItem
6. Kigs Framework Introduction (6/8) - Signal, Slot, Notification
7. Kigs Framework Introduction (7/8) - Lua Binding
8. Kigs Framework Introduction (8/8) - Data Driven Application

History

• 17^th June, 2020: Initial version
• 1^st March, 2023: Article updated after framework refactory