1 /*! \page image-mesh-actor Image and Mesh actors
4 * <h1 class="pg">Overview</h1>
5 * The Dali::ImageActor & Dali::MeshActor are inherited from Dali::Actor and provide means to display resources like Images and Geometries (Triangle meshes) on the stage.
6 * All the Dali::Actor methods can be called on them.<br>
8 * - <b>ImageActor:</b> An actor for displaying Images. It allows the developer to display a Dali::Image object on the stage.<br>
9 * - <b>MeshActor:</b> An actor for displaying one or more mesh geometries. It may have children, which may be plain actors or other mesh actors.<br>
11 * <h1 class="pg">Image Actor</h1>
13 * <h2 class="pg">Construction</h2>
14 * The Image Actor is constructed by passing a Dali::Image object
17 * Dali::Image image = Image::New(myImageFilename);
18 * Dali::ImageActor myImageActor = ImageActor::New(image);
21 * <h3 class="pg">Resizing at Load Time</h3>
22 * An application loading images from an external source will often want to
23 * display those images at a lower resolution than their native ones.
24 * To support this, %Dali can resize an image at load time so that its in-memory
25 * copy uses less space and its visual quality benefits from being prefiltered.
26 * There are four algorithms which can be used to fit an image to a desired
27 * rectangle, a desired width or a desired height
28 * (see Dali::ImageAttributes::ScalingMode).
30 * Here is an example doing rescaling:
33 * Dali::ImageAttributes attributes;
34 * attributes.SetSize( 256, 192 );
35 * attributes.SetScalingMode( Dali::ImageAttributes::ScaleToFill );
36 * Dali::Image image = Dali::Image::New( filename, attributes );
39 * This example sets the size and scaling mode appropriately for a large thumbnail
40 * on an Dali::ImageAttributes instance and passes that to Dali::Image construction.
41 * In general, to enable scaling on load, set-up a Dali::ImageAttributes object with
42 * a non-zero width or height and one of the four scaling modes, and pass it into a
43 * Dali::Image creator function as shown above.
45 * The scaling modes and a suggested use-case for each are as follows:
47 * <li> Dali::ImageAttributes::ShrinkToFit Full-screen image display: Limit loaded image resolution to device resolution.
48 * <li> Dali::ImageAttributes::ScaleToFill Thumbnail gallery grid: Limit loaded image resolution to screen tile.
49 * <li> Dali::ImageAttributes::FitWidth Image columns: Limit loaded image resolution to column.
50 * <li> Dali::ImageAttributes::FitHeight Image rows: Limit loaded image resolution to row height.
53 * The dali-demo project contains a full example under <code>examples/image</code>.
55 * <h2 class="pg">Style</h2>
56 * The Actor can render an image in two different ways.<br>
57 * -# STYLE_QUAD: A simple flat quad style for rendering images.<br>
58 * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections.
59 * The four corners are not scaled; the four edges are scaled in one axis, and the middle is scaled in both axes.<br>
62 * // default : ImageActor::STYLE_QUAD
63 * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
67 * <h2 class="pg">Border</h2>
68 * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
71 * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
72 * myImageActor.SetBorder(border);
76 * <h2 class="pg">Pixel area</h2>
77 * The area of the image to be displayed by the Image Actor can be set by setting the Pixel area. Pixel area is relative to the top-left (0,0) of the image.
79 * Rect<int> pixel1( myX, myY, myWidth, myHeight );
80 * if(!myImageActor.IsPixelAreaSet())
82 * myImageActor.SetPixelArea( pixel1 );
85 * //Removes the pixel are set
86 * myImageActor.ClearPixelArea();
90 * <h2 class="pg">Changing the image</h2>
91 * The Image Actor needs a reference to a Dali::Image object on creation. However the Image object can be later changed by calling DaliActor:SetImage
93 * myImageActor.SetImage( newImage );
96 * <h2 class="pg">Fade in</h2>
97 * It's possible to fade in the image gradually when first rendered.
99 * if (!myImageActor.GetFadeIn())
101 * myImageActor.SetFadeIn(true);
104 * // default : 1 Second
105 * myImageActor.SetFadeInDuration(seconds);
109 * <h1 class="pg">Mesh Actor</h1>
111 * <h2 class="pg">Construction</h2>
112 * The mesh actor is created by passing a reference to Dali::Mesh object
115 * Dali::Mesh mesh = Dali::Mesh::New();
116 * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
120 * <h2 class="pg">Modifying material</h2>
121 * The developer can change the material of mesh actor using the material entity name.
124 * Dali::Image image = Dali::Image::New(myTextureFile);
125 * myCustomMaterial = Dali::Material::New("CustomMaterial");
126 * myCustomMaterial.SetDiffuseTexture(image);
127 * Dali::MeshActor::SetMaterial(myMeshActor, materialEntityNameInModel, 0, myCustomMaterial);