Tizen Native API
Public Member Functions | Static Public Member Functions
Dali::BufferImage Class Reference
Images

BufferImage represents an image resource that can be added to ImageViews. More...

Inheritance diagram for Dali::BufferImage:
Dali::Image Dali::BaseHandle

Public Member Functions

 BufferImage ()
 Constructor which creates an uninitialized BufferImage object.
 ~BufferImage ()
 Destructor.
 BufferImage (const BufferImage &handle)
 This copy constructor is required for (smart) pointer semantics.
BufferImage & operator= (const BufferImage &rhs)
 This assignment operator is required for (smart) pointer semantics.
PixelBuffer * GetBuffer ()
 Returns the pixel buffer of the Image.
unsigned int GetBufferSize () const
 Returns buffer size in bytes.
unsigned int GetBufferStride () const
 Returns buffer stride (in bytes).
Pixel::Format GetPixelFormat () const
 Returns the pixel format of the contained buffer.
void Update ()
 Inform Dali that the contents of the buffer have changed.
void Update (RectArea updateArea)
bool IsDataExternal () const
 Returns whether BufferImage uses external data source or not.

Static Public Member Functions

static BufferImage New (unsigned int width, unsigned int height, Pixel::Format pixelformat=Pixel::RGBA8888)
 Create a new BufferImage.
static BufferImage New (PixelBuffer *pixelBuffer, unsigned int width, unsigned int height, Pixel::Format pixelFormat=Pixel::RGBA8888, unsigned int stride=0)
 Create a new BufferImage, which uses an external data source.
static BufferImage DownCast (BaseHandle handle)
 Downcast a handle to BufferImage handle.
static const BufferImage WHITE ()
 White pixel as image data.

Detailed Description

BufferImage represents an image resource that can be added to ImageViews.

Its pixel buffer data is provided by the application developer.

Care should be taken with pixel data allocated by the application, as the data is copied to GL both when the image is added to the stage and after a call to Update(). In both of these cases, a Image::UploadedSignal will be sent to the application confirming that the operation has completed.

The application can free the pixel data after receiving a Image::UploadedSignal.

