source: OGRE/trunk/ogrenew/OgreMain/include/OgreRenderable.h @ 692

Revision 692, 12.4 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

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