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

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

added ogre dependencies and patched ogre sources

RevLine 
[657]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 __Pass_H__
26#define __Pass_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreGpuProgram.h"
30#include "OgreColourValue.h"
31#include "OgreBlendMode.h"
32#include "OgreCommon.h"
33#include "OgreLight.h"
34
35namespace Ogre {
36    /** Class defining a single pass of a Technique (of a Material), ie
37        a single rendering call.
38    @remarks
39        Rendering can be repeated with many passes for more complex effects.
40        Each pass is either a fixed-function pass (meaning it does not use
41        a vertex or fragment program) or a programmable pass (meaning it does
42        use either a vertex and fragment program, or both).
43    @par
44        Programmable passes are complex to define, because they require custom
45        programs and you have to set all constant inputs to the programs (like
46        the position of lights, any base material colours you wish to use etc), but
47        they do give you much total flexibility over the algorithms used to render your
48        pass, and you can create some effects which are impossible with a fixed-function pass.
49        On the other hand, you can define a fixed-function pass in very little time, and
50        you can use a range of fixed-function effects like environment mapping very
51        easily, plus your pass will be more likely to be compatible with older hardware.
52        There are pros and cons to both, just remember that if you use a programmable
53        pass to create some great effects, allow more time for definition and testing.
54    */
55    class _OgreExport Pass
56    {
57    protected:
58        Technique* mParent;
59        unsigned short mIndex; // pass index
60        unsigned long mHash; // pass hash
61        //-------------------------------------------------------------------------
62        // Colour properties, only applicable in fixed-function passes
63        ColourValue mAmbient;
64        ColourValue mDiffuse;
65        ColourValue mSpecular;   
66        ColourValue mEmissive;
67        Real mShininess;
68        TrackVertexColourType mTracking;
69        //-------------------------------------------------------------------------
70
71        //-------------------------------------------------------------------------
72        // Blending factors
73        SceneBlendFactor mSourceBlendFactor;   
74        SceneBlendFactor mDestBlendFactor;
75        //-------------------------------------------------------------------------
76
77        //-------------------------------------------------------------------------   
78        // Depth buffer settings
79        bool mDepthCheck;
80        bool mDepthWrite;
81        CompareFunction mDepthFunc;
82        ushort mDepthBias;
83
84        // Colour buffer settings
85        bool mColourWrite;
86               
87                // Alpha reject settings
88                CompareFunction mAlphaRejectFunc;
89                unsigned char mAlphaRejectVal;
90        //-------------------------------------------------------------------------   
91
92        //-------------------------------------------------------------------------
93        // Culling mode
94        CullingMode mCullMode;
95        ManualCullingMode mManualCullMode;
96        //-------------------------------------------------------------------------
97
98        /// Lighting enabled?
99        bool mLightingEnabled;
100        /// Max simultaneous lights
101        unsigned short mMaxSimultaneousLights;
102                /// Run this pass once per light?
103                bool mRunOncePerLight;
104        // Should it only be run for a certain light type?
105        bool mRunOnlyForOneLightType;
106        Light::LightTypes mOnlyLightType;
107
108        /// Shading options
109        ShadeOptions mShadeOptions;
110
111        //-------------------------------------------------------------------------   
112        // Fog
113        bool mFogOverride;
114        FogMode mFogMode;
115        ColourValue mFogColour;
116        Real mFogStart;
117        Real mFogEnd;
118        Real mFogDensity;
119        //-------------------------------------------------------------------------   
120
121        /// Storage of texture unit states
122        typedef std::vector<TextureUnitState*> TextureUnitStates;
123        TextureUnitStates mTextureUnitStates;   
124
125                // Vertex program details
126                GpuProgramUsage *mVertexProgramUsage;
127        // Vertex program details
128        GpuProgramUsage *mShadowCasterVertexProgramUsage;
129        // Vertex program details
130        GpuProgramUsage *mShadowReceiverVertexProgramUsage;
131                // Fragment program details
132                GpuProgramUsage *mFragmentProgramUsage;
133        // Is this pass queued for deletion?
134        bool mQueuedForDeletion;
135        public:
136                typedef std::set<Pass*> PassSet;
137    protected:
138                /// List of Passes whose hashes need recalculating
139                static PassSet msDirtyHashList;
140        /// The place where passes go to die
141        static PassSet msPassGraveyard;
142    public:
143        /// Default constructor
144                Pass(Technique* parent, unsigned short index);
145        /// Copy constructor
146        Pass(Technique* parent, unsigned short index, const Pass& oth );
147        /// Operator = overload
148        Pass& operator=(const Pass& oth);
149        ~Pass();
150
151        /// Returns true if this pass is programmable ie includes either a vertex or fragment program.
152        bool isProgrammable(void) const { return mVertexProgramUsage || mFragmentProgramUsage; }
153
154        /// Returns true if this pass uses a programmable vertex pipeline
155        bool hasVertexProgram(void) const { return mVertexProgramUsage != NULL; }
156
157        /// Returns true if this pass uses a programmable fragment pipeline
158        bool hasFragmentProgram(void) const { return mFragmentProgramUsage != NULL; }
159
160        /// Gets the index of this Pass in the parent Technique
161        unsigned short getIndex(void) const { return mIndex; }
162        /** Sets the ambient colour reflectance properties of this pass.
163        @remarks
164        The base colour of a pass is determined by how much red, green and blue light is reflects
165        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
166        much ambient light (directionless global light) is reflected. The default is full white, meaning
167        objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light
168        effects, or change the blend of colours to make the object have a base colour other than white.
169        @note
170        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
171        or if this is a programmable pass.
172        */
173        void setAmbient(Real red, Real green, Real blue);
174
175        /** Sets the ambient colour reflectance properties of this pass.
176        @remarks
177        The base colour of a pass is determined by how much red, green and blue light is reflects
178        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
179        much ambient light (directionless global light) is reflected. The default is full white, meaning
180        objects are completely globally illuminated. Reduce this if you want to see diffuse or specular light
181        effects, or change the blend of colours to make the object have a base colour other than white.
182        @note
183        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
184        or if this is a programmable pass.
185        */
186
187        void setAmbient(const ColourValue& ambient);
188
189        /** Sets the diffuse colour reflectance properties of this pass.
190        @remarks
191        The base colour of a pass is determined by how much red, green and blue light is reflects
192        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
193        much diffuse light (light from instances of the Light class in the scene) is reflected. The default
194        is full white, meaning objects reflect the maximum white light they can from Light objects.
195        @note
196        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
197        or if this is a programmable pass.
198        */
199        void setDiffuse(Real red, Real green, Real blue, Real alpha);
200
201        /** Sets the diffuse colour reflectance properties of this pass.
202        @remarks
203        The base colour of a pass is determined by how much red, green and blue light is reflects
204        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
205        much diffuse light (light from instances of the Light class in the scene) is reflected. The default
206        is full white, meaning objects reflect the maximum white light they can from Light objects.
207        @note
208        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
209        or if this is a programmable pass.
210        */
211        void setDiffuse(const ColourValue& diffuse);
212
213        /** Sets the specular colour reflectance properties of this pass.
214        @remarks
215        The base colour of a pass is determined by how much red, green and blue light is reflects
216        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
217        much specular light (highlights from instances of the Light class in the scene) is reflected.
218        The default is to reflect no specular light.
219        @note
220        The size of the specular highlights is determined by the separate 'shininess' property.
221        @note
222        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
223        or if this is a programmable pass.
224        */
225        void setSpecular(Real red, Real green, Real blue, Real alpha);
226
227        /** Sets the specular colour reflectance properties of this pass.
228        @remarks
229        The base colour of a pass is determined by how much red, green and blue light is reflects
230        (provided texture layer #0 has a blend mode other than LBO_REPLACE). This property determines how
231        much specular light (highlights from instances of the Light class in the scene) is reflected.
232        The default is to reflect no specular light.
233        @note
234        The size of the specular highlights is determined by the separate 'shininess' property.
235        @note
236        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
237        or if this is a programmable pass.
238        */
239        void setSpecular(const ColourValue& specular);
240
241        /** Sets the shininess of the pass, affecting the size of specular highlights.
242        @note
243        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
244        or if this is a programmable pass.
245        */
246        void setShininess(Real val);
247
248        /** Sets the amount of self-illumination an object has.
249        @remarks
250        If an object is self-illuminating, it does not need external sources to light it, ambient or
251        otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since
252        you can already specify per-pass ambient light, but is here for completeness.
253        @note
254        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
255        or if this is a programmable pass.
256        */
257        void setSelfIllumination(Real red, Real green, Real blue);
258
259        /** Sets the amount of self-illumination an object has.
260        @remarks
261        If an object is self-illuminating, it does not need external sources to light it, ambient or
262        otherwise. It's like the object has it's own personal ambient light. This property is rarely useful since
263        you can already specify per-pass ambient light, but is here for completeness.
264        @note
265        This setting has no effect if dynamic lighting is disabled (see Pass::setLightingEnabled),
266        or if this is a programmable pass.
267        */
268        void setSelfIllumination(const ColourValue& selfIllum);
269
270        /** Sets which material properties follow the vertex colour
271         */
272        void setVertexColourTracking(TrackVertexColourType tracking);
273
274        /** Gets the ambient colour reflectance of the pass.
275        */
276        const ColourValue& getAmbient(void) const;
277
278        /** Gets the diffuse colour reflectance of the pass.
279        */
280        const ColourValue& getDiffuse(void) const;
281
282        /** Gets the specular colour reflectance of the pass.
283        */
284        const ColourValue& getSpecular(void) const;
285
286        /** Gets the self illumination colour of the pass.
287        */
288        const ColourValue& getSelfIllumination(void) const;
289
290        /** Gets the 'shininess' property of the pass (affects specular highlights).
291        */
292        Real getShininess(void) const;
293       
294        /** Gets which material properties follow the vertex colour
295         */
296        TrackVertexColourType getVertexColourTracking(void) const;
297
298        /** Inserts a new TextureUnitState object into the Pass.
299        @remarks
300        This unit is is added on top of all previous units.
301        */
302        TextureUnitState* createTextureUnitState(void);
303        /** Inserts a new TextureUnitState object into the Pass.
304        @remarks
305        This unit is is added on top of all previous units.
306        @param
307        name The basic name of the texture e.g. brickwall.jpg, stonefloor.png
308        @param
309        texCoordSet The index of the texture coordinate set to use.
310        @note
311        Applies to both fixed-function and programmable passes.
312        */
313        TextureUnitState* createTextureUnitState( const String& textureName, unsigned short texCoordSet = 0);
314                /** Adds the passed in TextureUnitState, to the existing Pass. */
315                void addTextureUnitState(TextureUnitState* state);
316        /** Retrieves a pointer to a texture unit state so it may be modified.
317        */
318        TextureUnitState* getTextureUnitState(unsigned short index);
319
320        typedef VectorIterator<TextureUnitStates> TextureUnitStateIterator;
321        /** Get an iterator over the TextureUnitStates contained in this Pass. */
322        TextureUnitStateIterator getTextureUnitStateIterator(void);
323
324        /** Removes the indexed texture unit state from this pass.
325        @remarks
326            Note that removing a texture which is not the topmost will have a larger performance impact.
327        */
328        void removeTextureUnitState(unsigned short index);
329
330        /** Removes all texture unit settings.
331        */
332        void removeAllTextureUnitStates(void);
333
334        /** Returns the number of texture unit settings.
335        */
336        size_t getNumTextureUnitStates(void) const
337        {
338            return mTextureUnitStates.size();
339        }
340
341        /** Sets the kind of blending this pass has with the existing contents of the scene.
342        @remarks
343        Wheras the texture blending operations seen in the TextureUnitState class are concerned with
344        blending between texture layers, this blending is about combining the output of the Pass
345        as a whole with the existing contents of the rendering target. This blending therefore allows
346        object transparency and other special effects. If all passes in a technique have a scene
347        blend, then the whole technique is considered to be transparent.
348        @par
349        This method allows you to select one of a number of predefined blending types. If you require more
350        control than this, use the alternative version of this method which allows you to specify source and
351        destination blend factors.
352        @note
353        This method is applicable for both the fixed-function and programmable pipelines.
354        @param
355        sbt One of the predefined SceneBlendType blending types
356        */
357        void setSceneBlending( const SceneBlendType sbt );
358
359        /** Allows very fine control of blending this Pass with the existing contents of the scene.
360        @remarks
361        Wheras the texture blending operations seen in the TextureUnitState class are concerned with
362        blending between texture layers, this blending is about combining the output of the material
363        as a whole with the existing contents of the rendering target. This blending therefore allows
364        object transparency and other special effects.
365        @par
366        This version of the method allows complete control over the blending operation, by specifying the
367        source and destination blending factors. The result of the blending operation is:
368        <span align="center">
369        final = (texture * sourceFactor) + (pixel * destFactor)
370        </span>
371        @par
372        Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor
373        enumerated type.
374        @param
375        sourceFactor The source factor in the above calculation, i.e. multiplied by the texture colour components.
376        @param
377        destFactor The destination factor in the above calculation, i.e. multiplied by the pixel colour components.
378        @note
379        This method is applicable for both the fixed-function and programmable pipelines.
380        */
381        void setSceneBlending( const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor);
382
383        /** Retrieves the source blending factor for the material (as set using Materiall::setSceneBlending).
384        */
385        SceneBlendFactor getSourceBlendFactor() const;
386
387        /** Retrieves the destination blending factor for the material (as set using Materiall::setSceneBlending).
388        */
389        SceneBlendFactor getDestBlendFactor() const;
390
391                /** Returns true if this pass has some element of transparency. */
392                bool isTransparent(void) const;
393
394                /** Sets whether or not this pass renders with depth-buffer checking on or not.
395        @remarks
396        If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer
397        the depth buffer is checked to see if the pixel is in front of all other pixels written at that
398        point. If not, the pixel is not written.
399        @par
400        If depth checking is off, pixels are written no matter what has been rendered before.
401        Also see setDepthFunction for more advanced depth check configuration.
402        @see
403        setDepthFunction
404        */
405        void setDepthCheckEnabled(bool enabled);
406
407        /** Returns whether or not this pass renders with depth-buffer checking on or not.
408        @see
409        setDepthCheckEnabled
410        */
411        bool getDepthCheckEnabled(void) const;
412
413        /** Sets whether or not this pass renders with depth-buffer writing on or not.
414        @remarks
415        If depth-buffer writing is on, whenever a pixel is written to the frame buffer
416        the depth buffer is updated with the depth value of that new pixel, thus affecting future
417        rendering operations if future pixels are behind this one.
418        @par
419        If depth writing is off, pixels are written without updating the depth buffer Depth writing should
420        normally be on but can be turned off when rendering static backgrounds or when rendering a collection
421        of transparent objects at the end of a scene so that they overlap each other correctly.
422        */
423        void setDepthWriteEnabled(bool enabled);
424
425        /** Returns whether or not this pass renders with depth-buffer writing on or not.
426        @see
427        setDepthWriteEnabled
428        */
429        bool getDepthWriteEnabled(void) const;
430
431        /** Sets the function used to compare depth values when depth checking is on.
432        @remarks
433        If depth checking is enabled (see setDepthCheckEnabled) a comparison occurs between the depth
434        value of the pixel to be written and the current contents of the buffer. This comparison is
435        normally CMPF_LESS_EQUAL, i.e. the pixel is written if it is closer (or at the same distance)
436        than the current contents. If you wish you can change this comparison using this method.
437        */
438        void setDepthFunction( CompareFunction func );
439        /** Returns the function used to compare depth values when depth checking is on.
440        @see
441        setDepthFunction
442        */
443        CompareFunction getDepthFunction(void) const;
444
445                /** Sets whether or not colour buffer writing is enabled for this Pass.
446                @remarks
447                        For some effects, you might wish to turn off the colour write operation
448                        when rendering geometry; this means that only the depth buffer will be
449                        updated (provided you have depth buffer writing enabled, which you
450                        probably will do, although you may wish to only update the stencil
451                        buffer for example - stencil buffer state is managed at the RenderSystem
452                        level only, not the Material since you are likely to want to manage it
453                        at a higher level).
454                */
455                void setColourWriteEnabled(bool enabled);
456                /** Determines if colour buffer writing is enabled for this pass. */
457                bool getColourWriteEnabled(void) const;
458
459        /** Sets the culling mode for this pass  based on the 'vertex winding'.
460        @remarks
461        A typical way for the rendering engine to cull triangles is based on the 'vertex winding' of
462        triangles. Vertex winding refers to the direction in which the vertices are passed or indexed
463        to in the rendering operation as viewed from the camera, and will wither be clockwise or
464        anticlockwise (that's 'counterclockwise' for you Americans out there ;) The default is
465        CULL_CLOCKWISE i.e. that only triangles whose vertices are passed/indexed in anticlockwise order
466        are rendered - this is a common approach and is used in 3D studio models for example. You can
467        alter this culling mode if you wish but it is not advised unless you know what you are doing.
468        @par
469        You may wish to use the CULL_NONE option for mesh data that you cull yourself where the vertex
470        winding is uncertain.
471        */
472        void setCullingMode( CullingMode mode );
473
474        /** Returns the culling mode for geometry rendered with this pass. See setCullingMode for more information.
475        */
476        CullingMode getCullingMode(void) const;
477
478        /** Sets the manual culling mode, performed by CPU rather than hardware.
479        @pemarks
480        In some situations you want to use manual culling of triangles rather than sending the
481        triangles to the hardware and letting it cull them. This setting only takes effect on SceneManager's
482        that use it (since it is best used on large groups of planar world geometry rather than on movable
483        geometry since this would be expensive), but if used can cull geometry before it is sent to the
484        hardware.
485        @note
486        The default for this setting is MANUAL_CULL_BACK.
487        @param
488        mode The mode to use - see enum ManualCullingMode for details
489
490        */
491        void setManualCullingMode( ManualCullingMode mode );
492
493        /** Retrieves the manual culling mode for this pass
494        @see
495        setManualCullingMode
496        */
497        ManualCullingMode getManualCullingMode(void) const;
498
499        /** Sets whether or not dynamic lighting is enabled.
500        @param
501        enabled
502        If true, dynamic lighting is performed on geometry with normals supplied, geometry without
503        normals will not be displayed.
504        @par
505        If false, no lighting is applied and all geometry will be full brightness.
506        */
507        void setLightingEnabled(bool enabled);
508
509        /** Returns whether or not dynamic lighting is enabled.
510        */
511        bool getLightingEnabled(void) const;
512
513        /** Sets the maximum number of lights to be used by this pass.
514        @remarks
515            During rendering, if lighting is enabled (or if the pass uses an automatic
516            program parameter based on a light) the engine will request the nearest lights
517            to the object being rendered in order to work out which ones to use. This
518            parameter sets the limit on the number of lights which should apply to objects
519            rendered with this pass.
520        */
521        void setMaxSimultaneousLights(unsigned short maxLights);
522        /** Gets the maximum number of lights to be used by this pass. */
523        unsigned short getMaxSimultaneousLights(void) const;
524
525        /** Sets the type of light shading required
526        @note
527        The default shading method is Gouraud shading.
528        */
529        void setShadingMode( ShadeOptions mode );
530
531        /** Returns the type of light shading to be used.
532        */
533        ShadeOptions getShadingMode(void) const;
534
535
536        /** Sets the fogging mode applied to this pass.
537        @remarks
538        Fogging is an effect that is applied as polys are rendered. Sometimes, you want
539        fog to be applied to an entire scene. Other times, you want it to be applied to a few
540        polygons only. This pass-level specification of fog parameters lets you easily manage
541        both.
542        @par
543        The SceneManager class also has a setFog method which applies scene-level fog. This method
544        lets you change the fog behaviour for this pass compared to the standard scene-level fog.
545        @param
546        overrideScene If true, you authorise this pass to override the scene's fog params with it's own settings.
547        If you specify false, so other parameters are necessary, and this is the default behaviour for passs.
548        @param
549        mode Only applicable if overrideScene is true. You can disable fog which is turned on for the
550        rest of the scene by specifying FOG_NONE. Otherwise, set a pass-specific fog mode as
551        defined in the enum FogMode.
552        @param
553        colour The colour of the fog. Either set this to the same as your viewport background colour,
554        or to blend in with a skydome or skybox.
555        @param
556        expDensity The density of the fog in FOG_EXP or FOG_EXP2 mode, as a value between 0 and 1.
557        The default is 0.001.
558        @param
559        linearStart Distance in world units at which linear fog starts to encroach.
560        Only applicable if mode is FOG_LINEAR.
561        @param
562        linearEnd Distance in world units at which linear fog becomes completely opaque.
563        Only applicable if mode is FOG_LINEAR.
564        */
565        void setFog(
566            bool overrideScene,
567            FogMode mode = FOG_NONE,
568            const ColourValue& colour = ColourValue::White,
569            Real expDensity = 0.001, Real linearStart = 0.0, Real linearEnd = 1.0 );
570
571        /** Returns true if this pass is to override the scene fog settings.
572        */
573        bool getFogOverride(void) const;
574
575        /** Returns the fog mode for this pass.
576        @note
577        Only valid if getFogOverride is true.
578        */
579        FogMode getFogMode(void) const;
580
581        /** Returns the fog colour for the scene.
582        */
583        const ColourValue& getFogColour(void) const;
584
585        /** Returns the fog start distance for this pass.
586        @note
587        Only valid if getFogOverride is true.
588        */
589        Real getFogStart(void) const;
590
591        /** Returns the fog end distance for this pass.
592        @note
593        Only valid if getFogOverride is true.
594        */
595        Real getFogEnd(void) const;
596
597        /** Returns the fog density for this pass.
598        @note
599        Only valid if getFogOverride is true.
600        */
601        Real getFogDensity(void) const;
602
603        /** Sets the depth bias to be used for this material.
604        @remarks
605        When polygons are coplanar, you can get problems with 'depth fighting' where
606        the pixels from the two polys compete for the same screen pixel. This is particularly
607        a problem for decals (polys attached to another surface to represent details such as
608        bulletholes etc.).
609        @par
610        A way to combat this problem is to use a depth bias to adjust the depth buffer value
611        used for the decal such that it is slightly higher than the true value, ensuring that
612        the decal appears on top.
613        @param bias The bias value, should be between 0 and 16.
614        */
615        void setDepthBias(ushort bias);
616
617        /** Retrieves the depth bias value as set by setDepthValue. */
618        ushort getDepthBias(void) const;
619
620        /** Sets the way the pass will have use alpha to totally reject pixels from the pipeline.
621        @remarks
622                        The default is CMPF_ALWAYS_PASS i.e. alpha is not used to reject pixels.
623        @param func The comparison which must pass for the pixel to be written.
624        @param value 1 byte value against which alpha values will be tested(0-255)
625        @note
626                        This option applies in both the fixed function and the programmable pipeline.
627        */
628        void setAlphaRejectSettings(CompareFunction func, unsigned char value);
629
630                /** Sets the alpha reject function. See setAlphaRejectSettings for more information.
631                */
632                void setAlphaRejectFunction(CompareFunction func);
633
634                /** Gets the alpha reject value. See setAlphaRejectSettings for more information.
635                */
636                void setAlphaRejectValue(unsigned char val);
637
638                /** Gets the alpha reject function. See setAlphaRejectSettings for more information.
639        */
640                CompareFunction getAlphaRejectFunction(void) const { return mAlphaRejectFunc; }
641
642        /** Gets the alpha reject value. See setAlphaRejectSettings for more information.
643        */
644                unsigned char getAlphaRejectValue(void) const { return mAlphaRejectVal; }
645        /** Sets whether or not this pass should be run once per light which
646                    can affect the object being rendered.
647                @remarks
648                        The default behaviour for a pass (when this option is 'false'), is
649                        for a pass to be rendered only once, with all the lights which could
650                        affect this object set at the same time (up to the maximum lights
651                        allowed in the render system, which is typically 8).
652                @par
653                        Setting this option to 'true' changes this behaviour, such that
654                        instead of trying to issue render this pass once per object, it
655                        is run once <b>per light</b> which can affect this object. In
656                        this case, only light index 0 is ever used, and is a different light
657                        every time the pass is issued, up to the total number of lights
658                        which is affecting this object. This has 2 advantages:
659                        <ul><li>There is no limit on the number of lights which can be
660                        supported</li>
661                        <li>It's easier to write vertex / fragment programs for this because
662                        a single program can be used for any number of lights</li>
663                        </ul>
664                        However, this technique is a lot more expensive, and typically you
665                        will want an additional ambient pass, because if no lights are
666                        affecting the object it will not be rendered at all, which will look
667                        odd even if ambient light is zero (imagine if there are lit objects
668                        behind it - the objects silhouette would not show up). Therefore,
669                        use this option with care, and you would be well advised to provide
670                        a less expensive fallback technique for use in the distance.
671                @note
672                        The number of times this pass runs is still limited by the maximum
673                        number of lights allowed as set in setMaxSimultaneousLights, so
674                        you will never get more passes than this.
675        @param enabled Whether this feature is enabled
676        @param onlyForOneLightType If true, the pass will only be run for a single type
677            of light, other light types will be ignored.
678        @param lightType The single light type which will be considered for this pass
679                */
680        void setRunOncePerLight(bool enabled,
681            bool onlyForOneLightType = true, Light::LightTypes lightType = Light::LT_POINT);
682
683        /** Does this pass run once for every light in range? */
684                bool getRunOncePerLight(void) const { return mRunOncePerLight; }
685        /** Does this pass run only for a single light type (if getRunOncePerLight is true). */
686        bool getRunOnlyForOneLightType(void) const { return mRunOnlyForOneLightType; }
687        /** Gets the single light type this pass runs for if  getRunOncePerLight and
688            getRunOnlyForOneLightType are both true. */
689        Light::LightTypes getOnlyLightType() const { return mOnlyLightType; }
690               
691                /// Gets the parent Technique
692        Technique* getParent(void) { return mParent; }
693
694                /// Gets the resource group of the ultimate parent Material
695                const String& getResourceGroup(void) const;
696
697                /** Sets the details of the vertex program to use.
698                @remarks
699                        Only applicable to programmable passes, this sets the details of
700                        the vertex program to use in this pass. The program will not be
701                        loaded until the parent Material is loaded.
702                @param name The name of the program - this must have been
703                        created using GpuProgramManager by the time that this Pass
704                        is loaded. If this parameter is blank, any vertex program in this pass is disabled.
705        @param resetParams
706            If true, this will create a fresh set of parameters from the
707            new program being linked, so if you had previously set parameters
708            you will have to set them again. If you set this to false, you must
709            be absolutely sure that the parameters match perfectly, and in the
710            case of named parameters refers to the indexes underlying them,
711            not just the names.
712                */
713                void setVertexProgram(const String& name, bool resetParams = true);
714                /** Sets the vertex program parameters.
715                @remarks
716                        Only applicable to programmable passes, and this particular call is
717                        designed for low-level programs; use the named parameter methods
718                        for setting high-level program parameters.
719                */
720                void setVertexProgramParameters(GpuProgramParametersSharedPtr params);
721                /** Gets the name of the vertex program used by this pass. */
722                const String& getVertexProgramName(void) const;
723        /** Gets the vertex program parameters used by this pass. */
724        GpuProgramParametersSharedPtr getVertexProgramParameters(void);
725                /** Gets the vertex program used by this pass, only available after _load(). */
726                const GpuProgramPtr& getVertexProgram(void);
727
728
729        /** Sets the details of the vertex program to use when rendering as a
730        shadow caster.
731        @remarks
732        Texture-based shadows require that the caster is rendered to a texture
733        in a solid colour (the shadow colour in the case of modulative texture
734        shadows). Whilst Ogre can arrange this for the fixed function
735        pipeline, passes which use vertex programs might need the vertex
736        programs still to run in order to preserve any deformation etc
737        that it does. However, lighting calculations must be a lot simpler,
738        with only the ambient colour being used (which the engine will ensure
739        is bound to the shadow colour).
740        @par
741        Therefore, it is up to implemetors of vertex programs to provide an
742        alternative vertex program which can be used to render the object
743        to a shadow texture. Do all the same vertex transforms, but set the
744        colour of the vertex to the ambient colour, as bound using the
745        standard auto parameter binding mechanism.
746        @note
747        Some vertex programs will work without doing this, because Ogre ensures
748        that all lights except for ambient are set black. However, the chances
749        are that your vertex program is doing a lot of unnecessary work in this
750        case, since the other lights are having no effect, and it is good practice
751        to supply an alternative.
752        @note
753        This is only applicable to programmable passes.
754        @par
755        The default behaviour is for Ogre to switch to fixed-function
756        rendering if an explict vertex program alternative is not set.
757        */
758        void setShadowCasterVertexProgram(const String& name);
759        /** Sets the vertex program parameters for rendering as a shadow caster.
760        @remarks
761        Only applicable to programmable passes, and this particular call is
762        designed for low-level programs; use the named parameter methods
763        for setting high-level program parameters.
764        */
765        void setShadowCasterVertexProgramParameters(GpuProgramParametersSharedPtr params);
766        /** Gets the name of the vertex program used by this pass when rendering shadow casters. */
767        const String& getShadowCasterVertexProgramName(void) const;
768        /** Gets the vertex program parameters used by this pass when rendering shadow casters. */
769        GpuProgramParametersSharedPtr getShadowCasterVertexProgramParameters(void);
770        /** Gets the vertex program used by this pass when rendering shadow casters,
771            only available after _load(). */
772        const GpuProgramPtr& getShadowCasterVertexProgram(void);
773
774        /** Sets the details of the vertex program to use when rendering as a
775            shadow receiver.
776        @remarks
777            Texture-based shadows require that the shadow receiver is rendered using
778            a projective texture. Whilst Ogre can arrange this for the fixed function
779            pipeline, passes which use vertex programs might need the vertex
780            programs still to run in order to preserve any deformation etc
781            that it does. So in this case, we need a vertex program which does the
782            appropriate vertex transformation, but generates projective texture
783            coordinates.
784        @par
785            Therefore, it is up to implemetors of vertex programs to provide an
786            alternative vertex program which can be used to render the object
787            as a shadow receiver. Do all the same vertex transforms, but generate
788            <strong>2 sets</strong> of texture coordinates using the auto parameter
789            ACT_TEXTURE_VIEWPROJ_MATRIX, which Ogre will bind to the parameter name /
790            index you supply as the second parameter to this method. 2 texture
791            sets are needed because Ogre needs to use 2 texture units for some
792            shadow effects.
793        @note
794            This is only applicable to programmable passes.
795        @par
796            The default behaviour is for Ogre to switch to fixed-function
797            rendering if an explict vertex program alternative is not set.         
798        */
799        void setShadowReceiverVertexProgram(const String& name);
800        /** Sets the vertex program parameters for rendering as a shadow receiver.
801        @remarks
802        Only applicable to programmable passes, and this particular call is
803        designed for low-level programs; use the named parameter methods
804        for setting high-level program parameters.
805        */
806        void setShadowReceiverVertexProgramParameters(GpuProgramParametersSharedPtr params);
807        /** Gets the name of the vertex program used by this pass when rendering shadow receivers. */
808        const String& getShadowReceiverVertexProgramName(void) const;
809        /** Gets the vertex program parameters used by this pass when rendering shadow receivers. */
810        GpuProgramParametersSharedPtr getShadowReceiverVertexProgramParameters(void);
811        /** Gets the vertex program used by this pass when rendering shadow receivers,
812        only available after _load(). */
813        const GpuProgramPtr& getShadowReceiverVertexProgram(void);
814
815
816                /** Sets the details of the fragment program to use.
817                @remarks
818                        Only applicable to programmable passes, this sets the details of
819                        the fragment program to use in this pass. The program will not be
820                        loaded until the parent Material is loaded.
821                @param name The name of the program - this must have been
822                        created using GpuProgramManager by the time that this Pass
823                        is loaded. If this parameter is blank, any fragment program in this pass is disabled.
824        @param resetParams
825            If true, this will create a fresh set of parameters from the
826            new program being linked, so if you had previously set parameters
827            you will have to set them again. If you set this to false, you must
828            be absolutely sure that the parameters match perfectly, and in the
829            case of named parameters refers to the indexes underlying them,
830            not just the names.
831                */
832                void setFragmentProgram(const String& name, bool resetParams = true);
833                /** Sets the vertex program parameters.
834                @remarks
835                        Only applicable to programmable passes.
836                */
837                void setFragmentProgramParameters(GpuProgramParametersSharedPtr params);
838                /** Gets the name of the fragment program used by this pass. */
839                const String& getFragmentProgramName(void) const;
840                /** Gets the vertex program parameters used by this pass. */
841                GpuProgramParametersSharedPtr getFragmentProgramParameters(void);
842                /** Gets the vertex program used by this pass, only available after _load(). */
843                const GpuProgramPtr& getFragmentProgram(void);
844
845                /** Splits this Pass to one which can be handled in the number of
846                        texture units specified.
847                @remarks
848                        Only works on non-programmable passes, programmable passes cannot be
849                        split, it's up to the author to ensure that there is a fallback Technique
850                        for less capable cards.
851                @param numUnits The target number of texture units
852                @returns A new Pass which contains the remaining units, and a scene_blend
853                                setting appropriate to approximate the multitexture. This Pass will be
854                                attached to the parent Technique of this Pass.
855                */
856                Pass* _split(unsigned short numUnits);
857
858                /** Internal method to adjust pass index. */
859                void _notifyIndex(unsigned short index);
860
861                /** Internal method for loading this pass. */
862                void _load(void);
863                /** Internal method for unloading this pass. */
864                void _unload(void);
865        // Is this loaded?
866        bool isLoaded(void) const;
867
868        /** Gets the 'hash' of this pass, ie a precomputed number to use for sorting
869        @remarks
870            This hash is used to sort passes, and for this reason the pass is hashed
871            using firstly its index (so that all passes are rendered in order), then
872            by the textures which it's TextureUnitState instances are using.
873        */
874        unsigned long getHash(void) const;
875                /// Mark the hash as dirty
876                void _dirtyHash(void);
877        /** Internal method for recalculating the hash.
878                @remarks
879                        Do not call this unless you are sure the old hash is not still being
880                        used by anything. If in doubt, call _dirtyHash if you want to force
881                        recalculation of the has next time.
882                */
883        void _recalculateHash(void);
884        /** Tells the pass that it needs recompilation. */
885        void _notifyNeedsRecompile(void);
886
887        /** Update any automatic parameters (except lights) on this pass */
888        void _updateAutoParamsNoLights(const AutoParamDataSource& source);
889        /** Update any automatic light parameters on this pass */
890        void _updateAutoParamsLightsOnly(const AutoParamDataSource& source);
891
892        /** Set texture filtering for every texture unit
893        @note
894            This property actually exists on the TextureUnitState class
895            For simplicity, this method allows you to set these properties for
896            every current TeextureUnitState, If you need more precision, retrieve the 
897            TextureUnitState instance and set the property there.
898        @see TextureUnitState::setTextureFiltering
899        */
900        void setTextureFiltering(TextureFilterOptions filterType);
901        /** Sets the anisotropy level to be used for all textures.
902        @note
903            This property has been moved to the TextureUnitState class, which is accessible via the
904            Technique and Pass. For simplicity, this method allows you to set these properties for
905            every current TeextureUnitState, If you need more precision, retrieve the Technique,
906            Pass and TextureUnitState instances and set the property there.
907        @see TextureUnitState::setTextureAnisotropy
908        */
909        void setTextureAnisotropy(unsigned int maxAniso);
910                /** Static method to retrieve all the Passes which need their
911                    hash values recalculated.
912                */
913                static const PassSet& getDirtyHashList(void)
914                { return msDirtyHashList; }
915        /** Static method to retrieve all the Passes which are pending deletion.
916        */
917        static const PassSet& getPassGraveyard(void)
918        { return msPassGraveyard; }
919                /** Static method to reset the list of passes which need their hash
920                    values recalculated.
921                @remarks
922                        For performance, the dirty list is not updated progressively as
923                        the hashes are recalculated, instead we expect the processor of the
924                        dirty hash list to clear the list when they are done.
925                */
926                static void clearDirtyHashList(void) { msDirtyHashList.clear(); }
927
928        /** Process all dirty and pending deletion passes. */
929        static void processPendingPassUpdates(void);
930
931        /** Queue this pass for deletion when appropriate. */
932        void queueForDeletion(void);
933
934        /** Returns whether this pass is ambient only.
935        */
936        bool isAmbientOnly(void) const;
937
938       
939    };
940
941    enum IlluminationStage
942    {
943        /// Part of the rendering which occurs without any kind of direct lighting
944        IS_AMBIENT,
945        /// Part of the rendering which occurs per light
946        IS_PER_LIGHT,
947        /// Post-lighting rendering
948        IS_DECAL
949    };
950    /** Struct recording a pass which can be used for a specific illumination stage.
951    @remarks
952        This structure is used to record categorised passes which fit into a
953        number of distinct illumination phases - ambient, diffuse / specular
954        (per-light) and decal (post-lighting texturing).
955        An original pass may fit into one of these categories already, or it
956        may require splitting into its component parts in order to be categorised
957        properly.
958    */
959    struct IlluminationPass
960    {
961        IlluminationStage stage;
962        /// The pass to use in this stage
963        Pass* pass;
964        /// Whether this pass is one which should be deleted itself
965        bool destroyOnShutdown;
966        /// The original pass which spawned this one
967        Pass* originalPass;
968    };
969
970    typedef std::vector<IlluminationPass*> IlluminationPassList;
971
972
973}
974
975#endif
Note: See TracBrowser for help on using the repository browser.