# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
-PROJECT_NAME = "Dali Internal Documentation"
+PROJECT_NAME = "DALi Internal Documentation"
# The PROJECT_NUMBER tag can be used to enter a project or revision number.
# This could be handy for archiving the generated documentation or
# title of most generated pages and in a few other places.
# The default value is: My Project.
-PROJECT_NAME = Dali
+PROJECT_NAME = DALi
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
+ [DALi Fundamentals](@ref fundamentals)
+ [Actors & Stage](@ref actors-and-stage)
+ [Coordinate System](@ref coordinate-system)
- + Units & the Default Camera (default unit 1 is 1 pixel with default camera)
+ + [Scene Graph](@ref scene-graph)
+ [Handle / Body Idiom](@ref handle-body-idiom)
+ Signals
+ [Properties](@ref properties)
<h2 class="pg">Multi-threaded Architecture</h2>
-Dali animations and rendering occur in a dedicated rendering thread. This allows animations to run smoothly, regardless of the time taken to process inputs events etc. in application code.
+DALi animations and rendering occur in a dedicated rendering thread. This allows animations to run smoothly, regardless of the time taken to process inputs events etc. in application code.
-Internally Dali contains a scene-graph, which mirrors the Actor hierachy. The scene-graph objects perform the actual animation & rendering, whilst Actors provide thread-safe access.
+Internally DALi contains a scene-graph, which mirrors the Actor hierachy. The scene-graph objects perform the actual animation & rendering, whilst Actors provide thread-safe access.
An example actor hierachy is shown below, in which one of the actors is being animated. The objects in green are created by the application code, whilst the private objects in blue are used in the dedicated rendering thread.
*
<h2 class="pg">Creating an Application</h2>
-The Adaptor framework provides provides a Dali::Application class which initialises and sets up Dali appropriately so that the application writer does not have to.
+The Adaptor framework provides provides a Dali::Application class which initialises and sets up DALi appropriately so that the application writer does not have to.
This provides many platform related services.
Several signals can be connected to so that the application writer is informed when certain platform related activities occur.
@code
void CreateProgram(Application& app)
{
- // Create Dali components...
+ // Create DALi components...
Dali::Actor actor = Actor::New();
...
}
/*! \page event-system Event Handling
-Dali emits several signals to an application to inform it of user actions.
+DALi emits several signals to an application to inform it of user actions.
<h2 class="pg">Touch Events</h2>
-An application can be notified when a user interacts with the touch screen on the device by connecting to the touch signal provided by Dali::Actor. This signal will be emitted by Dali whenever the touch occurs within the connected actor's bounds.
+An application can be notified when a user interacts with the touch screen on the device by connecting to the touch signal provided by Dali::Actor. This signal will be emitted by DALi whenever the touch occurs within the connected actor's bounds.
Each point on the screen that is currently being touched or where touch has stopped is represented by a Dali::TouchPoint. This object stores information about the state of the touch point (down, up, motion etc.) and the co-ordinates of the touch.
/*! \page handle-body-idiom Handle – body
<h2 class="pg">What is the Handle/Body (Pimpl) pattern?</h2>
It is a technique for hiding implementation details in the header file.
-Dali achieves it by using "handles" in the public API. These handles internally contain a reference counted pointer to the concrete implementation.
+DALi achieves it by using "handles" in the public API. These handles internally contain a reference counted pointer to the concrete implementation.
<h2 class="pg">Why does Dali::Object use the Handle/Body (Pimpl) pattern?</h2>
It provides:
This way the danger of API/ABI breaks is also reduced since the implementation of a class can change without modifying the public API.
\par Easier memory management
-Dali objects have implicit smart-pointer semantics.
-Each Dali::Object contains a single reference counted object which can be intitialized with the static "New" methods in the Dali API.
+DALi objects have implicit smart-pointer semantics.
+Each Dali::Object contains a single reference counted object which can be intitialized with the static "New" methods in the DALi API.
This means that C++ new/delete operators do not have to be used (or paired) in the user code (RAII idiom).
Of course there's no way of stopping users from allocating heap memory, but calls to the new operator can be minimised.
<h2 class="pg">What does 'implicit smart-pointer semantics' mean in the case of Dali?</h2>
-Since Dali objects are just handles, they can be copied by value. When a Dali object is copied, both the copy and original will point to the same Dali resource.
-The internal Dali resources are reference counted; copying a Dali object will increase the reference count. A resource will not be deleted until all its Dali::Object handles are destroyed, or reset.
+Since DALi objects are just handles, they can be copied by value. When a DALi object is copied, both the copy and original will point to the same DALi resource.
+The internal DALi resources are reference counted; copying a DALi object will increase the reference count. A resource will not be deleted until all its Dali::Object handles are destroyed, or reset.
\code
class AnimationTest
The following steps are required for displaying the sentence 'Hello World' with Dali:
-- initialize the Dali library
+- initialize the DALi library
- create an Actor showing text
- add it to the Stage
-To understand the basic building blocks of the UI make sure to read the chapter on \link fundamentals Dali Fundamentals\endlink first.
+To understand the basic building blocks of the UI make sure to read the chapter on \link fundamentals DALi Fundamentals\endlink first.
Let's take a look at the code for this test application.
There are a couple of steps which are very important to understand.
- <h2 class="pg"> Initializing Dali </h2>
- The application should not use the Dali library until it has sent the init complete signal!
+ <h2 class="pg"> Initializing DALi </h2>
+ The application should not use the DALi library until it has sent the init complete signal!
That's why we connect our ExampleApp::Create callback to Dali::Application's SignalInit signal:
\code
...
<h2 class="pg"> Reference counting </h2>
The application should store Actors' and resources' handles.
- Dali objects are reference counted, which makes sure they exist only as long as they are needed.
+ DALi objects are reference counted, which makes sure they exist only as long as they are needed.
That's why we store the Actor's handle:
\code
...
* <h3 class="pg">Resizing at Load Time</h3>
* An application loading images from an external source will often want to
* display those images at a lower resolution than their native ones.
- * To support this, %Dali can resize an image at load time so that its
+ * To support this, DALi can resize an image at load time so that its
* in-memory copy uses less space and its visual quality benefits from being
* prefiltered.
* There are four algorithms which can be used to fit an image to a desired
@section what-is-a-property What is a property?
A property is a value used by an object that can be modified or read externally to that object.
-This could be from within Dali or externally by an application.
+This could be from within DALi or externally by an application.
<h2 class="pg">What is a property used for?</h2>
-/**
- *
+<!--
+/**-->
+
# DALi 3D ( Dynamic Animation Library ) {#dali-introduction}
DALi is a quick and easy way of allowing developers to create Rich UI Applications like:
-/**
- *
+<!--
+/**-->
# Writing documentation for the DALi programing guide {#documentationguide}
-/**
- *
-# Dali Fundamentals {#fundamentals}
+<!--
+/**-->
+
+# DALi Fundamentals {#fundamentals}
## Actors and the Stage {#actors-and-stage}
-A Dali application uses a hierachy of Dali::Actor objects to position visible content. An actor inherits a position relative to its parent, and can be moved relative to this point. UI controls can be built by combining multiple actors.
+A DALi application uses a hierachy of Dali::Actor objects to position visible content. An actor inherits a position relative to its parent, and can be moved relative to this point. UI controls can be built by combining multiple actors.
To display the contents of an actor, it must be connected to the Dali::Stage. This provides an invisible root (top-level) actor, to which all other actors are added. A direct or indirect child of the root actor is considered "on-stage". Multi-touch events are received through signals emitted by on-stage actors.
## The Coordinate System {#coordinate-system}
-The Stage has a 2D size, which matches the size of the application window. The default coordinate system in Dali has the origin at the top-left corner, with positive X to right, and position Y going
-downwards. This is intended to be convenient when laying-out 2D views.
+The Stage has a 2D size, which matches the size of the application window.
+The default **unit 1 is 1 pixel with default camera and** the default coordinate system in DALi has the **origin at the top-left corner, with positive X to right, and position Y going
+downwards**. This is intended to be convenient when laying-out 2D views.
+
## Positioning Actors {#positioning-actors}
An actor inherits its parent's position. The relative position between the actor & parent is determined by 3 properties:
-The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D Dali world. The actor's position is relative to this point.
+The default is "top-left", which can be visualized in 2D as (0, 0), but is actually Vector3(0, 0, 0.5) in the 3D DALi world. The actor's position is relative to this point.
2) AnchorPoint. This Vector3 property defines a point within the child actor's area.
-The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D Dali world. The actor's position is also relative to this point.
+The default is "center", which can be visualized in 2D as (0.5, 0.5), but is actually Vector3(0.5, 0.5, 0.5) in the 3D DALi world. The actor's position is also relative to this point.
3) Position. This is the position vector between the parent-origin and anchor-point.
An actor added directly to the stage with position (X = stageWidth*0.5, Y = stageHeight*0.5), would appear in the center of the screen. Likewise an actor with position (X = actorWidth*0.5, Y = actorWidth*0.5), would appear at the top-left of the screen.
-Note that since Dali is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
+Note that since DALi is a 3D toolkit, this behaviour is the result of a default perspective camera setup.
+
+## Scene Graph {#scene-graph}
+
+From wikipedia...
+
+A scene graph is a collection of nodes in a graph or tree structure.
+A node may have many children but often only a single parent,
+with the effect of a parent applied to all its child nodes;
+an operation performed on a group automatically propagates
+its effect to all of its members. In many programs, associating
+a geometrical transformation matrix (see also transformation and matrix)
+at each group level and concatenating such matrices together is an
+efficient and natural way to process such operations. A common feature,
+for instance, is the ability to group related shapes/objects into a
+compound object that can then be moved, transformed, selected,
+etc. as easily as a single object.
+
+### How does this relate to the DALi public API?
+
+Actors are effectively nodes that receive input (touch events) and act as a
+container for draw-able elements (which are also nodes) and other actors.
@class _Guide_DALi_Fundamentals
-/**
- *
+<!--
+/**-->
# High Level Design {#dali-hld}
+ **DALi Platform Abstraction:** Resource loading & decoding in multiple threads (part of dali-adaptor)
+ **DALi Toolkit:** Reusable UI Controls, Effects & Scripting Support
+
## Main, Update & Render Threads {#dali-threads}
+ **Render Thread:** OpenGL drawing, texture and geometry uploading etc.
+ **Resource Threads:** Loads images and decodes into bitmaps etc.
+
*/
-/**
- *
+<!--
+/**-->
+
# JavaScript wrapping guide {#javascriptwrapping}
This guide outlines what files to modify when the DALi C++ public API changes.
The wrapped object, then forwards the command to the real DALi object.
Whenever we want to access functions / properties of that wrapped object, we unwrap it
-to get access to the Dali object.
+to get access to the DALi object.
-Each wrapped object registers with Dali garbage collector so they can be deleted
-when Dali shuts down
+Each wrapped object registers with DALi garbage collector so they can be deleted
+when DALi shuts down
@class _Guide_JavaScript_Wrapping
+
*/
\ No newline at end of file
-/**
- *
+<!--
+/**-->
Multi-Touch Events
==================
touch signals are also emitted from the touch-down actor with an "Interrupted" state.
@class MultiTouch
-*
+
*/
-/**
- *
+<!--
+/**-->
# Performance Profiling {#performanceprofiling}
## Background
-The Dali rendering pipeline has 2 stages.
+The DALi rendering pipeline has 2 stages.
Each stage is typically run once per frame.
This will leave enough time for the output to be composited (if the system uses a compositor) and to avoid using
too much CPU power.
-The main Dali application thread which deals with event processing is independent of the update / render threads.
+The main DALi application thread which deals with event processing is independent of the update / render threads.
This means animations won't stop if the main thread decides to do a long operation like downloading a file from the internet.
| Marker | Description
|--------|-------------
-| V_SYNC.| The heart beat which represents Dali should start creating a new frame if anything has changed. Runs at display refresh rate, typically 60Hz |
-| UPDATE_START | Dali update task has started |
-| UPDATE_START | Dali update task has finished |
-| RENDER_START | Dali render task has started |
-| RENDER_END | Dali render task has finished |
-| PROCESS_EVENT_START | Dali main thread processing events (e.g. in response to a touch event or a timer) |
-| PROCESS_EVENT_START | Dali main thread processing events finished |
+| V_SYNC.| The heart beat which represents DALi should start creating a new frame if anything has changed. Runs at display refresh rate, typically 60Hz |
+| UPDATE_START | DALi update task has started |
+| UPDATE_START | DALi update task has finished |
+| RENDER_START | DALi render task has started |
+| RENDER_END | DALi render task has finished |
+| PROCESS_EVENT_START | DALi main thread processing events (e.g. in response to a touch event or a timer) |
+| PROCESS_EVENT_START | DALi main thread processing events finished |
| SWAP_START | glSwapBuffers started (todo) |
| SWAP_END | glSwapBuffers end (todo) |
| PAUSE | Application paused |
## Statistics logging
-Statistics logging uses Dali log output which on Tizen is dlog, but this can also be used on desktop by redirecting stderr to a file.
+Statistics logging uses DALi log output which on Tizen is dlog, but this can also be used on desktop by redirecting stderr to a file.
Setting DALI_LOG_PERFORMANCE_STATS environment variable will enable time stamps.
TableViewInit, min 76.55 ms, max 76.55 ms, total (0.1 secs), avg 76.55 ms, std dev 0.00 ms
~~~
-If nothing is animating Dali will enter a paused state to save power. At this
+If nothing is animating DALi will enter a paused state to save power. At this
point nothing will be logged.
### Custom statistics for application developers
## Application profiling
- The main application thread in Dali is used to process and respond to events such as touch, key, mouse, gestures and timers.
+ The main application thread in DALi is used to process and respond to events such as touch, key, mouse, gestures and timers.
Example:
~~~
~~~
Ftrace is a kernel tracer designed to help developers find out what is going on inside the kernel.
-It can be used for analysing how long Dali takes to perform different tasks and
-what Dali is doing in relation to other system processes / interrupts.
+It can be used for analysing how long DALi takes to perform different tasks and
+what DALi is doing in relation to other system processes / interrupts.
-On Tizen if the kernel has been built with ftrace enabled, then Dali can log out to ftrace.
+On Tizen if the kernel has been built with ftrace enabled, then DALi can log out to ftrace.
This gives exact time stamps of the main events in Dali.
Current markers that are logged:
If the message did not get added to the trace, then check the write permissions on trace_marker file. E.g.
$ chmod ugoa+w trace_marker
~~~
-To view Dali markers in trace file
+To view DALi markers in trace file
~~~
$ export DALI_LOG_PERFORMANCE=2
-/**
- *
+<!--
+/**-->
# Performance Tips {#performancetips}
-/**
- *
+<!--
+/**-->
+
# Programming Languages {#programming-languages}
DALi applications can be written in several different programming languages.
-/**
- *
+<!--
+/**-->
+
[TOC]
# Resource Image Scaling {#resourceimagescaling}
-/**
- *
+<!--
+/**-->
+
# Resource Tracking {#resourcetracking}
## Enable Logging
-Setting DALI_ENABLE_LOG environment variable to RESOURCE_LOG will enable resource usage logging in Dali applications.
+Setting DALI_ENABLE_LOG environment variable to RESOURCE_LOG will enable resource usage logging in DALi applications.
On target resource logging utilizes dlog, but this can also be used on desktop by redirecting stderr to a file.
The generated information includes any image files that are loaded with their dimensions,
GPU memory consumption, CPU RAM used and details of texture atlases created.
## Viewing Resource Logs
-dalireslog.sh is installed as part of the dali-adaptor package and can be found in the adaptors/tizen/scripts folder.
+dalireslog.sh is installed as part of the DALi Adaptor package and can be found in the adaptors/tizen/scripts folder.
The script shows a summary of memory used by resources.
USAGE:
./dalireslog.sh [FILE]
+++ /dev/null
-# Scene Graph
-## What is a scene graph?
-From wikipedia...
-
-A scene graph is a collection of nodes in a graph or tree structure.
-A node may have many children but often only a single parent,
-with the effect of a parent applied to all its child nodes;
-an operation performed on a group automatically propagates
-its effect to all of its members. In many programs, associating
-a geometrical transformation matrix (see also transformation and matrix)
-at each group level and concatenating such matrices together is an
-efficient and natural way to process such operations. A common feature,
-for instance, is the ability to group related shapes/objects into a
-compound object that can then be moved, transformed, selected,
-etc. as easily as a single object.
-
- ### How does this relate to the Dali public API?
-
- Actors are effectively nodes that receive input (touch events) and act as a
- container for draw-able elements (which are also nodes) and other actors.
\ No newline at end of file
-/**
- *
+<!--
+/**-->
+
# Hello World - JSON layout{#script-hello}
The following JSON code is the minimum required to put the sentence "Hello World" on the screen.
~~~
## Hello World - Javascript
- The Dali script application is needed to run the Javascript which provides a Javascript runtime and an interface to Dali.
+ The DALi script application is needed to run the Javascript which provides a Javascript runtime and an interface to Dali.
~~~
scripting.example hello-world.js
~~~
- The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing Dali Actor Properties.
+ The TextLabel control to display Hello World can be constructed using Javascript dot notation accessing DALi Actor Properties.
~~~{.js}
// JavaScript
~~~
@class _Guide_Script_Hello_World
- */
\ No newline at end of file
+
+*/
\ No newline at end of file
-/**
- *
+<!--
+/**-->
+
[TOC]
# DALi JSON Specification {#script-json-specification}
## Overview {#overview}
-This document describes the Dali JSON specification.
+This document describes the DALi JSON specification.
The format is not yet formally versioned within the JSON.
# General format {#format}
Concrete Actors and Controls can be created from types registered in the
-Dali Type Registry.
+DALi Type Registry.
Template, style and scene sections all configure Actors and Controls via
-the Dali property system.
+the DALi property system.
The JSON format deviates from the formal JSON specification and allows C style comments.
"stage": // Stage section
[ //
{ // Actors|Controls to create on JSON file load
- "type": "basic-text", // A Dali Control or a template name
+ "type": "basic-text", // A DALi Control or a template name
"styles":["base-theme","light-theme"] // Style list to apply to this instance
} //
] //
}, //
... //
{ //
- "type":"ImageActor" // An Dali type or a template name
+ "type":"ImageActor" // An DALi type or a template name
"image": //
{ //
"filename":"{IMAGES}b.jpg" // Image filename substring replacement
{ //
"basic-text": // The template name
{ //
- "type":"ImageActor", // Concrete Dali Type/Class to create
+ "type":"ImageActor", // Concrete DALi Type/Class to create
"styles":["base-style"], // Style list to apply
"name":"image", // }
"image": // } property name : value
~~~
A template has a special 'type' property which must contain a concrete
-Dali Actor or Control type name.
+DALi Actor or Control type name.
A template has a special 'styles' property which contains a list of
styles to apply when creating using the template.
When applied to an actor tree the actors are referenced by name. Names
are not unique in Dali.
-When a style is applied in code Dali will perform a depth first search
+When a style is applied in code DALi will perform a depth first search
stopping with the first matching name.
Typically an application developer will apply the style to the template
{
"type": "TextView",
\\ The Type to create; this can be a
- ... \\ concrete Dali type (actor/control)
+ ... \\ concrete DALi type (actor/control)
\\ or a template name.
"styles": ["base-style"]
\\ A list of styles to apply to the
-/**
- *
+<!--
+/**-->
+
# Scripting Overview {#scriptoverview}
-Dali has:
+DALi has:
- JSON to support:
- layouting
- theme / styling
JSON support is built in to DALi.
-JavaScript support is via a plugin held in dali-toolkit, which builds automatically if Google's V8 engine is installed.
+JavaScript support is via a plugin held in DALi Toolkit, which builds automatically if Google's V8 engine is installed.
The V8 version required by DALi can be built and installed using dali-core/scripts/dali_env script.
Files can be loaded inside any DALi application, or from command line using the launcher ( part of dali-demo).
-/**
- *
+<!--
+/**-->
+
# Stagehand Visual Debugger for DALi {#stagehand}
-/**
- *
+<!--
+/**-->
# Text Field {#text-field}
-/**
- *
+<!--
+/**-->
# Text Label {#text-label}
-/**
- *
+<!--
+/**-->
+
# Texture Atlases {#textureatlases}
## Example demo application
@class _Guide_TextureAtlases
-*
*/
\ No newline at end of file
-/**
- *
+<!--
+/**-->
# Texture Compression {#texturecompression}
-Deep internal documentation for Dali Toolkit.
+Deep internal documentation for DALi Toolkit.
Generate the documentation here as follows:
# Start doxygen:
./build.sh
-Note, the doxfile assumes you have your Dali repositories checked-out
+Note, the doxfile assumes you have your DALi repositories checked-out
side by side with the following structure:
.
projects / platform / core / uifw / dali-toolkit.git / commitdiff