Celartem::ImageLock

Celartem::ImageLock Class Reference

#include <pxl_image.h>

Inheritance diagram for Celartem::ImageLock:

Inheritance graph
[legend]

List of all members.

Public Types

enum  RenderingMode { rmDefault = 0, rmPreview = 1 }

Public Member Functions

virtual const u8 * read (ssize_t *outRowStride, const Rect &inRect, RenderingMode inRenderMode=rmDefault)=0
virtual void read (const Rect &inRect, void *inFirstLinePtr, ssize_t inRowStride, RenderingMode inRenderMode=rmDefault)=0

Detailed Description

ImageLock manages the read access to an Image instance.
Any read access to the raw data of an Image instace should go through an ImageLock instance.
If you want to render several portions of an Image instance simultaneously, you should create an ImageLock instance per a thread. In other words, an ImageLock can serve only a call to ImageLock::read method at once; you should not call ImageLock::read of the same ImageLock instance simultaneously.
ImageMultiThread function is an easy way to render images with several threads.
See also:
Image, ImageUtils::ImageMultiThread

Definition at line 119 of file pxl_image.h.

Member Enumeration Documentation

enum Celartem::ImageLock::RenderingMode

This enumeration controls the quality and the speed of image rendering.

See also:
read
Enumerator:
rmDefault  This directs read function to render the image in the normal way.
See also:
read
rmPreview  This directs the image to use faster rendering mode. It does not care about the quality of the image.
See also:
read

Definition at line 127 of file pxl_image.h.

Member Function Documentation

virtual const u8* Celartem::ImageLock::read ( ssize_t *  outRowStride,
const Rect &  inRect,
RenderingMode  inRenderMode = rmDefault 
) [pure virtual]

This function returns pointer to the raw data of the specified portion. The buffer returned by this function is valid until the next read call.

Parameters:
outRowStride Pointer to the buffer that receives the row stride.
Although row stride is usually calculated by [Bytes per pixel] * [Number of pixels], sometimes it may contain padding bytes. The padding bytes depend on the implementation and you should not assume certain padding bytes.
In some condition, it may be a negative value and it means that the image is stored as bottom-up image. In this case, you could not block copy the buffer by the code like the following: 
                    // This code may work incorrectly if rowStride is negative
                    ssize_t rowStride;
                    const u8 *raw = image->read(&rowStride, SomeRect);
                    std::memcpy(someBuffer, raw, rowStride * SomeRect.height);
Instead of the code above, you should use the code like the following: 
                    // This code always works fine
                    ssize_t rowStride;
                    const u8 *raw = image->read(&rowStride, SomeRect);
                    size_t bytesPerLine
                        = (size_t)(rowStride > 0 ? rowStride : -rowStride);
                    for(size_t y = 0; y < SomeRect.height)
                    {
                        std::memcpy(someBuffer, raw, bytesPerLine);
                        someBuffer += bytesPerLine;
                        raw += rowStride;
                    }
For more information about row-stride, see Accessing to Raster Image Data.
inRect This parameter specifies a portion to read.
inRenderMode This parameter specifies how the image is rendered. This should be one of the RenderingMode enumeration.
Returns:
Pointer to the first line of the image. If the row-stride value stored in outRowStride is a negative value, it is not identical to the pointer to the memory block but a pointer to the first line that is placed near the end of the memory block. See Accessing to Raster Image Data for more information.
See also:
RenderingMode, Accessing to Raster Image Data

virtual void Celartem::ImageLock::read ( const Rect &  inRect,
void *  inFirstLinePtr,
ssize_t  inRowStride,
RenderingMode  inRenderMode = rmDefault 
) [pure virtual]

This function loads the raw image onto the specified buffer.

Parameters:
inRect This parameter specifies a portion to read.
inFirstLinePtr Pointer to the first line of the image data. For bottom-up images, it is not identical to the pointer to the memory block. See Accessing to Raster Image Data for more information.
inRowStride The number of bytes to be skipped to go to the next line. It could be a negative value and then the image is regarded as bottom-upped.
By definition, the address of the scanline y should be calculated by the following formula: 
                    u8 *scanline = (u8 *)inBufStart + y * inRowStride;
As you've already found, with bottom-up image, inBufStart should point the last line of the image. For more information about row-stride, see Accessing to Raster Image Data.
inRenderMode This parameter specifies how the image is rendered. This should be one of the RenderingMode enumeration.
See also:
RenderingMode, Accessing to Raster Image Data, Image::estimateBufferSize, PixelAttributes::estimateBufferSize

The documentation for this class was generated from the following file:
This document is automatically generated using doxygen 1.5.4 at Fri Jun 27 18:23:11 2008.