Dali 3D User Interface Engine
List of all members | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Private Attributes | Friends
Dali::Internal::ImageAttributes Class Reference

Describes Image properties like dimensions and pixel format and operations to be applied to images during the load process. More...

#include <image-attributes.h>

Collaboration diagram for Dali::Internal::ImageAttributes:
Collaboration graph
[legend]

Public Types

typedef Dali::FittingMode::Type ScalingMode
 Scaling options, used when resizing images on load to fit desired dimensions. More...
 
typedef Dali::SamplingMode::Type FilterMode
 Filtering options, used when resizing images on load to sample original pixels. More...
 

Public Member Functions

 ImageAttributes ()
 Default constructor, initializes to default values. More...
 
 ImageAttributes (const ImageAttributes &rhs)
 This copy constructor is required for correctly copying internal implementation. More...
 
ImageAttributesoperator= (const ImageAttributes &rhs)
 This assignment operator is required for correctly handling the internal implementation. More...
 
 ~ImageAttributes ()
 Default destructor. More...
 
void SetSize (unsigned int width, unsigned int height)
 Set the size properties. More...
 
void SetSize (const Size &size)
 Set the image dimension properties. More...
 
void SetScalingMode (ScalingMode scalingMode)
 Set the scale field of the image attributes. More...
 
void SetFilterMode (FilterMode filterMode)
 Setter for the FilterMode. More...
 
void SetOrientationCorrection (bool enabled)
 Set whether the image will be rotated/flipped back into portrait orientation. More...
 
void Reset (ImageDimensions dimensions=ImageDimensions(0, 0), ScalingMode scaling=ScalingMode(), FilterMode sampling=FilterMode(), bool orientationCorrection=true)
 Change all members in one operation. More...
 
unsigned int GetWidth () const
 Return the width currently represented by the attribute. More...
 
unsigned int GetHeight () const
 Return the height currently represented by the attribute. More...
 
Size GetSize () const
 Return the size currently represented by the attribute. More...
 
ScalingMode GetScalingMode () const
 Return the scale currently represented by the attribute. More...
 
FilterMode GetFilterMode () const
 Getter for the FilterMode. More...
 
bool GetOrientationCorrection () const
 Whether to correct for physical orientation of an image. More...
 

Static Public Member Functions

static ImageAttributes New ()
 Create an initialised image attributes object. More...
 
static ImageAttributes New (unsigned int width, unsigned int height)
 Create an initialised image attributes object. More...
 

Static Public Attributes

static const ImageAttributes DEFAULT_ATTRIBUTES
 Default attributes have no size. More...
 

Private Attributes

ImageAttributesImpl * impl
 Implementation pointer. More...
 

Friends

bool operator< (const ImageAttributes &a, const ImageAttributes &b)
 Less then comparison operator. More...
 
bool operator== (const ImageAttributes &a, const ImageAttributes &b)
 Equal to comparison operator. More...
 
bool operator!= (const ImageAttributes &a, const ImageAttributes &b)
 Not equal to comparison operator. More...
 

Detailed Description

Describes Image properties like dimensions and pixel format and operations to be applied to images during the load process.

ImageAttributes is used to define a set of properties of an image and a sequence of operations to be applied when loading it.

The overall order of operations which can be applied is:

  1. Determine the desired dimensions for the final bitmap.
  2. Scale the image to fit the desired dimensions.

The default for each stage is to do nothing. To enable a calculation of desired final image dimensions and fitting to it, SetSize() must be called.

The loader does not guarantee to rescale a loaded image to the exact desired dimensions, but it will make a best effort to downscale images. The fitting to destination dimensions controlled by the ScalingMode may choose to fit to a larger area with an equivalent aspect ratio. If the requested dimensions are larger than the loaded ones, it will never upscale on load to fill them but will instead fit to smaller dimensions of identical aspect ratio. This is transparent to an application as the upscaling can happen during rendering.

To enable scaling of images on load, desired dimensions must be set using SetSize(). Only one of the dimensions need be supplied, in which case, the other is calculated based on the aspect ratio of the raw loaded image. The desired dimensions 2-tuple 'd' is determined as follows for loaded image dimensions 'l' and 's', the dimensions tuple set with SetSize():

Use cases for scaling images on load include:

  1. Full-screen image display: Limit loaded image resolution to device resolution using ShrinkToFit mode.
  2. Thumbnail gallery grid: Limit loaded image resolution to screen tile using ScaleToFill mode.
  3. Image columns: Limit loaded image resolution to column width using FitWidth mode.
  4. Image rows: Limit loaded image resolution to row height using FitHeight mode.
Note
The aspect ratio of image contents is preserved by all scaling modes, so for example squares in input images stay square after loading.

Definition at line 70 of file image-attributes.h.

Member Typedef Documentation

Filtering options, used when resizing images on load to sample original pixels.

A FilterMode controls how pixels in the raw image on-disk are sampled and combined to generate each pixel of the destination loaded image.

