f9ef313cec8a68f853d9658ad4a50d67a8d81b6c
[platform/core/uifw/dali-toolkit.git] / 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  */