[1] | 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-2006 Torus Knot Software Ltd |
---|
| 8 | Also see acknowledgements in Readme.html |
---|
| 9 | |
---|
| 10 | This program is free software; you can redistribute it and/or modify it under |
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software |
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later |
---|
| 13 | version. |
---|
| 14 | |
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT |
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. |
---|
| 18 | |
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with |
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple |
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to |
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt. |
---|
| 23 | |
---|
| 24 | You may alternatively use this source under the terms of a specific version of |
---|
| 25 | the OGRE Unrestricted License provided you have obtained such a license from |
---|
| 26 | Torus Knot Software Ltd. |
---|
| 27 | ----------------------------------------------------------------------------- |
---|
| 28 | */ |
---|
| 29 | #ifndef __HardwareBuffer__ |
---|
| 30 | #define __HardwareBuffer__ |
---|
| 31 | |
---|
| 32 | // Precompiler options |
---|
| 33 | #include "OgrePrerequisites.h" |
---|
| 34 | |
---|
| 35 | namespace Ogre { |
---|
| 36 | |
---|
| 37 | /** Abstract class defining common features of hardware buffers. |
---|
| 38 | @remarks |
---|
| 39 | A 'hardware buffer' is any area of memory held outside of core system ram, |
---|
| 40 | and in our case refers mostly to video ram, although in theory this class |
---|
| 41 | could be used with other memory areas such as sound card memory, custom |
---|
| 42 | coprocessor memory etc. |
---|
| 43 | @par |
---|
| 44 | This reflects the fact that memory held outside of main system RAM must |
---|
| 45 | be interacted with in a more formal fashion in order to promote |
---|
| 46 | cooperative and optimal usage of the buffers between the various |
---|
| 47 | processing units which manipulate them. |
---|
| 48 | @par |
---|
| 49 | This abstract class defines the core interface which is common to all |
---|
| 50 | buffers, whether it be vertex buffers, index buffers, texture memory |
---|
| 51 | or framebuffer memory etc. |
---|
| 52 | @par |
---|
| 53 | Buffers have the ability to be 'shadowed' in system memory, this is because |
---|
| 54 | the kinds of access allowed on hardware buffers is not always as flexible as |
---|
| 55 | that allowed for areas of system memory - for example it is often either |
---|
| 56 | impossible, or extremely undesirable from a performance standpoint to read from |
---|
| 57 | a hardware buffer; when writing to hardware buffers, you should also write every |
---|
| 58 | byte and do it sequentially. In situations where this is too restrictive, |
---|
| 59 | it is possible to create a hardware, write-only buffer (the most efficient kind) |
---|
| 60 | and to back it with a system memory 'shadow' copy which can be read and updated arbitrarily. |
---|
| 61 | Ogre handles synchronising this buffer with the real hardware buffer (which should still be |
---|
| 62 | created with the HBU_DYNAMIC flag if you intend to update it very frequently). Whilst this |
---|
| 63 | approach does have it's own costs, such as increased memory overhead, these costs can |
---|
| 64 | often be outweighed by the performance benefits of using a more hardware efficient buffer. |
---|
| 65 | You should look for the 'useShadowBuffer' parameter on the creation methods used to create |
---|
| 66 | the buffer of the type you require (see HardwareBufferManager) to enable this feature. |
---|
| 67 | */ |
---|
| 68 | class _OgreExport HardwareBuffer |
---|
| 69 | { |
---|
| 70 | |
---|
| 71 | public: |
---|
| 72 | /// Enums describing buffer usage; not mutually exclusive |
---|
| 73 | enum Usage |
---|
| 74 | { |
---|
| 75 | /** Static buffer which the application rarely modifies once created. Modifying |
---|
| 76 | the contents of this buffer will involve a performance hit. |
---|
| 77 | */ |
---|
| 78 | HBU_STATIC = 1, |
---|
| 79 | /** Indicates the application would like to modify this buffer with the CPU |
---|
| 80 | fairly often. |
---|
| 81 | Buffers created with this flag will typically end up in AGP memory rather |
---|
| 82 | than video memory. |
---|
| 83 | */ |
---|
| 84 | HBU_DYNAMIC = 2, |
---|
| 85 | /** Indicates the application will never read the contents of the buffer back, |
---|
| 86 | it will only ever write data. Locking a buffer with this flag will ALWAYS |
---|
| 87 | return a pointer to new, blank memory rather than the memory associated |
---|
| 88 | with the contents of the buffer; this avoids DMA stalls because you can |
---|
| 89 | write to a new memory area while the previous one is being used. |
---|
| 90 | */ |
---|
| 91 | HBU_WRITE_ONLY = 4, |
---|
| 92 | /** Indicates that the application will be refilling the contents |
---|
| 93 | of the buffer regularly (not just updating, but generating the |
---|
| 94 | contents from scratch), and therefore does not mind if the contents |
---|
| 95 | of the buffer are lost somehow and need to be recreated. This |
---|
| 96 | allows and additional level of optimisation on the buffer. |
---|
| 97 | This option only really makes sense when combined with |
---|
| 98 | HBU_DYNAMIC_WRITE_ONLY. |
---|
| 99 | */ |
---|
| 100 | HBU_DISCARDABLE = 8, |
---|
| 101 | /// Combination of HBU_STATIC and HBU_WRITE_ONLY |
---|
| 102 | HBU_STATIC_WRITE_ONLY = 5, |
---|
| 103 | /** Combination of HBU_DYNAMIC and HBU_WRITE_ONLY. If you use |
---|
| 104 | this, strongly consider using HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE |
---|
| 105 | instead if you update the entire contents of the buffer very |
---|
| 106 | regularly. |
---|
| 107 | */ |
---|
| 108 | HBU_DYNAMIC_WRITE_ONLY = 6, |
---|
| 109 | /// Combination of HBU_DYNAMIC, HBU_WRITE_ONLY and HBU_DISCARDABLE |
---|
| 110 | HBU_DYNAMIC_WRITE_ONLY_DISCARDABLE = 14 |
---|
| 111 | |
---|
| 112 | |
---|
| 113 | }; |
---|
| 114 | /// Locking options |
---|
| 115 | enum LockOptions |
---|
| 116 | { |
---|
| 117 | /** Normal mode, ie allows read/write and contents are preserved. */ |
---|
| 118 | HBL_NORMAL, |
---|
| 119 | /** Discards the <em>entire</em> buffer while locking; this allows optimisation to be |
---|
| 120 | performed because synchronisation issues are relaxed. Only allowed on buffers |
---|
| 121 | created with the HBU_DYNAMIC flag. |
---|
| 122 | */ |
---|
| 123 | HBL_DISCARD, |
---|
| 124 | /** Lock the buffer for reading only. Not allowed in buffers which are created with HBU_WRITE_ONLY. |
---|
| 125 | Mandatory on statuc buffers, ie those created without the HBU_DYNAMIC flag. |
---|
| 126 | */ |
---|
| 127 | HBL_READ_ONLY, |
---|
| 128 | /** As HBL_NORMAL, except the application guarantees not to overwrite any |
---|
| 129 | region of the buffer which has already been used in this frame, can allow |
---|
| 130 | some optimisation on some APIs. */ |
---|
| 131 | HBL_NO_OVERWRITE |
---|
| 132 | |
---|
| 133 | }; |
---|
| 134 | protected: |
---|
| 135 | size_t mSizeInBytes; |
---|
| 136 | Usage mUsage; |
---|
| 137 | bool mIsLocked; |
---|
| 138 | size_t mLockStart; |
---|
| 139 | size_t mLockSize; |
---|
| 140 | bool mSystemMemory; |
---|
| 141 | bool mUseShadowBuffer; |
---|
| 142 | HardwareBuffer* mpShadowBuffer; |
---|
| 143 | bool mShadowUpdated; |
---|
| 144 | bool mSuppressHardwareUpdate; |
---|
| 145 | |
---|
| 146 | /// Internal implementation of lock() |
---|
| 147 | virtual void* lockImpl(size_t offset, size_t length, LockOptions options) = 0; |
---|
| 148 | /// Internal implementation of unlock() |
---|
| 149 | virtual void unlockImpl(void) = 0; |
---|
| 150 | |
---|
| 151 | public: |
---|
| 152 | /// Constructor, to be called by HardwareBufferManager only |
---|
| 153 | HardwareBuffer(Usage usage, bool systemMemory, bool useShadowBuffer) |
---|
| 154 | : mUsage(usage), mIsLocked(false), mSystemMemory(systemMemory), |
---|
| 155 | mUseShadowBuffer(useShadowBuffer), mpShadowBuffer(NULL), mShadowUpdated(false), |
---|
| 156 | mSuppressHardwareUpdate(false) |
---|
| 157 | { |
---|
| 158 | // If use shadow buffer, upgrade to WRITE_ONLY on hardware side |
---|
| 159 | if (useShadowBuffer && usage == HBU_DYNAMIC) |
---|
| 160 | { |
---|
| 161 | mUsage = HBU_DYNAMIC_WRITE_ONLY; |
---|
| 162 | } |
---|
| 163 | else if (useShadowBuffer && usage == HBU_STATIC) |
---|
| 164 | { |
---|
| 165 | mUsage = HBU_STATIC_WRITE_ONLY; |
---|
| 166 | } |
---|
| 167 | } |
---|
| 168 | virtual ~HardwareBuffer() {} |
---|
| 169 | /** Lock the buffer for (potentially) reading / writing. |
---|
| 170 | @param offset The byte offset from the start of the buffer to lock |
---|
| 171 | @param length The size of the area to lock, in bytes |
---|
| 172 | @param options Locking options |
---|
| 173 | @returns Pointer to the locked memory |
---|
| 174 | */ |
---|
| 175 | virtual void* lock(size_t offset, size_t length, LockOptions options) |
---|
| 176 | { |
---|
| 177 | assert(!isLocked() && "Cannot lock this buffer, it is already locked!"); |
---|
| 178 | void* ret; |
---|
| 179 | if (mUseShadowBuffer) |
---|
| 180 | { |
---|
| 181 | if (options != HBL_READ_ONLY) |
---|
| 182 | { |
---|
| 183 | // we have to assume a read / write lock so we use the shadow buffer |
---|
| 184 | // and tag for sync on unlock() |
---|
| 185 | mShadowUpdated = true; |
---|
| 186 | } |
---|
| 187 | |
---|
| 188 | ret = mpShadowBuffer->lock(offset, length, options); |
---|
| 189 | } |
---|
| 190 | else |
---|
| 191 | { |
---|
| 192 | // Lock the real buffer if there is no shadow buffer |
---|
| 193 | ret = lockImpl(offset, length, options); |
---|
| 194 | mIsLocked = true; |
---|
| 195 | } |
---|
| 196 | mLockStart = offset; |
---|
| 197 | mLockSize = length; |
---|
| 198 | return ret; |
---|
| 199 | } |
---|
| 200 | |
---|
| 201 | /** Lock the entire buffer for (potentially) reading / writing. |
---|
| 202 | @param options Locking options |
---|
| 203 | @returns Pointer to the locked memory |
---|
| 204 | */ |
---|
| 205 | void* lock(LockOptions options) |
---|
| 206 | { |
---|
| 207 | return this->lock(0, mSizeInBytes, options); |
---|
| 208 | } |
---|
| 209 | /** Releases the lock on this buffer. |
---|
| 210 | @remarks |
---|
| 211 | Locking and unlocking a buffer can, in some rare circumstances such as |
---|
| 212 | switching video modes whilst the buffer is locked, corrupt the |
---|
| 213 | contents of a buffer. This is pretty rare, but if it occurs, |
---|
| 214 | this method will throw an exception, meaning you |
---|
| 215 | must re-upload the data. |
---|
| 216 | @par |
---|
| 217 | Note that using the 'read' and 'write' forms of updating the buffer does not |
---|
| 218 | suffer from this problem, so if you want to be 100% sure your |
---|
| 219 | data will not be lost, use the 'read' and 'write' forms instead. |
---|
| 220 | */ |
---|
| 221 | virtual void unlock(void) |
---|
| 222 | { |
---|
| 223 | assert(isLocked() && "Cannot unlock this buffer, it is not locked!"); |
---|
| 224 | |
---|
| 225 | // If we used the shadow buffer this time... |
---|
| 226 | if (mUseShadowBuffer && mpShadowBuffer->isLocked()) |
---|
| 227 | { |
---|
| 228 | mpShadowBuffer->unlock(); |
---|
| 229 | // Potentially update the 'real' buffer from the shadow buffer |
---|
| 230 | _updateFromShadow(); |
---|
| 231 | } |
---|
| 232 | else |
---|
| 233 | { |
---|
| 234 | // Otherwise, unlock the real one |
---|
| 235 | unlockImpl(); |
---|
| 236 | mIsLocked = false; |
---|
| 237 | } |
---|
| 238 | |
---|
| 239 | } |
---|
| 240 | |
---|
| 241 | /** Reads data from the buffer and places it in the memory pointed to by pDest. |
---|
| 242 | @param offset The byte offset from the start of the buffer to read |
---|
| 243 | @param length The size of the area to read, in bytes |
---|
| 244 | @param pDest The area of memory in which to place the data, must be large enough to |
---|
| 245 | accommodate the data! |
---|
| 246 | */ |
---|
| 247 | virtual void readData(size_t offset, size_t length, void* pDest) = 0; |
---|
| 248 | /** Writes data to the buffer from an area of system memory; note that you must |
---|
| 249 | ensure that your buffer is big enough. |
---|
| 250 | @param offset The byte offset from the start of the buffer to start writing |
---|
| 251 | @param length The size of the data to write to, in bytes |
---|
| 252 | @param pSource The source of the data to be written |
---|
| 253 | @param discardWholeBuffer If true, this allows the driver to discard the entire buffer when writing, |
---|
| 254 | such that DMA stalls can be avoided; use if you can. |
---|
| 255 | */ |
---|
| 256 | virtual void writeData(size_t offset, size_t length, const void* pSource, |
---|
| 257 | bool discardWholeBuffer = false) = 0; |
---|
| 258 | |
---|
| 259 | /** Copy data from another buffer into this one. |
---|
| 260 | @remarks |
---|
| 261 | Note that the source buffer must not be created with the |
---|
| 262 | usage HBU_WRITE_ONLY otherwise this will fail. |
---|
| 263 | @param srcBuffer The buffer from which to read the copied data |
---|
| 264 | @param srcOffset Offset in the source buffer at which to start reading |
---|
| 265 | @param dstOffset Offset in the destination buffer to start writing |
---|
| 266 | @param length Length of the data to copy, in bytes. |
---|
| 267 | @param discardWholeBuffer If true, will discard the entire contents of this buffer before copying |
---|
| 268 | */ |
---|
| 269 | virtual void copyData(HardwareBuffer& srcBuffer, size_t srcOffset, |
---|
| 270 | size_t dstOffset, size_t length, bool discardWholeBuffer = false) |
---|
| 271 | { |
---|
| 272 | const void *srcData = srcBuffer.lock( |
---|
| 273 | srcOffset, length, HBL_READ_ONLY); |
---|
| 274 | this->writeData(dstOffset, length, srcData, discardWholeBuffer); |
---|
| 275 | srcBuffer.unlock(); |
---|
| 276 | } |
---|
| 277 | |
---|
| 278 | /// Updates the real buffer from the shadow buffer, if required |
---|
| 279 | virtual void _updateFromShadow(void) |
---|
| 280 | { |
---|
| 281 | if (mUseShadowBuffer && mShadowUpdated && !mSuppressHardwareUpdate) |
---|
| 282 | { |
---|
| 283 | // Do this manually to avoid locking problems |
---|
| 284 | const void *srcData = mpShadowBuffer->lockImpl( |
---|
| 285 | mLockStart, mLockSize, HBL_READ_ONLY); |
---|
| 286 | // Lock with discard if the whole buffer was locked, otherwise normal |
---|
| 287 | LockOptions lockOpt; |
---|
| 288 | if (mLockStart == 0 && mLockSize == mSizeInBytes) |
---|
| 289 | lockOpt = HBL_DISCARD; |
---|
| 290 | else |
---|
| 291 | lockOpt = HBL_NORMAL; |
---|
| 292 | |
---|
| 293 | void *destData = this->lockImpl( |
---|
| 294 | mLockStart, mLockSize, lockOpt); |
---|
| 295 | // Copy shadow to real |
---|
| 296 | memcpy(destData, srcData, mLockSize); |
---|
| 297 | this->unlockImpl(); |
---|
| 298 | mpShadowBuffer->unlockImpl(); |
---|
| 299 | mShadowUpdated = false; |
---|
| 300 | } |
---|
| 301 | } |
---|
| 302 | |
---|
| 303 | /// Returns the size of this buffer in bytes |
---|
| 304 | size_t getSizeInBytes(void) const { return mSizeInBytes; } |
---|
| 305 | /// Returns the Usage flags with which this buffer was created |
---|
| 306 | Usage getUsage(void) const { return mUsage; } |
---|
| 307 | /// Returns whether this buffer is held in system memory |
---|
| 308 | bool isSystemMemory(void) const { return mSystemMemory; } |
---|
| 309 | /// Returns whether this buffer has a system memory shadow for quicker reading |
---|
| 310 | bool hasShadowBuffer(void) const { return mUseShadowBuffer; } |
---|
| 311 | /// Returns whether or not this buffer is currently locked. |
---|
| 312 | bool isLocked(void) const { |
---|
| 313 | return mIsLocked || (mUseShadowBuffer && mpShadowBuffer->isLocked()); |
---|
| 314 | } |
---|
| 315 | /// Pass true to suppress hardware upload of shadow buffer changes |
---|
| 316 | void suppressHardwareUpdate(bool suppress) { |
---|
| 317 | mSuppressHardwareUpdate = suppress; |
---|
| 318 | if (!suppress) |
---|
| 319 | _updateFromShadow(); |
---|
| 320 | } |
---|
| 321 | |
---|
| 322 | |
---|
| 323 | |
---|
| 324 | |
---|
| 325 | |
---|
| 326 | }; |
---|
| 327 | } |
---|
| 328 | #endif |
---|
| 329 | |
---|
| 330 | |
---|