Note
NoFilter and Box modes do not guarantee that the loaded pixel array exactly matches the rectangle specified by the desired dimensions and ScalingMode, but all other filter modes do if the desired dimensions are <= the raw dimensions of the image file.

Definition at line 94 of file image-attributes.h.

Scaling options, used when resizing images on load to fit desired dimensions.

A scaling mode controls the region of a loaded image to be mapped to the desired image rectangle specified using ImageAttributes.SetSize(). All scaling modes preserve the aspect ratio of the image contents.

Definition at line 81 of file image-attributes.h.

Constructor & Destructor Documentation

Dali::Internal::ImageAttributes::ImageAttributes ( )

Default constructor, initializes to default values.

Definition at line 78 of file image-attributes.cpp.

Referenced by New().

Here is the caller graph for this function:

Dali::Internal::ImageAttributes::ImageAttributes ( const ImageAttributes rhs)

This copy constructor is required for correctly copying internal implementation.

Parameters
[in]rhsA reference to the copied handle

Definition at line 83 of file image-attributes.cpp.

Dali::Internal::ImageAttributes::~ImageAttributes ( )

Default destructor.

Definition at line 95 of file image-attributes.cpp.

References impl.

Member Function Documentation

ImageAttributes::FilterMode Dali::Internal::ImageAttributes::GetFilterMode ( ) const

Getter for the FilterMode.

Returns
The FilterMode previously set, or the default value if none has been.

Definition at line 156 of file image-attributes.cpp.

References impl.

Referenced by Dali::Internal::ImageFactory::CompareAttributes(), Dali::ResourceImage::GetImageSize(), Dali::Internal::ImageFactory::GetImageSize(), Dali::Internal::ImageFactory::IssueLoadRequest(), Dali::Scripting::NewImage(), and Dali::Internal::ImageFactory::Reload().

Here is the caller graph for this function:

unsigned int Dali::Internal::ImageAttributes::GetHeight ( ) const

Return the height currently represented by the attribute.

Returns
height

Definition at line 141 of file image-attributes.cpp.

References impl.

Referenced by Dali::Internal::ImageFactory::CompareAttributes(), Dali::Internal::ImageTicket::GetHeight(), Dali::ResourceImage::GetImageSize(), Dali::Internal::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

bool Dali::Internal::ImageAttributes::GetOrientationCorrection ( ) const

Whether to correct for physical orientation of an image.

Returns
Whether image pixels should be transformed according to the orientation metadata, if any.

Definition at line 161 of file image-attributes.cpp.

References impl.

Referenced by Dali::ResourceImage::GetImageSize(), Dali::Internal::ImageFactory::GetImageSize(), Dali::Internal::ImageFactory::IssueLoadRequest(), Dali::Scripting::NewImage(), and Dali::Internal::ImageFactory::Reload().

Here is the caller graph for this function:

ImageAttributes::ScalingMode Dali::Internal::ImageAttributes::GetScalingMode ( ) const

Return the scale currently represented by the attribute.

Returns
scale

Definition at line 151 of file image-attributes.cpp.

References impl.

Referenced by Dali::Internal::ImageFactory::CompareAttributes(), Dali::ResourceImage::GetImageSize(), Dali::Internal::ImageFactory::GetImageSize(), Dali::Internal::ImageFactory::IssueLoadRequest(), Dali::Scripting::NewImage(), and Dali::Internal::ImageFactory::Reload().

Here is the caller graph for this function:

Size Dali::Internal::ImageAttributes::GetSize ( ) const

Return the size currently represented by the attribute.

Returns
size

Definition at line 146 of file image-attributes.cpp.

References impl.

Referenced by Dali::Internal::ResourceClient::AddBitmapImage(), Dali::Internal::ImageFactory::GetImageSize(), Dali::Internal::ImageFactory::IssueLoadRequest(), Dali::Scripting::NewImage(), and Dali::Internal::ImageFactory::Reload().

Here is the caller graph for this function:

unsigned int Dali::Internal::ImageAttributes::GetWidth ( ) const

Return the width currently represented by the attribute.

Returns
width

Definition at line 136 of file image-attributes.cpp.

References impl.

Referenced by Dali::Internal::ImageFactory::CompareAttributes(), Dali::ResourceImage::GetImageSize(), Dali::Internal::ImageTicket::GetWidth(), Dali::Internal::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

ImageAttributes Dali::Internal::ImageAttributes::New ( )
static

Create an initialised image attributes object.

Returns
A handle to a newly allocated object

Definition at line 166 of file image-attributes.cpp.

References ImageAttributes().

Referenced by Dali::Internal::ResourceClient::AddBitmapImage(), Dali::Internal::ResourceClient::AddFrameBufferImage(), Dali::Internal::ResourceClient::AddNativeImage(), Dali::Internal::ResourceClient::AllocateTexture(), and Dali::Scripting::NewImage().

Here is the call graph for this function:

Here is the caller graph for this function:

ImageAttributes Dali::Internal::ImageAttributes::New ( unsigned int  width,
unsigned int  height 
)
static

Create an initialised image attributes object.

