source: OGRE/trunk/ogrenew/OgreMain/include/OgreHardwareBufferManager.h @ 657

Revision 657, 15.8 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources

Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef __HardwareBufferManager__
26#define __HardwareBufferManager__
27
28// Precompiler options
29#include "OgrePrerequisites.h"
30
31#include "OgreSingleton.h"
32#include "OgreHardwareVertexBuffer.h"
33#include "OgreHardwareIndexBuffer.h"
34
35
36namespace Ogre {
37
38    /** Abtract interface representing a 'licensee' of a hardware buffer copy.
39    remarks
40        Often it's useful to have temporary buffers which are used for working
41        but are not necessarily needed permanently. However, creating and
42        destroying buffers is expensive, so we need a way to share these
43        working areas, especially those based on existing fixed buffers.
44        This class represents a licensee of one of those temporary buffers,
45        and must be implemented by any user of a temporary buffer if they
46        wish to be notified when the license is expired.
47    */
48    class _OgreExport HardwareBufferLicensee
49    {
50    public:
51        virtual ~HardwareBufferLicensee() { }
52        /** This method is called when the buffer license is expired and is about
53        to be returned to the shared pool. */
54        virtual void licenseExpired(HardwareBuffer* buffer) = 0;
55    };
56
57    /** Structure for recording the use of temporary blend buffers */
58    class _OgreExport TempBlendedBufferInfo : public HardwareBufferLicensee
59    {
60    public:
61        // Pre-blended
62        HardwareVertexBufferSharedPtr srcPositionBuffer;
63        HardwareVertexBufferSharedPtr srcNormalBuffer;
64        // Post-blended
65        HardwareVertexBufferSharedPtr destPositionBuffer;
66        HardwareVertexBufferSharedPtr destNormalBuffer;
67        /// Both positions and normals are contained in the same buffer
68        bool posNormalShareBuffer;
69        unsigned short posBindIndex;
70        unsigned short normBindIndex;
71        bool bindPositions;
72        bool bindNormals;
73
74        ~TempBlendedBufferInfo(void);
75        /// Utility method, checks out temporary copies of src into dest
76        void checkoutTempCopies(bool positions = true, bool normals = true);
77        /// Utility method, binds dest copies into a given VertexData struct
78        void bindTempCopies(VertexData* targetData, bool suppressHardwareUpload);
79        /** Overridden member from HardwareBufferLicensee. */
80        void licenseExpired(HardwareBuffer* buffer);
81    };
82
83
84    /** Abstract singleton class for managing hardware buffers, a concrete instance
85    of this will be created by the RenderSystem. */
86    class _OgreExport HardwareBufferManager : public Singleton<HardwareBufferManager>
87    {
88        friend class HardwareVertexBufferSharedPtr;
89        friend class HardwareIndexBufferSharedPtr;
90    protected:
91        typedef std::list<VertexDeclaration*> VertexDeclarationList;
92                typedef std::list<VertexBufferBinding*> VertexBufferBindingList;
93
94        VertexDeclarationList mVertexDeclarations;
95                VertexBufferBindingList mVertexBufferBindings;
96
97
98        virtual void destroyAllDeclarations(void);
99        virtual void destroyAllBindings(void);
100
101    public:
102
103        enum BufferLicenseType
104        {
105            /// Licensee will only release buffer when it says so
106            BLT_MANUAL_RELEASE,
107            /// Licensee can have license revoked
108            BLT_AUTOMATIC_RELEASE
109        };
110
111    protected:
112        /** Struct holding details of a license to use a temporary shared buffer. */
113        class _OgrePrivate VertexBufferLicense
114        {
115        public:
116            HardwareVertexBuffer* originalBufferPtr;
117            BufferLicenseType licenseType;
118            HardwareVertexBufferSharedPtr buffer;
119            HardwareBufferLicensee* licensee;
120            VertexBufferLicense(
121                HardwareVertexBuffer* orig,
122                BufferLicenseType ltype,
123                HardwareVertexBufferSharedPtr buf,
124                HardwareBufferLicensee* lic)
125                : originalBufferPtr(orig), licenseType(ltype), buffer(buf), licensee(lic) {}
126
127        };
128
129        /// List of free temporary vertex buffers
130        typedef std::vector<HardwareVertexBufferSharedPtr> FreeTemporaryVertexBufferList;
131        /// Map from original buffer to list of temporary buffers
132        typedef std::map<HardwareVertexBuffer*, FreeTemporaryVertexBufferList*> FreeTemporaryVertexBufferMap;
133        /// Map of current available temp buffers
134        FreeTemporaryVertexBufferMap mFreeTempVertexBufferMap;
135        /// List of currently licensed temp buffers
136        typedef std::vector<VertexBufferLicense> TemporaryVertexBufferLicenseList;
137        /// List of currently licensed temp buffers
138        TemporaryVertexBufferLicenseList mTempVertexBufferLicenses;
139
140                typedef std::set<HardwareVertexBuffer*> VertexBufferList;
141                typedef std::set<HardwareIndexBuffer*> IndexBufferList;
142                VertexBufferList mVertexBuffers;
143                IndexBufferList mIndexBuffers;
144
145
146        /// Creates  a new buffer as a copy of the source, does not copy data
147        HardwareVertexBufferSharedPtr makeBufferCopy(
148            const HardwareVertexBufferSharedPtr& source,
149            HardwareBuffer::Usage usage, bool useShadowBuffer);
150
151    public:
152        HardwareBufferManager();
153        virtual ~HardwareBufferManager();
154                /** Create a hardware vertex buffer.
155        @remarks
156            This method creates a new vertex buffer; this will act as a source of geometry
157            data for rendering objects. Note that because the meaning of the contents of
158            the vertex buffer depends on the usage, this method does not specify a
159            vertex format; the user of this buffer can actually insert whatever data
160            they wish, in any format. However, in order to use this with a RenderOperation,
161            the data in this vertex buffer will have to be associated with a semantic element
162            of the rendering pipeline, e.g. a position, or texture coordinates. This is done
163            using the VertexDeclaration class, which itself contains VertexElement structures
164            referring to the source data.
165        @remarks Note that because vertex buffers can be shared, they are reference
166            counted so you do not need to worry about destroying themm this will be done
167            automatically.
168        @param vertexSize The size in bytes of each vertex in this buffer; you must calculate
169            this based on the kind of data you expect to populate this buffer with.
170        @param numVerts The number of vertices in this buffer.
171        @param usage One or more members of the HardwareBuffer::Usage enumeration; you are
172            strongly advised to use HBU_STATIC_WRITE_ONLY wherever possible, if you need to
173            update regularly, consider HBU_DYNAMIC_WRITE_ONLY and useShadowBuffer=true.
174                @param useShadowBuffer If set to true, this buffer will be 'shadowed' by one stored in
175            system memory rather than GPU or AGP memory. You should set this flag if you intend
176            to read data back from the vertex buffer, because reading data from a buffer
177                        in the GPU or AGP memory is very expensive, and is in fact impossible if you
178            specify HBU_WRITE_ONLY for the main buffer. If you use this option, all
179            reads and writes will be done to the shadow buffer, and the shadow buffer will
180            be synchronised with the real buffer at an appropriate time.
181        */
182                virtual HardwareVertexBufferSharedPtr
183            createVertexBuffer(size_t vertexSize, size_t numVerts, HardwareBuffer::Usage usage,
184                        bool useShadowBuffer = false) = 0;
185                /** Create a hardware index buffer.
186        @remarks Note that because buffers can be shared, they are reference
187            counted so you do not need to worry about destroying themm this will be done
188            automatically.
189                @param itype The type in index, either 16- or 32-bit, depending on how many vertices
190                        you need to be able to address
191                @param numIndexes The number of indexes in the buffer
192        @param usage One or more members of the HardwareBuffer::Usage enumeration.
193                @param useShadowBuffer If set to true, this buffer will be 'shadowed' by one stored in
194            system memory rather than GPU or AGP memory. You should set this flag if you intend
195            to read data back from the index buffer, because reading data from a buffer
196                        in the GPU or AGP memory is very expensive, and is in fact impossible if you
197            specify HBU_WRITE_ONLY for the main buffer. If you use this option, all
198            reads and writes will be done to the shadow buffer, and the shadow buffer will
199            be synchronised with the real buffer at an appropriate time.
200        */
201                virtual HardwareIndexBufferSharedPtr
202            createIndexBuffer(HardwareIndexBuffer::IndexType itype, size_t numIndexes,
203                        HardwareBuffer::Usage usage, bool useShadowBuffer = false) = 0;
204        /// Creates a vertex declaration, may be overridden by certain rendering APIs
205        virtual VertexDeclaration* createVertexDeclaration(void);
206        /// Destroys a vertex declaration, may be overridden by certain rendering APIs
207        virtual void destroyVertexDeclaration(VertexDeclaration* decl);
208
209                /** Creates a new VertexBufferBinding. */
210                virtual VertexBufferBinding* createVertexBufferBinding(void);
211                /** Destroys a VertexBufferBinding. */
212                virtual void destroyVertexBufferBinding(VertexBufferBinding* binding);
213
214                /** Registers a vertex buffer as a copy of another.
215                @remarks
216                        This is useful for registering an existing buffer as a temporary buffer
217                        which can be allocated just like a copy.
218                */
219                virtual void registerVertexBufferSourceAndCopy(
220                        const HardwareVertexBufferSharedPtr& sourceBuffer,
221                        const HardwareVertexBufferSharedPtr& copy);
222
223        /** Allocates a copy of a given vertex buffer.
224        @remarks
225            This method allocates a temporary copy of an existing vertex buffer.
226            This buffer is subsequently stored and can be made available for
227            other purposes later without incurring the cost of construction /
228            destruction.
229        @param sourceBuffer The source buffer to use as a copy
230        @param licenseType The type of license required on this buffer - automatic
231            release causes this class to release licenses every frame so that
232            they can be reallocated anew.
233        @param licensee Pointer back to the class requesting the copy, which must
234            implement HardwareBufferLicense in order to be notified when the license
235            expires.
236        @param copyData If true, the current data is copied as well as the
237            structure of the buffer
238        */
239        virtual HardwareVertexBufferSharedPtr allocateVertexBufferCopy(
240            const HardwareVertexBufferSharedPtr& sourceBuffer,
241            BufferLicenseType licenseType,
242            HardwareBufferLicensee* licensee,
243            bool copyData = false);
244        /** Manually release a vertex buffer copy for others to subsequently use.
245        @remarks
246            Only required if the original call to allocateVertexBufferCopy
247            included a licenseType of BLT_MANUAL_RELEASE.
248        @param bufferCopy The buffer copy. The caller is expected to delete
249            or at least no longer use this reference, since another user may
250            well begin to modify the contents of the buffer.
251        */
252        virtual void releaseVertexBufferCopy(
253            const HardwareVertexBufferSharedPtr& bufferCopy);
254
255        /** Internal method for releasing all temporary buffers which have been
256           allocated using BLT_AUTOMATIC_RELEASE; is called by OGRE. */
257        virtual void _releaseBufferCopies(void);
258
259        /** Internal method that forces the release of copies of a given buffer.
260        @remarks
261            This usually means that the buffer which the copies are based on has
262            been changed in some fundamental way, and the owner of the original
263            wishes to make that known so that new copies will reflect the
264            changes.
265        @param sourceBuffer the source buffer as a shared pointer.  Any buffer copies created from the source buffer
266            are deleted.
267        */
268        virtual void _forceReleaseBufferCopies(
269            const HardwareVertexBufferSharedPtr& sourceBuffer)
270        { _forceReleaseBufferCopies(sourceBuffer.get()); }
271
272        /** Internal method that forces the release of copies of a given buffer.
273        @remarks
274            This usually means that the buffer which the copies are based on has
275            been changed in some fundamental way, and the owner of the original
276            wishes to make that known so that new copies will reflect the
277            changes.
278        @param sourceBuffer the source buffer as a pointer.  Any buffer copies created from the source buffer
279            are deleted.
280        */
281        void _forceReleaseBufferCopies(HardwareVertexBuffer* sourceBuffer);
282
283                /// Notification that a hardware vertex buffer has been destroyed
284                void _notifyVertexBufferDestroyed(HardwareVertexBuffer* buf);
285                /// Notification that a hardware index buffer has been destroyed
286                void _notifyIndexBufferDestroyed(HardwareIndexBuffer* buf);
287
288        /** Override standard Singleton retrieval.
289        @remarks
290        Why do we do this? Well, it's because the Singleton
291        implementation is in a .h file, which means it gets compiled
292        into anybody who includes it. This is needed for the
293        Singleton template to work, but we actually only want it
294        compiled into the implementation of the class based on the
295        Singleton, not all of them. If we don't change this, we get
296        link errors when trying to use the Singleton-based class from
297        an outside dll.
298        @par
299        This method just delegates to the template version anyway,
300        but the implementation stays in this single compilation unit,
301        preventing link errors.
302        */
303        static HardwareBufferManager& getSingleton(void);
304        /** Override standard Singleton retrieval.
305        @remarks
306        Why do we do this? Well, it's because the Singleton
307        implementation is in a .h file, which means it gets compiled
308        into anybody who includes it. This is needed for the
309        Singleton template to work, but we actually only want it
310        compiled into the implementation of the class based on the
311        Singleton, not all of them. If we don't change this, we get
312        link errors when trying to use the Singleton-based class from
313        an outside dll.
314        @par
315        This method just delegates to the template version anyway,
316        but the implementation stays in this single compilation unit,
317        preventing link errors.
318        */
319        static HardwareBufferManager* getSingletonPtr(void);
320           
321    };
322
323}
324
325#endif
326
Note: See TracBrowser for help on using the repository browser.