docs/content/shared-javascript-and-cpp-documentation/resources.md

   1 <!--
   2 /**-->
   3 # Resources {#resoources}
   4
   5 ## Resource Image {#resource-image}
   6
   7 A resource image is an image that is loaded using a file path or a URL.
   8
   9 To create a resource image:
  10 ~~~{.cpp}
  11 Dali::ResourceImage image = Dali::ResourceImage::New( "/my-path/my-image.png" );
  12 ~~~
  13 Which can then be used with actors (e.g. ImageView).
  14
  15 Resources are loaded in separate threads.
  16 The application can connect to the Dali::ResourceImage::LoadingFinishedSignal() to get notified when the image has loaded.
  17
  18 By default, resource images start loading immediately and the data is released only when the ResourceImage handle is destroyed.
  19 To optimise an application's memory footprint, the application can ask resources to be only loaded when actually required and
  20 their data to be released automatically when they are no longer being used (not being used by Actors).
  21 ~~~{.cpp}
  22 Dali::ResourceImage image = Dali::ResourceImage::New( "/my-path/my-image.png", Dali::ResourceImage::ON_DEMAND, Dali::Image::UNUSED );
  23 ~~~
  24 If Dali::Image::UNUSED is used, then when the ResourceImage is used again, the resource data is reloaded automatically.
  25
  26 If the application requires the image dimensions immediately, then they can be retrieved synchronously:
  27 ~~~{.cpp}
  28 Dali::ImageDimensions dimensions = Dali::ResourceImage::GetImageSize( "/my-path/my-image.png" );
  29 ~~~
  30 This is a disk read which can be slow and will block the event thread, so should only be used if absolutely necessary.
  31
  32 ## 9-Patch Image {#resource-9-patch}
  33
  34 DALi has support for 9-patch images.
  35 These are stretchable, repeatable images which are reduced to their smallest size.
  36 Essentially, an image is sliced up into 9 squares and the four corners do not change size at all.
  37 The other 5 segments are stretched (or repeated) to allow the whole image to scale appropriately.
  38
  39 DALi has inbuilt support for *.9.png, *.9.jpg etc. images as well.
  40 More information about these images can be found here: http://developer.android.com/tools/help/draw9patch.html
  41
  42 The following is an example of a *.9.png image:
  43 ![ ](resource/9-patch.png)
  44
  45 Zoomed in, the red section shows the part that will be repeated.
  46 The four corners areas remain static.
  47 The one pixel border will also be stripped out.
  48 ![ ](resource/9-patch-zoomed.png)
  49
  50 And if the image is given a 200 by 200 size, it will look like the following:
  51 ![ ](resource/9-patch-full.png)
  52
  53 ## Buffer Image {#resource-buffer}
  54
  55 A BufferImage represents an image resource in the form of a pixel buffer data that can be provided by the application developer.
  56 The application can then write to this buffer as required and the image is updated on the screen.
  57
  58 ~~~{.cpp}
  59 Dali::BufferImage image = Dali::BufferImage::New( 200, 200 ); // Creates a 200 by 200 pixel buffer with a color-depth of 32-bits (with alpha)
  60 ~~~
  61
  62 */