Similarly, once the image is on stage (i.e. it's being used by an ImageView that is on stage), the application should only write to the buffer after receiving a Image::UploadedSignal, then call Update() once the write is finished. This avoids the pixel data being changed whilst it's being copied to GL. Writing to the buffer without waiting for the signal will likely result in visible tearing.

If the pixel format of the pixel buffer contains an alpha channel, then the image is considered to be have transparent pixels without regard for the actual content of the channel, and will be blended.

Since :
2.4

Constructor & Destructor Documentation

Dali::BufferImage::BufferImage ( )

Constructor which creates an uninitialized BufferImage object.

Use BufferImage::New(...) to create an initialised object.

Since :
2.4
Dali::BufferImage::~BufferImage ( )

Destructor.

This is non-virtual since derived Handle types must not contain data or virtual methods.

Since :
2.4
Dali::BufferImage::BufferImage ( const BufferImage &  handle)

This copy constructor is required for (smart) pointer semantics.

Since :
2.4
Parameters:
[in]handleA reference to the copied handle

Member Function Documentation

static BufferImage Dali::BufferImage::DownCast ( BaseHandle  handle) [static]

Downcast a handle to BufferImage handle.

If handle points to a BufferImage the downcast produces valid handle. If not the returned handle is left uninitialized.

Since :
2.4
Parameters:
[in]handleHandle to an object
Returns:
Handle to a BufferImage or an uninitialized handle

Reimplemented from Dali::Image.

PixelBuffer* Dali::BufferImage::GetBuffer ( )

Returns the pixel buffer of the Image.

The application can write to the buffer to modify its contents.

Whilst the image is on stage, after writing to the buffer the application should call Update() and wait for the Image::UploadedSignal() method before writing again.

Since :
2.4
Returns:
The pixel buffer
unsigned int Dali::BufferImage::GetBufferSize ( ) const

Returns buffer size in bytes.

Since :
2.4
Returns:
The buffer size in bytes
unsigned int Dali::BufferImage::GetBufferStride ( ) const

Returns buffer stride (in bytes).

Since :
2.4
Returns:
The buffer stride
Pixel::Format Dali::BufferImage::GetPixelFormat ( ) const

Returns the pixel format of the contained buffer.

Since :
2.4
Returns:
The pixel format
bool Dali::BufferImage::IsDataExternal ( ) const

Returns whether BufferImage uses external data source or not.

If not, dali holds ownership of the PixelBuffer, otherwise the application is responsible for freeing it.

The application must not destroy an external PixelBuffer on a staged image if it has called Update() and hasn't received a Image::UploadedSignal.

Since :
2.4
Returns:
True if application owns data, false otherwise
static BufferImage Dali::BufferImage::New ( unsigned int  width,
unsigned int  height,
Pixel::Format  pixelformat = Pixel::RGBA8888 
) [static]

Create a new BufferImage.

Also a pixel buffer for image data is allocated. Dali has ownership of the buffer. For better performance and portability use power of two dimensions. The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.

Since :
2.4
Parameters:
[in]widthImage width in pixels
[in]heightImage height in pixels
[in]pixelformatThe pixel format (rgba 32 bit by default)
Returns:
A handle to a new instance of BufferImage
Precondition:
width & height are greater than zero
Note:
default resource management policies are Immediate and Never
static BufferImage Dali::BufferImage::New ( PixelBuffer *  pixelBuffer,
unsigned int  width,
unsigned int  height,
Pixel::Format  pixelFormat = Pixel::RGBA8888,
unsigned int  stride = 0 
) [static]

Create a new BufferImage, which uses an external data source.

The PixelBuffer has to be allocated by application.

The application holds ownership of the buffer. It must not destroy the PixelBuffer on a staged image if it has called Update() and hasn't received a Image::UploadedSignal, or if it has just added it to the stage and has not received a Image::UploadedSignal.

For better performance and portability use power of two dimensions. The maximum size of the image is limited by GL_MAX_TEXTURE_SIZE.

Since :
2.4
Parameters:
[in]pixelBufferPixel buffer. has to be allocated by application.
[in]widthImage width in pixels
[in]heightImage height in pixels
[in]pixelFormatThe pixel format (rgba 32 bit by default)
[in]strideThe internal stride of the pixelbuffer in pixels
Returns:
A handle to a new instance of BufferImage
Precondition:
width & height are greater than zero
BufferImage& Dali::BufferImage::operator= ( const BufferImage &  rhs)

This assignment operator is required for (smart) pointer semantics.

Since :
2.4
Parameters:
[in]rhsA reference to the copied handle
Returns:
A reference to this
void Dali::BufferImage::Update ( )

Inform Dali that the contents of the buffer have changed.

Image::UploadedSignal will be sent in response if the image is on stage and the image data has been successfully copied to graphics memory. To avoid visual tearing, the application should wait for the Image::UploadedSignal before modifying the data.

The application must not destroy an external PixelBuffer on a staged image after calling this method until the Image::UploadedSignal has been successfully received.

Since :
2.4
Note:
BufferImage::Update might not work with BGR/BGRA formats!
Some GPUs may not support Non power of two buffer updates (for example C110/SGX540)
void Dali::BufferImage::Update ( RectArea  updateArea)

Inform Dali that the contents of the buffer have changed.

Image::UploadedSignal will be sent in response if the image is on stage and the image data has been successfully copied to graphics memory. To avoid visual tearing, the application should wait for the Image::UploadedSignal before modifying the data.

The application must not destroy an external PixelBuffer on a staged image after calling this method until the Image::UploadedSignal has been successfully received.

Since :
2.4
Note:
BufferImage::Update might not work with BGR/BGRA formats!
Some GPUs may not support Non power of two buffer updates (for example C110/SGX540)
Parameters:
[in]updateAreaArea that has changed in buffer
static const BufferImage Dali::BufferImage::WHITE ( ) [static]

White pixel as image data.

Can be used to create solid color actors.

Since :
2.4
Returns:
1 white pixel with 32 bit colordepth