OgreHardwareBuffer.h
Go to the documentation of this file.
1 /*
2 -----------------------------------------------------------------------------
3 This source file is part of OGRE
4  (Object-oriented Graphics Rendering Engine)
5 For the latest info, see http://www.ogre3d.org/
6 
7 Copyright (c) 2000-2013 Torus Knot Software Ltd
8 
9 Permission is hereby granted, free of charge, to any person obtaining a copy
10 of this software and associated documentation files (the "Software"), to deal
11 in the Software without restriction, including without limitation the rights
12 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13 copies of the Software, and to permit persons to whom the Software is
14 furnished to do so, subject to the following conditions:
15 
16 The above copyright notice and this permission notice shall be included in
17 all copies or substantial portions of the Software.
18 
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25 THE SOFTWARE.
26 -----------------------------------------------------------------------------
27 */
28 #ifndef __HardwareBuffer__
29 #define __HardwareBuffer__
30 
31 // Precompiler options
32 #include "OgrePrerequisites.h"
33 #include "OgreException.h"
34 
35 namespace Ogre {
36 
74  class _OgreExport HardwareBuffer : public BufferAlloc
75  {
76 
77  public:
79  enum Usage
80  {
84  HBU_STATIC = 1,
90  HBU_DYNAMIC = 2,
97  HBU_WRITE_ONLY = 4,
106  HBU_DISCARDABLE = 8,
108  HBU_STATIC_WRITE_ONLY = 5,
114  HBU_DYNAMIC_WRITE_ONLY = 6,
116  HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE = 14
117 
118 
119  };
122  {
139  HBL_WRITE_ONLY
140 
141  };
142  protected:
143  size_t mSizeInBytes;
145  bool mIsLocked;
146  size_t mLockStart;
147  size_t mLockSize;
153 
155  virtual void* lockImpl(size_t offset, size_t length, LockOptions options) = 0;
157  virtual void unlockImpl(void) = 0;
158 
159  public:
161  HardwareBuffer(Usage usage, bool systemMemory, bool useShadowBuffer)
162  : mUsage(usage), mIsLocked(false), mLockStart(0), mLockSize(0), mSystemMemory(systemMemory),
163  mUseShadowBuffer(useShadowBuffer), mShadowBuffer(NULL), mShadowUpdated(false),
164  mSuppressHardwareUpdate(false)
165  {
166  // If use shadow buffer, upgrade to WRITE_ONLY on hardware side
167  if (useShadowBuffer && usage == HBU_DYNAMIC)
168  {
169  mUsage = HBU_DYNAMIC_WRITE_ONLY;
170  }
171  else if (useShadowBuffer && usage == HBU_STATIC)
172  {
173  mUsage = HBU_STATIC_WRITE_ONLY;
174  }
175  }
176  virtual ~HardwareBuffer() {}
183  virtual void* lock(size_t offset, size_t length, LockOptions options)
184  {
185  assert(!isLocked() && "Cannot lock this buffer, it is already locked!");
186 
187  void* ret = NULL;
188  if ((length + offset) > mSizeInBytes)
189  {
191  "Lock request out of bounds.",
192  "HardwareBuffer::lock");
193  }
194  else if (mUseShadowBuffer)
195  {
196  if (options != HBL_READ_ONLY)
197  {
198  // we have to assume a read / write lock so we use the shadow buffer
199  // and tag for sync on unlock()
200  mShadowUpdated = true;
201  }
202 
203  ret = mShadowBuffer->lock(offset, length, options);
204  }
205  else
206  {
207  // Lock the real buffer if there is no shadow buffer
208  ret = lockImpl(offset, length, options);
209  mIsLocked = true;
210  }
211  mLockStart = offset;
212  mLockSize = length;
213  return ret;
214  }
215 
220  void* lock(LockOptions options)
221  {
222  return this->lock(0, mSizeInBytes, options);
223  }
236  virtual void unlock(void)
237  {
238  assert(isLocked() && "Cannot unlock this buffer, it is not locked!");
239 
240  // If we used the shadow buffer this time...
241  if (mUseShadowBuffer && mShadowBuffer->isLocked())
242  {
243  mShadowBuffer->unlock();
244  // Potentially update the 'real' buffer from the shadow buffer
245  _updateFromShadow();
246  }
247  else
248  {
249  // Otherwise, unlock the real one
250  unlockImpl();
251  mIsLocked = false;
252  }
253 
254  }
255 
262  virtual void readData(size_t offset, size_t length, void* pDest) = 0;
271  virtual void writeData(size_t offset, size_t length, const void* pSource,
272  bool discardWholeBuffer = false) = 0;
273 
284  virtual void copyData(HardwareBuffer& srcBuffer, size_t srcOffset,
285  size_t dstOffset, size_t length, bool discardWholeBuffer = false)
286  {
287  const void *srcData = srcBuffer.lock(
288  srcOffset, length, HBL_READ_ONLY);
289  this->writeData(dstOffset, length, srcData, discardWholeBuffer);
290  srcBuffer.unlock();
291  }
292 
298  virtual void copyData(HardwareBuffer& srcBuffer)
299  {
300  size_t sz = std::min(getSizeInBytes(), srcBuffer.getSizeInBytes());
301  copyData(srcBuffer, 0, 0, sz, true);
302  }
303 
305  virtual void _updateFromShadow(void)
306  {
307  if (mUseShadowBuffer && mShadowUpdated && !mSuppressHardwareUpdate)
308  {
309  // Do this manually to avoid locking problems
310  const void *srcData = mShadowBuffer->lockImpl(
311  mLockStart, mLockSize, HBL_READ_ONLY);
312  // Lock with discard if the whole buffer was locked, otherwise normal
313  LockOptions lockOpt;
314  if (mLockStart == 0 && mLockSize == mSizeInBytes)
315  lockOpt = HBL_DISCARD;
316  else
317  lockOpt = HBL_NORMAL;
318 
319  void *destData = this->lockImpl(
320  mLockStart, mLockSize, lockOpt);
321  // Copy shadow to real
322  memcpy(destData, srcData, mLockSize);
323  this->unlockImpl();
324  mShadowBuffer->unlockImpl();
325  mShadowUpdated = false;
326  }
327  }
328 
330  size_t getSizeInBytes(void) const { return mSizeInBytes; }
332  Usage getUsage(void) const { return mUsage; }
334  bool isSystemMemory(void) const { return mSystemMemory; }
336  bool hasShadowBuffer(void) const { return mUseShadowBuffer; }
338  bool isLocked(void) const {
339  return mIsLocked || (mUseShadowBuffer && mShadowBuffer->isLocked());
340  }
342  void suppressHardwareUpdate(bool suppress) {
343  mSuppressHardwareUpdate = suppress;
344  if (!suppress)
345  _updateFromShadow();
346  }
347 
348 
349 
350 
351 
352  };
357  template <typename T> struct HardwareBufferLockGuard
358  {
360  : pBuf(p)
361  {
362  pData = pBuf->lock(options);
363  }
364  HardwareBufferLockGuard(const T& p, size_t offset, size_t length, HardwareBuffer::LockOptions options)
365  : pBuf(p)
366  {
367  pData = pBuf->lock(offset, length, options);
368  }
370  {
371  pBuf->unlock();
372  }
373 
374  const T& pBuf;
375  void* pData;
376  };
377 }
378 #endif
379 
380 
Ogre::HardwareBuffer::mUsage
Usage mUsage
Definition: OgreHardwareBuffer.h:144
Ogre::HardwareBuffer::copyData
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.
Definition: OgreHardwareBuffer.h:284
Ogre::HardwareBuffer::copyData
virtual void copyData(HardwareBuffer &srcBuffer)
Copy all data from another buffer into this one.
Definition: OgreHardwareBuffer.h:298
Ogre::AllocatedObject
Superclass for all objects that wish to use custom memory allocators when their new / delete operator...
Definition: OgreMemoryAllocatedObject.h:58
Ogre
Definition: OgreAndroidLogListener.h:34
Ogre::HardwareBuffer::mSystemMemory
bool mSystemMemory
Definition: OgreHardwareBuffer.h:148
Ogre::HardwareBuffer::lock
void * lock(LockOptions options)
Lock the entire buffer for (potentially) reading / writing.
Definition: OgreHardwareBuffer.h:220
Ogre::HardwareBuffer::getUsage
Usage getUsage(void) const
Returns the Usage flags with which this buffer was created.
Definition: OgreHardwareBuffer.h:332
OgreException.h
Ogre::HardwareBuffer::getSizeInBytes
size_t getSizeInBytes(void) const
Returns the size of this buffer in bytes.
Definition: OgreHardwareBuffer.h:330
Ogre::HardwareBufferLockGuard::HardwareBufferLockGuard
HardwareBufferLockGuard(const T &p, HardwareBuffer::LockOptions options)
Definition: OgreHardwareBuffer.h:359
Ogre::HardwareBuffer::mLockStart
size_t mLockStart
Definition: OgreHardwareBuffer.h:146
Ogre::HardwareBufferLockGuard::HardwareBufferLockGuard
HardwareBufferLockGuard(const T &p, size_t offset, size_t length, HardwareBuffer::LockOptions options)
Definition: OgreHardwareBuffer.h:364
Ogre::HardwareBuffer::mIsLocked
bool mIsLocked
Definition: OgreHardwareBuffer.h:145
Ogre::HardwareBuffer::unlockImpl
virtual void unlockImpl(void)=0
Internal implementation of unlock()
Ogre::HardwareBuffer::hasShadowBuffer
bool hasShadowBuffer(void) const
Returns whether this buffer has a system memory shadow for quicker reading.
Definition: OgreHardwareBuffer.h:336
Ogre::HardwareBufferLockGuard::~HardwareBufferLockGuard
~HardwareBufferLockGuard()
Definition: OgreHardwareBuffer.h:369
Ogre::HardwareBuffer::HBL_NORMAL
@ HBL_NORMAL
Normal mode, ie allows read/write and contents are preserved.
Definition: OgreHardwareBuffer.h:124
Ogre::HardwareBuffer::mSizeInBytes
size_t mSizeInBytes
Definition: OgreHardwareBuffer.h:143
Ogre::HardwareBuffer::unlock
virtual void unlock(void)
Releases the lock on this buffer.
Definition: OgreHardwareBuffer.h:236
OgrePrerequisites.h
Ogre::HardwareBuffer::~HardwareBuffer
virtual ~HardwareBuffer()
Definition: OgreHardwareBuffer.h:176
Ogre::HardwareBuffer::HBL_NO_OVERWRITE
@ HBL_NO_OVERWRITE
As HBL_DISCARD, except the application guarantees not to overwrite any region of the buffer which has...
Definition: OgreHardwareBuffer.h:137
Ogre::HardwareBuffer::mUseShadowBuffer
bool mUseShadowBuffer
Definition: OgreHardwareBuffer.h:149
Ogre::HardwareBuffer
Abstract class defining common features of hardware buffers.
Definition: OgreHardwareBuffer.h:74
Ogre::HardwareBufferLockGuard::pData
void * pData
Definition: OgreHardwareBuffer.h:375
Ogre::HardwareBuffer::HBL_DISCARD
@ HBL_DISCARD
Discards the entire buffer while locking; this allows optimisation to be performed because synchronis...
Definition: OgreHardwareBuffer.h:129
Ogre::HardwareBufferLockGuard::pBuf
const T & pBuf
Definition: OgreHardwareBuffer.h:374
Ogre::HardwareBuffer::Usage
Usage
Enums describing buffer usage; not mutually exclusive.
Definition: OgreHardwareBuffer.h:79
Ogre::HardwareBuffer::_updateFromShadow
virtual void _updateFromShadow(void)
Updates the real buffer from the shadow buffer, if required.
Definition: OgreHardwareBuffer.h:305
Ogre::HardwareBuffer::lock
virtual void * lock(size_t offset, size_t length, LockOptions options)
Lock the buffer for (potentially) reading / writing.
Definition: OgreHardwareBuffer.h:183
Ogre::HardwareBuffer::LockOptions
LockOptions
Locking options.
Definition: OgreHardwareBuffer.h:121
OGRE_EXCEPT
#define OGRE_EXCEPT(num, desc, src)
Definition: OgreException.h:334
Ogre::Exception::ERR_INVALIDPARAMS
@ ERR_INVALIDPARAMS
Definition: OgreException.h:103
Ogre::HardwareBuffer::HardwareBuffer
HardwareBuffer(Usage usage, bool systemMemory, bool useShadowBuffer)
Constructor, to be called by HardwareBufferManager only.
Definition: OgreHardwareBuffer.h:161
Ogre::HardwareBuffer::isLocked
bool isLocked(void) const
Returns whether or not this buffer is currently locked.
Definition: OgreHardwareBuffer.h:338
Ogre::HardwareBuffer::mLockSize
size_t mLockSize
Definition: OgreHardwareBuffer.h:147
Ogre::HardwareBufferLockGuard
Locking helper.
Definition: OgreHardwareBuffer.h:357
Ogre::HardwareBuffer::suppressHardwareUpdate
void suppressHardwareUpdate(bool suppress)
Pass true to suppress hardware upload of shadow buffer changes.
Definition: OgreHardwareBuffer.h:342
Ogre::HardwareBuffer::isSystemMemory
bool isSystemMemory(void) const
Returns whether this buffer is held in system memory.
Definition: OgreHardwareBuffer.h:334
Ogre::HardwareBuffer::mShadowBuffer
HardwareBuffer * mShadowBuffer
Definition: OgreHardwareBuffer.h:150
Ogre::HardwareBuffer::mShadowUpdated
bool mShadowUpdated
Definition: OgreHardwareBuffer.h:151
Ogre::HardwareBuffer::lockImpl
virtual void * lockImpl(size_t offset, size_t length, LockOptions options)=0
Internal implementation of lock()
Ogre::HardwareBuffer::HBL_READ_ONLY
@ HBL_READ_ONLY
Lock the buffer for reading only.
Definition: OgreHardwareBuffer.h:133
Ogre::HardwareBuffer::mSuppressHardwareUpdate
bool mSuppressHardwareUpdate
Definition: OgreHardwareBuffer.h:152

Copyright © 2012 Torus Knot Software Ltd
Creative Commons License
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Tue Apr 13 2021 08:53:15