plugins/dali-script-v8/docs/content/image.js

   1 /**
   2  *
   3 ## Image API
   4
   5 An Image object represents a resource that can be added to ImageActors and ShaderEffects.
   6
   7 The image is discarded when all ImageActors using the Image object are discarded or in case they
   8 were created with dali.IMAGE_RELEASE_POLICY_UNUSED, taken off stage.
   9
  10 Note: if a resource was shared between Image objects it exists until its last reference is gone.
  11
  12 Image objects are responsible for the underlying resource's lifetime.
  13
  14 ### ReleasePolicies
  15
  16  - dali.IMAGE_RELEASE_POLICY_UNUSED: release resource once ImageActor using it is taken off stage.
  17  - dali.IMAGE_RELEASE_POLICY_NEVER: keep resource alive until Image object is thrown away ( default).
  18
  19 #### Resolution of conflicting policies
  20  - If the same image is created more than once with conflicting policies, ReleasePolicy "Never" overrides "Unused".
  21
  22
  23 ### The hierarchy of Image is:
  24
  25 - {{#crossLink "image"}}Image base class {{/crossLink}} provides basic functionality
  26  - {{#crossLink "ResourceImage"}}ResourceImage {{/crossLink}} used for loading image files and nine-patch files
  27   - {{#crossLink "NinePatchImage"}}NinePatch {{/crossLink}} used just for nine patch files
  28  - {{#crossLink "BufferImage"}}BufferImage {{/crossLink}} used for generating your own image
  29  - {{#crossLink "FrameBufferImage"}}FrameBufferImage {{/crossLink}} contains the result of an 'off screen' render pass of a RenderTask.
  30  - {{#crossLink "NativeImage"}}NativeImage {{/crossLink}} Its data is provided by native resources, such as shared bitmap memory or pixmap from X11 or ECORE-X11, etc.
  31
  32
  33 ### Example:
  34 ```
  35 var image = new dali.ResourceImage( {url: "background.png"} );
  36
  37 var imageActor1 = new dali.ImageActor( image );
  38 var imageActor2 = new dali.ImageActor( image );
  39
  40 shaderEffect.setEffectImage( image );
  41
  42
  43 ```
  44 The API supports functionality such as:
  45
  46 + {{#crossLink "image/Image:method"}}new dali.ResourceImage{{/crossLink}}
  47 + {{#crossLink "image/getWidth:method"}}{{/crossLink}}
  48 + {{#crossLink "image/getHeight:method"}}{{/crossLink}}
  49
  50 ### 9 patch images
  51
  52 The Image class also has support for loading 9 patch Images if the filename contains .9.
  53 e.g.
  54 ```
  55 var blackFrame = new dali.ResourceImage( url:"black-frame.9.png"});
  56 var borderNinePatch = new dali.ResourceImage( {url:"border.9.png"} );
  57 // or if the image doesn't have a .9 filename, you can use the NinePatchImage class
  58 var image = new dali.NinePatchImage( {url:"my_image.png"})
  59 ```
  60 The nine patch image will scale automatically with the size of the actor.
  61
  62 Tool for making 9 patches
  63
  64   http://romannurik.github.io/AndroidAssetStudio/nine-patches.html
  65
  66 More information on them:
  67
  68   http://radleymarx.com/blog/simple-guide-to-9-patch/
  69
  70   http://developer.android.com/tools/help/draw9patch.html
  71
  72
  73
  74  @class Image
  75  */