From: Nick Holland Date: Thu, 2 Apr 2015 11:54:08 +0000 (+0100) Subject: Add more shared C++/JavaScript docs and add JavaScript wrapping guide X-Git-Tag: accepted/tizen/common/20150512.125104~6^2 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=2d5d28f89d92f5a7db5bd84f39ce0c5dbc74508d;hp=-c Add more shared C++/JavaScript docs and add JavaScript wrapping guide Change-Id: Ief3c78e0b752b0c21e3dbebeb216317a154a440c --- 2d5d28f89d92f5a7db5bd84f39ce0c5dbc74508d diff --git a/build/tizen/docs/dali.doxy.in b/build/tizen/docs/dali.doxy.in index e072023..bbb08c2 100644 --- a/build/tizen/docs/dali.doxy.in +++ b/build/tizen/docs/dali.doxy.in @@ -931,7 +931,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = main.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/keyframe-animation.png b/docs/content/images/animation/keyframe-animation.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/keyframe-animation.png rename to docs/content/images/animation/keyframe-animation.png diff --git a/docs/content/images/example-documentation/example-code.png b/docs/content/images/example-documentation/example-code.png new file mode 100644 index 0000000..881dc8f Binary files /dev/null and b/docs/content/images/example-documentation/example-code.png differ diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/focus-manager.png b/docs/content/images/focus-manager/focus-manager.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/focus-manager.png rename to docs/content/images/focus-manager/focus-manager.png diff --git a/docs/content/images/javascript-wrapping-guide/adding-function.png b/docs/content/images/javascript-wrapping-guide/adding-function.png new file mode 100644 index 0000000..9d1c311 Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/adding-function.png differ diff --git a/docs/content/images/javascript-wrapping-guide/base-wrapped-types.png b/docs/content/images/javascript-wrapping-guide/base-wrapped-types.png new file mode 100644 index 0000000..6fd2707 Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/base-wrapped-types.png differ diff --git a/docs/content/images/javascript-wrapping-guide/constructors.png b/docs/content/images/javascript-wrapping-guide/constructors.png new file mode 100644 index 0000000..07c4111 Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/constructors.png differ diff --git a/docs/content/images/javascript-wrapping-guide/folder-view.png b/docs/content/images/javascript-wrapping-guide/folder-view.png new file mode 100644 index 0000000..2e12028 Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/folder-view.png differ diff --git a/docs/content/images/javascript-wrapping-guide/high-level-design.png b/docs/content/images/javascript-wrapping-guide/high-level-design.png new file mode 100644 index 0000000..e1acc8f Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/high-level-design.png differ diff --git a/docs/content/images/javascript-wrapping-guide/plugin-creation.png b/docs/content/images/javascript-wrapping-guide/plugin-creation.png new file mode 100644 index 0000000..e9f26be Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/plugin-creation.png differ diff --git a/docs/content/images/javascript-wrapping-guide/plugin-execution.png b/docs/content/images/javascript-wrapping-guide/plugin-execution.png new file mode 100644 index 0000000..8f3006c Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/plugin-execution.png differ diff --git a/docs/content/images/javascript-wrapping-guide/scripting-overview.png b/docs/content/images/javascript-wrapping-guide/scripting-overview.png new file mode 100644 index 0000000..0dea37b Binary files /dev/null and b/docs/content/images/javascript-wrapping-guide/scripting-overview.png differ diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/path.png b/docs/content/images/path/path.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/path.png rename to docs/content/images/path/path.png diff --git a/docs/content/images/performance/update-render.png b/docs/content/images/performance/update-render.png new file mode 100644 index 0000000..018f6a8 Binary files /dev/null and b/docs/content/images/performance/update-render.png differ diff --git a/docs/content/images/screenshot.png b/docs/content/images/screen-shot.png similarity index 100% rename from docs/content/images/screenshot.png rename to docs/content/images/screen-shot.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/fragment-shader-color.png b/docs/content/images/shaders/fragment-shader-color.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/fragment-shader-color.png rename to docs/content/images/shaders/fragment-shader-color.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/fragment-shader-reveal.png b/docs/content/images/shaders/fragment-shader-reveal.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/fragment-shader-reveal.png rename to docs/content/images/shaders/fragment-shader-reveal.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/shader-animation.png b/docs/content/images/shaders/shader-animation.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/shader-animation.png rename to docs/content/images/shaders/shader-animation.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/shader-grid-hint.png b/docs/content/images/shaders/shader-grid-hint.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/shader-grid-hint.png rename to docs/content/images/shaders/shader-grid-hint.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/vertex-shader.png b/docs/content/images/shaders/vertex-shader.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/vertex-shader.png rename to docs/content/images/shaders/vertex-shader.png diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/spinner.gif b/docs/content/images/spinner.gif similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/spinner.gif rename to docs/content/images/spinner.gif diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/stage.png b/docs/content/images/stage/stage.png similarity index 100% rename from plugins/dali-script-v8/docs/dali-theme/assets/img/stage.png rename to docs/content/images/stage/stage.png diff --git a/docs/content/images/texture-atlas/example-javascript-code.jpg b/docs/content/images/texture-atlas/example-javascript-code.jpg new file mode 100644 index 0000000..a4f0805 Binary files /dev/null and b/docs/content/images/texture-atlas/example-javascript-code.jpg differ diff --git a/docs/content/main-page.h b/docs/content/main-page.h deleted file mode 100644 index f74e830..0000000 --- a/docs/content/main-page.h +++ /dev/null @@ -1,109 +0,0 @@ -/*! \mainpage - * - * \section mainintro_sec Introduction - * - * It is a quick and easy way of allowing developers to create Rich UI Applications like Home - * screen, Gallery, Music player, Games, Maps... - * - * DALI is based on OpenGL ES 2.0, however it hides the complexity of - * the OpenGL API from developers and provides a clean cross-platform C++ framework. - * - * \section Introduction Introduction - * - \link fundamentals Dali Fundamentals \endlink - * - \link dali-application Dali Application and Adaptor \endlink - * - \link hello-world Hello World - explained \endlink - * - * \section Actors Actors - * - \link image-mesh-actor Image and Mesh actors \endlink - * - \link event-system Event Handling \endlink - * - \link custom-actor Custom Actor \endlink - * - * \section ShaderEffects Shader Effects - * - \link shader-intro Shader Effects\endlink - * - * \section Animation Animation - * - \link animation-example Example and Usage\endlink - * - \link animation-rotation Rotation with quaternions \endlink - * - \link animation-shader Shader Animation \endlink - * - \link animation-multi-threading-notes Multi-threading Notes \endlink - * - * \section Constraints - * - \link constraints Constraints \endlink - * - * \section SizeNegotiation Size Negotiation - * - \link size-negotiation Size Negotiation \endlink - * - * \section UIControls UI Controls - * - \link text-label Text Label \endlink - * - \link item-view Item View \endlink - * - \link scroll-view Scroll View \endlink - * - \link size-negotiation-controls Size Negotiation for Controls \endlink - * - \link type-registration Type Registration \endlink - * - \link properties Properties \endlink - * - \link background Background \endlink - * - * \section Dynamics Dynamics - * - \link dynamics-intro Introduction to Dynamics\endlink - * - \link dynamics-initialization Initializing the Simulation\endlink - * - \link dynamics-bodies Bodies - adding and controlling dynamic objects \endlink - * - \link dynamics-joints Joints - linking objects\endlink - * - \link dynamics-collisions Collision Detection and Filtering\endlink - * - * \section Scripting - * - \link script-overview Overview \endlink - * - \link script-hello Hello World in script \endlink - * - \link handle-body-idiom Handle – body idiom \endlink - * - * \section Rendering - * - \link viewing-modes Viewing modes \endlink - * - * \section Profiling - * - \link resource-tracking Resource Tracking \endlink - * - \link performance-profiling Performance Profiling \endlink - * - * \section Performance - * - \link performance-tips Performance Tips \endlink - * - \link texture-atlases Texture Atlases \endlink - * - \link Texture_Compression Compressing Textures \endlink - * - * \section Testing - * See [Automated Tests](@ref auto_testing) for instructions. - */ - -/*! \page scene-graph - * - * \section scene_intro 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. - * - * \section scene_dali 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. - * - * For example a Button actor will be an actor with several elements such as button background, - * text label and button face. When the actor is moved around, it's child elements will move with it. - * When the button is pressed, the actor will receive an event and adjust the color of its button face - * element. - * - * \section scene_internal Why does Dali internally have a second scene graph? - * Actors and elements are contained in a scene graph which deals with input, layout and some animation - * it doesn't perform any drawing. - * - * All the drawing is done via the Render Manager which has it's own render scene graph, where it's nodes - * are just for drawing things like image/text and moving them around. So when you create an Image element - * it will ask the RenderManager to create an Image node. The separation allows the RenderManager to - * run in a separate thread to maintain a high frame rate, without being slowed down by any logic - * performed on the actor/element side. - * - */ diff --git a/docs/content/main.md b/docs/content/main.md new file mode 100644 index 0000000..3665970 --- /dev/null +++ b/docs/content/main.md @@ -0,0 +1,92 @@ +# DALi introduction + +## DALi 3D ( Dynamic Animation Library ) + +DALi is a quick and easy way of allowing developers to create Rich UI Applications like: + + + Image & Video galleries + + Music players + + Games + + Maps + + Homescreens / launch pads + + Advanced watch faces for wearable devices + +DALi is based on OpenGL ES 2.0 & 3.0, however it hides the complexity of +the OpenGL API from developers and provides a clean cross-platform C++ & JavaScript framework. + ++ Create Images, Text and Meshes ++ Create shaders using GLSL ++ Provide multiple cameras and render targets ++ Provides Layers to aid in 2D UI layout ++ Easy to use Animation framework ++ Automatic background loading of resources ( images / text / meshes ) ++ Runs all animations in a seperate thread. This helps maintain 60 FPS even if JavaScript is performing a long operation ( e.g. Garbage Collection ). ++ Provides keyboard / touch / mouse handling + +![ ](screen-shot.png) + +## Introduction +- \link fundamentals Dali Fundamentals \endlink +- \link dali-application Dali Application and Adaptor \endlink +- \link hello-world Hello World - explained \endlink +- \link handle-body-idiom Handle – body idiom \endlink + +## Actors + - \link image-mesh-actor Image, Text and Mesh actors \endlink + - \link event-system Event Handling \endlink + - \link custom-actor Custom Actor \endlink + + ## ShaderEffects + - \link shader-intro Shader Effects\endlink + + ## Animation + - \link animation-example Example and Usage\endlink + - \link animation-rotation Rotation with quaternions \endlink + - \link animation-shader Shader Animation \endlink + - \link animation-multi-threading-notes Multi-threading Notes \endlink + + ## Constraints + - \link constraints Introduction to Constraints \endlink + +## Size Negotation + - \link size-negotiation Size Negotiation \endlink + + ## UI Controls + - \link scroll-view Scroll View \endlink + - \link size-negotiation-controls Size Negotiation for Controls \endlink + - \link type-registration Type Registration \endlink + - \link properties Properties \endlink + - \link background Background \endlink + + ## Dynamics + - \link dynamics-intro Introduction to Dynamics\endlink + - \link dynamics-initialization Initializing the Simulation\endlink + - \link dynamics-bodies Bodies - adding and controlling dynamic objects \endlink + - \link dynamics-joints Joints - linking objects\endlink + - \link dynamics-collisions Collision Detection and Filtering\endlink + + ## Scripting + - \link scriptoverview.html JSON and JavaScript Overview \endlink + - \link javascriptwrapping.html JavaScript Wrapping Guide for DALi developers\endlink + - \link script-hello Hello World in script \endlink + + ## Rendering + - \link viewing-modes Viewing modes \endlink + + ## Profiling + - \link performanceprofiling.html Performance Profiling \endlink + - \link resourcetracking.html Resource Tracking \endlink + + ## Performance + - \link performancetips.html Performance Tips \endlink + - \link textureatlases.html Texture Atlases \endlink + - \link texturecompression.html Compressing Textures \endlink + +## Testing + See [Automated Tests](@ref auto_testing) for instructions. + + +## Modifying this documentation +- \link documentationguide.html Modifying this documentation \endlink + + diff --git a/docs/content/programming-guide/dali-application.h b/docs/content/programming-guide/dali-application.h index c17b910..07cc934 100644 --- a/docs/content/programming-guide/dali-application.h +++ b/docs/content/programming-guide/dali-application.h @@ -149,7 +149,7 @@ void OrientationChanged(const Orientation& orientation) int main(int argc, char **argv) { Application app = Application::New(&argc, &argv); - app.GetOrientation().SignalChanged().Connect(&OrientationChanged); + app.GetWindow().GetOrientation().SignalChanged().Connect(&OrientationChanged); } @endcode diff --git a/docs/content/programming-guide/fundamentals.h b/docs/content/programming-guide/fundamentals.h index 7ab85c7..506934e 100644 --- a/docs/content/programming-guide/fundamentals.h +++ b/docs/content/programming-guide/fundamentals.h @@ -18,7 +18,7 @@ Stage::GetCurrent().Add(actor); 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. -\image html coordinate-system-and-stage.png +![ ](../assets/img/coordinate-system-and-stage.png)

