1 /*! \page image-actor Image Actors
4 * <h1 class="pg">Overview</h1>
5 * The Dali::ImageActor inherits from Dali::Actor and provide means to display resources like Images 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>
10 * <h1 class="pg">Image Actor</h1>
12 * <h2 class="pg">Construction</h2>
13 * The Image Actor is constructed by passing a Dali::Image object.
14 * Dali::Image is an abstract base class with multiple derived classes.
15 * Dali::ResourceImage is used for the common case of loading an image
19 * Dali::Image image = ResourceImage::New( myImageFilename );
20 * Dali::ImageActor myImageActor = ImageActor::New( image );
23 * <h3 class="pg">Resizing at Load Time</h3>
24 * An application loading images from an external source will often want to
25 * display those images at a lower resolution than their native ones.
26 * To support this, DALi can resize an image at load time so that its
27 * in-memory copy uses less space and its visual quality benefits from being
29 * There are four algorithms which can be used to fit an image to a desired
30 * rectangle, a desired width or a desired height
31 * (see Dali::FittingMode).
33 * Here is an example doing rescaling:
36 * Dali::Image image = Dali::ResourceImage::New( filename, ImageDimensions( 240, 240 ), FittingMode::SCALE_TO_FILL );
39 * This example sets the size and fitting mode appropriately for a large thumbnail
40 * during Dali::ResourceImage construction.
41 * In general, to enable scaling on load, pass a non-zero width or height and
42 * one of the four fitting modes to the Dali::ResourceImage creator function
45 * The fitting modes and a suggested use-case for each are as follows:
47 * <li> Dali::FittingMode::SHRINK_TO_FIT Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
48 * <li> Dali::FittingMode::SCALE_TO_FILL Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape.
49 * <li> Dali::FittingMode::FIT_WIDTH Image columns: Limit loaded image resolution to column.
50 * <li> Dali::FittingMode::FIT_HEIGHT Image rows: Limit loaded image resolution to row height.
53 * The dali-demo project contains a full example under
54 * <code>examples/image-scaling-and-filtering</code>
55 * and a specific sampling mode example under
56 * <code>examples/image-scaling-irregular-grid</code>.
58 * There are more details on this topic in the
59 * \link resourceimagescaling Rescaling Images \endlink
62 * <h2 class="pg">Style</h2>
63 * The Actor can render an image in two different ways.<br>
64 * -# STYLE_QUAD: A simple flat quad style for rendering images.<br>
65 * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections.
66 * The four corners are not scaled; the four edges are scaled in one axis, and the middle is scaled in both axes.<br>
69 * // default : ImageActor::STYLE_QUAD
70 * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
74 * <h2 class="pg">Border</h2>
75 * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
78 * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
79 * myImageActor.SetBorder(border);
83 * <h2 class="pg">Pixel area</h2>
84 * 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.
86 * Rect<int> pixel1( myX, myY, myWidth, myHeight );
87 * if(!myImageActor.IsPixelAreaSet())
89 * myImageActor.SetPixelArea( pixel1 );
92 * //Removes the pixel are set
93 * myImageActor.ClearPixelArea();
97 * <h2 class="pg">Changing the image</h2>
98 * 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
100 * myImageActor.SetImage( newImage );