OGRE: Ogre::HardwarePixelBuffer Class Reference

| OGRE 14.5 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::HardwarePixelBuffer Class Referenceabstract
Core » RenderSystem

Specialisation of HardwareBuffer for a pixel buffer. More...

`#include <OgreHardwarePixelBuffer.h>`

Inheritance diagram for Ogre::HardwarePixelBuffer:
[legend]

## Public Member Functions
| HardwarePixelBuffer (uint32 mWidth, uint32 mHeight, uint32 mDepth, PixelFormat mFormat, HardwareBuffer::Usage usage, bool useShadowBuffer)
| Should be called by HardwareBufferManager.
| ~HardwarePixelBuffer ()
void | blit (const HardwarePixelBufferSharedPtr &src)
| Convenience function that blits the entire source pixel buffer to this buffer.
virtual void | blit (const HardwarePixelBufferSharedPtr &src, const Box &srcBox, const Box &dstBox)
| Copies a box from another PixelBuffer to a region of the this PixelBuffer.
void | blitFromMemory (const PixelBox &src)
| Convenience function that blits a pixelbox from memory to the entire buffer.
virtual void | blitFromMemory (const PixelBox &src, const Box &dstBox)=0
| Copies a region from normal memory to a region of this pixelbuffer.
virtual void | blitToMemory (const Box &srcBox, const PixelBox &dst)=0
| Copies a region of this pixelbuffer to normal memory.
void | blitToMemory (const PixelBox &dst)
| Convenience function that blits this entire buffer to a pixelbox.
const PixelBox & | getCurrentLock ()
| Get the current locked region.
uint32 | getDepth () const
| Gets the depth of this buffer.
PixelFormat | getFormat () const
| Gets the native pixel format of this buffer.
uint32 | getHeight () const
| Gets the height of this buffer.
RenderTexture * | getRenderTarget (size_t slice=0) const
| Get a render target for this PixelBuffer, or a slice of it.
Vector3i | getSize () const
| size (width, height, depth) of the pixel buffer
uint32 | getWidth () const
| Gets the width of this buffer.
const PixelBox & | lock (const Box &lockBox, LockOptions options)
| Lock the buffer for (potentially) reading / writing.
void * | lock (LockOptions options)
| Make every lock method from HardwareBuffer available.
void * | lock (size_t offset, size_t length, LockOptions options) override
| Lock the buffer for (potentially) reading / writing.
void | readData (size_t offset, size_t length, void *pDest) override
| Reads data from the buffer and places it in the memory pointed to by pDest.
void | writeData (size_t offset, size_t length, const void *pSource, bool discardWholeBuffer=false) override
| Writes data to the buffer from an area of system memory; note that you must ensure that your buffer is big enough.
Public Member Functions inherited from Ogre::HardwareBuffer
| HardwareBuffer (Usage usage, bool useShadowBuffer)
| Constructor, to be called by HardwareBufferManager only.
virtual | ~HardwareBuffer ()
template<typename T>
T * | _getImpl ()
virtual void | _updateFromShadow (void)
| Updates the real buffer from the shadow buffer, if required.
void | copyData (HardwareBuffer &srcBuffer)
| Copy all data from another buffer into this one.
virtual void | copyData (HardwareBuffer &srcBuffer, size_t srcOffset, size_t dstOffset, size_t length, bool discardWholeBuffer=false)
| Copy data from another buffer into this one.
size_t | getSizeInBytes (void) const
| Returns the size of this buffer in bytes.
Usage | getUsage (void) const
| Returns the Usage flags with which this buffer was created.
bool | hasShadowBuffer (void) const
| Returns whether this buffer has a system memory shadow for quicker reading.
bool | isLocked (void) const
| Returns whether or not this buffer is currently locked.
virtual bool | isSystemMemory (void) const
| Returns whether this buffer is held in system memory.
void * | lock (LockOptions options)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void | suppressHardwareUpdate (bool suppress)
| Pass true to suppress hardware upload of shadow buffer changes.
void | unlock (void)
| Releases the lock on this buffer.

