source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreMesh.h @ 1809

Revision 1809, 40.5 KB checked in by gumbau, 18 years ago (diff)
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 __Mesh_H__
26#define __Mesh_H__
27
28#include "OgrePrerequisites.h"
29
30#include "OgreResource.h"
31#include "OgreVertexIndexData.h"
32#include "OgreAxisAlignedBox.h"
33#include "OgreVertexBoneAssignment.h"
34#include "OgreIteratorWrappers.h"
35#include "OgreProgressiveMesh.h"
36#include "OgreHardwareVertexBuffer.h"
37#include "OgreSkeleton.h"
38#include "OgreAnimationTrack.h"
39#include "OgrePose.h"
40
41
42namespace Ogre {
43
44
45    /** Resource holding data about 3D mesh.
46        @remarks
47            This class holds the data used to represent a discrete
48            3-dimensional object. Mesh data usually contains more
49            than just vertices and triangle information; it also
50            includes references to materials (and the faces which use them),
51            level-of-detail reduction information, convex hull definition,
52            skeleton/bones information, keyframe animation etc.
53            However, it is important to note the emphasis on the word
54            'discrete' here. This class does not cover the large-scale
55            sprawling geometry found in level / landscape data.
56        @par
57            Multiple world objects can (indeed should) be created from a
58            single mesh object - see the Entity class for more info.
59            The mesh object will have it's own default
60            material properties, but potentially each world instance may
61            wish to customise the materials from the original. When the object
62            is instantiated into a scene node, the mesh material properties
63            will be taken by default but may be changed. These properties
64            are actually held at the SubMesh level since a single mesh may
65            have parts with different materials.
66        @par
67            As described above, because the mesh may have sections of differing
68            material properties, a mesh is inherently a compound contruct,
69            consisting of one or more SubMesh objects.
70            However, it strongly 'owns' it's SubMeshes such that they
71            are loaded / unloaded at the same time. This is contrary to
72            the approach taken to hierarchically related (but loosely owned)
73            scene nodes, where data is loaded / unloaded separately. Note
74            also that mesh sub-sections (when used in an instantiated object)
75            share the same scene node as the parent.
76    */
77
78
79    struct MeshLodUsage;
80
81    class _OgreExport Mesh: public Resource
82    {
83        friend class SubMesh;
84        friend class MeshSerializerImpl;
85        friend class MeshSerializerImpl_v1_2;
86        friend class MeshSerializerImpl_v1_1;
87
88    public:
89                typedef std::vector<Real> LodDistanceList;
90        /// Multimap of vertex bone assignments (orders by vertex index)
91        typedef std::multimap<size_t, VertexBoneAssignment> VertexBoneAssignmentList;
92        typedef MapIterator<VertexBoneAssignmentList> BoneAssignmentIterator;
93        typedef std::vector<SubMesh*> SubMeshList;
94        typedef std::vector<unsigned short> IndexMap;
95
96    protected:
97        /** A list of submeshes which make up this mesh.
98            Each mesh is made up of 1 or more submeshes, which
99            are each based on a single material and can have their
100            own vertex data (they may not - they can share vertex data
101            from the Mesh, depending on preference).
102        */
103        SubMeshList mSubMeshList;
104       
105        /** Internal method for making the space for a 3D texture coord buffer to hold tangents. */
106        void organiseTangentsBuffer(VertexData *vertexData, unsigned short destCoordSet);
107
108    public:
109                /** A hashmap used to store optional SubMesh names.
110                        Translates a name into SubMesh index
111                */
112                typedef HashMap<String, ushort> SubMeshNameMap ;
113
114               
115    protected:
116                SubMeshNameMap mSubMeshNameMap ;
117
118        /// Local bounding box volume
119        AxisAlignedBox mAABB;
120                /// Local bounding sphere radius (centered on object)
121                Real mBoundRadius;
122
123        /// Optional linked skeleton
124        String mSkeletonName;
125        SkeletonPtr mSkeleton;
126
127       
128        VertexBoneAssignmentList mBoneAssignments;
129
130        /// Flag indicating that bone assignments need to be recompiled
131        bool mBoneAssignmentsOutOfDate;
132
133        /** Build the index map between bone index and blend index */
134        void buildIndexMap(const VertexBoneAssignmentList& boneAssignments,
135            IndexMap& boneIndexToBlendIndexMap, IndexMap& blendIndexToBoneIndexMap);
136        /** Compile bone assignments into blend index and weight buffers. */
137        void compileBoneAssignments(const VertexBoneAssignmentList& boneAssignments,
138            unsigned short numBlendWeightsPerVertex,
139            IndexMap& blendIndexToBoneIndexMap,
140            VertexData* targetVertexData);
141
142                bool mIsLodManual;
143                ushort mNumLods;
144                typedef std::vector<MeshLodUsage> MeshLodUsageList;
145                MeshLodUsageList mMeshLodUsageList;
146
147                HardwareBuffer::Usage mVertexBufferUsage;
148                HardwareBuffer::Usage mIndexBufferUsage;
149                bool mVertexBufferShadowBuffer;
150                bool mIndexBufferShadowBuffer;
151
152
153        bool mPreparedForShadowVolumes;
154        bool mEdgeListsBuilt;
155        bool mAutoBuildEdgeLists;
156
157                /// Storage of morph animations, lookup by name
158                typedef std::map<String, Animation*> AnimationList;
159                AnimationList mAnimationsList;
160                /// The vertex animation type associated with the shared vertex data
161                mutable VertexAnimationType mSharedVertexDataAnimationType;
162                /// Do we need to scan animations for animation types?
163                mutable bool mAnimationTypesDirty;
164
165                /// List of available poses for shared and dedicated geometryPoseList
166                PoseList mPoseList;
167
168
169        /// @copydoc Resource::loadImpl
170        void loadImpl(void);
171        /// @copydoc Resource::unloadImpl
172        void unloadImpl(void);
173                /// @copydoc Resource::calculateSize
174                size_t calculateSize(void) const;
175
176
177
178    public:
179        /** Default constructor - used by MeshManager
180            @warning
181                Do not call this method directly.
182        */
183        Mesh(ResourceManager* creator, const String& name, ResourceHandle handle,
184            const String& group, bool isManual = false, ManualResourceLoader* loader = 0);
185        ~Mesh();
186
187                /// @copydoc Resource::load
188                void load(void);
189
190                // NB All methods below are non-virtual since they will be
191        // called in the rendering loop - speed is of the essence.
192
193        /** Creates a new SubMesh.
194            @remarks
195                Method for manually creating geometry for the mesh.
196                Note - use with extreme caution - you must be sure that
197                you have set up the geometry properly.
198        */
199        SubMesh* createSubMesh(void);
200
201                /** Creates a new SubMesh and gives it a name
202                */
203                SubMesh* createSubMesh(const String& name);
204               
205                /** Gives a name to a SubMesh
206                */
207                void nameSubMesh(const String& name, ushort index);
208               
209                /** Gets the index of a submesh with a given name.
210        @remarks
211            Useful if you identify the SubMeshes by name (using nameSubMesh)
212            but wish to have faster repeat access.
213        */
214                ushort _getSubMeshIndex(const String& name) const;
215
216        /** Gets the number of sub meshes which comprise this mesh.
217        */
218        unsigned short getNumSubMeshes(void) const;
219
220        /** Gets a pointer to the submesh indicated by the index.
221        */
222        SubMesh* getSubMesh(unsigned short index) const;
223
224                /** Gets a SubMesh by name
225                */
226                SubMesh* getSubMesh(const String& name) const ;
227
228        typedef VectorIterator<SubMeshList> SubMeshIterator;
229        /// Gets an iterator over the available submeshes
230        SubMeshIterator getSubMeshIterator(void)
231        { return SubMeshIterator(mSubMeshList.begin(), mSubMeshList.end()); }
232     
233        /** Shared vertex data.
234            @remarks
235                This vertex data can be shared among multiple submeshes. SubMeshes may not have
236                their own VertexData, they may share this one.
237            @par
238                The use of shared or non-shared buffers is determined when
239                model data is converted to the OGRE .mesh format.
240        */
241        VertexData *sharedVertexData;
242
243        /** Shared index map for translating blend index to bone index.
244            @remarks
245                This index map can be shared among multiple submeshes. SubMeshes might not have
246                their own IndexMap, they might share this one.
247            @par
248                We collect actually used bones of all bone assignments, and build the
249                blend index in 'packed' form, then the range of the blend index in vertex
250                data VES_BLEND_INDICES element is continuous, with no gaps. Thus, by
251                minimising the world matrix array constants passing to GPU, we can support
252                more bones for a mesh when hardware skinning is used. The hardware skinning
253                support limit is applied to each set of vertex data in the mesh, in other words, the
254                hardware skinning support limit is applied only to the actually used bones of each
255                SubMeshes, not all bones across the entire Mesh.
256            @par
257                Because the blend index is different to the bone index, therefore, we use
258                the index map to translate the blend index to bone index.
259            @par
260                The use of shared or non-shared index map is determined when
261                model data is converted to the OGRE .mesh format.
262        */
263        IndexMap sharedBlendIndexToBoneIndexMap;
264
265        /** Makes a copy of this mesh object and gives it a new name.
266            @remarks
267                This is useful if you want to tweak an existing mesh without affecting the original one. The
268                newly cloned mesh is registered with the MeshManager under the new name.
269            @param newName The name to give the clone
270            @param newGroup Optional name of the new group to assign the clone to;
271                if you leave this blank, the clone will be assigned to the same
272                group as this Mesh.
273        */
274        MeshPtr clone(const String& newName, const String& newGroup = StringUtil::BLANK);
275
276        /** Get the axis-aligned bounding box for this mesh.
277        */
278        const AxisAlignedBox& getBounds(void) const;
279
280                /** Gets the radius of the bounding sphere surrounding this mesh. */
281                Real getBoundingSphereRadius(void) const;
282
283        /** Manually set the bounding box for this Mesh.
284            @remarks
285            Calling this method is required when building manual meshes now, because OGRE can no longer
286            update the bounds for you, because it cannot necessarily read vertex data back from
287            the vertex buffers which this mesh uses (they very well might be write-only, and even
288            if they are not, reading data from a hardware buffer is a bottleneck).
289            @param pad If true, a certain padding will be added to the bounding box to separate it from the mesh
290        */
291        void _setBounds(const AxisAlignedBox& bounds, bool pad = true);
292
293        /** Manually set the bounding radius.
294        @remarks
295            Calling this method is required when building manual meshes now, because OGRE can no longer
296            update the bounds for you, because it cannot necessarily read vertex data back from
297            the vertex buffers which this mesh uses (they very well might be write-only, and even
298            if they are not, reading data from a hardware buffer is a bottleneck).
299        */
300        void _setBoundingSphereRadius(Real radius);
301
302        /** Sets the name of the skeleton this Mesh uses for animation.
303        @remarks
304            Meshes can optionally be assigned a skeleton which can be used to animate
305            the mesh through bone assignments. The default is for the Mesh to use no
306            skeleton. Calling this method with a valid skeleton filename will cause the
307            skeleton to be loaded if it is not already (a single skeleton can be shared
308            by many Mesh objects).
309        @param skelName The name of the .skeleton file to use, or an empty string to use
310            no skeleton
311        */
312        void setSkeletonName(const String& skelName);
313
314        /** Returns true if this Mesh has a linked Skeleton. */
315        bool hasSkeleton(void) const;
316
317                /** Returns whether or not this mesh has some kind of vertex animation.
318                */
319                bool hasVertexAnimation(void) const;
320
321                /** Gets a pointer to any linked Skeleton.
322        @returns Weak reference to the skeleton - copy this if you want to hold a strong pointer.
323        */
324        const SkeletonPtr& getSkeleton(void) const;
325
326        /** Gets the name of any linked Skeleton */
327        const String& getSkeletonName(void) const;
328        /** Initialise an animation set suitable for use with this mesh.
329        @remarks
330            Only recommended for use inside the engine, not by applications.
331        */
332        void _initAnimationState(AnimationStateSet* animSet);
333
334                /** Refresh an animation set suitable for use with this mesh.
335                @remarks
336                Only recommended for use inside the engine, not by applications.
337                */
338                void _refreshAnimationState(AnimationStateSet* animSet);
339        /** Assigns a vertex to a bone with a given weight, for skeletal animation.
340        @remarks   
341            This method is only valid after calling setSkeletonName.
342            Since this is a one-off process there exists only 'addBoneAssignment' and
343            'clearBoneAssignments' methods, no 'editBoneAssignment'. You should not need
344            to modify bone assignments during rendering (only the positions of bones) and OGRE
345            reserves the right to do some internal data reformatting of this information, depending
346            on render system requirements.
347        @par
348            This method is for assigning weights to the shared geometry of the Mesh. To assign
349            weights to the per-SubMesh geometry, see the equivalent methods on SubMesh.
350        */
351        void addBoneAssignment(const VertexBoneAssignment& vertBoneAssign);
352
353        /** Removes all bone assignments for this mesh.
354        @remarks
355            This method is for modifying weights to the shared geometry of the Mesh. To assign
356            weights to the per-SubMesh geometry, see the equivalent methods on SubMesh.
357        */
358        void clearBoneAssignments(void);
359
360        /** Internal notification, used to tell the Mesh which Skeleton to use without loading it.
361        @remarks
362            This is only here for unusual situation where you want to manually set up a
363            Skeleton. Best to let OGRE deal with this, don't call it yourself unless you
364            really know what you're doing.
365        */
366        void _notifySkeleton(SkeletonPtr& pSkel);
367
368
369        /** Gets an iterator for access all bone assignments.
370        */
371        BoneAssignmentIterator getBoneAssignmentIterator(void);
372
373
374                /** Automatically generates lower level of detail versions of this mesh for use
375                        when a simpler version of the model is acceptable for rendering.
376                @remarks
377                        There are 2 ways that you can create level-of-detail (LOD) versions of a mesh;
378                        the first is to call this method, which does fairly extensive calculations to
379                        work out how to simplify the mesh whilst having the minimum affect on the model.
380                        The alternative is to actually create simpler versions of the mesh yourself in
381                        a modelling tool, and having exported them, tell the 'master' mesh to use these
382                        alternative meshes for lower detail versions; this is done by calling the
383                        createManualLodLevel method.
384                @par
385                        As well as creating the lower detail versions of the mesh, this method will
386                        also associate them with depth values. As soon as an object is at least as far
387                        away from the camera as the depth value associated with it's LOD, it will drop
388                        to that level of detail.
389                @par
390                        I recommend calling this method before mesh export, not at runtime.
391                @param lodDistances A list of depth values indicating the distances at which new lods should be
392                        generated.
393                @param reductionMethod The way to determine the number of vertices collapsed per LOD
394                @param reductionValue Meaning depends on reductionMethod, typically either the proportion
395                        of remaining vertices to collapse or a fixed number of vertices.
396                */
397                void generateLodLevels(const LodDistanceList& lodDistances,
398                        ProgressiveMesh::VertexReductionQuota reductionMethod, Real reductionValue);
399
400                /** Returns the number of levels of detail that this mesh supports.
401                @remarks
402                        This number includes the original model.
403                */
404                ushort getNumLodLevels(void) const;
405                /** Gets details of the numbered level of detail entry. */
406                const MeshLodUsage& getLodLevel(ushort index) const;
407                /** Adds a new manual level-of-detail entry to this Mesh.
408                @remarks
409                        As an alternative to generating lower level of detail versions of a mesh, you can
410                        use your own manually modelled meshes as lower level versions. This lets you
411                        have complete control over the LOD, and in addition lets you scale down other
412                        aspects of the model which cannot be done using the generated method; for example,
413                        you could use less detailed materials and / or use less bones in the skeleton if
414                        this is an animated mesh. Therefore for complex models you are likely to be better off
415                        modelling your LODs yourself and using this method, whilst for models with fairly
416                        simple materials and no animation you can just use the generateLodLevels method.
417                @param fromDepth The z value from which this Lod will apply.
418                @param meshName The name of the mesh which will be the lower level detail version.
419                */
420                void createManualLodLevel(Real fromDepth, const String& meshName);
421
422                /** Changes the alternate mesh to use as a manual LOD at the given index.
423                @remarks
424                        Note that the index of a LOD may change if you insert other LODs. If in doubt,
425                        use getLodIndex().
426                @param index The index of the level to be changed
427                @param meshName The name of the mesh which will be the lower level detail version.
428                */
429                void updateManualLodLevel(ushort index, const String& meshName);
430
431                /** Retrieves the level of detail index for the given depth value.
432                */
433                ushort getLodIndex(Real depth) const;
434
435                /** Retrieves the level of detail index for the given squared depth value.
436                @remarks
437                        Internally the lods are stored at squared depths to avoid having to perform
438                        square roots when determining the lod. This method allows you to provide a
439                        squared length depth value to avoid having to do your own square roots.
440                */
441                ushort getLodIndexSquaredDepth(Real squaredDepth) const;
442
443                /** Returns true if this mesh is using manual LOD.
444                @remarks
445                        A mesh can either use automatically generated LOD, or it can use alternative
446                        meshes as provided by an artist. A mesh can only use either all manual LODs
447                        or all generated LODs, not a mixture of both.
448                */
449                bool isLodManual(void) const { return mIsLodManual; }
450
451                /** Internal methods for loading LOD, do not use. */
452                void _setLodInfo(unsigned short numLevels, bool isManual);
453                /** Internal methods for loading LOD, do not use. */
454                void _setLodUsage(unsigned short level, MeshLodUsage& usage);
455                /** Internal methods for loading LOD, do not use. */
456                void _setSubMeshLodFaceList(unsigned short subIdx, unsigned short level, IndexData* facedata);
457
458        /** Removes all LOD data from this Mesh. */
459        void removeLodLevels(void);
460
461                /** Sets the policy for the vertex buffers to be used when loading
462                        this Mesh.
463                @remarks
464                        By default, when loading the Mesh, static, write-only vertex and index buffers
465                        will be used where possible in order to improve rendering performance.
466                        However, such buffers
467                        cannot be manipulated on the fly by CPU code (although shader code can). If you
468                        wish to use the CPU to modify these buffers, you should call this method. Note,
469                        however, that it only takes effect after the Mesh has been reloaded. Note that you
470                        still have the option of manually repacing the buffers in this mesh with your
471                        own if you see fit too, in which case you don't need to call this method since it
472                        only affects buffers created by the mesh itself.
473                @par
474                        You can define the approach to a Mesh by changing the default parameters to
475                        MeshManager::load if you wish; this means the Mesh is loaded with those options
476                        the first time instead of you having to reload the mesh after changing these options.
477                @param usage The usage flags, which by default are
478                        HardwareBuffer::HBU_STATIC_WRITE_ONLY
479                @param shadowBuffer If set to true, the vertex buffers will be created with a
480            system memory shadow buffer. You should set this if you want to be able to
481                        read from the buffer, because reading from a hardware buffer is a no-no.
482                */
483                void setVertexBufferPolicy(HardwareBuffer::Usage usage, bool shadowBuffer = false);
484                /** Sets the policy for the index buffers to be used when loading
485                        this Mesh.
486                @remarks
487                        By default, when loading the Mesh, static, write-only vertex and index buffers
488                        will be used where possible in order to improve rendering performance.
489                        However, such buffers
490                        cannot be manipulated on the fly by CPU code (although shader code can). If you
491                        wish to use the CPU to modify these buffers, you should call this method. Note,
492                        however, that it only takes effect after the Mesh has been reloaded. Note that you
493                        still have the option of manually repacing the buffers in this mesh with your
494                        own if you see fit too, in which case you don't need to call this method since it
495                        only affects buffers created by the mesh itself.
496                @par
497                        You can define the approach to a Mesh by changing the default parameters to
498                        MeshManager::load if you wish; this means the Mesh is loaded with those options
499                        the first time instead of you having to reload the mesh after changing these options.
500                @param usage The usage flags, which by default are
501                        HardwareBuffer::HBU_STATIC_WRITE_ONLY
502                @param shadowBuffer If set to true, the index buffers will be created with a
503            system memory shadow buffer. You should set this if you want to be able to
504                        read from the buffer, because reading from a hardware buffer is a no-no.
505                */
506                void setIndexBufferPolicy(HardwareBuffer::Usage usage, bool shadowBuffer = false);
507        /** Gets the usage setting for this meshes vertex buffers. */
508        HardwareBuffer::Usage getVertexBufferUsage(void) const { return mVertexBufferUsage; }
509        /** Gets the usage setting for this meshes index buffers. */
510        HardwareBuffer::Usage getIndexBufferUsage(void) const { return mIndexBufferUsage; }
511        /** Gets whether or not this meshes vertex buffers are shadowed. */
512        bool isVertexBufferShadowed(void) const { return mVertexBufferShadowBuffer; }
513        /** Gets whether or not this meshes index buffers are shadowed. */
514        bool isIndexBufferShadowed(void) const { return mIndexBufferShadowBuffer; }
515       
516
517        /** Rationalises the passed in bone assignment list.
518        @remarks
519            OGRE supports up to 4 bone assignments per vertex. The reason for this limit
520            is that this is the maximum number of assignments that can be passed into
521            a hardware-assisted blending algorithm. This method identifies where there are
522            more than 4 bone assignments for a given vertex, and eliminates the bone
523            assignments with the lowest weights to reduce to this limit. The remaining
524            weights are then re-balanced to ensure that they sum to 1.0.
525        @param vertexCount The number of vertices.
526        @param assignments The bone assignment list to rationalise. This list will be modified and
527            entries will be removed where the limits are exceeded.
528        @returns The maximum number of bone assignments per vertex found, clamped to [1-4]
529        */
530        unsigned short _rationaliseBoneAssignments(size_t vertexCount, VertexBoneAssignmentList& assignments);
531
532        /** Internal method, be called once to compile bone assignments into geometry buffer.
533        @remarks
534            The OGRE engine calls this method automatically. It compiles the information
535            submitted as bone assignments into a format usable in realtime. It also
536            eliminates excessive bone assignments (max is OGRE_MAX_BLEND_WEIGHTS)
537            and re-normalises the remaining assignments.
538        */
539        void _compileBoneAssignments(void);
540
541        /** Internal method, be called once to update the compiled bone assignments.
542        @remarks
543            The OGRE engine calls this method automatically. It updates the compiled bone
544            assignments if requested.
545        */
546        void _updateCompiledBoneAssignments(void);
547
548        /** This method builds a set of tangent vectors for a given mesh into a 3D texture coordinate buffer.
549        @remarks
550            Tangent vectors are vectors representing the local 'X' axis for a given vertex based
551            on the orientation of the 2D texture on the geometry. They are built from a combination
552            of existing normals, and from the 2D texture coordinates already baked into the model.
553            They can be used for a number of things, but most of all they are useful for
554            vertex and fragment programs, when you wish to arrive at a common space for doing
555            per-pixel calculations.
556        @par
557            The prerequisites for calling this method include that the vertex data used by every
558            SubMesh has both vertex normals and 2D texture coordinates.
559        @param sourceTexCoordSet The texture coordinate index which should be used as the source
560            of 2D texture coordinates, with which to calculate the tangents.
561        @param destTexCoordSet The texture coordinate set which should be used to store the 3D
562            coordinates representing a tangent vector per vertex. If this already exists, it
563            will be overwritten.
564        */
565        void buildTangentVectors(unsigned short sourceTexCoordSet = 0, unsigned short destTexCoordSet = 1);
566
567        /** Ask the mesh to suggest parameters to a future buildTangentVectors call.
568        @remarks
569            This helper method will suggest source and destination texture coordinate sets
570            for a call to buildTangentVectors. It will detect when there are inappropriate
571            conditions (such as multiple geometry sets which don't agree).
572            Moreover, it will return 'true' if it detects that there are aleady 3D
573            coordinates in the mesh, and therefore tangents may have been prepared already.
574        @param outSourceCoordSet Reference to a source texture coordinate set which
575            will be populated
576        @param outDestCoordSet Reference to a destination texture coordinate set which
577            will be populated
578        */
579        bool suggestTangentVectorBuildParams(unsigned short& outSourceCoordSet, unsigned short& outDestCoordSet);
580
581        /** Builds an edge list for this mesh, which can be used for generating a shadow volume
582            among other things.
583        */
584        void buildEdgeList(void);
585        /** Destroys and frees the edge lists this mesh has built. */
586        void freeEdgeList(void);
587
588        /** This method prepares the mesh for generating a renderable shadow volume.
589        @remarks
590            Preparing a mesh to generate a shadow volume involves firstly ensuring that the
591            vertex buffer containing the positions for the mesh is a standalone vertex buffer,
592            with no other components in it. This method will therefore break apart any existing
593            vertex buffers this mesh holds if position is sharing a vertex buffer.
594            Secondly, it will double the size of this vertex buffer so that there are 2 copies of
595            the position data for the mesh. The first half is used for the original, and the second
596            half is used for the 'extruded' version of the mesh. The vertex count of the main
597            VertexData used to render the mesh will remain the same though, so as not to add any
598            overhead to regular rendering of the object.
599            Both copies of the position are required in one buffer because shadow volumes stretch
600            from the original mesh to the extruded version.
601        @par
602            Because shadow volumes are rendered in turn, no additional
603            index buffer space is allocated by this method, a shared index buffer allocated by the
604            shadow rendering algorithm is used for addressing this extended vertex buffer.
605        */
606        void prepareForShadowVolume(void);
607
608        /** Return the edge list for this mesh, building it if required.
609        @remarks
610            You must ensure that the Mesh as been prepared for shadow volume
611            rendering if you intend to use this information for that purpose.
612        @lodIndex The LOD at which to get the edge list, 0 being the highest.
613        */
614        EdgeData* getEdgeList(unsigned int lodIndex = 0);
615
616        /** Return the edge list for this mesh, building it if required.
617        @remarks
618            You must ensure that the Mesh as been prepared for shadow volume
619            rendering if you intend to use this information for that purpose.
620        @lodIndex The LOD at which to get the edge list, 0 being the highest.
621        */
622        const EdgeData* getEdgeList(unsigned int lodIndex = 0) const;
623
624        /** Returns whether this mesh has already had it's geometry prepared for use in
625            rendering shadow volumes. */
626        bool isPreparedForShadowVolumes(void) const { return mPreparedForShadowVolumes; }
627
628                /** Returns whether this mesh has an attached edge list. */
629                bool isEdgeListBuilt(void) const { return mEdgeListsBuilt; }
630
631        /** Performs a software indexed vertex blend, of the kind used for
632            skeletal animation although it can be used for other purposes.
633        @remarks
634        This function is supplied to update vertex data with blends
635        done in software, either because no hardware support is available,
636        or that you need the results of the blend for some other CPU operations.
637        @param sourceVertexData VertexData class containing positions, normals,
638            blend indices and blend weights.
639        @param targetVertexData VertexData class containing target position
640            and normal buffers which will be updated with the blended versions.
641            Note that the layout of the source and target position / normal
642            buffers must be identical, ie they must use the same buffer indexes
643        @param pMatrices Pointer to an array of matrices to be used to blend
644        @param pIndexMap Pointer to an array of indices to translate blend indices
645            in the sourceVertexData to the index of pMatrices
646        @param blendNormals If true, normals are blended as well as positions
647        */
648        static void softwareVertexBlend(const VertexData* sourceVertexData,
649            const VertexData* targetVertexData, const Matrix4* pMatrices,
650            const unsigned short* pIndexMap,
651            bool blendNormals);
652
653        /** Performs a software vertex morph, of the kind used for
654            morph animation although it can be used for other purposes.
655        @remarks
656                        This function will linearly interpolate positions between two
657                        source buffers, into a third buffer.
658        @param t Parametric distance between the start and end buffer positions
659        @param b1 Vertex buffer containing VET_FLOAT3 entries for the start positions
660                @param b2 Vertex buffer containing VET_FLOAT3 entries for the end positions
661                @param targetVertexData VertexData destination; assumed to have a separate position
662                        buffer already bound, and the number of vertices must agree with the
663                        number in start and end
664                */
665        static void softwareVertexMorph(Real t,
666            const HardwareVertexBufferSharedPtr& b1,
667                        const HardwareVertexBufferSharedPtr& b2,
668                        VertexData* targetVertexData);
669
670        /** Performs a software vertex pose blend, of the kind used for
671            morph animation although it can be used for other purposes.
672        @remarks
673                        This function will apply a weighted offset to the positions in the
674                        incoming vertex data (therefore this is a read/write operation, and
675                        if you expect to call it more than once with the same data, then
676                        you would be best to suppress hardware uploads of the position buffer
677                        for the duration)
678        @param weight Parametric weight to scale the offsets by
679                @param vertexOffsetMap Potentially sparse map of vertex index -> offset
680                @param targetVertexData VertexData destination; assumed to have a separate position
681                        buffer already bound, and the number of vertices must agree with the
682                        number in start and end
683                */
684                static void softwareVertexPoseBlend(Real weight,
685                        const std::map<size_t, Vector3>& vertexOffsetMap,
686                        VertexData* targetVertexData);
687        /** Gets a reference to the optional name assignments of the SubMeshes. */
688        const SubMeshNameMap& getSubMeshNameMap(void) const { return mSubMeshNameMap; }
689
690        /** Sets whether or not this Mesh should automatically build edge lists
691            when asked for them, or whether it should never build them if
692            they are not already provided.
693        @remarks
694            This allows you to create meshes which do not have edge lists calculated,
695            because you never want to use them. This value defaults to 'true'
696            for mesh formats which did not include edge data, and 'false' for
697            newer formats, where edge lists are expected to have been generated
698            in advance.
699        */
700        void setAutoBuildEdgeLists(bool autobuild) { mAutoBuildEdgeLists = autobuild; }
701        /** Sets whether or not this Mesh should automatically build edge lists
702            when asked for them, or whether it should never build them if
703            they are not already provided.
704        */
705        bool getAutoBuildEdgeLists(void) const { return mAutoBuildEdgeLists; }
706
707                /** Gets the type of vertex animation the shared vertex data of this mesh supports.
708                */
709                virtual VertexAnimationType getSharedVertexDataAnimationType(void) const;
710
711                /** Creates a new Animation object for vertex animating this mesh.
712        @param name The name of this animation
713        @param length The length of the animation in seconds
714        */
715        virtual Animation* createAnimation(const String& name, Real length);
716
717        /** Returns the named vertex Animation object.
718                @param name The name of the animation
719                */
720        virtual Animation* getAnimation(const String& name) const;
721
722                /** Internal access to the named vertex Animation object - returns null
723                        if it does not exist.
724                @param name The name of the animation
725                */
726                virtual Animation* _getAnimationImpl(const String& name) const;
727
728                /** Returns whether this mesh contains the named vertex animation. */
729                virtual bool hasAnimation(const String& name);
730
731        /** Removes vertex Animation from this mesh. */
732        virtual void removeAnimation(const String& name);
733
734                /** Gets the number of morph animations in this mesh. */
735                virtual unsigned short getNumAnimations(void) const;
736
737                /** Gets a single morph animation by index.
738                */
739                virtual Animation* getAnimation(unsigned short index) const;
740
741                /** Removes all morph Animations from this mesh. */
742                virtual void removeAllAnimations(void);
743                /** Gets a pointer to a vertex data element based on a morph animation
744                        track handle.
745                @remarks
746                        0 means the shared vertex data, 1+ means a submesh vertex data (index+1)
747                */
748                VertexData* getVertexDataByTrackHandle(unsigned short handle);
749        /** Iterates through all submeshes and requests them
750            to apply their texture aliases to the material they use.
751        @remarks
752            The submesh will only apply texture aliases to the material if matching
753            texture alias names are found in the material.  If a match is found, the
754            submesh will automatically clone the original material and then apply its
755            texture to the new material.
756        @par
757            This method is normally called by the protected method loadImpl when a
758            mesh if first loaded.
759        */
760                void updateMaterialForAllSubMeshes(void);
761
762                /** Internal method which, if animation types have not been determined,
763                        scans any vertex animations and determines the type for each set of
764                        vertex data (cannot have 2 different types).
765                */
766                void _determineAnimationTypes(void) const;
767                /** Are the derived animation types out of date? */
768                bool _getAnimationTypesDirty(void) const { return mAnimationTypesDirty; }
769
770                /** Create a new Pose for this mesh or one of its submeshes.
771            @param target The target geometry index; 0 is the shared Mesh geometry, 1+ is the
772                        dedicated SubMesh geometry belonging to submesh index + 1.
773                @param name Name to give the pose, which is optional
774                @returns A new Pose ready for population
775                */
776                Pose* createPose(ushort target, const String& name = StringUtil::BLANK);
777                /** Get the number of poses.*/
778                size_t getPoseCount(void) const { return mPoseList.size(); }
779                /** Retrieve an existing Pose by index.*/
780                Pose* getPose(ushort index);
781                /** Retrieve an existing Pose by name.*/
782                Pose* getPose(const String& name);
783                /** Destroy a pose by index.
784                @note This will invalidate any animation tracks referring to this pose or those after it.
785                */
786                void removePose(ushort index);
787                /** Destroy a pose by name.
788                @note This will invalidate any animation tracks referring to this pose or those after it.
789                */
790                void removePose(const String& name);
791                /** Destroy all poses */
792                void removeAllPoses(void);
793
794                typedef VectorIterator<PoseList> PoseIterator;
795                typedef ConstVectorIterator<PoseList> ConstPoseIterator;
796
797                /** Get an iterator over all the poses defined. */
798                PoseIterator getPoseIterator(void);
799                /** Get an iterator over all the poses defined. */
800                ConstPoseIterator getPoseIterator(void) const;
801                /** Get pose list */
802                const PoseList& getPoseList(void) const;
803
804    };
805
806    /** Specialisation of SharedPtr to allow SharedPtr to be assigned to MeshPtr
807    @note Has to be a subclass since we need operator=.
808    We could templatise this instead of repeating per Resource subclass,
809    except to do so requires a form VC6 does not support i.e.
810    ResourceSubclassPtr<T> : public SharedPtr<T>
811    */
812    class _OgreExport MeshPtr : public SharedPtr<Mesh>
813    {
814    public:
815        MeshPtr() : SharedPtr<Mesh>() {}
816        explicit MeshPtr(Mesh* rep) : SharedPtr<Mesh>(rep) {}
817        MeshPtr(const MeshPtr& r) : SharedPtr<Mesh>(r) {}
818        MeshPtr(const ResourcePtr& r);
819        /// Operator used to convert a ResourcePtr to a MeshPtr
820        MeshPtr& operator=(const ResourcePtr& r);
821    protected:
822        /// Override destroy since we need to delete Mesh after fully defined
823        void destroy(void);
824    };
825
826        /** A way of recording the way each LODs is recorded this Mesh. */
827        struct MeshLodUsage
828        {
829                /// squared Z value from which this LOD will apply
830                Real fromDepthSquared;
831                /// Only relevant if mIsLodManual is true, the name of the alternative mesh to use
832                String manualName;
833                /// Hard link to mesh to avoid looking up each time
834                mutable MeshPtr manualMesh;
835        /// Edge list for this LOD level (may be derived from manual mesh)
836        mutable EdgeData* edgeData;
837        };
838
839
840
841} // namespace
842
843#endif
Note: See TracBrowser for help on using the repository browser.