Parameters
[in]widthdesired width.
[in]heightdesired height
Returns
A handle to a newly allocated object

Definition at line 171 of file image-attributes.cpp.

References impl.

ImageAttributes & Dali::Internal::ImageAttributes::operator= ( const ImageAttributes rhs)

This assignment operator is required for correctly handling the internal implementation.

Parameters
[in]rhsA reference to the copied handle
Returns
a reference to this object

Definition at line 88 of file image-attributes.cpp.

References impl.

void Dali::Internal::ImageAttributes::Reset ( ImageDimensions  dimensions = ImageDimensions(0, 0),
ScalingMode  scaling = ScalingMode(),
FilterMode  sampling = FilterMode(),
bool  orientationCorrection = true 
)

Change all members in one operation.

Parameters
[in]dimensionswidth and height
[in]scalingScaling mode for resizing loads.
[in]samplingSampling mode.
[in]orientationOrientation correction toggle.

Definition at line 127 of file image-attributes.cpp.

References Dali::Uint16Pair::GetHeight(), Dali::Uint16Pair::GetWidth(), and impl.

Here is the call graph for this function:

void Dali::Internal::ImageAttributes::SetFilterMode ( FilterMode  filterMode)

Setter for the FilterMode.

By default, Box is set.

Parameters
[in]filterModeThe desired filter mode.

Definition at line 117 of file image-attributes.cpp.

References impl.

Referenced by Dali::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

void Dali::Internal::ImageAttributes::SetOrientationCorrection ( bool  enabled)

Set whether the image will be rotated/flipped back into portrait orientation.

This will only be necessary if metadata indicates that the image has a different viewing orientation.

This metadata, optionally present in formats that use exif for example, can encode the physical orientation of the camera which took the picture, establishing which directions in the image correspond to real-world "up" and the horizon. By default the metadata is ignored, but if this function is called with the value "true", the pixels of an image are reordered at load time to reflect the orientation in the metadata.

Parameters
[in]enabledIf true, the image orientation metadata will be used to transform the pixels of the image as laid-out in memory.

Definition at line 122 of file image-attributes.cpp.

References impl.

Referenced by Dali::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

void Dali::Internal::ImageAttributes::SetScalingMode ( ScalingMode  scalingMode)

Set the scale field of the image attributes.

By default, ShrinkToFit is set.

Parameters
[in]scalingModeThe desired scaling mode

Definition at line 112 of file image-attributes.cpp.

References impl.

Referenced by Dali::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

void Dali::Internal::ImageAttributes::SetSize ( unsigned int  width,
unsigned int  height 
)

Set the size properties.

By default width and height are set to zero which means the image loaded has the original size. If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from the one that is set and the aspect ratio of the image.

Parameters
[in]widthdesired width.
[in]heightdesired height

Definition at line 100 of file image-attributes.cpp.

References height, impl, and width.

Referenced by Dali::ResourceImage::New(), and Dali::Scripting::NewImage().

Here is the caller graph for this function:

void Dali::Internal::ImageAttributes::SetSize ( const Size size)

Set the image dimension properties.

By default, width and height are set to zero which means the image loaded has the original size. If one dimension is set to non-zero, but the other zeroed, the unspecified one is derived from the one that is set and the aspect ratio of the image.

Parameters
[in]sizedesired size.

Definition at line 106 of file image-attributes.cpp.

References Dali::Vector2::height, impl, and Dali::Vector2::width.

Friends And Related Function Documentation

bool operator!= ( const ImageAttributes a,
const ImageAttributes b 
)
friend

Not equal to comparison operator.

Parameters
[in]aparameter tested for equality
[in]bparameter tested for equality
Returns
true if a is not equal to b
Parameters
[in]aparameter tested for equality
[in]bparameter tested for equality
[in]aparameter tested for equality
[in]bparameter tested for equality
Returns
true if a is not equal to b

Definition at line 234 of file image-attributes.cpp.

bool operator< ( const ImageAttributes a,
const ImageAttributes b 
)
friend

Less then comparison operator.

Parameters
[in]aparameter tested
[in]bparameter tested
Returns
true if a is less than b
Parameters
[in]aparameter tested
[in]bparameter tested
[in]aparameter tested
[in]bparameter tested
Returns
true if a is less than b

Definition at line 184 of file image-attributes.cpp.

bool operator== ( const ImageAttributes a,
const ImageAttributes b 
)
friend

Equal to comparison operator.

Parameters
[in]aparameter tested for equality
[in]bparameter tested for equality
Returns
true if a is equal to b
Parameters
[in]aparameter tested for equality
[in]bparameter tested for equality
[in]aparameter tested for equality
[in]bparameter tested for equality
Returns
true if a is equal to b

Definition at line 220 of file image-attributes.cpp.

Member Data Documentation

const ImageAttributes Dali::Internal::ImageAttributes::DEFAULT_ATTRIBUTES
static
ImageAttributesImpl* Dali::Internal::ImageAttributes::impl
private

The documentation for this class was generated from the following files:
Dali Docs Home
Read more about Dali