Merge "Fix for multi-language support." into tizen
[platform/core/uifw/dali-toolkit.git] / plugins / dali-script-v8 / docs / content / texture-atlases.js
1 /**
2  *
3
4 ## Using Texture Atlases in DALi
5
6
7 ### Example demo application
8
9 <img src="../assets/img/shared/texture-atlas/image-wall.jpg">
10
11
12 ### Application above is running slow as there are many small individual images displayed (50)
13
14
15 <table>
16   <tr>
17     <td> Launch Time </td>
18     <td> Slow </td>
19     <td> Has to perform: <br>- 50 file open requests and multiple reads for each image</td>
20   </tr>
21   <tr>
22     <td> Memory Usage </td>
23     <td> High </td>
24     <td> Has to create:
25       <br>- 50 Dali::Image objects
26       <br>- 50 OpenGL Textures
27     </td>
28   </tr>
29   <tr>
30     <td>Rendering Performance </td>
31     <td> Slow </td>
32     <td> Has to perform:
33       <br>- 50 glBindTexture calls per frame ( each OpenGL calls takes time)
34       <br>- 50 a frame = 3000 calls per second @60 FPS.
35       <br>- Texture switching is a major state change in the GPU
36     </td>
37   </tr>
38 </table>
39 <br><br>
40
41
42 ### Solutions to problem: Use a Texture Atlas
43
44 A texture atlas is simply one larger image that contains smaller images.<br>
45 A texture atlas is sometimes called a sprite sheet, bitmap sheet or texture pack.
46 <br><br>
47 <img src="../assets/img/shared/texture-atlas/atlas.jpg">
48 <br><br>
49 Dali::ImageActor has the ability to display a portion of an image using ImageActor::PixelArea setting.
50 For example to display the first 3 image in the atlas
51 <br><br>
52 ```
53 var imageAtlas = new dali.ResourceImage( {url:"atlas.png"} )
54 ```
55 <img src="../assets/img/example-javascript-code.png">
56 <br>
57 ### Result of using an Atlas
58 <table>
59   <tr>
60     <td> Launch Time </td>
61     <td> Fast </td>
62     <td> Has to perform: <br>- 1 file open request </td>
63   </tr>
64   <tr>
65     <td> Memory Usage </td>
66     <td> Better </td>
67     <td> Has to create:
68       <br>- 1 Dali::Image objects
69       <br>- 1 OpenGL Textures
70     </td>
71   </tr>
72   <tr>
73     <td>Rendering Performance </td>
74     <td> Fast </td>
75     <td> Has to perform:
76       <br>- 1 glBindTexture calls per frame ( each OpenGL calls takes time)
77       <br>- 1 a frame = 6- calls per second @60 FPS.
78     </td>
79   </tr>
80 </table>
81 <br>
82 ## Atlas creation guide
83
84 Many tools exist for creating texture atlases.<br>
85 In the following example we are using a tool called TexturePacker as DALi has an exporter script for it.
86 The exporter automatically generates a source file that has the ImageActor::PixelArea pre-defined.
87 <br>
88
89 + Download http://www.codeandweb.com/texturepacker
90 + Launch TexturePacker
91 + Go to the menu File -> Preferences
92 + Set the "Exporter directory" to be the location of <b>dali-toolkit/texture-atlas-exporter</b>  <br>
93   
94  <img src="../assets/img/shared/texture-atlas/texture-packer-preferences.jpg"> <br>
95 + <b> Restart the application! </b>
96 + Select DALi 3D framework for new project
97   
98  <img src="../assets/img/shared/texture-atlas/texture-packer-startup.jpg"><br>
99 + <h3> Create the atlas </h3>
100    <img src="../assets/img/shared/texture-atlas/texture-packer-add-sprites.jpg">
101 + <h3> Click publish to produce the files </h3><br><br>
102    <img src="../assets/img/shared/texture-atlas/texture-packer-publish.jpg">
103   
104 ## Using the generated cpp file
105
106 The generated cpp file contains 3 different ways of describing the atlas.
107 2 ways are designed for the DALi C++ API, the 3rd way is for JavaScript.
108 Example exported property map from TexturePacker:
109 ```
110 var ATLAS_IMAGE_LIST : [
111     { name: "add_user_usericon_bg", x: 2, y:109, w:105, h:105, dali.BLENDING_ON  },
112     { name: "app_background", x: 180, y:183, w:1, h:1, dali.BLENDING_OFF  },
113     { name: "btn_arrow_left", x: 141, y:183, w:11, h:20, dali.BLENDING_ON  },
114     { name: "btn_arrow_right", x: 154, y:183, w:11, h:20, dali.BLENDING_ON  },
115     { name: "icn_app_foc", x: 194, y:2, w:72, h:72, dali.BLENDING_ON  },
116     { name: "icn_app_nor", x: 109, y:109, w:72, h:72, dali.BLENDING_ON  }
117     ]
118 var atlas = new dali.ResourceImage( { url: "atlas_filename.png" });
119
120 // display the user icon using the size / position data in the ATLAS_IMAGE_LIST
121 var userIconData = ATLAS_IMAGE_LIST[0];
122 var userIconRect = [ userIconData.x, userIconData.y,userIconData.w,userIconData.h];
123
124 var btnArrowLeft = new dali.ImageActor( atlas, userIconRect );
125 ```
126
127 ## Atlas creation tips
128
129
130  - Compress the atlas
131  - Avoid adding large images to the Atlas.
132     E.g. don't add background images to it. Medium to large images should
133     be kept seperate. <br><br>
134    <img src="../assets/img/shared/texture-atlas/atlas-size.jpg">
135
136  - Try to ensure the atlas contains only images that are frequently used. <br>
137     There's no point in having images taking up GPU texture memory if they're not displayed.<br>
138
139  - Avoid very large atlases <br>
140     Try to create multiple atlases based on how they are used within your application.<br>
141     <br>
142     Alternatively Texture packer has the option to split atlases ( search help for Multipack)
143  -
144
145
146
147   @class TextureAtlases
148  */
149