This documents an old version of bs::framework. Click here to see the latest release.
PixelData Class Reference

Description

A buffer describing a volume (3D), image (2D) or line (1D) of pixels in memory.

Pixels are stored as a succession of "depth" slices, each containing "height" rows of "width" pixels.

Note
If using the constructor instead of create() you must call GpuResourceData::allocateInternalBuffer or set the buffer in some other way before reading/writing from this object, as by the default there is no buffer allocated.
See also
GpuResourceData

Inherits GpuResourceData.

Methods

 PixelData (const PixelVolume &extents, PixelFormat pixelFormat)
 Constructs a new object with an internal buffer capable of holding "extents" volume of pixels, where each pixel is of the specified pixel format. More...
 
 PixelData (UINT32 width, UINT32 height, UINT32 depth, PixelFormat pixelFormat)
 Constructs a new object with an internal buffer capable of holding volume of pixels described by provided width, height and depth, where each pixel is of the specified pixel format.
 
 PixelData (const PixelData &copy)
 
PixelDataoperator= (const PixelData &rhs)
 
UINT32 getRowPitch () const
 Returns the number of pixels that offsets one row from another. More...
 
UINT32 getSlicePitch () const
 Returns the number of pixels that offsets one depth slice from another. More...
 
void setRowPitch (UINT32 rowPitch)
 Sets the pitch (in pixels) that determines offset between rows of the pixel buffer. More...
 
void setSlicePitch (UINT32 slicePitch)
 Sets the pitch (in pixels) that determines offset between depth slices of the pixel buffer. More...
 
UINT32 getRowSkip () const
 Returns the number of extra pixels in a row (non-zero only if rows are not consecutive (row pitch is larger than width)).
 