## Additional Inherited Members
Public Types inherited from Ogre::HardwareBuffer
enum | LockOptions : uint8 { HBL_NORMAL , HBL_DISCARD , HBL_READ_ONLY , HBL_NO_OVERWRITE , HBL_WRITE_ONLY }
| Locking options. More...
typedef uint8 | Usage
enum | UsageEnum { HBU_STATIC = HBU_GPU_TO_CPU , HBU_DYNAMIC = HBU_CPU_ONLY , HBU_WRITE_ONLY = HBU_DETAIL_WRITE_ONLY , HBU_DISCARDABLE = 8 , HBU_STATIC_WRITE_ONLY = HBU_GPU_ONLY , HBU_DYNAMIC_WRITE_ONLY = HBU_CPU_TO_GPU , HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE = HBU_CPU_TO_GPU }
| Rather use HardwareBufferUsage. More...

## Detailed Description

Specialisation of HardwareBuffer for a pixel buffer.

The HardwarePixelbuffer abstracts an 1D, 2D or 3D quantity of pixels stored by the rendering API. The buffer can be located on the card or in main memory depending on its usage. One mipmap level of a texture is an example of a HardwarePixelBuffer.

## Constructor & Destructor Documentation

## ◆ HardwarePixelBuffer()

Ogre::HardwarePixelBuffer::HardwarePixelBuffer | ( | uint32 | mWidth,
|  | uint32 | mHeight,
|  | uint32 | mDepth,
|  | PixelFormat | mFormat,
|  | HardwareBuffer::Usage | usage,
|  | bool | useShadowBuffer )

Should be called by HardwareBufferManager.

## ◆ ~HardwarePixelBuffer()

Ogre::HardwarePixelBuffer::~HardwarePixelBuffer | ( |  | ) |

References Ogre::HardwareBuffer::lock().

## Member Function Documentation

## ◆ lock() [1/3]

const PixelBox & Ogre::HardwarePixelBuffer::lock | ( | const Box & | lockBox,
|  | LockOptions | options )

Lock the buffer for (potentially) reading / writing.

Parameters

  lockBox | Region of the buffer to lock
  options | Locking options

Returns
  PixelBox containing the locked region, the pitches and the pixel format

## ◆ lock() [2/3]

void * Ogre::HardwarePixelBuffer::lock | ( | size_t | offset,
|  | size_t | length,
|  | LockOptions | options )
| overridevirtual

Lock the buffer for (potentially) reading / writing.

Parameters

  offset | The byte offset from the start of the buffer to lock
  length | The size of the area to lock, in bytes
  options | Locking options

Returns
  Pointer to the locked memory

Attention
  this method returns a pointer to the raw buffer storage, which is likely not what you want. The RenderSystem is free to add padding, which you have to query from getCurrentLock() and apply during copying. Prefer Blit from memory, which correctly handles copying in this case

See also
  Updating Pixel Buffers

Reimplemented from Ogre::HardwareBuffer.

## ◆ getCurrentLock()

const PixelBox & Ogre::HardwarePixelBuffer::getCurrentLock | ( |  | ) |

Get the current locked region.

This is the same value as returned by lock(const Box, LockOptions)

Returns
  PixelBox containing the locked region

## ◆ readData()

void Ogre::HardwarePixelBuffer::readData | ( | size_t | offset,
|  | size_t | length,
|  | void * | pDest )
| overridevirtual

Reads data from the buffer and places it in the memory pointed to by pDest.

Parameters

  offset | The byte offset from the start of the buffer to read
  length | The size of the area to read, in bytes
  pDest | The area of memory in which to place the data, must be large enough to accommodate the data!

Reimplemented from Ogre::HardwareBuffer.

## ◆ writeData()

void Ogre::HardwarePixelBuffer::writeData | ( | size_t | offset,
|  | size_t | length,
|  | const void * | pSource,
|  | bool | discardWholeBuffer = false )
| overridevirtual

Writes data to the buffer from an area of system memory; note that you must ensure that your buffer is big enough.

Parameters

  offset | The byte offset from the start of the buffer to start writing
  length | The size of the data to write to, in bytes
  pSource | The source of the data to be written
  discardWholeBuffer | If true, this allows the driver to discard the entire buffer when writing, such that DMA stalls can be avoided; use if you can.

Reimplemented from Ogre::HardwareBuffer.

## ◆ blit() [1/2]

virtual void Ogre::HardwarePixelBuffer::blit | ( | const HardwarePixelBufferSharedPtr & | src,
|  | const Box & | srcBox,
|  | const Box & | dstBox )
| virtual

Copies a box from another PixelBuffer to a region of the this PixelBuffer.

Parameters

  src | Source pixel buffer
  srcBox | Box describing the source region in src
  dstBox | Box describing the destination region in this buffer

