4 ## Using Texture Atlases in DALi
7 ### Example demo application
9 <img src="../assets/img/shared/texture-atlas/image-wall.jpg">
12 ### Application above is running slow as there are many small individual images displayed (50)
17 <td> Launch Time </td>
19 <td> Has to perform: <br>- 50 file open requests and multiple reads for each image</td>
22 <td> Memory Usage </td>
25 <br>- 50 Dali::Image objects
26 <br>- 50 OpenGL Textures
30 <td>Rendering Performance </td>
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
42 ### Solutions to problem: Use a Texture Atlas
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.
47 <img src="../assets/img/shared/texture-atlas/atlas.jpg">
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
53 var imageAtlas = new dali.ResourceImage( {url:"atlas.png"} )
55 <img src="../assets/img/example-javascript-code.png">
57 ### Result of using an Atlas
60 <td> Launch Time </td>
62 <td> Has to perform: <br>- 1 file open request </td>
65 <td> Memory Usage </td>
68 <br>- 1 Dali::Image objects
69 <br>- 1 OpenGL Textures
73 <td>Rendering Performance </td>
76 <br>- 1 glBindTexture calls per frame ( each OpenGL calls takes time)
77 <br>- 1 a frame = 6- calls per second @60 FPS.
82 ## Atlas creation guide
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.
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>
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
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">
104 ## Using the generated cpp file
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:
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 }
118 var atlas = new dali.ResourceImage( { url: "atlas_filename.png" });
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];
124 var btnArrowLeft = new dali.ImageActor( atlas, userIconRect );
127 ## Atlas creation tips
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">
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>
139 - Avoid very large atlases <br>
140 Try to create multiple atlases based on how they are used within your application.<br>
142 Alternatively Texture packer has the option to split atlases ( search help for Multipack)
147 @class TextureAtlases