source: OGRE/trunk/ogre_changes/obsolete/OgreMain/include/OgreRenderable.h @ 193

Revision 193, 13.0 KB checked in by mattausch, 19 years ago (diff)

changed to ogre 103
added readme

Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://ogre.sourceforge.net/
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 __Renderable_H__
26#define __Renderable_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreCommon.h"
30
31#include "OgreRenderOperation.h"
32#include "OgreMatrix4.h"
33#include "OgreMaterial.h"
34#include "OgrePlane.h"
35#include "OgreGpuProgram.h"
36#include "OgreVector4.h"
37#include "OgreException.h"
38
39namespace Ogre {
40
41    /** Abstract class defining the interface all renderable objects must implement.
42        @remarks
43            This interface abstracts renderable discrete objects which will be queued in the render pipeline,
44            grouped by material. Classes implementing this interface must be based on a single material, a single
45            world matrix (or a collection of world matrices which are blended by weights), and must be
46            renderable via a single render operation.
47        @par
48            Note that deciding whether to put these objects in the rendering pipeline is done from the more specific
49            classes e.g. entities. Only once it is decided that the specific class is to be rendered is the abstract version
50            created (could be more than one per visible object) and pushed onto the rendering queue.
51    */
52    class _OgreExport Renderable
53    {
54    public:
55                Renderable() : mRenderDetailOverrideable(true)
56#ifdef GTP_VISIBILITY_MODIFIED_OGRE
57, mId(-1)
58#endif // GTP_VISIBILITY_MODIFIED_OGRE
59{}
60               
61        /** Virtual destructor needed as class has virtual methods. */
62        virtual ~Renderable() { }
63        /** Retrieves a weak reference to the material this renderable object uses.
64        @remarks
65            Note that the Renderable also has the option to override the getTechnique method
66            to specify a particular Technique to use instead of the best one available.
67        */
68        virtual const MaterialPtr& getMaterial(void) const = 0;
69        /** Retrieves a pointer to the Material Technique this renderable object uses.
70        @remarks
71            This is to allow Renderables to use a chosen Technique if they wish, otherwise
72            they will use the best Technique available for the Material they are using.
73        */
74        virtual Technique* getTechnique(void) const { return getMaterial()->getBestTechnique(); }
75        /** Gets the render operation required to send this object to the frame buffer.
76        */
77        virtual void getRenderOperation(RenderOperation& op) = 0;
78        /** Gets the world transform matrix / matrices for this renderable object.
79            @remarks
80                If the object has any derived transforms, these are expected to be up to date as long as
81                all the SceneNode structures have been updated before this is called.
82            @par
83                This method will populate xform with 1 matrix if it does not use vertex blending. If it
84                does use vertex blending it will fill the passed in pointer with an array of matrices,
85                the length being the value returned from getNumWorldTransforms.
86        */
87        virtual void getWorldTransforms(Matrix4* xform) const = 0;
88        /** Gets the worldspace orientation of this renderable; this is used in order to
89            more efficiently update parameters to vertex & fragment programs, since inverting Quaterion
90            and Vector in order to derive object-space positions / directions for cameras and
91            lights is much more efficient than inverting a complete 4x4 matrix, and also
92            eliminates problems introduced by scaling. */
93        virtual const Quaternion& getWorldOrientation(void) const = 0;
94        /** Gets the worldspace orientation of this renderable; this is used in order to
95            more efficiently update parameters to vertex & fragment programs, since inverting Quaterion
96            and Vector in order to derive object-space positions / directions for cameras and
97            lights is much more efficient than inverting a complete 4x4 matrix, and also
98            eliminates problems introduced by scaling. */
99        virtual const Vector3& getWorldPosition(void) const = 0;
100
101        /** Returns the number of world transform matrices this renderable requires.
102        @remarks
103            When a renderable uses vertex blending, it uses multiple world matrices instead of a single
104            one. Each vertex sent to the pipeline can reference one or more matrices in this list
105            with given weights.
106            If a renderable does not use vertex blending this method returns 1, which is the default for
107            simplicity.
108        */
109        virtual unsigned short getNumWorldTransforms(void) const { return 1; }
110
111        /** Returns whether or not to use an 'identity' projection.
112        @remarks
113            Usually Renderable objects will use a projection matrix as determined
114            by the active camera. However, if they want they can cancel this out
115            and use an identity projection, which effectively projects in 2D using
116            a {-1, 1} view space. Useful for overlay rendering. Normal renderables need
117            not override this.
118        */
119        virtual bool useIdentityProjection(void) const { return false; }
120
121        /** Returns whether or not to use an 'identity' projection.
122        @remarks
123            Usually Renderable objects will use a view matrix as determined
124            by the active camera. However, if they want they can cancel this out
125            and use an identity matrix, which means all geometry is assumed
126            to be relative to camera space already. Useful for overlay rendering.
127            Normal renderables need not override this.
128        */
129        virtual bool useIdentityView(void) const { return false; }
130
131                /** Returns the camera-relative squared depth of this renderable.
132                @remarks
133                        Used to sort transparent objects. Squared depth is used rather than
134                        actual depth to avoid having to perform a square root on the result.
135                */
136                virtual Real getSquaredViewDepth(const Camera* cam) const = 0;
137
138        /** Returns the preferred rasterisation mode of this renderable.
139        */
140        virtual SceneDetailLevel getRenderDetail() const {return SDL_SOLID;}
141
142        /** Returns whether or not this Renderable wishes the hardware to normalise normals. */
143        virtual bool getNormaliseNormals(void) const { return false; }
144
145        /** Gets a list of lights, ordered relative to how close they are to this renderable.
146        @remarks
147            Directional lights, which have no position, will always be first on this list.
148        */
149        virtual const LightList& getLights(void) const = 0;
150
151        virtual const PlaneList& getClipPlanes() const { return msDummyPlaneList; };
152
153        /** Method which reports whether this renderable would normally cast a
154            shadow.
155        @remarks
156            Subclasses should override this if they could have been used to
157            generate a shadow.
158        */
159        virtual bool getCastsShadows(void) const { return false; }
160
161        /** Sets a custom parameter for this Renderable, which may be used to
162            drive calculations for this specific Renderable, like GPU program parameters.
163        @remarks
164            Calling this method simply associates a numeric index with a 4-dimensional
165            value for this specific Renderable. This is most useful if the material
166            which this Renderable uses a vertex or fragment program, and has an
167            ACT_CUSTOM parameter entry. This parameter entry can refer to the
168            index you specify as part of this call, thereby mapping a custom
169            parameter for this renderable to a program parameter.
170        @param index The index with which to associate the value. Note that this
171            does not have to start at 0, and can include gaps. It also has no direct
172            correlation with a GPU program parameter index - the mapping between the
173            two is performed by the ACT_CUSTOM entry, if that is used.
174        @param value The value to associate.
175        */
176        void setCustomParameter(size_t index, const Vector4& value)
177        {
178            mCustomParameters[index] = value;
179        }
180
181        /** Gets the custom value associated with this Renderable at the given index.
182        @param
183            @see setCustomParaemter for full details.
184        */
185        const Vector4& getCustomParameter(size_t index) const
186        {
187            CustomParameterMap::const_iterator i = mCustomParameters.find(index);
188            if (i != mCustomParameters.end())
189            {
190                return i->second;
191            }
192            else
193            {
194                OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND,
195                    "Parameter at the given index was not found.",
196                    "Renderable::getCustomParameter");
197            }
198        }
199
200        /** Update a custom GpuProgramParameters constant which is derived from
201            information only this Renderable knows.
202        @remarks
203            This method allows a Renderable to map in a custom GPU program parameter
204            based on it's own data. This is represented by a GPU auto parameter
205            of ACT_CUSTOM, and to allow there to be more than one of these per
206            Renderable, the 'data' field on the auto parameter will identify
207            which parameter is being updated. The implementation of this method
208            must identify the parameter being updated, and call a 'setConstant'
209            method on the passed in GpuProgramParameters object, using the details
210            provided in the incoming auto constant setting to identify the index
211            at which to set the parameter.
212        @par
213            You do not need to override this method if you're using the standard
214            sets of data associated with the Renderable as provided by setCustomParameter
215            and getCustomParameter. By default, the implementation will map from the
216            value indexed by the 'constantEntry.data' parameter to a value previously
217            set by setCustomParameter. But custom Renderables are free to override
218            this if they want, in any case.
219        @param constantEntry The auto constant entry referring to the parameter
220            being updated
221        @param params The parameters object which this method should call to
222            set the updated parameters.
223        */
224        virtual void _updateCustomGpuParameter(
225            const GpuProgramParameters::AutoConstantEntry& constantEntry,
226            GpuProgramParameters* params) const
227        {
228            CustomParameterMap::const_iterator i = mCustomParameters.find(constantEntry.data);
229            if (i != mCustomParameters.end())
230            {
231                params->setConstant(constantEntry.index, i->second);
232            }
233        }
234
235                /** Sets whether this renderable's chosen detail level can be
236                        overridden (downgraded) by the camera setting.
237                @param override true means that a lower camera detail will override this
238                        renderables detail level, false means it won't.
239                */
240                virtual void setRenderDetailOverrideable(bool override)
241                {
242                        mRenderDetailOverrideable = override;
243                }
244
245                /** Gets whether this renderable's chosen detail level can be
246                        overridden (downgraded) by the camera setting.
247                */
248                virtual bool getRenderDetailOverrideable(void) const
249                {
250                        return mRenderDetailOverrideable;
251                }
252
253#ifdef GTP_VISIBILITY_MODIFIED_OGRE
254                /** Sets an id for this renderable.
255                */
256                void setId(int id) {mId = id;}
257                /** see set
258                */
259                int getId() {return mId;}
260#endif // GTP_VISIBILITY_MODIFIED_OGRE
261    protected:
262        static const PlaneList msDummyPlaneList;
263        typedef std::map<size_t, Vector4> CustomParameterMap;
264        CustomParameterMap mCustomParameters;
265                bool mRenderDetailOverrideable;
266#ifdef GTP_VISIBILITY_MODIFIED_OGRE
267                int mId;
268#endif // GTP_VISIBILITY_MODIFIED_OGRE
269    };
270
271
272
273}
274
275#endif //__Renderable_H__
Note: See TracBrowser for help on using the repository browser.