5.8.5 Pixel boxes

All methods in Ogre that take or return raw image data return a PixelBox object.

A PixelBox is a primitive describing a volume (3D), image (2D) or line (1D) of pixels in CPU memory. It describes the location and data format of a region of memory used for image data, but does not do any memory management in itself.

Inside the memory pointed to by the data member of a pixel box, pixels are stored as a succession of "depth" slices (in Z), each containing "height" rows (Y) of "width" pixels (X).

Dimensions that are not used must be 1. For example, a one dimensional image will have extents (width,1,1). A two dimensional image has extents (width,height,1).

A PixelBox has the following members:

data

The pointer to the first component of the image data in memory.

format

The pixel format (See section 5.8.4 Pixel Formats) of the image data.

rowPitch

The number of elements between the leftmost pixel of one row and the left pixel of the next. This value must always be equal to getWidth() (consecutive) for compressed formats.

slicePitch

The number of elements between the top left pixel of one (depth) slice and the top left pixel of the next. Must be a multiple of rowPitch. This value must always be equal to getWidth()*getHeight() (consecutive) for compressed formats.

left, top, right, bottom, front, back

Extents of the box in three dimensional integer space. Note that the left, top, and front edges are included but the right, bottom and top ones are not. left must always be smaller or equal to right, top must always be smaller or equal to bottom, and front must always be smaller or equal to back.

It also has some useful methods:

getWidth()

Get the width of this box

getHeight()

Get the height of this box. This is 1 for one dimensional images.

getDepth()

Get the depth of this box. This is 1 for one and two dimensional images.

setConsecutive()

Set the rowPitch and slicePitch so that the buffer is laid out consecutive in memory.

getRowSkip()

Get the number of elements between one past the rightmost pixel of one row and the leftmost pixel of the next row. This is zero if rows are consecutive.

getSliceSkip()

Get the number of elements between one past the right bottom pixel of one slice and the left top pixel of the next slice. This is zero if slices are consecutive.

isConsecutive()

Return whether this buffer is laid out consecutive in memory (ie the pitches are equal to the dimensions)

getConsecutiveSize()

Return the size (in bytes) this image would take if it was laid out consecutive in memory

getSubVolume(const Box &def)

Return a subvolume of this PixelBox, as a PixelBox.

For more information about these methods consult the API documentation.