UINT32 getSliceSkip () const
 Returns the number of extra pixels in a depth slice (non-zero only if slices aren't consecutive (slice pitch is larger than width*height).
 
PixelFormat getFormat () const
 Returns the pixel format used by the internal buffer for storing the pixels. More...
 
UINT32 getWidth () const
 Returns width of the buffer in pixels. More...
 
UINT32 getHeight () const
 Returns height of the buffer in pixels. More...
 
UINT32 getDepth () const
 Returns depth of the buffer in pixels. More...
 
UINT32 getLeft () const
 Returns left-most start of the pixel volume. More...
 
UINT32 getRight () const
 Returns right-most end of the pixel volume. More...
 
UINT32 getTop () const
 Returns top-most start of the pixel volume. More...
 
UINT32 getBottom () const
 Returns bottom-most end of the pixel volume. More...
 
UINT32 getFront () const
 Returns front-most start of the pixel volume. More...
 
UINT32 getBack () const
 Returns back-most end of the pixel volume. More...
 
PixelVolume getExtents () const
 Returns extents of the pixel volume this object is capable of holding. More...
 
bool isConsecutive () const
 Return whether this buffer is laid out consecutive in memory (meaning the pitches are equal to the dimensions).
 
UINT32 getConsecutiveSize () const
 Return the size (in bytes) this image would take if it was laid out consecutive in memory. More...
 
UINT32 getSize () const
 Return the size (in bytes) of the buffer this image requires. More...
 
PixelData getSubVolume (const PixelVolume &volume) const
 Returns pixel data containing a sub-volume of this object. More...
 
Color sampleColorAt (const Vector2 &coords, TextureFilter filter=TF_BILINEAR) const
 Samples a color at the specified coordinates using a specific filter. More...
 
Color getColorAt (UINT32 x, UINT32 y, UINT32 z=0) const
 Returns pixel color at the specified coordinates. More...
 
void setColorAt (const Color &color, UINT32 x, UINT32 y, UINT32 z=0)
 Sets the pixel color at the specified coordinates. More...
 
Vector< ColorgetColors () const
 Converts all the internal data into an array of colors. More...
 
void setColors (const Vector< Color > &colors)
 Initializes the internal buffer with the provided set of colors. More...
 
void setColors (Color *colors, UINT32 numElements)
 Initializes the internal buffer with the provided set of colors. More...
 
void setColors (const Color &color)
 Initializes all the pixels with a single color. More...
 
float getDepthAt (UINT32 x, UINT32 y, UINT32 z=0) const
 Interprets pixel data as depth information as retrieved from the GPU's depth buffer. More...
 
Vector< float > getDepths () const
 Converts all the internal data into an array of floats as if each individual pixel is retrieved with getDepthAt(). More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from GpuResourceData
 GpuResourceData (const GpuResourceData &copy)
 
GpuResourceDataoperator= (const GpuResourceData &rhs)
 
UINT8 * getData () const
 Returns pointer to the internal buffer. More...
 
void allocateInternalBuffer ()
 Allocates an internal buffer of a certain size. More...
 
void allocateInternalBuffer (UINT32 size)
 Allocates an internal buffer of a certain size. More...
 
void freeInternalBuffer ()
 Frees the internal buffer that was allocated using allocateInternalBuffer(). More...
 
void setExternalBuffer (UINT8 *data)
 Makes the internal data pointer point to some external data. More...
 
bool isLocked () const
 Checks if the internal buffer is locked due to some other thread using it. More...
 
void _lock () const
 Locks the data and makes it available only to the core thread. More...
 
void _unlock () const
 Unlocks the data and makes it available to all threads. More...
 
RTTITypeBasegetRTTI () const override
 Returns an interface you can use to access class' Run Time Type Information. More...
 
- Methods inherited from IReflectable
bool isDerivedFrom (RTTITypeBase *base)
 Returns true if current RTTI class is derived from base (Or if it is the same type as base). More...
 
UINT32 getTypeId () const
 Returns an unique type identifier of the class. More...
 
const StringgetTypeName () const
 Returns the type name of the class. More...
 

Static methods

static SPtr< PixelDatacreate (const PixelVolume &extents, PixelFormat pixelFormat)
 Constructs a new object with an internal buffer capable of holding "extents" volume of pixels, where each pixel is of the specified pixel format. More...
 
static SPtr< PixelDatacreate (UINT32 width, UINT32 height, UINT32 depth, PixelFormat pixelFormat)
 Constructs a new object with an internal buffer capable of holding volume of pixels described by provided width, height and depth, where each pixel is of the specified pixel format.
 
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from GpuResourceData
static RTTITypeBasegetRTTIStatic ()
 
- Static methods inherited from IReflectable
static UnorderedMap< UINT32, RTTITypeBase * > & getAllRTTITypes ()
 Returns all available RTTI types. More...
 
static SPtr< IReflectablecreateInstanceFromTypeId (UINT32 rttiTypeId)
 Creates an empty instance of a class from a type identifier. More...
 
static void _registerRTTIType (RTTITypeBase *rttiType)
 Called by each type implementing RTTITypeBase, on program load. More...
 
static RTTITypeBase_getRTTIfromTypeId (UINT32 rttiTypeId)
 Returns class' RTTI type from type id. More...
 
static bool _isTypeIdDuplicate (UINT32 typeId)
 Checks if the provided type id is unique. More...
 
static void _checkForCircularReferences ()
 Iterates over all RTTI types and reports any circular references (for example one type having a field referencing another type, and that type having a field referencing the first type). More...
 
static RTTITypeBasegetRTTIStatic ()
 Returns an interface you can use to access class' Run Time Type Information. More...
 

Method documentation

◆ create()

static SPtr<PixelData> create ( const PixelVolume extents,
PixelFormat  pixelFormat 
)
static

Constructs a new object with an internal buffer capable of holding "extents" volume of pixels, where each pixel is of the specified pixel format.

Extent offsets are also stored, but are not used internally.

◆ getBack()

UINT32 getBack ( ) const

Returns back-most end of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getBottom()

UINT32 getBottom ( ) const

Returns bottom-most end of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getColorAt()

Color getColorAt ( UINT32  x,
UINT32  y,
UINT32  z = 0 
) const

Returns pixel color at the specified coordinates.

◆ getColors()

Vector<Color> getColors ( ) const

Converts all the internal data into an array of colors.

Array is mapped as such: arrayIdx = x + y * width + z * width * height.

◆ getConsecutiveSize()

UINT32 getConsecutiveSize ( ) const

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

◆ getDepth()

UINT32 getDepth ( ) const

Returns depth of the buffer in pixels.

◆ getDepthAt()

float getDepthAt ( UINT32  x,
UINT32  y,
UINT32  z = 0 
) const

Interprets pixel data as depth information as retrieved from the GPU's depth buffer.

Converts the device specific depth value to range [0, 1] and returns it.

◆ getDepths()

Vector<float> getDepths ( ) const

Converts all the internal data into an array of floats as if each individual pixel is retrieved with getDepthAt().

Array is mapped as such: arrayIdx = x + y * width + z * width * height.

◆ getExtents()

PixelVolume getExtents ( ) const

Returns extents of the pixel volume this object is capable of holding.

◆ getFormat()

PixelFormat getFormat ( ) const

Returns the pixel format used by the internal buffer for storing the pixels.

◆ getFront()

UINT32 getFront ( ) const

Returns front-most start of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getHeight()

UINT32 getHeight ( ) const

Returns height of the buffer in pixels.

◆ getLeft()

UINT32 getLeft ( ) const

Returns left-most start of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getRight()

UINT32 getRight ( ) const

Returns right-most end of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getRowPitch()

UINT32 getRowPitch ( ) const

Returns the number of pixels that offsets one row from another.

This can be "width", but doesn't have to be as some buffers require padding.

◆ getRTTI()

RTTITypeBase* getRTTI ( ) const
overridevirtual

Returns an interface you can use to access class' Run Time Type Information.

Note

You must derive your own version of RTTITypeBase, in which you may encapsulate all reflection specific operations.

Implements IReflectable.

◆ getSize()

UINT32 getSize ( ) const

Return the size (in bytes) of the buffer this image requires.

◆ getSlicePitch()

UINT32 getSlicePitch ( ) const

Returns the number of pixels that offsets one depth slice from another.

This can be "width * height", but doesn't have to be as some buffers require padding.

◆ getSubVolume()

PixelData getSubVolume ( const PixelVolume volume) const

Returns pixel data containing a sub-volume of this object.

Returned data will not have its own buffer, but will instead point to this one. It is up to the caller to ensure this object outlives any sub-volume objects.

◆ getTop()

UINT32 getTop ( ) const

Returns top-most start of the pixel volume.

This value is not used internally in any way. It is just passed through from the constructor.

◆ getWidth()

UINT32 getWidth ( ) const

Returns width of the buffer in pixels.

◆ sampleColorAt()

Color sampleColorAt ( const Vector2 coords,
TextureFilter  filter = TF_BILINEAR 
) const

Samples a color at the specified coordinates using a specific filter.

Parameters
[in]coordsCoordinates to sample the color at. They start at top left corner (0, 0), and are in range [0, 1].
[in]filterFiltering mode to use when sampling the color.
Returns
Sampled color.

◆ setColorAt()

void setColorAt ( const Color color,
UINT32  x,
UINT32  y,
UINT32  z = 0 
)

Sets the pixel color at the specified coordinates.

◆ setColors() [1/3]

void setColors ( const Vector< Color > &  colors)

Initializes the internal buffer with the provided set of colors.

The array should be of width * height * depth size and mapped as such: arrayIdx = x + y * width + z * width * height.

◆ setColors() [2/3]

void setColors ( Color colors,
UINT32  numElements 
)

Initializes the internal buffer with the provided set of colors.

The array should be of width * height * depth size and mapped as such: arrayIdx = x + y * width + z * width * height.

◆ setColors() [3/3]

void setColors ( const Color color)

Initializes all the pixels with a single color.

◆ setRowPitch()

void setRowPitch ( UINT32  rowPitch)

Sets the pitch (in pixels) that determines offset between rows of the pixel buffer.

Call this before allocating the buffer.

◆ setSlicePitch()

void setSlicePitch ( UINT32  slicePitch)

Sets the pitch (in pixels) that determines offset between depth slices of the pixel buffer.

Call this before allocating the buffer.

Constructor & Destructor Documentation

◆ PixelData()

PixelData ( const PixelVolume extents,
PixelFormat  pixelFormat 
)

Constructs a new object with an internal buffer capable of holding "extents" volume of pixels, where each pixel is of the specified pixel format.

Extent offsets are also stored, but are not used internally.