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