Dali 3D User Interface Engine
Image Actors

Overview

The Dali::ImageActor inherits from Dali::Actor and provide means to display resources like Images on the stage. All the Dali::Actor methods can be called on them.

Image Actor

Construction

The Image Actor is constructed by passing a Dali::Image object. Dali::Image is an abstract base class with multiple derived classes. Dali::ResourceImage is used for the common case of loading an image from a file.

Dali::Image image = ResourceImage::New( myImageFilename );
Dali::ImageActor myImageActor = ImageActor::New( image );

Resizing at Load Time

An application loading images from an external source will often want to display those images at a lower resolution than their native ones. To support this, DALi can resize an image at load time so that its in-memory copy uses less space and its visual quality benefits from being prefiltered. There are four algorithms which can be used to fit an image to a desired rectangle, a desired width or a desired height (see Dali::FittingMode).

Here is an example doing rescaling:

This example sets the size and fitting mode appropriately for a large thumbnail during Dali::ResourceImage construction. In general, to enable scaling on load, pass a non-zero width or height and one of the four fitting modes to the Dali::ResourceImage creator function as shown above.

The fitting modes and a suggested use-case for each are as follows:

  1. Dali::FittingMode::SHRINK_TO_FIT Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
  2. 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.
  3. Dali::FittingMode::FIT_WIDTH Image columns: Limit loaded image resolution to column.
  4. Dali::FittingMode::FIT_HEIGHT Image rows: Limit loaded image resolution to row height.

The dali-demo project contains a full example under examples/image-scaling-and-filtering and a specific sampling mode example under examples/image-scaling-irregular-grid.

There are more details on this topic in the Rescaling Images section.

Style

The Actor can render an image in only as a quad. Use ImageView for nine-patch/n-patch image rendering.

  1. STYLE_QUAD: A simple flat quad style for rendering images.
  2. STYLE_NINE_PATCH: This is deprecated as of Dali 1.1.11.

Pixel area

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.

Rect<int> pixel1( myX, myY, myWidth, myHeight );
if(!myImageActor.IsPixelAreaSet())
{
myImageActor.SetPixelArea( pixel1 );
}
//Removes the pixel are set
myImageActor.ClearPixelArea();

Changing the image

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

myImageActor.SetImage( newImage );
Dali Docs Home
Read more about Dali