OGRE  1.9
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
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-2014 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 
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 
size_t getSizeInBytes(void) const
Returns the size of this buffer in bytes.
HardwareBufferLockGuard(const T &p, HardwareBuffer::LockOptions options)
HardwareBufferLockGuard(const T &p, size_t offset, size_t length, HardwareBuffer::LockOptions options)
#define _OgreExport
Definition: OgrePlatform.h:260
As HBL_DISCARD, except the application guarantees not to overwrite any region of the buffer which has...
virtual void * lock(size_t offset, size_t length, LockOptions options)
Lock the buffer for (potentially) reading / writing.
HardwareBuffer(Usage usage, bool systemMemory, bool useShadowBuffer)
Constructor, to be called by HardwareBufferManager only.
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.
Discards the entire buffer while locking; this allows optimisation to be performed because synchronis...
void * lock(LockOptions options)
Lock the entire buffer for (potentially) reading / writing.
HardwareBuffer * mShadowBuffer
LockOptions
Locking options.
Normal mode, ie allows read/write and contents are preserved.
bool isLocked(void) const
Returns whether or not this buffer is currently locked.
Superclass for all objects that wish to use custom memory allocators when their new / delete operator...
void suppressHardwareUpdate(bool suppress)
Pass true to suppress hardware upload of shadow buffer changes.
bool hasShadowBuffer(void) const
Returns whether this buffer has a system memory shadow for quicker reading.
Usage
Enums describing buffer usage; not mutually exclusive.
Usage getUsage(void) const
Returns the Usage flags with which this buffer was created.
#define OGRE_EXCEPT(code, desc, src)
virtual void unlock(void)
Releases the lock on this buffer.
Lock the buffer for reading only.
virtual void copyData(HardwareBuffer &srcBuffer)
Copy all data from another buffer into this one.
Abstract class defining common features of hardware buffers.
bool isSystemMemory(void) const
Returns whether this buffer is held in system memory.
virtual void _updateFromShadow(void)
Updates the real buffer from the shadow buffer, if required.