OGRE  2.0
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 
147  {
148  /* Normal mode,
149  Data is automatically updated in all devices
150  */
151  HBU_DEFAULT = 0x0000,
152  /* Lazy load,
153  Data is updated in the currently active device. Any other device will only be updated once
154  buffer is requested for rendering.
155  */
156  HBU_ON_DEMAND = 0x0001
157  };
158 
159  protected:
160  size_t mSizeInBytes;
162  bool mIsLocked;
163  size_t mLockStart;
164  size_t mLockSize;
171 
173  virtual void* lockImpl(size_t offset, size_t length, LockOptions options) = 0;
175  virtual void unlockImpl(void) = 0;
176 
177  public:
179  HardwareBuffer(Usage usage, bool systemMemory, bool useShadowBuffer)
180  : mSizeInBytes(0), mUsage(usage), mIsLocked(false), mLockStart(0), mLockSize(0), mSystemMemory(systemMemory),
181  mUseShadowBuffer(useShadowBuffer), mShadowBuffer(NULL), mShadowUpdated(false),
182  mSuppressHardwareUpdate(false)
183  {
184  // If use shadow buffer, upgrade to WRITE_ONLY on hardware side
185  if (useShadowBuffer && usage == HBU_DYNAMIC)
186  {
187  mUsage = HBU_DYNAMIC_WRITE_ONLY;
188  }
189  else if (useShadowBuffer && usage == HBU_STATIC)
190  {
191  mUsage = HBU_STATIC_WRITE_ONLY;
192  }
193  }
194  virtual ~HardwareBuffer() {}
201  virtual void* lock(size_t offset, size_t length, LockOptions options, UploadOptions uploadOpt = HBU_DEFAULT)
202  {
203  assert(!isLocked() && "Cannot lock this buffer, it is already locked!");
204 
205  void* ret = NULL;
206  if ((length + offset) > mSizeInBytes)
207  {
209  "Lock request out of bounds.",
210  "HardwareBuffer::lock");
211  }
212  else if (mUseShadowBuffer)
213  {
214  if (options != HBL_READ_ONLY)
215  {
216  // we have to assume a read / write lock so we use the shadow buffer
217  // and tag for sync on unlock()
218  mShadowUpdated = true;
219  }
220 
221  ret = mShadowBuffer->lock(offset, length, options, uploadOpt);
222  }
223  else
224  {
225  // Lock the real buffer if there is no shadow buffer
226  ret = lockImpl(offset, length, options);
227  mIsLocked = true;
228  }
229  mLockStart = offset;
230  mLockSize = length;
231  mLockUploadOption = uploadOpt;
232  return ret;
233  }
234 
239  void* lock(LockOptions options, UploadOptions uploadOpt = HBU_DEFAULT)
240  {
241  return this->lock(0, mSizeInBytes, options, uploadOpt);
242  }
255  virtual void unlock(void)
256  {
257  assert(isLocked() && "Cannot unlock this buffer, it is not locked!");
258 
259  // If we used the shadow buffer this time...
260  if (mUseShadowBuffer && mShadowBuffer->isLocked())
261  {
262  mShadowBuffer->unlock();
263  // Potentially update the 'real' buffer from the shadow buffer
264  _updateFromShadow();
265  }
266  else
267  {
268  // Otherwise, unlock the real one
269  unlockImpl();
270  mIsLocked = false;
271  }
272 
273  }
274 
281  virtual void readData(size_t offset, size_t length, void* pDest) = 0;
290  virtual void writeData(size_t offset, size_t length, const void* pSource,
291  bool discardWholeBuffer = false) = 0;
292 
303  virtual void copyData(HardwareBuffer& srcBuffer, size_t srcOffset,
304  size_t dstOffset, size_t length, bool discardWholeBuffer = false)
305  {
306  const void *srcData = srcBuffer.lock(
307  srcOffset, length, HBL_READ_ONLY);
308  this->writeData(dstOffset, length, srcData, discardWholeBuffer);
309  srcBuffer.unlock();
310  }
311 
317  virtual void copyData(HardwareBuffer& srcBuffer)
318  {
319  size_t sz = std::min(getSizeInBytes(), srcBuffer.getSizeInBytes());
320  copyData(srcBuffer, 0, 0, sz, true);
321  }
322 
324  virtual void _updateFromShadow(void)
325  {
326  if (mUseShadowBuffer && mShadowUpdated && !mSuppressHardwareUpdate)
327  {
328  // Do this manually to avoid locking problems
329  const void *srcData = mShadowBuffer->lockImpl(
330  mLockStart, mLockSize, HBL_READ_ONLY);
331  // Lock with discard if the whole buffer was locked, otherwise normal
332  LockOptions lockOpt;
333  if (mLockStart == 0 && mLockSize == mSizeInBytes)
334  lockOpt = HBL_DISCARD;
335  else
336  lockOpt = HBL_NORMAL;
337 
338  void *destData = this->lockImpl(
339  mLockStart, mLockSize, lockOpt);
340  // Copy shadow to real
341  memcpy(destData, srcData, mLockSize);
342  this->unlockImpl();
343  mShadowBuffer->unlockImpl();
344  mShadowUpdated = false;
345  }
346  }
347 
349  size_t getSizeInBytes(void) const { return mSizeInBytes; }
351  Usage getUsage(void) const { return mUsage; }
353  bool isSystemMemory(void) const { return mSystemMemory; }
355  bool hasShadowBuffer(void) const { return mUseShadowBuffer; }
357  bool isLocked(void) const {
358  return mIsLocked || (mUseShadowBuffer && mShadowBuffer->isLocked());
359  }
361  void suppressHardwareUpdate(bool suppress) {
362  mSuppressHardwareUpdate = suppress;
363  if (!suppress)
364  _updateFromShadow();
365  }
366 
367 
368 
369 
370 
371  };
376  template <typename T> struct HardwareBufferLockGuard
377  {
379  : pBuf(p)
380  {
381  pData = pBuf->lock(options);
382  }
383  HardwareBufferLockGuard(const T& p, size_t offset, size_t length, HardwareBuffer::LockOptions options)
384  : pBuf(p)
385  {
386  pData = pBuf->lock(offset, length, options);
387  }
389  {
390  pBuf->unlock();
391  }
392 
393  const T& pBuf;
394  void* pData;
395  };
396 }
397 #endif
398 
399 
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:255
As HBL_DISCARD, except the application guarantees not to overwrite any region of the buffer which has...
void * lock(LockOptions options, UploadOptions uploadOpt=HBU_DEFAULT)
Lock the entire 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...
HardwareBuffer * mShadowBuffer
LockOptions
Locking options.
virtual void * lock(size_t offset, size_t length, LockOptions options, UploadOptions uploadOpt=HBU_DEFAULT)
Lock the buffer for (potentially) reading / writing.
Normal mode, ie allows read/write and contents are preserved.
bool isLocked(void) const
Returns whether or not this buffer is currently locked.
#define OGRE_EXCEPT(num, desc, src)
Superclass for all objects that wish to use custom memory allocators when their new / delete operator...
const float & min(const float &a, const float &b)
Definition: OgreCommon.h:846
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.
UploadOptions
Device load options The following enum is used to controls how data is loaded to devices in a multi d...
Usage getUsage(void) const
Returns the Usage flags with which this buffer was created.
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.
UploadOptions mLockUploadOption
virtual void _updateFromShadow(void)
Updates the real buffer from the shadow buffer, if required.