docs/content/programming-guide/image-actor.h

   1 /*! \page image-actor Image Actors
   2  *
   3  *
   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>
   7  *
   8  * - <b>ImageActor:</b> An actor for displaying Images. It allows the developer to display a Dali::Image object on the stage.<br>
   9  *
  10  * <h1 class="pg">Image Actor</h1>
  11  *
  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
  16  * from a file.
  17  *
  18  * @code
  19  * Dali::Image image = ResourceImage::New( myImageFilename );
  20  * Dali::ImageActor myImageActor = ImageActor::New( image );
  21  * @endcode
  22  *
  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
  28  * prefiltered.
  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).
  32  *
  33  * Here is an example doing rescaling:
  34  *
  35  * @code
  36  * Dali::Image image = Dali::ResourceImage::New( filename, ImageDimensions( 240, 240 ), FittingMode::SCALE_TO_FILL );
  37  * @endcode
  38  *
  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
  43  * as shown above.
  44  *
  45  * The fitting modes and a suggested use-case for each are as follows:
  46  * <ol>
  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.
  51  * </ol>
  52  *
  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>.
  57  *
  58  * There are more details on this topic in the
  59  * \link resourceimagescaling Rescaling Images \endlink
  60  * section.
  61  *
  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>
  67  *
  68  * @code
  69  * // default : ImageActor::STYLE_QUAD
  70  * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
  71  * @endcode
  72  *
  73  *
  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>
  76  *
  77  * @code
  78  * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
  79  * myImageActor.SetBorder(border);
  80  * @endcode
  81  *
  82  *
  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.
  85  * @code
  86  * Rect<int> pixel1( myX, myY, myWidth, myHeight );
  87  * if(!myImageActor.IsPixelAreaSet())
  88  * {
  89  *   myImageActor.SetPixelArea( pixel1 );
  90  * }
  91  *
  92  * //Removes the pixel are set
  93  * myImageActor.ClearPixelArea();
  94  * @endcode
  95  *
  96  *
  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
  99  * @code
 100  * myImageActor.SetImage( newImage );
 101  * @endcode
 102  *
 103  */