Remarks
  The source and destination regions dimensions don't have to match, in which case scaling is done. This scaling is generally done using a bilinear filter in hardware, but it is faster to pass the source image in the right dimensions.

Note
  Only call this function when both buffers are unlocked.

## ◆ blit() [2/2]

void Ogre::HardwarePixelBuffer::blit | ( | const HardwarePixelBufferSharedPtr & | src | ) |

Convenience function that blits the entire source pixel buffer to this buffer.

If source and destination dimensions don't match, scaling is done.

Parameters

  src | PixelBox containing the source pixels and format in memory

Note
  Only call this function when the buffer is unlocked.

## ◆ blitFromMemory() [1/2]

virtual void Ogre::HardwarePixelBuffer::blitFromMemory | ( | const PixelBox & | src,
|  | const Box & | dstBox )
| pure virtual

Copies a region from normal memory to a region of this pixelbuffer.

The source image can be in any pixel format supported by OGRE, and in any size.

Parameters

  src | PixelBox containing the source pixels and format in memory
  dstBox | Box describing the destination region in this buffer

Remarks
  The source and destination regions dimensions don't have to match, in which case scaling is done. This scaling is generally done using a bilinear filter in hardware, but it is faster to pass the source image in the right dimensions.

Note
  Only call this function when the buffer is unlocked.

## ◆ blitFromMemory() [2/2]

void Ogre::HardwarePixelBuffer::blitFromMemory | ( | const PixelBox & | src | ) |
| inline

Convenience function that blits a pixelbox from memory to the entire buffer.

The source image is scaled as needed.

Parameters

  src | PixelBox containing the source pixels and format in memory

Note
  Only call this function when the buffer is unlocked.

References blitFromMemory(), and getSize().

Referenced by blitFromMemory().

## ◆ blitToMemory() [1/2]

virtual void Ogre::HardwarePixelBuffer::blitToMemory | ( | const Box & | srcBox,
|  | const PixelBox & | dst )
| pure virtual

Copies a region of this pixelbuffer to normal memory.

Parameters

  srcBox | Box describing the source region of this buffer
  dst | PixelBox describing the destination pixels and format in memory

Remarks
  The source and destination regions don't have to match, in which case scaling is done.

Note
  Only call this function when the buffer is unlocked.

## ◆ blitToMemory() [2/2]

void Ogre::HardwarePixelBuffer::blitToMemory | ( | const PixelBox & | dst | ) |
| inline

Convenience function that blits this entire buffer to a pixelbox.

The image is scaled as needed.

Parameters

  dst | PixelBox describing the destination pixels and format in memory

Note
  Only call this function when the buffer is unlocked.

References blitToMemory(), and getSize().

Referenced by blitToMemory().

## ◆ getRenderTarget()

RenderTexture * Ogre::HardwarePixelBuffer::getRenderTarget | ( | size_t | slice = 0 | ) | const

Get a render target for this PixelBuffer, or a slice of it.

The texture this was acquired from must have TU_RENDERTARGET set

Parameters

  slice | Which slice

Returns
  A pointer to the render target. This pointer has the lifespan of this PixelBuffer.

References RenderTexture.

## ◆ getWidth()

uint32 Ogre::HardwarePixelBuffer::getWidth | ( |  | ) | const
| inline

Gets the width of this buffer.

Referenced by getSize().

## ◆ getHeight()

uint32 Ogre::HardwarePixelBuffer::getHeight | ( |  | ) | const
| inline

Gets the height of this buffer.

Referenced by getSize().

## ◆ getDepth()

uint32 Ogre::HardwarePixelBuffer::getDepth | ( |  | ) | const
| inline

Gets the depth of this buffer.

Referenced by getSize().

## ◆ getSize()

Vector3i Ogre::HardwarePixelBuffer::getSize | ( |  | ) | const
| inline

size (width, height, depth) of the pixel buffer

References getDepth(), getHeight(), and getWidth().

Referenced by blitFromMemory(), and blitToMemory().

## ◆ getFormat()

PixelFormat Ogre::HardwarePixelBuffer::getFormat | ( |  | ) | const
| inline

Gets the native pixel format of this buffer.

## ◆ lock() [3/3]

void * Ogre::HardwareBuffer::lock | ( | LockOptions | options | ) |
| inline

Make every lock method from HardwareBuffer available.

See http://www.research.att.com/~bs/bs_faq2.html#overloadderived

The documentation for this class was generated from the following file:

- OgreHardwarePixelBuffer.h