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

   1 /*! \page image-mesh-actor Image and Mesh actors
   2  *
   3  *
   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>
   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  * - <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>
  10  *
  11  * <h1 class="pg">Image Actor</h1>
  12  *
  13  * <h2 class="pg">Construction</h2>
  14  * The Image Actor is constructed by passing a Dali::Image object
  15  *
  16  * @code
  17  * Dali::Image image = Image::New(myImageFilename);
  18  * Dali::ImageActor myImageActor = ImageActor::New(image);
  19  * @endcode
  20  *
  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).
  29  *
  30  * Here is an example doing rescaling:
  31  *
  32  * @code
  33  * Dali::ImageAttributes attributes;
  34  * attributes.SetSize( 256, 192 );
  35  * attributes.SetScalingMode( Dali::ImageAttributes::ScaleToFill );
  36  * Dali::Image image = Dali::Image::New( filename, attributes );
  37  * @endcode
  38  *
  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.
  44  *
  45  * The scaling modes and a suggested use-case for each are as follows:
  46  * <ol>
  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.
  51  * </ol>
  52  *
  53  * The dali-demo project contains a full example under <code>examples/image</code>.
  54  *
  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>
  60  *
  61  * @code
  62  * // default : ImageActor::STYLE_QUAD
  63  * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
  64  * @endcode
  65  *
  66  *
  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>
  69  *
  70  * @code
  71  * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
  72  * myImageActor.SetBorder(border);
  73  * @endcode
  74  *
  75  *
  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.
  78  * @code
  79  * Rect<int> pixel1( myX, myY, myWidth, myHeight );
  80  * if(!myImageActor.IsPixelAreaSet())
  81  * {
  82  *   myImageActor.SetPixelArea( pixel1 );
  83  * }
  84  *
  85  * //Removes the pixel are set
  86  * myImageActor.ClearPixelArea();
  87  * @endcode
  88  *
  89  *
  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
  92  * @code
  93  * myImageActor.SetImage( newImage );
  94  * @endcode
  95  *
  96  * <h2 class="pg">Fade in</h2>
  97  * It's possible to fade in the image gradually when first rendered.
  98  * @code
  99  * if (!myImageActor.GetFadeIn())
 100  * {
 101  *   myImageActor.SetFadeIn(true);
 102  * }
 103  *
 104  * // default : 1 Second
 105  * myImageActor.SetFadeInDuration(seconds);
 106  * @endcode
 107  *
 108  *
 109  * <h1 class="pg">Mesh Actor</h1>
 110  *
 111  * <h2 class="pg">Construction</h2>
 112  * The mesh actor is created by passing a reference to Dali::Mesh object
 113  *
 114  * @code
 115  * Dali::Mesh mesh = Dali::Mesh::New();
 116  * Dali::MeshActor myMeshActor = Dali::MeshActor::New(mesh);
 117  * @endcode
 118
 119  *
 120  * <h2 class="pg">Modifying material</h2>
 121  * The developer can change the material of mesh actor using the material entity name.
 122  *
 123  * @code
 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);
 128  *
 129  * @endcode
 130  *
 131  *
 132  */
 133