Positioning Actors

@@ -26,19 +26,19 @@ An actor inherits its parent's position. The relative position between the acto 1) ParentOrigin. This Vector3 property defines a point within the parent actor's area. -\image html parent-origin.png +![ ](../assets/img/parent-origin.png) 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. -\image html anchor-point.png +![ ](../assets/img/anchor-point.png) 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. -\image html actor-position.png +![ ](../assets/img/actor-position.png) Therefore by default, an actors position is the distance between its center and the top-left corner of its parent. diff --git a/docs/content/programming-guide/performance-profiling.h b/docs/content/programming-guide/performance-profiling.h deleted file mode 100644 index 8e70c5d..0000000 --- a/docs/content/programming-guide/performance-profiling.h +++ /dev/null @@ -1,157 +0,0 @@ -/*! \page performance-profiling Performance Profiling - * - *

Enable Logging

- * - * Setting DALI_LOG_PERFORMANCE environment variable will enable performance profiling
- * It uses a bit mask to decide what to log.
- * The log options are:
- * \code - * Bit 0 = Log update and render threads (e.g. DALI_LOG_PERFORMANCE=1 dali-demo) - * Bit 1 = Log event process time (e.g. DALI_LOG_PERFORMANCE=2 dali-demo) - * Bit 2 = Log Dali markers to trace file (e.g. DALI_LOG_PERFORMANCE=4 dali-demo) - * - * To log both update, render and event times, then combine bits 0 and 1.
- * DALI_LOG_PERFORMANCE=3 dali-demo - * \endcode - * - * - *

Background

- * The Dali rendering pipeline has 2 stages. - * Each stage is typically run once per frame. - *

1. Update

- * - *

2. Render

- * - * - * - * To run at 60 FPS (16 milliseconds per frame), it is recommended to stay below the following times: - * - * - * 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.
- * This means animations won't stop if the main thread decides to do a long operation like downloading a file from the internet. - * - * Performance logging uses Dali log output which on Tizen is dlog, but this can also be used on desktop by redirecting stderr to a file.
- * - * Example: - * \code - * $ export DALI_LOG_PERFORMANCE=1 - * $ dali-demo - * $ - * $ ... - * $ I/DALI ( 5692): tizen-logging.cpp: LogMessage(40) > Update , min 0.59 ms, max 6.43 ms, total (3.4 secs), avg 1.26 ms - * $ I/DALI ( 5692): tizen-logging.cpp: LogMessage(40) > Render , min 1.67 ms, max 5.01 ms, total (4.5 secs), avg 3.71 ms - * \endcode - * - * If nothing is animating Dali will enter a paused state to save power. At this - * point nothing will be logged. - * - * - *

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 time taken to process events can be measured by setting DALI_LOG_PERFORMANCE environment variable to 2
- * - * Example: - * \code - * $ export DALI_LOG_PERFORMANCE=2 - * $ dali-demo - * $ - * $ ... - * $ INFO: DALI: Event , min 0.01 ms, max 14.99 ms, total (2.4 secs), avg 1.83 ms - * \endcode - * - * Inside the event processing, the application may be listening for certain events.
- * For example when an actor is touched, some application code may be run in an OnTouchEvent callback.
- * By checking the max times you can check for any spikes that occur when interacting with the application. - * - * Example: - * \code - * $ INFO: DALI: Event , min 0.10 ms, max 500.01 ms, total (6.4 secs), avg 20.83 ms - * - * - Something has taken 500 ms = 1/2 second during event processing. - * - Need to investigate what the application is doing for 1/2 a second. - * \endcode - * - * - *

Logging performance markers to Kernel trace file

- * - * 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. - * - * 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: - * - * - *

Checking ftrace is working on Linux

- * - * Documentation for ftrace: - * Follow these instructions to ensure the debugfs has been mounted, and the kernel you are using - * has been built with ftrace enabled.
- * https://www.kernel.org/doc/Documentation/trace/ftrace.txt - * - * To check ftrace is working: - * \code - * $ cd /sys/kernel/debug/tracing - * $ echo 1 > tracing_enabled (enabled tracing) - * $ echo "test" > trace_marker - * $ echo 0 > tracing_enabled (disable tracing) - * $ cat trace - * # - * # TASK-PID CPU# TIMESTAMP FUNCTION - * # | | | | | - * <...>-2539 [001] 267964.345607: tracing_mark_write: test - * - * - * 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 - * \endcode - * - * To view Dali markers in trace file
- * - * \code - * $ export DALI_LOG_PERFORMANCE=4 - * $ dali-demo - * $ - * $ cat /sys/kernel/debug/tracing/trace - * - * <...>-3330 [000] 785155.216611: tracing_mark_write: SPI_EV_DALI_V_SYNC - * <...>-3328 [003] 785155.216644: tracing_mark_write: SPI_EV_DALI_UPDATE_START - * <...>-3328 [003] 785155.217045: tracing_mark_write: SPI_EV_DALI_UPDATE_END - * <...>-3329 [001] 785155.227418: tracing_mark_write: SPI_EV_DALI_RENDER_START - * <...>-3329 [001] 785155.227807: tracing_mark_write: SPI_EV_DALI_RENDER_END - * <...>-3330 [000] 785155.233336: tracing_mark_write: SPI_EV_DALI_V_SYNC - * <...>-3328 [002] 785155.233374: tracing_mark_write: SPI_EV_DALI_UPDATE_START - * <...>-3328 [002] 785155.233672: tracing_mark_write: SPI_EV_DALI_UPDATE_END - * <...>-3329 [001] 785155.235161: tracing_mark_write: SPI_EV_DALI_RENDER_START - * <...>-3329 [001] 785155.235475: tracing_mark_write: SPI_EV_DALI_RENDER_END - * <...>-3330 [000] 785155.250029: tracing_mark_write: SPI_EV_DALI_V_SYNC - * <...>-3328 [003] 785155.250065: tracing_mark_write: SPI_EV_DALI_UPDATE_START - * <...>-3328 [003] 785155.250330: tracing_mark_write: SPI_EV_DALI_UPDATE_END - * <...>-3329 [001] 785155.252860: tracing_mark_write: SPI_EV_DALI_RENDER_START - * <...>-3329 [001] 785155.253178: tracing_mark_write: SPI_EV_DALI_RENDER_END - * <...>-3329 [001] 785155.264508: tracing_mark_write: SPI_EV_DALI_RENDER_START - * <...>-3329 [001] 785155.265006: tracing_mark_write: SPI_EV_DALI_RENDER_END - * \endcode - */ diff --git a/docs/content/programming-guide/performance-tips.h b/docs/content/programming-guide/performance-tips.h deleted file mode 100644 index 969054a..0000000 --- a/docs/content/programming-guide/performance-tips.h +++ /dev/null @@ -1,39 +0,0 @@ -/*! \page performance-tips Performance Tips - - - - - - - - - -
High CPU occupancy
- - Try to reduce actor count ( less actors == less processing)
- - Delete any actors that are not visible, or move them off stage
- - Use TextureAtlases ( greatly reduces OpenGL driver calls to glBindTexture
- - Optimise / reduce any constraints used -
-

- - - - - - - -
High GPU occupancy
- - Reduce visible actor count ( == less draw calls)
- - For 2D UI graphics which require no z sorting use @code Actor::SetDrawMode( DrawMode::OVERLAY ); -// In this mode depth testing is turned off and order is determined by the hierachy (depth-first search order). - @endcode - - Use TextureAtlases ( reduces state changes in the GPU)
- - Use compressed textures - - Use lower quality textures, e.g. smaller, lower number of bits per pixel - - Use Dali::NinePatchImage where possible. - - Avoid using too many textures which contain alpha and require blending - - Avoid using too many Dali::Layer with depth testing enabled. Otherwise the layer has to clear the depth buffer. - - Optimise any shaders used. Pixel shaders should be kept as lean as possible. -
- - */ diff --git a/docs/content/programming-guide/resource-tracking.h b/docs/content/programming-guide/resource-tracking.h deleted file mode 100644 index 5782eff..0000000 --- a/docs/content/programming-guide/resource-tracking.h +++ /dev/null @@ -1,48 +0,0 @@ -/*! \page resource-tracking Resource Tracking - * - * - *

Enable Logging

- * 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.
- * The script shows a summary of memory used by resources. - * - * USAGE: - * ./dalireslog.sh [FILE]
- * if FILE isn't specified, the script will try to use dlogutil. - * - * Example: - * - *      sh-4.1$ ./dalireslog.sh
- * - *      On a separate terminal:
- *      sh-4.1$ DALI_ENABLE_LOG=RESOURCE_LOG /opt/apps/com.samsung.dali-demo/bin/album.example - * - * Example on desktop:

- *      jon-doe\@ws-1234$ DALI_ENABLE_LOG=RESOURCE_LOG blind-effect.example 2>/home/SERILOCAL/john.doe/log.txt
- * - *      On a separate terminal:
- *      dalireslog.sh ~/log.txt - * - * Displayed information:
- * - * - * A list of files is displayed in the main view, with different color codes representing different states:
- * - * - */ diff --git a/docs/content/programming-guide/script-overview.h b/docs/content/programming-guide/script-overview.h deleted file mode 100644 index 6224f60..0000000 --- a/docs/content/programming-guide/script-overview.h +++ /dev/null @@ -1,108 +0,0 @@ -/*! \page script-overview Scripting Overview - * - * Dali has scripting support to - * - * - * - * This is accessed via the Dali script external application which wraps Dali with a scripting engine. For example - * - * @code - * daliscript hello-world.js - * @endcode - * - *

A Mechanism To Allow Custom Controls in Scripting

- * - *

The TypeRegistry

- * - * The TypeRegistry allows class 'types' to register themselves as creatable from a scripting environment. - * - * Custom controls can register a creation function using class run time type information (RTTI). - * - * The RTTI typeid provides Dali with a unique name to register the type. In this registration the creation function is responsible for creating new instances of the custom class. - * - * Signals can be added to this type registration with a signal connection function. - * - * Actions can be similarly added with an action function. - * - * - *

Non Animatable Properies

- * - * The property system has non animatable properties that can be used by the scripting runtime to set actor attributes. - * - * Custom controls can register properties for scripting access. - * - * - *

A Javascript example

- * - * A Javascript runtime wrapping Dali and the V8 Javacript engine is being developed to allow the creation of pure Javascript applications. - * - * ie 'daliscript helloworld.js'. - * - * This example shows how a Javacript file relates to the TypeRegistry and Property system. - * - * @code - * // Creation - * // This line looks for a type registered as "MyActor" and calls its creation function - * var custom = new MyActor(); - * - * // Property access - * // This line finds a property called "alpha" and Sets with SetProperty(index, Property::Value(2.0)) - * custom.alpha = 2.0; - * - * // NB: non animatable properties can be strings - * custom.text = "a label"; - * - * // Actions - * // This line finds the action function registered as "SelectPage" and calls its with a list of arguments - * // (NB: arguments are currently limited to non aggregate types ie no list, maps or objects) - * custom.SelectPage("one"); - * - * // Signals - * // This line finds the signal registered as "touched" and sets the "OnTouch" callback function - * custom.signals.touched = OnTouch; - * - * // OnTouch could have been previously defined as - * function OnTouch(name) - * { - * custom.text = name - * } - * @endcode - * - *

Supporting Layouts Using JSON

- * - * The builder in Dali Toolkit provides a means to define layouts using the JSON file format. - * - * This format defines a text representation for key value pairs and lists of data. Lists and Maps can hold the fundamental Javascript data types of string, number(float/int), true, false, nil. - * - * *** Current Status - * - * Currently the builder supports internal Toolkit and Dali controls. - * - * *** Next Iteration - * - * The builder will be improved to make use of the TypeRegistry and non animatable properties and allow Custom Controls to be added into Scripting. - * - * This means the current JSON format will alter slightly (for example; properties will not be defined as a tree but as one level below the actor definition) - * - * An actor tree defined in JSON will be retrievable as a "Buildable" class instance. - * - * This buildable class allows the creation of the actor tree. It will also aid resource managment as a buildable can store the layout representation and unload resources when off stage (reconstructing the object when its added back onto the stage). - * - *

Supporting A Javascript Runtime

- * - * As a separate project an application will be available that can execute Javascript. - * - * This application will provide a wrapping layer between V8 and Dali and allow a natural interface to the Javascript developer. - * - * - * - * - * - * - * - * - */ diff --git a/docs/content/programming-guide/texture-atlases.h b/docs/content/programming-guide/texture-atlases.h deleted file mode 100644 index b664d3e..0000000 --- a/docs/content/programming-guide/texture-atlases.h +++ /dev/null @@ -1,261 +0,0 @@ -/*! \page texture-atlases Texture Atlases - * - *

Using Texture Atlases in DALi

- * - * - *

Example demo application

- - \image html image-wall.jpg - - -

Application above is running slow as there are many small individual images displayed (50)

- - - - - - - - - - - - - - - - - -
Launch Time Slow Has to perform:
- 50 file open requests and multiple reads for each image
Memory Usage High Has to create: -
- 50 Dali::Image objects -
- 50 OpenGL Textures -
Rendering Performance Slow Has to perform: -
- 50 glBindTexture calls per frame ( each OpenGL calls takes time) -
- 50 a frame = 3000 calls per second @60 FPS. -
- Texture switching is a major state change in the GPU -
-

- - -*

Solutions to problem: Use a Texture Atlas

- -A texture atlas is simply one larger image that contains smaller images. A texture atlas is sometimes called a -sprite sheet, bitmap sheet or texture pack. - - \image html atlas.jpg - -
-Dali::ImageActor has the ability to display a portion of an image using ImageActor::PixelArea setting. -For example to display the first 3 image in the atlas - - \image html example-code.jpg - -

Result of using an Atlas

- - - - - - - - - - - - - - - - -
Launch Time Fast Has to perform:
- 1 file open request
Memory Usage Better Has to create: -
- 1 Dali::Image objects -
- 1 OpenGL Textures -
Rendering Performance Fast Has to perform: -
- 1 glBindTexture calls per frame ( each OpenGL calls takes time) -
- 1 a frame = 6- calls per second @60 FPS. -
-
-

Atlas creation guide

- -Many tools exist for creating texture atlases.
-In the following example we are using a tool called TexturePacker as DALi has an exporter script for it. -The exporter automatically generates a source file that has the ImageActor::PixelArea pre-defined. -
- -

Using the generated cpp file

- -The generated cpp file contains 3 different ways of describing the atlas.
-Copy and paste the section that best suits your application. - -

Using the lookup table

- -Cut and paste the lookup table code into your application. - -\code - -\\ The following code is automatically generated. -\\ -const char* ATLAS_FILE_NAME( "my_first_atlas.png" ); ///< Atlas image filename - -/** - * Structure to hold image name and position within the atlas. - * - */ -struct ImageInfo -{ - const char* name; - unsigned int x,y,w,h; - Dali::BlendingMode::Type blendMode; // only enable blending if image has alpha -}; - -/** - * lookup table - */ -const ImageInfo ImageAtlas[]= -{ - { "blocks-ball", 2, 198, 51, 51, BlendingMode::ON }, - { "bubble-ball", 288, 74, 32, 32, BlendingMode::ON }, - { "gallery-small-52", 2, 2, 128, 128, BlendingMode::OFF }, - { "icon-change", 219, 2, 37, 34, BlendingMode::ON }, - { "icon-cluster-carousel", 180, 2, 37, 34, BlendingMode::ON } -}; - -const ImageInfo* GetImageInfo(const char* name) -{ - typedef std::map< const char*, const ImageInfo* > LookupMap; - static LookupMap lookup; - if( lookup.empty() ) - { - for( unsigned int i = 0; i < ATLAS_IMAGE_COUNT; ++i) - { - lookup[ ImageAtlas[i].name ] = &ImageAtlas[i]; - } - } - LookupMap::const_iterator iter = lookup.find(name); - if( iter != lookup.end() ) - { - return (*iter).second; - } - DALI_ASSERT_ALWAYS(0 && "image name not found in atlas"); - return NULL; -} - -\endcode - -To use the lookup table you can do something like this: -\code - -// Example function on how to get an image info from the table - -std::string fileName = std::string( DALI_IMAGE_DIR ) + ATLAS_FILE_NAME; -Image imageImage = Image::New( fileName ); - -const ImageInfo* info(NULL); - -info = GetImageInfo("blocks-ball"); -if( info) -{ - ImageActor ballActor = ImageActor::New( imageAtlas, ImageActor::PixelArea( info->x, info->y, info->w, info->h) ); - ballActor->SetBlendMode( info->blendMode ); -} -info = GetImageInfo("bubble-ball"); -if( info) -{ - ImageActor bubbleActor = ImageActor::New( imageAtlas, ImageActor::PixelArea( info->x, info->y, info->w, info->h) ); - bubbleActor->SetBlendMode( info->blendMode ); -} - -\endcode -

Using the constant definitions

- -1. Cut and paste the constant definition code into your application. - -You'll notice the code below won't compile because C++ variables can't have a dash character.
-E.g. BLOCKS-BALL, BUBBLE-BALL will cause errors. Do a search and replace for - and replace with underscores. -This is one reason why using lookup table which holds the filename as a string maybe easier to use. - -\code -\\ The following code is automatically generated. -\\ -const char* ATLAS_FILE_NAME( "my_first_atlas.png" ); - -/** - * Structure to hold position / blend mode within the atlas. - * - */ -struct ImageInfo -{ - ImageInfo(unsigned int x,unsigned int y,unsigned int w,unsigned int h, Dali::BlendingMode::Type mode) - :pixelArea(x,y,w,h),blendMode(mode) - {} - ImageActor::PixelArea pixelArea; - Dali::BlendingMode::Type blendMode; // only enable blending if image has alpha -}; - - -const ImageInfo BLOCKS-BALL( 2, 198, 51, 51 ,BlendingMode::ON ); -const ImageInfo BUBBLE-BALL( 288, 74, 32, 32 ,BlendingMode::ON ); -const ImageInfo GALLERY-SMALL-52( 2, 2, 128, 128 ,BlendingMode::OFF ); -\endcode - -2. To use it, you can copy example code from the generated cpp file which looks -like this -\code -void LoadAtlasImages() -{ - std::string fileName = std::string(DALI_IMAGE_DIR) + ATLAS_FILE_NAME; - Image atlasImage = Image::New( fileName ); - ImageActor Blocksball = ImageActor::New( atlasImage, BLOCKS_BALL.pixelArea); - Blocksball.SetBlendMode( BLOCKS_BALL.blendMode ); - - ImageActor Bubbleball = ImageActor::New( atlasImage, BUBBLE_BALL.pixelArea); - Bubbleball.SetBlendMode( BUBBLE_BALL.blendMode ); - ... - \endcode - - - -

-

Atlas creation tips

- - - - - - */ - diff --git a/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md b/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md index 3be5549..a1200e6 100644 --- a/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md +++ b/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md @@ -1,18 +1,44 @@ /** * -## Writing documentation for the DALi programing guide + +# Writing documentation for the DALi programing guide {#documentationguide} To allow documentation to be shared between C++ and JavaScript, please follow these guidelines: - Create a mark down file (.md) using GitHub Flavoured Markdown https://help.github.com/articles/github-flavored-markdown/ - - Put it into the shared C++ / JavaScript documentation: ~dali-toolkit/docs/content/shared-javascript-and-cpp-documentation/~ + - Put it into the shared C++ / JavaScript documentation: dali-toolkit/docs/content/shared-javascript-and-cpp-documentation/~ - Include code samples for both C++ and JavaScript in the mark down. - - See multi-touch-guide.md in toolkit for an example + - See script-overview.md overview in dali-toolkit/docs/content/shared-javascript-and-cpp-documentation for an example + - For YUIDOC to parse the file it needs: + - Enclosed in code comment block + - Have a class tag with a description of the file + - For DOXYGEN to link to the mark down it currently needs a reference {hash myfile} + + +#### Images + Images are shared between both Doxygen and YUIDOC tools using a symbolic link. + You need to link to the image twice in shared documentation. + This is because YUIDOC stores images in a folder called assets/img/ which is relative to the HTML pages. + Where as Doxygen copies all images in to the same folder as the HTML generated pages. + + ~~~ +![ ](../assets/img/screen-shot.png) // required for YUIDOC +![ ](screen-shot.png) // required for Doxygen + +The space between the brackets is the alternative text. This means you will never see a broken image symbol. +~~~ -Why use GitHub flavoured markdown? +## Example +![ ](../assets/img/example-documentation/example-code.png) +![ ](example-code.png) + + + +#### Why use GitHub flavoured markdown? - Table support is good and language specific code blocks are easier to define ( javascript/C++). - Doxygen and YUIDOC both support it. -@class Writing_DALi_Programming_Guide_Documentation +@class _Guide_Writing_DALi_Programming_Guide_Documentation + */ diff --git a/docs/content/shared-javascript-and-cpp-documentation/javascript-wrapping-guide.md b/docs/content/shared-javascript-and-cpp-documentation/javascript-wrapping-guide.md new file mode 100644 index 0000000..50dd022 --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/javascript-wrapping-guide.md @@ -0,0 +1,113 @@ +/** + * +# JavaScript wrapping guide {#javascriptwrapping} + +This guide outlines what files to modify when the DALi C++ public API changes. + +## Background + +We use Google's V8 to run JavaScript code. +https://developers.google.com/v8/get_started + +#### Folder structure + +There is a folder for each type of wrapped object. + + +The filename for a wrapped type are always object-wrapper.xxx +The filename for the static functions that forward calls to DALi are always object-api.xxx + +The current file / folder structure is as follows: + +![ ](../assets/img/javascript-wrapping-guide/folder-view.png) +![ ](folder-view.png) + + +## What to do when the DALi public API changes: + +### New property has been added +- No code change required. +- It will be automatically avalable using the dot notation. E.g. actor.my_new_property = true; + +### New property type has been added +- modify property-value-wrapper.h / .cpp to support the new type + +### New function added to an object +- Add the function name to function table in my-object-wrapper.cpp +- Add the forwarding function to my-object-api.cpp/.h +- Ensure you have created YUIDOC documention above the function + +![ ](../assets/img/javascript-wrapping-guide/adding-function.png) +![ ](adding-function.png) + +### New object added + +This is an example of wrapping a new DALi C++ object called Light. + +- in dali-wrapper.cpp in ConstructorFunctionTable insert the constructor in the table. + +![ ](../assets/img/javascript-wrapping-guide/constructors.png) +![ ](constructors.png) + + +Objects registered in this table can be created in JavaScript as follows: + +~~~{.js} +var light = new dali.Light(); +~~~ + +- Add the Light to the Type enum in BaseWrappedObject class. + +![ ](../assets/img/javascript-wrapping-guide/base-wrapped-types.png) +![ ](base-wrapped-types.png) + + +- Create the light-wrapper / light-api files + +If Light inherits from Handle then use path-wrapper and path-api as a template to create light-wrapper and light-api +( inherits from HandleWrapper) + +Otherwise use animation-wrapper and animation-api as a template ( inherts from BaseWrappedObject) + + + +## Design +![ ](../assets/img/javascript-wrapping-guide/high-level-design.png) +![ ](high-level-design.png) + + +![ ](../assets/img/javascript-wrapping-guide/plugin-creation.png) +![ ](plugin-creation.png) + + +![ ](../assets/img/javascript-wrapping-guide/plugin-execution.png) +![ ](plugin-execution.png) + +### Internals +In order to wrap DALi C++ objects in JavaScript, we use +hidden fields inside the JavaScript object. + + + +| JavaScript Object | _ | C++ WrappedObject (e.g. ImageWrapper)| +|---------------------------------------|-------|----------------------------------------| +| Hidden internal fields | | | +| *Pointer to a WrappedObject | ----> | Handle to a Dali::Image object | +| Type of wrapped object (e.g. Image) | | | + + +So if you call +~~~{.js} +var name = myActor.getId(); +~~~ +v8 will detect myActor is a wrapped object, and call getId() on that wrapped object. +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. + +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 diff --git a/docs/content/shared-javascript-and-cpp-documentation/performance-profiling.md b/docs/content/shared-javascript-and-cpp-documentation/performance-profiling.md new file mode 100644 index 0000000..1fb8f06 --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/performance-profiling.md @@ -0,0 +1,258 @@ +/** + * + +# Performance Profiling {#performanceprofiling} + + +DALi has many mechanisms for analysing performance including kernel, system and network logging. + + +## Background +The Dali rendering pipeline has 2 stages. + +Each stage is typically run once per frame. + +- Update + - Run animations + - Run constraints + - Run physics + - Update the scene-graph +- Render + - Upload 3D data using OpenGL ( textures, vertex buffers etc). + - Draw the scene using OpenGL + + +Update produces data - **Writes** final object positions to a buffer + +Render consumes data - **Reads** object positions from a buffer and draws with OpenGL + +![ ](../assets/img/performance/update-render.png) +![ ](update-render.png) + + +One reason for having 2 buffers is to allow both tasks to overlap and run in parallel in certain situations. +E.g. if rendering is taking a long time (due to a texture upload), the Update thread can start work producing +data for the next frame. The aim being to take advantage of multi-core CPU's. + +To run at a solid 60 FPS (16 milliseconds per frame), it is recommended to stay below the following times: + + - Update: 4 milliseconds + - Render: 4 milliseconds + +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. +This means animations won't stop if the main thread decides to do a long operation like downloading a file from the internet. + + +## Time Stamp Logging + +This type of logging is used for recording individual time stamped events. + +Setting DALI_PERFORMANCE_TIMESTAMP_OUTPUT environment variable will enable time stamps. + +Tools such as Tizen dynamic analyser and StageHand can be used to provide a GUI display of +the output. + + +The log options are: + +| Bit | Function | Example | +|------|--------------------------|--------------| +| 0 | log markers to DALi log (dlog on Tizen) | DALI_PERFORMANCE_TIMESTAMP_OUTPUT=1 dali-demo | +| 1 | log markers to kernel trace ( logs to ftrace )| DALI_PERFORMANCE_TIMESTAMP_OUTPUT=2 dali-demo | +| 2 | log markers to system trace ( ttrace on Tizen for Tizen analyser) | DALI_PERFORMANCE_TIMESTAMP_OUTPUT=4 dali-demo | +| 3 | log markers to network client (tcp port 3001+) | DALI_PERFORMANCE_TIMESTAMP_OUTPUT=8 dali-demo | + + + +~~~ +DALI_PERFORMANCE_TIMESTAMP_OUTPUT=1 dali-demo +INFO: DALI: 1134155.500142 (seconds), V_SYNC +INFO: DALI: 1134155.500167 (seconds), UPDATE_START +INFO: DALI: 1134155.500214 (seconds), PROCESS_EVENT_END +INFO: DALI: 1134155.500659 (seconds), UPDATE_END +INFO: DALI: 1134155.508039 (seconds), PROCESS_EVENT_START +INFO: DALI: 1134155.508295 (seconds), PROCESS_EVENT_END +INFO: DALI: 1134155.511109 (seconds), RENDER_START +INFO: DALI: 1134155.511548 (seconds), RENDER_END +INFO: DALI: 1134155.516899 (seconds), V_SYNC +INFO: DALI: 1134155.516945 (seconds), UPDATE_START +INFO: DALI: 1134155.517462 (seconds), UPDATE_END +INFO: DALI: 1134155.527884 (seconds), RENDER_START +INFO: DALI: 1134155.528108 (seconds), PROCESS_EVENT_START +INFO: DALI: 1134155.528327 (seconds), RENDER_END +INFO: DALI: 1134155.528358 (seconds), PROCESS_EVENT_END +INFO: DALI: 1134155.528388 (seconds), PROCESS_EVENT_START +INFO: DALI: 1134155.528749 (seconds), PROCESS_EVENT_END +INFO: DALI: 1134155.533672 (seconds), V_SYNC +~~~ + +### Markers that are logged + +| 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 | +| SWAP_START | glSwapBuffers started (todo) | +| SWAP_END | glSwapBuffers end (todo) | +| PAUSE | Application paused | +| RESUME | Application resumed | + +### Custom time stamps for application developers + +A developer can output custom markers using the PerformanceLogger API (C++ only currently) + +~~~ +PerformanceLogger logger = PerformanceLogger::New("MyMarker"); +logger.AddMarker(PerformanceLogger::START_EVENT); + +// do stuff + +logger.AddMarker(PerformanceLogger::END_EVENT); +~~~ + +## 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. + +Setting DALI_LOG_PERFORMANCE_STATS environment variable will enable time stamps. + +The log options are: + +| Bit | Function | Example | +|------|--------------------------|--------------| +| 0 | log all statistics to the DALi log | DALI_LOG_PERFORMANCE_STATS=1 dali-demo | +| 1 | log update and render statistics to the DALi log| DALI_LOG_PERFORMANCE_STATS=2 dali-demo | +| 2 | log event (main) task statistics to the DALi log| DALI_LOG_PERFORMANCE_STATS=4 dali-demo | +| 3 | log custom marker statistics to the DALi log | DALI_LOG_PERFORMANCE_STATS=8 dali-demo | + +Example output +~~~ +$ export DALI_LOG_PERFORMANCE_STATS=1 +$ dali-demo + + Event, min 0.04 ms, max 5.27 ms, total (0.1 secs), avg 0.28 ms, std dev 0.73 ms + Update, min 0.29 ms, max 0.91 ms, total (0.5 secs), avg 0.68 ms, std dev 0.15 ms + Render, min 0.33 ms, max 0.97 ms, total (0.6 secs), avg 0.73 ms, std dev 0.17 ms + 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 +point nothing will be logged. + +### Custom statistics for application developers + +This is identical to the custom timestamp example. +~~~ +PerformanceLogger logger = PerformanceLogger::New("MyMarker"); +logger.AddMarker(PerformanceLogger::START_EVENT); + +// do stuff + +logger.AddMarker(PerformanceLogger::END_EVENT); +~~~ + + +## Application profiling + + The main application thread in Dali is used to process and respond to events such as touch, key, mouse, gestures and timers. + +Example: +~~~ +$ export DALI_LOG_PERFORMANCE_STATS=4 +$ dali-demo +$ +$ ... +$ INFO: DALI: Event, min 0.04 ms, max 5.27 ms, total (0.1 secs), avg 0.28 ms, std dev 0.73 ms +~~~ + +Inside the event processing, the application may be listening for certain events. +For example when an actor is touched, some application code may be run in an OnTouchEvent callback. +By checking the max times you can check for any spikes that occur when interacting with the application. + +Example: +~~~ +$ INFO: DALI: Event , min 0.10 ms, max 500.01 ms, total (6.4 secs), avg 20.83 ms + +- Something has taken 500 ms = 1/2 second during event processing. +- Need to investigate what the application is doing for 1/2 a second. +~~~ + + +## Using ftrace for timestamp logging + +~~~ +DALI_PERFORMANCE_TIMESTAMP_OUTPUT=2 dali-demo +~~~ + +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. + +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: + + + +### Checking ftrace is working on Linux + +Documentation for ftrace: +Follow these instructions to ensure the debugfs has been mounted, and the kernel you are using +has been built with ftrace enabled. + +https://www.kernel.org/doc/Documentation/trace/ftrace.txt + +To check ftrace is working: +~~~ +$ cd /sys/kernel/debug/tracing +$ echo 1 > tracing_enabled (enabled tracing) +$ echo "test" > trace_marker +$ echo 0 > tracing_enabled (disable tracing) +$ cat trace +# +# TASK-PID CPU# TIMESTAMP FUNCTION +# | | | | | + <...>-2539 [001] 267964.345607: tracing_mark_write: test + + +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 + +~~~ +$ export DALI_LOG_PERFORMANCE=2 +$ dali-demo +$ +$ cat /sys/kernel/debug/tracing/trace + + <...>-3330 [000] 785155.216611: tracing_mark_write: SPI_EV_DALI_V_SYNC + <...>-3328 [003] 785155.216644: tracing_mark_write: SPI_EV_DALI_UPDATE_START + <...>-3328 [003] 785155.217045: tracing_mark_write: SPI_EV_DALI_UPDATE_END + <...>-3329 [001] 785155.227418: tracing_mark_write: SPI_EV_DALI_RENDER_START + <...>-3329 [001] 785155.227807: tracing_mark_write: SPI_EV_DALI_RENDER_END + <...>-3330 [000] 785155.233336: tracing_mark_write: SPI_EV_DALI_V_SYNC + <...>-3328 [002] 785155.233374: tracing_mark_write: SPI_EV_DALI_UPDATE_START + <...>-3328 [002] 785155.233672: tracing_mark_write: SPI_EV_DALI_UPDATE_END + <...>-3329 [001] 785155.235161: tracing_mark_write: SPI_EV_DALI_RENDER_START + <...>-3329 [001] 785155.235475: tracing_mark_write: SPI_EV_DALI_RENDER_END + <...>-3330 [000] 785155.250029: tracing_mark_write: SPI_EV_DALI_V_SYNC + <...>-3328 [003] 785155.250065: tracing_mark_write: SPI_EV_DALI_UPDATE_START + <...>-3328 [003] 785155.250330: tracing_mark_write: SPI_EV_DALI_UPDATE_END + <...>-3329 [001] 785155.252860: tracing_mark_write: SPI_EV_DALI_RENDER_START + <...>-3329 [001] 785155.253178: tracing_mark_write: SPI_EV_DALI_RENDER_END + <...>-3329 [001] 785155.264508: tracing_mark_write: SPI_EV_DALI_RENDER_START + <...>-3329 [001] 785155.265006: tracing_mark_write: SPI_EV_DALI_RENDER_END +~~~ +@class _Guide_Performance_Profiling +*/ + + diff --git a/docs/content/shared-javascript-and-cpp-documentation/performance-tips.md b/docs/content/shared-javascript-and-cpp-documentation/performance-tips.md new file mode 100644 index 0000000..e96ae4d --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/performance-tips.md @@ -0,0 +1,38 @@ +/** + * + +# Performance Tips {#performancetips} + +## High CPU occupancy + + - Try to reduce actor count ( less actors == less processing) + - Delete any actors that are not visible, or move them off stage + - Use TextureAtlases ( reduces OpenGL driver calls to glBindTexture + - Optimise / reduce any constraints used + +## High GPU occupancy + + - Reduce visible actor count ( == less draw calls) + - For 2D UI graphics which require no z sorting you can use +~~~{.cpp} + // In this mode depth testing is turned off and order is determined by the hierachy (depth-first search order). + // Not always recommended if there is going to be a lot of overdraw ( if lots of actors are on top of each other) + + Actor::SetDrawMode( DrawMode::OVERLAY ); // C++ +~~~~ +~~~{.js} + actor.drawMode = dali.DRAW_MODE_OVERLAY; // JavaScript +~~~ + - Use TextureAtlases ( reduces state changes in the GPU) + - Use compressed textures + - Use lower quality textures, e.g. smaller, lower number of bits per pixel + - Use Dali::NinePatchImage where possible. + - Avoid using too many textures which contain alpha and require blending + - Avoid using too many Dali::Layer with depth testing enabled. Otherwise the layer has to clear the depth buffer. + - Optimise any shaders used. Pixel shaders should be kept as lean as possible. + + +@class _Guide_Performance_Tips +*/ + + diff --git a/docs/content/shared-javascript-and-cpp-documentation/resource-tracking.md b/docs/content/shared-javascript-and-cpp-documentation/resource-tracking.md new file mode 100644 index 0000000..92c1850 --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/resource-tracking.md @@ -0,0 +1,56 @@ +/** + * +# Resource Tracking {#resourcetracking} + +## Enable Logging + +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. +The script shows a summary of memory used by resources. +USAGE: +./dalireslog.sh [FILE] +if FILE isn't specified, the script will try to use dlogutil. + +### Example: +~~~{.bash} +sh-4.1$ ./dalireslog.sh + +**On a separate terminal:** + +sh-4.1$ DALI_ENABLE_LOG=RESOURCE_LOG /opt/apps/com.samsung.dali-demo/bin/album.example +~~~ +Example on desktop: +~~~{.bash} +jon-doe\@ws-1234$ DALI_ENABLE_LOG=RESOURCE_LOG blind-effect.example 2>/home/SERILOCAL/john.doe/log.txt + +**On a separate terminal:** + +dalireslog.sh ~/log.txt + +~~~ + +### Displayed information: + +| | | +|--|-| +| 3D | amount of GPU memory used by application | +| MEM Atlas | amount of GPU memory used by texture atlases (usually this refers to font atlases) +| Number of atlases | how many texture atlases are present in memory.| + +A list of files is displayed in the main view, with different color codes representing different states: + +| | | +|-|-| +|CPU | resource is in memory, but hasn't been uploaded to a GL texture.| +|GPU | resource has been uploaded to a GL texture, bitmap buffer discarded.| +|CPUGPU | resource has been uploaded to a GL texture, but still present in CPU memory as well.| +|DISCARDED | resource has been discarded, memory freed up | + +@class _Guide_ResourceTracking + */ diff --git a/docs/content/shared-javascript-and-cpp-documentation/scene-graph.md b/docs/content/shared-javascript-and-cpp-documentation/scene-graph.md new file mode 100644 index 0000000..3092fa2 --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/scene-graph.md @@ -0,0 +1,20 @@ +# 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 diff --git a/docs/content/shared-javascript-and-cpp-documentation/script-overview.md b/docs/content/shared-javascript-and-cpp-documentation/script-overview.md new file mode 100644 index 0000000..bb7bb5d --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/script-overview.md @@ -0,0 +1,262 @@ +/** + * +# Scripting Overview {#scriptoverview} + +Dali has: +- JSON to support: + - layouting + - theme / styling + - templated actor/control creation + - basic actions + - DALi GUI builder generates JSON files. Allows UI designers to create / modify the application look and feel. + +- JavaScript to support: + - Rapid Application Development + - Hybrid C++/JavaScript applications + - Leaverage third party JavaScript modules (backbone.js etc) + +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. +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). + +~~~{.cpp} +scripting.example hello-world.json hello-world.js +~~~ + +We currently have JSON and JavaScript example files held in dali-demo/resources/scripts + +![ ](../assets/img/javascript-wrapping-guide/scripting-overview.png) +![ ](scripting-overview.png) + +# JSON + +JSON file contains different sections: +- **Templates** actor & control tree creation +- **Styles** used to style actor & control trees +- **Animations** +- **Instances** of objects for path, shader-effects, render-tasks, frame-buffers +- **Stage**. A list of actors / controls that can be added to the stage +- **Constants** (e.g. positions / colors, that can be references by other parts of the JSON file); +- **Actions** + +## Examples + +### JSON templates section + +~~~{.json} + + “templates”: + { + "name":"users", + "type":"Actor", + "parent-origin":"TOP_CENTER", + "anchor-point":"TOP_CENTER", + "size":"{DEFAULT_MENU_USER_SIZE}", + "color-mode":"USE_OWN_COLOR", + "actors": + [ + { + "name":"usersBackground", + "type":"ImageActor", + "parent-origin":"CENTER", + "anchor-point":"CENTER", + "size":"{DEFAULT_MENU_USER_SIZE}", + "color-mode":"USE_OWN_COLOR", + "image":{ "filename":"{IMAGE_PATH}white-pixel.png" }, + "color":"{DEFAULT_MENU_BACKGROUND_COLOR}" + }, + { + "name":"icon", + "type":"ImageActor", + "parent-origin":"TOP_CENTER", + "anchor-point":"TOP_CENTER", + "position":[0,41,1], + "image":{ "filename":"{IMAGE_PATH}ico_man_nor.png" } + }, + ] + }, + + +~~~ + +#### JavaScript example + +~~~{.js} + +var builder = new dali.Builder(); + +builder.loadFromFile( "my-app.json"); + +var userActorTree = builder.create( { template:"users"} ); + +~~~ + +#### C++ example + +~~~{.cpp} +Builder builder = Builder::New(); + +std::string jsonData = loadFile("my-app.json"); + +builder.LoadFromString( jsonData ); + +Actor userActorTree = builder.Create("users"); +~~~ + + +### JSON styles section + +~~~{.json} +“styles”: + { + “live-tv-focus": + { + "actors": + { + "background": + { + "image":{ "filename":"{IMAGE_PATH}live_tv_background.png" }, + "color":"{DEFAULT_MENU_ITEM_COLOR_1}" + }, + "icon": + { + "image":{ "filename":"{IMAGE_PATH}icn_live_tv_foc.png" } + }, + "label": + { + "color-alpha":1, + "text":"LIVE" + } + } + }, + } +~~~ + +#### JavaScript example + +~~~{.js} +builder.applyStyle = builder.create( "live-tv-focus", tvIcon ); +~~~ + +#### C++ example + +~~~{.cpp} +builder.ApplyStyle( "live-tv-focus", tvIcon ); +~~~ + +### JSON animations section + +~~~{.json} +"animations": + { + "animate-show": + { + "duration":0.5, + "properties": + [ + { + "actor":"background", + "property":"position-x", + "value":30, + "alpha-function":"EASE_IN_OUT" + }, + { + "actor":"itemsBackground", + "property":"color-alpha", + "value":0.85, + "time-period": {"delay": 0.25, "duration": 0.25 }, + "alpha-function":"EASE_IN_OUT" + }, + { + "actor":"usersBackground", + "property":"color-alpha", + "value":0.85, + "time-period": {"delay": 0.25, "duration": 0.25 }, + "alpha-function":"EASE_IN_OUT" + } + ] + }, +~~~ + +#### JavaScript example + +~~~{.js} +var anim = builder.createAnimation( { animation:"animate-show", actor: myActor } ); +~~~ + +#### C++ example + +~~~{.cpp} +Animation anim = builder.createAnimation( "animate-show", propertyMap ); +~~~ + +### JSON stage section + +~~~{.json} + +“stage": [{ + "name":"simple-table", + "type":"TableView", + "background-color": [0.5,0.5,0,1], + "parent-origin": "CENTER", + "size":[400,500,1], + "rows": 4, + "columns":4, + "cell-padding": [10, 5], + "layout-animation-duration": 0.5, + "layout-rows": { // set the height of the rows + "0": { "policy": "fixed", "value": 40 }, + "1": { "policy": "relative", "value": 0.33 }, + "2": { "policy": "fixed", "value": 120 } + }, + "layout-columns": { // set the widths of the columns + "1": { "policy": "fixed", "value": 150 }, + "2": { "policy": "relative", "value": 0.35 }, + "3": { "policy": "relative", "value": 0.15 } + }, + "actors": [{ + "name":"gallery-1", + "type":"ImageActor", + "image": { + "filename": "{DALI_IMAGE_DIR}gallery-large-1.jpg" + }, + "custom-properties": { // properties registered dynamically + "cell-indices": [0,0],// property to specify the top-left cell this child occupies + "row-span":4, // property to specify how many rows this child occupies, if not set, default value is 1 + "column-spam":1 // property to specify how many columns this child occupies + .... +~~~ + +#### JavaScript example + +~~~{.js} +// add all actors under stage section to the root layer +builder.addActors( dali.stage.getRootLayer() ); +~~~ + +#### C++ example + +~~~{.cpp} +// add all actors under stage section to the root layer +builder.AddActors( Stage::GetCurrent().GetRootLayer() ); +~~~ + +# JavaScript + +For the JavaScript API please build dali-toolkit with YUIDOC installed. This will generate the documentation. +See dali-toolkit/plugins/dali-script-v8/docs/README.txt + +To execute JavaScript from C++ + +~~~{.cpp} +script = Toolkit::Script::New(); + +script.ExecuteFile( scriptFileName ); +~~~ + +@class _Guide_JSON_and_JavaScript_overview + +*/ \ No newline at end of file diff --git a/docs/content/shared-javascript-and-cpp-documentation/texture-atlas.md b/docs/content/shared-javascript-and-cpp-documentation/texture-atlas.md new file mode 100644 index 0000000..23f414a --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/texture-atlas.md @@ -0,0 +1,249 @@ +/** + * +# Texture Atlases {#textureatlases} + +## Example demo application + +![ ](../assets/img/texture-atlas/image-wall.jpg) +![ ](image-wall.jpg) + + +Application above is running slow as there are many small individual images displayed (50) + +| Metric | Result | Explanation | +|--------|--------|-------------| +| Launch time | Slow | Has to perform: 50 file open requests and multiple reads for each image | +| Memory consumption| High | Has to create:50 Dali::Image objects,50 OpenGL Textures| +| Rendering | Slow | Has to perform: 50 glBindTexture calls per frame ( each OpenGL calls takes time) 50 a frame = 3000 calls per second @60 FPS.Texture switching is a major state change in the GPU| + + + +## Solutions to problem: Use a Texture Atlas + +A texture atlas is simply one larger image that contains smaller images. A texture atlas is sometimes called a +sprite sheet, bitmap sheet or texture pack. + +![ ](../assets/img/texture-atlas/atlas.jpg) +![ ](atlas.jpg) + +Dali::ImageActor has the ability to display a portion of an image using ImageActor::PixelArea setting. +For example to display the first 3 image in the atlas + +![ ](../assets/img/texture-atlas/example-javascript-code.jpg) +![ ](example-code.jpg) + +### Result of using an Atlas + +| Metric | Result | Explanation | +|--------|--------|-------------| +| Launch time | Fast | Has to perform: - 1 file open request | +| Memory consumption| Low | Has to create: 1 Dali::Image objects 1 OpenGL Textures| +| Rendering | Fast | HHas to perform: 1 glBindTexture calls per frame ( each OpenGL calls takes time) 1 a frame = 6- calls per second @60 FPS.| + + +## Atlas creation guide + +Many tools exist for creating texture atlases. +In the following example we are using a tool called TexturePacker as DALi has an exporter script for it. +The exporter automatically generates a source file that has the ImageActor::PixelArea pre-defined. + +- Download http://www.codeandweb.com/texturepacker +- Launch TexturePacker +- Go to the menu File -> Preferences +- Set the "Exporter directory" to be the location of dali-toolkit/texture-atlas-exporter + +![ ](../assets/img/texture-atlas/texture-packer-preferences.jpg) +![ ](texture-packer-preferences.jpg) + +- Restart the application! +- Select DALi 3D framework for new project + +![ ](../assets/img/texture-atlas/texture-packer-startup.jpg) +![ ](texture-packer-startup.jpg) + +- Create the atlas +![ ](../assets/img/texture-atlas/texture-packer-add-sprites.jpg) +![ ](texture-packer-add-sprites.jpg) +- Click publish to produce the files +![ ](../assets/img/texture-atlas/texture-packer-publish.jpg) +![ ](texture-packer-publish.jpg) + + + +## Using the generated cpp ( contains JavaScript code as well) + +The generated cpp file contains 3 different ways of describing the atlas. +Copy and paste the section that best suits your application. +- Lookup table. Includes code for storing the table in a std::map for fast lookup. +- constants. +- JavaScript property map + +### Using the JavaScript generated property map + +The property map should be cut and paste in to your application. It just looks like + +~~~{.js} +var ATLAS_IMAGE_LIST : [ + { name: "add_user_usericon_bg", x: 2, y:109, w:105, h:105, blendMode:dali.BLENDING_ON }, + { name: "app_background", x: 180, y:183, w:1, h:1, blendMode:dali.BLENDING_OFF }, + { name: "btn_arrow_left", x: 141, y:183, w:11, h:20, blendMode:dali.BLENDING_ON }, + { name: "btn_arrow_right", x: 154, y:183, w:11, h:20, blendMode:dali.BLENDING_ON }, + { name: "icn_app_foc", x: 194, y:2, w:72, h:72, blendMode:dali.BLENDING_ON }, + { name: "icn_app_nor", x: 109, y:109, w:72, h:72, blendMode:dali.BLENDING_ON } + ] +var atlas = new dali.ResourceImage( { url: "atlas_filename.png" }); + +// display the user icon using the size / position data in the ATLAS_IMAGE_LIST +var userIconData = ATLAS_IMAGE_LIST[0]; +var userIconRect = [ userIconData.x, userIconData.y,userIconData.w,userIconData.h]; + +var btnArrowLeft = new dali.ImageActor( atlas, userIconRect ); +btnArrowLeft.setBlendMode(userIconData.blendMode); + +~~~ + +![ ](example-javascript-code.jpg) + + +### Using the lookup table in C++ + +Cut and paste the lookup table code into your application. + +~~~{.cpp} + +// The following code is automatically generated when TexturePacker publishes to a cpp file. +const char* ATLAS_FILE_NAME( "my_first_atlas.png" ); ///< Atlas image filename + +// Structure to hold image name and position within the atlas. +struct ImageInfo +{ + const char* name; + unsigned int x,y,w,h; + Dali::BlendingMode::Type blendMode; // only enable blending if image has alpha +}; + + +// lookup table +const ImageInfo ImageAtlas[]= +{ + { "blocks-ball", 2, 198, 51, 51, BlendingMode::ON }, + { "bubble-ball", 288, 74, 32, 32, BlendingMode::ON }, + { "gallery-small-52", 2, 2, 128, 128, BlendingMode::OFF }, + { "icon-change", 219, 2, 37, 34, BlendingMode::ON }, + { "icon-cluster-carousel", 180, 2, 37, 34, BlendingMode::ON } +}; + +const ImageInfo* GetImageInfo(const char* name) +{ + typedef std::map< const char*, const ImageInfo* > LookupMap; + static LookupMap lookup; + if( lookup.empty() ) + { + for( unsigned int i = 0; i < ATLAS_IMAGE_COUNT; ++i) + { + lookup[ ImageAtlas[i].name ] = &ImageAtlas[i]; + } + } + LookupMap::const_iterator iter = lookup.find(name); + if( iter != lookup.end() ) + { + return (*iter).second; + } + DALI_ASSERT_ALWAYS(0 && "image name not found in atlas"); + return NULL; +} + +~~~ + +To use the lookup table you can do something like this: + +~~~{.cpp} +// Example function on how to get an image info from the table + +std::string fileName = std::string( DALI_IMAGE_DIR ) + ATLAS_FILE_NAME; +Image imageImage = Image::New( fileName ); + +const ImageInfo* info(NULL); + +info = GetImageInfo("blocks-ball"); +if( info) +{ + ImageActor ballActor = ImageActor::New( imageAtlas, ImageActor::PixelArea( info->x, info->y, info->w, info->h) ); + ballActor->SetBlendMode( info->blendMode ); +} +info = GetImageInfo("bubble-ball"); +if( info) +{ + ImageActor bubbleActor = ImageActor::New( imageAtlas, ImageActor::PixelArea( info->x, info->y, info->w, info->h) ); + bubbleActor->SetBlendMode( info->blendMode ); +} + +~~~ + +### Using the constant definitions (C++) + +1. Cut and paste the constant definition code into your application. + +You'll notice the code below won't compile because C++ variables can't have a dash character. +E.g. BLOCKS-BALL, BUBBLE-BALL will cause errors. Do a search and replace for - and replace with underscores. +This is one reason why using lookup table which holds the filename as a string maybe easier to use. + +~~~{.cpp} + +// The following code is automatically generated when TexturePacker publishes to a cpp file. +const char* ATLAS_FILE_NAME( "my_first_atlas.png" ); + + +// Structure to hold position / blend mode within the atlas. +struct ImageInfo +{ + ImageInfo(unsigned int x,unsigned int y,unsigned int w,unsigned int h, Dali::BlendingMode::Type mode) + :pixelArea(x,y,w,h),blendMode(mode) + {} + ImageActor::PixelArea pixelArea; + Dali::BlendingMode::Type blendMode; // only enable blending if image has alpha +}; + + +const ImageInfo BLOCKS-BALL( 2, 198, 51, 51 ,BlendingMode::ON ); +const ImageInfo BUBBLE-BALL( 288, 74, 32, 32 ,BlendingMode::ON ); +const ImageInfo GALLERY-SMALL-52( 2, 2, 128, 128 ,BlendingMode::OFF ); +~~~ + + 2. To use it, you can copy example code from the generated cpp file which looks +like this + +~~~{.cpp} +void LoadAtlasImages() +{ + std::string fileName = std::string(DALI_IMAGE_DIR) + ATLAS_FILE_NAME; + Image atlasImage = Image::New( fileName ); + ImageActor Blocksball = ImageActor::New( atlasImage, BLOCKS_BALL.pixelArea); + Blocksball.SetBlendMode( BLOCKS_BALL.blendMode ); + + ImageActor Bubbleball = ImageActor::New( atlasImage, BUBBLE_BALL.pixelArea); + Bubbleball.SetBlendMode( BUBBLE_BALL.blendMode ); + ... +~~~ + + +## Atlas creation tips + +- Compress the atlas - \link Texture_Compression Compressing Textures \endlink +- Avoid adding large images to the Atlas. +- E.g. don't add background images to it. Medium to large images should be kept seperate. + +![ ](../assets/img/texture-atlas/atlas-size.jpg) +![ ](atlas-size.jpg) + + +- Try to ensure the atlas contains only images that are frequently used. There's no point in having images taking up GPU texture memory if they're not displayed. +- Avoid very large atlases. Try to create multiple atlases based on how they are used within your application. +Alternatively Texture packer has the option to split atlases ( search help for Multipack) + + + +@class _Guide_TextureAtlases + +* +*/ \ No newline at end of file diff --git a/plugins/dali-script-v8/docs/content/texture-compression.js b/docs/content/shared-javascript-and-cpp-documentation/texture-compression.md similarity index 50% rename from plugins/dali-script-v8/docs/content/texture-compression.js rename to docs/content/shared-javascript-and-cpp-documentation/texture-compression.md index 4d9588f..a9910d5 100644 --- a/plugins/dali-script-v8/docs/content/texture-compression.js +++ b/docs/content/shared-javascript-and-cpp-documentation/texture-compression.md @@ -1,8 +1,8 @@ - /** * -## Texture Compression +# Texture Compression {#texturecompression} + Using compressing the textures will: @@ -11,24 +11,71 @@ Using compressing the textures will: - Speed up load times. Smaller files mean quicker load times. DALi supports the KTX file format. + You just load the compressed texture like you would any other image. - var image = new dali.ResourceImage({url:"my_compressed_file.ktx"}); +~~~{.cpp} +// C++ +ResourceImage image = ResourceImage::New("my_compressed_file.ktx"); +~~~ +~~~{.js} +// JavaScript +var image = new dali.ResourceImage( { url:"my_compressed_file.ktx"}); -ARMS texture compression tool
-http://malideveloper.arm.com/develop-for-mali/tools/asset-creation/mali-gpu-texture-compression-tool/
+~~~ + +### ARMS texture compression tool +http://malideveloper.arm.com/develop-for-mali/tools/asset-creation/mali-gpu-texture-compression-tool/ + Here is an example of using the ARM compression tool. + +![ ](../assets/img/texture-atlas/compression-options.jpg) +![ ](compression-options.jpg) + +![ ](../assets/img/texture-atlas/compression-example.jpg) +![ ](compression-example.jpg) - - - + +As shown above the ETC-1 compression format does not support alpha. + +As a work around the tool will export the alpha as a seperate compressed image. -As shown above the ETC-1 compression format does not support alpha.
As a work around the tool will export -the alpha as a seperate compressed image. In order to combine both the images you need to use a custom shader. Here is an example shader: -``` + +~~~{.cpp} +// C++ Code + const char* const COMPRESSED_RGB_PLUS_SEPARATE_ALPHA_FRAGMENT_SOURCE = + "\n" + "void main()\n" + "{\n" + " vec4 v4Color = (texture2D(sTexture, vTexCoord) * uColor);\n" + " v4Color.a = texture2D(sEffect, vTexCoord ).r;\n" + " gl_FragColor = v4Color;" + "}\n"; + + + mShaderEffect = ShaderEffect::New( "", COMPRESSED_RGB_PLUS_SEPARATE_ALPHA_FRAGMENT_SOURCE); + + mAtlasImageRGB = ResourceImage::New( ATLAS_RGB_FILENAME.KTX); + + mAtlasImageAlpha = ResourceImage::New( ATLAS_ALPHA_FILENAME.KTX ); + + mShaderEffect.SetEffectImage( mAtlasImageAlpha ); + + + + // to create Image Actor + ImageActor imageActor = ImageActor::New( mAtlasImageRGB, GetImagePosition( info) ); + + imageActor.SetShaderEffect( mShaderEffect ); + + imageActor.SetBlendMode(BlendingMode::ON); +~~~ + +~~~{.js} +// JavaScript code var fragSource = " \ void main() \ { \ @@ -51,8 +98,11 @@ ImageActor imageActor = ImageActor::New( mAtlasImageRGB, GetImagePosition( info imageActor.setShaderEffect( shaderEffect ); imageActor.setBlendMode( dali.BLENDING_ON ); -``` - @class TextureCompression +~~~ + +@class _Guide_Texture_compression + + +*/ - */ diff --git a/plugins/dali-script-v8/docs/content/actor.js b/plugins/dali-script-v8/docs/content/actor.js index b2ea595..e4d433b 100644 --- a/plugins/dali-script-v8/docs/content/actor.js +++ b/plugins/dali-script-v8/docs/content/actor.js @@ -16,7 +16,7 @@ var camera = new dali.CameraActor(); var layer = new dali.Layer(); ``` -### Hello world example +### Hello world example ``` var myActor = new dali.TextActor("hello-world"); @@ -40,7 +40,8 @@ An actor inherits its parent's position. The relative position between the acto 1) ParentOrigin. This Vector3 property defines a point within the parent actor's area. - +![ ](../assets/img/parent-origin.png) + 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. ``` @@ -50,7 +51,7 @@ myActor.parentOrigin = [0.5, 0.5, 0.5]; 2) AnchorPoint. This Vector3 property defines a point within the child actor's area. - +![ ](../assets/img/anchor-point.png) 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. ``` @@ -60,7 +61,7 @@ myActor.anchorPoint = [0.5, 0.5, 0.5]; 3) Position. This is the position vector between the parent-origin and anchor-point. - +![ ](../assets/img/actor-position.png) Therefore by default, an actors position is the distance between its center and the top-left corner of its parent. @@ -119,7 +120,7 @@ function OnPressed( actor, touchEvent ) var anim = new dali.Animation( 4 ); var rotation = new dali.Rotation( 90, 0, 0 ); // pitch, yaw, roll - anim.animateBy( actor, "orientation", rotation ); + anim.animateBy( actor, "rotation", rotation ); anim.play(); return true; } @@ -196,8 +197,8 @@ See worldPositionX |FLOAT | ✘ | ✘ worldPositionY |FLOAT | ✘ | ✘ worldPositionZ |FLOAT | ✘ | ✘ - orientation |ROTATION | ✔ | ✔ - worldOrientation |ROTATION | ✘ | ✘ + rotation |ROTATION | ✔ | ✔ + worldRotation |ROTATION | ✘ | ✘ scale |VECTOR3 | ✔ | ✔ scaleX |FLOAT | ✔ | ✔ scaleY |FLOAT | ✔ | ✔ @@ -214,7 +215,7 @@ See name |STRING | ✔ | ✘ sensitive |BOOLEAN | ✔ | ✘ leaveRequired |BOOLEAN | ✔ | ✘ - inheritOrientation |BOOLEAN | ✔ | ✘ + inheritRotation |BOOLEAN | ✔ | ✘ inheritScale |BOOLEAN | ✔ | ✘ colorMode |NUMBER | ✔ | ✘ positionInheritance |NUMBER | ✔ | ✘ @@ -381,19 +382,19 @@ WORLD_POSITION_Z /** - * Actors orientation - * @property orientation - * @type dali orientation object + * Actors rotation + * @property rotation + * @type dali Rotation object */ -ORIENTATION +ROTATION /** - * Actors world-orientation - * @property worldOrientation - * @type dali Orientation object ( read only) + * Actors world-rotation + * @property worldRotation + * @type dali Rotation object ( read only) */ -WORLD_ORIENTATION +WORLD_ROTATION /** * Actors scale @@ -521,10 +522,10 @@ LEAVE_REQUIRED /** * Set whether a child actor inherits it's parent's orientation. * @type Boolean - * @property inheritOrientation + * @property inheritRotation * @default true */ -INHERIT_ORIENTATION, +INHERIT_ROTATION, /** @@ -644,4 +645,4 @@ POSTITION_INHERITANCE * @type Vector3 * @property sizeModeFactor */ -SIZE_MODE_FACTOR +SIZE_MODE_FACTOR \ No newline at end of file diff --git a/plugins/dali-script-v8/docs/content/animation.js b/plugins/dali-script-v8/docs/content/animation.js index 33c64f8..727c139 100644 --- a/plugins/dali-script-v8/docs/content/animation.js +++ b/plugins/dali-script-v8/docs/content/animation.js @@ -118,7 +118,8 @@ The example below does the following with a single animation object: - rotates the image actor - magnifies and color shifts the image using a fragment shader - +![ ](../assets/img/shaders/shader-animation.png) + ``` diff --git a/plugins/dali-script-v8/docs/content/constants.js b/plugins/dali-script-v8/docs/content/constants.js index d70d538..e2383d0 100644 --- a/plugins/dali-script-v8/docs/content/constants.js +++ b/plugins/dali-script-v8/docs/content/constants.js @@ -1,6 +1,6 @@ /** * -

Dali Constants

+### Dali Constants Constants accessible under the dali global object. @@ -148,7 +148,6 @@ Constants accessible under the dali global object. | PIXEL_FORMAT_COMPRESSED_SRGB8_ALPHA8_ETC2_EAC | integer value | | PIXEL_FORMAT_COMPRESSED_RGB8_ETC1 | integer value | | PIXEL_FORMAT_COMPRESSED_RGB_PVRTC_4BPPV1 | integer value | - * @class Constants */ diff --git a/plugins/dali-script-v8/docs/content/dali.js b/plugins/dali-script-v8/docs/content/dali.js index 578f6ae..611d004 100644 --- a/plugins/dali-script-v8/docs/content/dali.js +++ b/plugins/dali-script-v8/docs/content/dali.js @@ -25,8 +25,7 @@ the OpenGL API from developers and provides a clean cross-platform JavaScript fr + Runs all animations in a seperate thread. This helps maintain 60 FPS even if JavaScript is performing a long operation ( e.g. Garbage Collection ). + Provides keyboard / touch / mouse handling - - +![Screen shots](../assets/img/screen-shot.png) ## Running JavaScript from DALi C++ API ``` @@ -52,7 +51,7 @@ The following example shows how to connect a new actor to the stage: 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. - +![Screen shots](../assets/img/coordinate-system-and-stage.png) * @module DALi diff --git a/plugins/dali-script-v8/docs/content/image-actor.js b/plugins/dali-script-v8/docs/content/image-actor.js index aebe46f..40a6d5f 100644 --- a/plugins/dali-script-v8/docs/content/image-actor.js +++ b/plugins/dali-script-v8/docs/content/image-actor.js @@ -45,7 +45,8 @@ dali.stage.add( imageActor ); ``` var imageAtlas = new dali.ResourceImage( {url:"atlas.png"} ) ``` - +![ ](../assets/img/texture-atlas/example-javascript-code.jpg) + ### Image Actor Specific Properties diff --git a/plugins/dali-script-v8/docs/content/image.js b/plugins/dali-script-v8/docs/content/image.js index 5d06d3e..f9ef313 100644 --- a/plugins/dali-script-v8/docs/content/image.js +++ b/plugins/dali-script-v8/docs/content/image.js @@ -58,17 +58,17 @@ var borderNinePatch = new dali.ResourceImage( {url:"border.9.png"} ); var image = new dali.NinePatchImage( {url:"my_image.png"}) ``` The nine patch image will scale automatically with the size of the actor. - + Tool for making 9 patches - + http://romannurik.github.io/AndroidAssetStudio/nine-patches.html - + More information on them: - + http://radleymarx.com/blog/simple-guide-to-9-patch/ - + http://developer.android.com/tools/help/draw9patch.html - + @class Image diff --git a/plugins/dali-script-v8/docs/content/keyboard-focus-manager.js b/plugins/dali-script-v8/docs/content/keyboard-focus-manager.js index 465e249..2bcae22 100644 --- a/plugins/dali-script-v8/docs/content/keyboard-focus-manager.js +++ b/plugins/dali-script-v8/docs/content/keyboard-focus-manager.js @@ -11,7 +11,7 @@ It also allows you to set an actor that is used to high light the focused actor. The application is required to help the manager when moving focus. - +![ Focus Manager ](../assets/img/focus-manager/focus-manager.png) ### keyboard-pre-focus-change diff --git a/plugins/dali-script-v8/docs/content/path-animation.js b/plugins/dali-script-v8/docs/content/path-animation.js index 36d7986..81aece0 100644 --- a/plugins/dali-script-v8/docs/content/path-animation.js +++ b/plugins/dali-script-v8/docs/content/path-animation.js @@ -4,7 +4,7 @@ Paths can be used to animate position and orientation of actors. - +![ ](../assets/img/path/path.png) Example diff --git a/plugins/dali-script-v8/docs/content/renderable-actor.js b/plugins/dali-script-v8/docs/content/renderable-actor.js index add11aa..b2509bf 100644 --- a/plugins/dali-script-v8/docs/content/renderable-actor.js +++ b/plugins/dali-script-v8/docs/content/renderable-actor.js @@ -1,15 +1,17 @@ /** * - *

Renderable Actor ( Extends Actor API )

- * Renderable actors are actors that can be drawn. - * These currently are: - * - {{#crossLink "ImageActor"}}{{/crossLink}} - * - {{#crossLink "TextActor"}}{{/crossLink}} - * - {{#crossLink "MeshActor"}}{{/crossLink}} - * - * @class RenderableActor - * @extends Actor - */ +# Renderable Actor ( Extends Actor API ) + +Renderable actors are actors that can be drawn. +These currently are: + +- {{#crossLink "ImageActor"}}{{/crossLink}} +- {{#crossLink "TextActor"}}{{/crossLink}} +- {{#crossLink "MeshActor"}}{{/crossLink}} + + @class RenderableActor + @extends Actor +*/ diff --git a/plugins/dali-script-v8/docs/content/shader-effect.js b/plugins/dali-script-v8/docs/content/shader-effect.js index 98e9c17..8c35f3d 100644 --- a/plugins/dali-script-v8/docs/content/shader-effect.js +++ b/plugins/dali-script-v8/docs/content/shader-effect.js @@ -58,8 +58,9 @@ The API supports functionality such as: + {{#crossLink "ShaderEffect/setUniform:method"}}{{/crossLink}} ### Example of using a custom uniform to brighten an Image (Fragment Shader) - - + +![ ](../assets/img/shaders/fragment-shader-color.png) + ``` createColorEffect = function() { @@ -118,8 +119,9 @@ Like all animatable properties we can also use keyframes to animate the value. ### Example of animating a custom uniform to perform a mask operation (Fragment Shader) In this example we are using the OpenGL discard function to draw an image with a circular mask. - - + +![ ](../assets/img/shaders/fragment-shader-reveal.png) + ``` createRevealEffect = function() { @@ -177,8 +179,9 @@ shaderAnim.play(); ``` * * * ### Example of paper twisting in the wind with color (Vertex + Fragment Shader) - -
+ +![ ](../assets/img/shaders/vertex-shader.png) + The example does the following: @@ -188,9 +191,9 @@ The example does the following: An ImageActor normally only has 4 vertices ( quad ). To allow the image to twist and bend we need it to have more vertices. To do this we can break the image into a grid using the gridX and gridY geometry hints. - - - + +![ ](../assets/img/shaders/shader-grid-hint.png) + ``` createTwistEffect = function() { diff --git a/plugins/dali-script-v8/docs/content/stage.js b/plugins/dali-script-v8/docs/content/stage.js index dcacca6..cfcdb76 100644 --- a/plugins/dali-script-v8/docs/content/stage.js +++ b/plugins/dali-script-v8/docs/content/stage.js @@ -22,7 +22,8 @@ dali.stage.add( imageActor ); dali.stage.remove( imageActor ); ``` - +![ ](../assets/img/stage.png) + ### Key Events diff --git a/plugins/dali-script-v8/docs/content/texture-atlases.js b/plugins/dali-script-v8/docs/content/texture-atlases.js deleted file mode 100644 index 7005fca..0000000 --- a/plugins/dali-script-v8/docs/content/texture-atlases.js +++ /dev/null @@ -1,149 +0,0 @@ -/** - * - -## Using Texture Atlases in DALi - - -### Example demo application - - - - -### Application above is running slow as there are many small individual images displayed (50) - - - - - - - - - - - - - - - - - - -
Launch Time Slow Has to perform:
- 50 file open requests and multiple reads for each image
Memory Usage High Has to create: -
- 50 Dali::Image objects -
- 50 OpenGL Textures -
Rendering Performance Slow Has to perform: -
- 50 glBindTexture calls per frame ( each OpenGL calls takes time) -
- 50 a frame = 3000 calls per second @60 FPS. -
- Texture switching is a major state change in the GPU -
-

- - -### Solutions to problem: Use a Texture Atlas - -A texture atlas is simply one larger image that contains smaller images.
-A texture atlas is sometimes called a sprite sheet, bitmap sheet or texture pack. -

- -

-Dali::ImageActor has the ability to display a portion of an image using ImageActor::PixelArea setting. -For example to display the first 3 image in the atlas -

-``` -var imageAtlas = new dali.ResourceImage( {url:"atlas.png"} ) -``` - -
-### Result of using an Atlas - - - - - - - - - - - - - - - - -
Launch Time Fast Has to perform:
- 1 file open request
Memory Usage Better Has to create: -
- 1 Dali::Image objects -
- 1 OpenGL Textures -
Rendering Performance Fast Has to perform: -
- 1 glBindTexture calls per frame ( each OpenGL calls takes time) -
- 1 a frame = 6- calls per second @60 FPS. -
-
-## Atlas creation guide - -Many tools exist for creating texture atlases.
-In the following example we are using a tool called TexturePacker as DALi has an exporter script for it. -The exporter automatically generates a source file that has the ImageActor::PixelArea pre-defined. -
- -+ Download http://www.codeandweb.com/texturepacker -+ Launch TexturePacker -+ Go to the menu File -> Preferences -+ Set the "Exporter directory" to be the location of dali-toolkit/texture-atlas-exporter
- -
-+ Restart the application! -+ Select DALi 3D framework for new project - -
-+

Create the atlas

- -+

Click publish to produce the files



- - -## Using the generated cpp file - -The generated cpp file contains 3 different ways of describing the atlas. -2 ways are designed for the DALi C++ API, the 3rd way is for JavaScript. -Example exported property map from TexturePacker: -``` -var ATLAS_IMAGE_LIST : [ - { name: "add_user_usericon_bg", x: 2, y:109, w:105, h:105, dali.BLENDING_ON }, - { name: "app_background", x: 180, y:183, w:1, h:1, dali.BLENDING_OFF }, - { name: "btn_arrow_left", x: 141, y:183, w:11, h:20, dali.BLENDING_ON }, - { name: "btn_arrow_right", x: 154, y:183, w:11, h:20, dali.BLENDING_ON }, - { name: "icn_app_foc", x: 194, y:2, w:72, h:72, dali.BLENDING_ON }, - { name: "icn_app_nor", x: 109, y:109, w:72, h:72, dali.BLENDING_ON } - ] -var atlas = new dali.ResourceImage( { url: "atlas_filename.png" }); - -// display the user icon using the size / position data in the ATLAS_IMAGE_LIST -var userIconData = ATLAS_IMAGE_LIST[0]; -var userIconRect = [ userIconData.x, userIconData.y,userIconData.w,userIconData.h]; - -var btnArrowLeft = new dali.ImageActor( atlas, userIconRect ); -``` - -## Atlas creation tips - - - - Compress the atlas - - Avoid adding large images to the Atlas. - E.g. don't add background images to it. Medium to large images should - be kept seperate.

- - - - Try to ensure the atlas contains only images that are frequently used.
- There's no point in having images taking up GPU texture memory if they're not displayed.
- - - Avoid very large atlases
- Try to create multiple atlases based on how they are used within your application.
-
- Alternatively Texture packer has the option to split atlases ( search help for Multipack) - - - - - - @class TextureAtlases - */ - diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img b/plugins/dali-script-v8/docs/dali-theme/assets/img new file mode 120000 index 0000000..e8c2249 --- /dev/null +++ b/plugins/dali-script-v8/docs/dali-theme/assets/img @@ -0,0 +1 @@ +../../../../../docs/content/images/ \ No newline at end of file diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/example-javascript-code.png b/plugins/dali-script-v8/docs/dali-theme/assets/img/example-javascript-code.png deleted file mode 100644 index 3888761..0000000 Binary files a/plugins/dali-script-v8/docs/dali-theme/assets/img/example-javascript-code.png and /dev/null differ diff --git a/plugins/dali-script-v8/docs/dali-theme/assets/img/shared b/plugins/dali-script-v8/docs/dali-theme/assets/img/shared deleted file mode 120000 index 6eab915..0000000 --- a/plugins/dali-script-v8/docs/dali-theme/assets/img/shared +++ /dev/null @@ -1 +0,0 @@ -../../../../../../docs/content/images/ \ No newline at end of file diff --git a/plugins/dali-script-v8/src/animation/animation-api.cpp b/plugins/dali-script-v8/src/animation/animation-api.cpp index 9378742..653f1d3 100644 --- a/plugins/dali-script-v8/src/animation/animation-api.cpp +++ b/plugins/dali-script-v8/src/animation/animation-api.cpp @@ -1030,7 +1030,7 @@ void AnimationApi::AnimateTo( const v8::FunctionCallbackInfo< v8::Value >& args * * create some keyframes to move an actor around a square, and return to the start *
- * + * * * * var keyframes = [ diff --git a/texture-atlas-exporter/dali-exporter/dali3d_exporter.cpp b/texture-atlas-exporter/dali-exporter/dali3d_exporter.cpp index ac505ef..38aa8e8 100755 --- a/texture-atlas-exporter/dali-exporter/dali3d_exporter.cpp +++ b/texture-atlas-exporter/dali-exporter/dali3d_exporter.cpp @@ -126,6 +126,6 @@ void LoadAtlasImages() // ATLAS_IMAGE_LIST : [ -{% for sprite in allSprites %} { name: "{{sprite.trimmedName}}", x: {{sprite.frameRect.x}}, y:{{sprite.frameRect.y}}, w:{{sprite.frameRect.width}}, h:{{sprite.frameRect.height}}, {%if sprite.isSolid %}dali.BLENDING_OFF{% else%}dali.BLENDING_ON{% endif %} }{% if not forloop.last %},{% endif %} +{% for sprite in allSprites %} { name: "{{sprite.trimmedName}}", x: {{sprite.frameRect.x}}, y:{{sprite.frameRect.y}}, w:{{sprite.frameRect.width}}, h:{{sprite.frameRect.height}}, blendMode:{%if sprite.isSolid %}dali.BLENDING_OFF{% else%}dali.BLENDING_ON{% endif %} }{% if not forloop.last %},{% endif %} {% endfor %} -] \ No newline at end of file +]