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

Revision 692, 49.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 __TextureUnitState_H__
26#define __TextureUnitState_H__
27
28#include "OgrePrerequisites.h"
29#include "OgreCommon.h"
30#include "OgreBlendMode.h"
31#include "OgreMatrix4.h"
32#include "OgreIteratorWrappers.h"
33#include "OgreString.h"
34#include "OgreTexture.h"
35
36namespace Ogre {
37    /** Class representing the state of a single texture unit during a Pass of a
38        Technique, of a Material.
39    @remarks
40        Texture units are pipelines for retrieving texture data for rendering onto
41        your objects in the world. Using them is common to both the fixed-function and
42        the programmable (vertex and fragment program) pipeline, but some of the
43        settings will only have an effect in the fixed-function pipeline (for example,
44        setting a texture rotation will have no effect if you use the programmable
45        pipeline, because this is overridden by the fragment program). The effect
46        of each setting as regards the 2 pipelines is commented in each setting.
47    @par
48        When I use the term 'fixed-function pipeline' I mean traditional rendering
49        where you do not use vertex or fragment programs (shaders). Programmable
50        pipeline means that for this pass you are using vertex or fragment programs.
51    */
52    class _OgreExport TextureUnitState
53    {
54        friend class RenderSystem;
55    public:
56        /** Definition of the broad types of texture effect you can apply to a texture unit.
57        @note
58            Note that these have no effect when using the programmable pipeline, since their
59            effect is overridden by the vertex / fragment programs.
60        */
61        enum TextureEffectType
62        {
63            /// Generate all texture coords based on angle between camera and vertex
64            ET_ENVIRONMENT_MAP,
65            /// Generate texture coords based on a frustum
66            ET_PROJECTIVE_TEXTURE,
67            /// Constant u/v scrolling effect
68            ET_UVSCROLL,
69                        /// Constant u scrolling effect
70            ET_USCROLL,
71                        /// Constant u/v scrolling effect
72            ET_VSCROLL,
73            /// Constant rotation
74            ET_ROTATE,
75            /// More complex transform
76            ET_TRANSFORM
77
78        };
79
80        /** Enumeration to specify type of envmap.
81        @note
82            Note that these have no effect when using the programmable pipeline, since their
83            effect is overridden by the vertex / fragment programs.
84        */
85        enum EnvMapType
86        {
87            /// Envmap based on vector from camera to vertex position, good for planar geometry
88            ENV_PLANAR,
89            /// Envmap based on dot of vector from camera to vertex and vertex normal, good for curves
90            ENV_CURVED,
91            /// Envmap entended to supply reflection vectors for cube mapping
92            ENV_REFLECTION,
93            /// Envmap entended to supply normal vectors for cube mapping
94            ENV_NORMAL
95        };
96
97        /** Useful enumeration when dealing with procedural transforms.
98        @note
99            Note that these have no effect when using the programmable pipeline, since their
100            effect is overridden by the vertex / fragment programs.
101        */
102        enum TextureTransformType
103        {
104            TT_TRANSLATE_U,
105            TT_TRANSLATE_V,
106            TT_SCALE_U,
107            TT_SCALE_V,
108            TT_ROTATE
109        };
110
111        /** Texture addressing modes - default is TAM_WRAP.
112        @note
113            These settings are relevant in both the fixed-function and the
114            programmable pipeline.
115        */
116        enum TextureAddressingMode
117        {
118            /// Texture wraps at values over 1.0
119            TAM_WRAP,
120            /// Texture mirrors (flips) at joins over 1.0
121            TAM_MIRROR,
122            /// Texture clamps at 1.0
123            TAM_CLAMP,
124            /// Texture coordinates outside the range [0.0, 1.0] are set to the border colour
125            TAM_BORDER
126        };
127
128                /** Texture addressing mode for each texture coordinate. */
129                struct UVWAddressingMode
130                {
131                        TextureAddressingMode u, v, w;
132                };
133
134        /** Enum identifying the frame indexes for faces of a cube map (not the composite 3D type.
135        */
136        enum TextureCubeFace
137        {
138            CUBE_FRONT = 0,
139            CUBE_BACK = 1,
140            CUBE_LEFT = 2,
141            CUBE_RIGHT = 3,
142            CUBE_UP = 4,
143            CUBE_DOWN = 5
144        };
145
146        /** Internal structure defining a texture effect.
147        */
148        struct TextureEffect {
149            TextureEffectType type;
150            int subtype;
151            Real arg1, arg2;
152            WaveformType waveType;
153            Real base;
154            Real frequency;
155            Real phase;
156            Real amplitude;
157            Controller<Real>* controller;
158            const Frustum* frustum;
159        };
160
161        /** Texture effects in a multimap paired array
162        */
163        typedef std::multimap<TextureEffectType, TextureEffect> EffectMap;
164
165        /** Default constructor.
166        */
167        TextureUnitState(Pass* parent);
168
169        TextureUnitState(Pass* parent, const TextureUnitState& oth );
170
171        TextureUnitState & operator = ( const TextureUnitState& oth );
172
173        /** Default destructor.
174        */
175        ~TextureUnitState();
176
177        /** Name-based constructor.
178        @param
179        name The basic name of the texture e.g. brickwall.jpg, stonefloor.png
180        @param
181        texCoordSet The index of the texture coordinate set to use.
182        */
183                TextureUnitState( Pass* parent, const String& texName, unsigned int texCoordSet = 0);
184
185        /** Get the name of current texture image for this layer.
186        @remarks
187        This will either always be a single name for this layer,
188        or will be the name of the current frame for an animated
189        or otherwise multi-frame texture.
190        @note
191        Applies to both fixed-function and programmable pipeline.
192        */
193        const String& getTextureName(void) const;
194
195        /** Sets this texture layer to use a single texture, given the
196        name of the texture to use on this layer.
197        @note
198        Applies to both fixed-function and programmable pipeline.
199        */
200        void setTextureName( const String& name, TextureType ttype = TEX_TYPE_2D, int mipmaps = -1, bool isAlpha = false);
201
202        /** Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube.
203        @remarks
204        Cubic textures are made up of 6 separate texture images. Each one of these is an orthoganal view of the
205        world with a FOV of 90 degrees and an aspect ratio of 1:1. You can generate these from 3D Studio by
206        rendering a scene to a reflection map of a transparent cube and saving the output files.
207        @par
208        Cubic maps can be used either for skyboxes (complete wrap-around skies, like space) or as environment
209        maps to simulate reflections. The system deals with these 2 scenarios in different ways:
210        <ol>
211        <li>
212        <p>
213        for cubic environment maps, the 6 textures are combined into a single 'cubic' texture map which
214        is then addressed using 3D texture coordinates. This is required because you don't know what
215        face of the box you're going to need to address when you render an object, and typically you
216        need to reflect more than one face on the one object, so all 6 textures are needed to be
217        'active' at once. Cubic environment maps are enabled by calling this method with the forUVW
218        parameter set to true, and then calling setEnvironmentMap(true).
219        </p>
220        <p>
221        Note that not all cards support cubic environment mapping.
222        </p>
223        </li>
224        <li>
225        <p>
226        for skyboxes, the 6 textures are kept separate and used independently for each face of the skybox.
227        This is done because not all cards support 3D cubic maps and skyboxes do not need to use 3D
228        texture coordinates so it is simpler to render each face of the box with 2D coordinates, changing
229        texture between faces.
230        </p>
231        <p>
232        Skyboxes are created by calling SceneManager::setSkyBox.
233        </p>
234        </li>
235        </ul>
236        @note
237        Applies to both fixed-function and programmable pipeline.
238        @param
239        name The basic name of the texture e.g. brickwall.jpg, stonefloor.png. There must be 6 versions
240        of this texture with the suffixes _fr, _bk, _up, _dn, _lf, and _rt (before the extension) which
241        make up the 6 sides of the box. The textures must all be the same size and be powers of 2 in width & height.
242        If you can't make your texture names conform to this, use the alternative method of the same name which takes
243        an array of texture names instead.
244        @param
245        forUVW Set to true if you want a single 3D texture addressable with 3D texture coordinates rather than
246        6 separate textures. Useful for cubic environment mapping.
247        */
248        void setCubicTextureName( const String& name, bool forUVW = false );
249
250        /** Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube.
251        @remarks
252        Cubic textures are made up of 6 separate texture images. Each one of these is an orthoganal view of the
253        world with a FOV of 90 degrees and an aspect ratio of 1:1. You can generate these from 3D Studio by
254        rendering a scene to a reflection map of a transparent cube and saving the output files.
255        @par
256        Cubic maps can be used either for skyboxes (complete wrap-around skies, like space) or as environment
257        maps to simulate reflections. The system deals with these 2 scenarios in different ways:
258        <ol>
259        <li>
260        <p>
261        for cubic environment maps, the 6 textures are combined into a single 'cubic' texture map which
262        is then addressed using 3D texture coordinates. This is required because you don't know what
263        face of the box you're going to need to address when you render an object, and typically you
264        need to reflect more than one face on the one object, so all 6 textures are needed to be
265        'active' at once. Cubic environment maps are enabled by calling this method with the forUVW
266        parameter set to true, and then calling setEnvironmentMap(true).
267        </p>
268        <p>
269        Note that not all cards support cubic environment mapping.
270        </p>
271        </li>
272        <li>
273        <p>
274        for skyboxes, the 6 textures are kept separate and used independently for each face of the skybox.
275        This is done because not all cards support 3D cubic maps and skyboxes do not need to use 3D
276        texture coordinates so it is simpler to render each face of the box with 2D coordinates, changing
277        texture between faces.
278        </p>
279        <p>
280        Skyboxes are created by calling SceneManager::setSkyBox.
281        </p>
282        </li>
283        </ul>
284        @note
285        Applies to both fixed-function and programmable pipeline.
286        @param
287        name The basic name of the texture e.g. brickwall.jpg, stonefloor.png. There must be 6 versions
288        of this texture with the suffixes _fr, _bk, _up, _dn, _lf, and _rt (before the extension) which
289        make up the 6 sides of the box. The textures must all be the same size and be powers of 2 in width & height.
290        If you can't make your texture names conform to this, use the alternative method of the same name which takes
291        an array of texture names instead.
292        @param
293        forUVW Set to true if you want a single 3D texture addressable with 3D texture coordinates rather than
294        6 separate textures. Useful for cubic environment mapping.
295        */
296        void setCubicTextureName( const String* const names, bool forUVW = false );
297
298        /** Sets the names of the texture images for an animated texture.
299        @remarks
300        Animated textures are just a series of images making up the frames of the animation. All the images
301        must be the same size, and their names must have a frame number appended before the extension, e.g.
302        if you specify a name of "wall.jpg" with 3 frames, the image names must be "wall_0.jpg", "wall_1.jpg"
303        and "wall_2.jpg".
304        @par
305        You can change the active frame on a texture layer by calling the setCurrentFrame method.
306        @note
307        If you can't make your texture images conform to the naming standard layed out here, you
308        can call the alternative setAnimatedTextureName method which takes an array of names instead.
309        @note
310        Applies to both fixed-function and programmable pipeline.
311        @param
312        name The base name of the textures to use e.g. wall.jpg for frames wall_0.jpg, wall_1.jpg etc.
313        @param
314        numFrames The number of frames in the sequence.
315        @param
316        duration The length of time it takes to display the whole animation sequence, in seconds.
317        If 0, no automatic transition occurs.
318        */
319        void setAnimatedTextureName( const String& name, unsigned int numFrames, Real duration = 0 );
320
321        /** Sets the names of the texture images for an animated texture.
322        @remarks
323        This an alternative method to the one where you specify a single name and let the system derive
324        the names of each frame, incase your images can't conform to this naming standard.
325        @par
326        Animated textures are just a series of images making up the frames of the animation. All the images
327        must be the same size, and you must provide their names as an array in the first parameter.
328        You can change the active frame on a texture layer by calling the setCurrentFrame method.
329        @note
330        If you can make your texture images conform to a naming standard of basicName_frame.ext, you
331        can call the alternative setAnimatedTextureName method which just takes a base name instead.
332        @note
333        Applies to both fixed-function and programmable pipeline.
334        @param
335        names Pointer to array of names of the textures to use, in frame order.
336        @param
337        numFrames The number of frames in the sequence.
338        @param
339        duration The length of time it takes to display the whole animation sequence, in seconds.
340        If 0, no automatic transition occurs.
341        */
342        void setAnimatedTextureName( const String* const names, unsigned int numFrames, Real duration = 0 );
343
344        /** Returns the width and height of the texture in the given frame.
345        */
346        std::pair< uint, uint > getTextureDimensions( unsigned int frame = 0 ) const;
347
348        /** Changes the active frame in an animated or multi-image texture.
349        @remarks
350        An animated texture (or a cubic texture where the images are not combined for 3D use) is made up of
351        a number of frames. This method sets the active frame.
352        @note
353        Applies to both fixed-function and programmable pipeline.
354        */
355        void setCurrentFrame( unsigned int frameNumber );
356
357        /** Gets the active frame in an animated or multi-image texture layer.
358        @note
359        Applies to both fixed-function and programmable pipeline.
360        */
361        unsigned int getCurrentFrame(void) const;
362
363        /** Gets the name of the texture associated with a frame number.
364            Throws an exception if frameNumber exceeds the number of stored frames.
365        @note
366        Applies to both fixed-function and programmable pipeline.
367        */
368        const String& getFrameTextureName(unsigned int frameNumber) const;
369
370        /** Sets the name of the texture associated with a frame.
371        @param name The name of the texture
372        @param frameNumber The frame the texture name is to be placed in
373        @note
374        Throws an exception if frameNumber exceeds the number of stored frames.
375        Applies to both fixed-function and programmable pipeline.
376        */
377        void setFrameTextureName(const String& name, unsigned int frameNumber);
378
379        /** Add a Texture name to the end of the frame container.
380        @param name The name of the texture
381        @note
382        Applies to both fixed-function and programmable pipeline.
383        */
384        void addFrameTextureName(const String& name);
385        /** deletes a specific texture frame.  The texture used is not deleted but the
386            texture will no longer be used by the Texture Unit.  An exception is raised
387            if the frame number exceeds the number of actual frames.
388        @param frameNumber The frame number of the texture to be deleted.
389        @note
390        Applies to both fixed-function and programmable pipeline.
391        */
392        void deleteFrameTextureName(const size_t frameNumber);
393        /** Gets the number of frames for a texture.
394        @note
395        Applies to both fixed-function and programmable pipeline.
396        */
397        unsigned int getNumFrames(void) const;
398
399        /** Returns true if this texture unit is either a series of 6 2D textures, each
400            in it's own frame, or is a full 3D cube map. You can tell which by checking
401            getTextureType.
402        @note
403        Applies to both fixed-function and programmable pipeline.
404        */
405        bool isCubic(void) const;
406
407        /** Returns true if this texture layer uses a composite 3D cubic texture.
408        @note
409        Applies to both fixed-function and programmable pipeline.
410        */
411        bool is3D(void) const;
412
413        /** Returns the type of this texture.
414        @note
415        Applies to both fixed-function and programmable pipeline.
416        */
417        TextureType getTextureType(void) const;
418
419        /** Gets the index of the set of texture co-ords this layer uses.
420        @note
421        Applies to both fixed-function and programmable pipeline.
422        */
423        unsigned int getTextureCoordSet(void) const;
424
425        /** Sets the index of the set of texture co-ords this layer uses.
426        @note
427        Default is 0 for all layers. Only change this if you have provided multiple texture co-ords per
428        vertex.
429        @note
430        Applies to both fixed-function and programmable pipeline.
431        */
432        void setTextureCoordSet(unsigned int set);
433
434        /** Sets a matrix used to transform any texture coordinates on this layer.
435        @remarks
436        Texture coordinates can be modified on a texture layer to create effects like scrolling
437        textures. A texture transform can either be applied to a layer which takes the source coordinates
438        from a fixed set in the geometry, or to one which generates them dynamically (e.g. environment mapping).
439        @par
440        It's obviously a bit impractical to create scrolling effects by calling this method manually since you
441        would have to call it every framw with a slight alteration each time, which is tedious. Instead
442        you can use the ControllerManager class to create a Controller object which will manage the
443        effect over time for you. See the ControllerManager::createTextureScroller and it's sibling methods for details.<BR>
444        In addition, if you want to set the individual texture transformations rather than concatenating them
445        yourself, use setTextureScroll, setTextureScale and setTextureRotate.
446        @note
447        Has no effect in the programmable pipeline.
448        */
449        void setTextureTransform(const Matrix4& xform);
450
451        /** Gets the current texture transformation matrix.
452        @remarks
453        Causes a reclaculation of the matrix if any parameters have been changed via
454        setTextureScroll, setTextureScale and setTextureRotate.
455        @note
456        Has no effect in the programmable pipeline.
457        */
458        const Matrix4& getTextureTransform(void) const;
459
460        /** Sets the translation offset of the texture, ie scrolls the texture.
461        @remarks
462        This method sets the translation element of the texture transformation, and is easier to use than setTextureTransform if
463        you are combining translation, scaling and rotation in your texture transformation. Again if you want
464        to animate these values you need to use a Controller
465        @note
466        Has no effect in the programmable pipeline.
467        @param u The amount the texture should be moved horizontally (u direction).
468        @param v The amount the texture should be moved vertically (v direction).
469        @see
470        ControllerManager, Controller
471        */
472        void setTextureScroll(Real u, Real v);
473
474        /** As setTextureScroll, but sets only U value.
475        @note
476        Has no effect in the programmable pipeline.
477        */
478        void setTextureUScroll(Real value);
479        // get texture uscroll value
480        Real getTextureUScroll(void) const;
481
482        /** As setTextureScroll, but sets only V value.
483        @note
484        Has no effect in the programmable pipeline.
485        */
486        void setTextureVScroll(Real value);
487        // get texture vscroll value
488        Real getTextureVScroll(void) const;
489
490        /** As setTextureScale, but sets only U value.
491        @note
492        Has no effect in the programmable pipeline.
493        */
494        void setTextureUScale(Real value);
495        // get texture uscale value
496        Real getTextureUScale(void) const;
497
498        /** As setTextureScale, but sets only V value.
499        @note
500        Has no effect in the programmable pipeline.
501        */
502        void setTextureVScale(Real value);
503        // get texture vscale value
504        Real getTextureVScale(void) const;
505
506        /** Sets the scaling factor applied to texture coordinates.
507        @remarks
508        This method sets the scale element of the texture transformation, and is easier to use than
509        setTextureTransform if you are combining translation, scaling and rotation in your texture transformation. Again if you want
510        to animate these values you need to use a Controller (see ControllerManager and it's methods for
511        more information).
512        @note
513        Has no effect in the programmable pipeline.
514        @param
515        uScale The value by which the texture is to be scaled horizontally.
516        @param
517        vScale The value by which the texture is to be scaled vertically.
518        */
519        void setTextureScale(Real uScale, Real vScale);
520
521        /** Sets the anticlockwise rotation factor applied to texture coordinates.
522        @remarks
523        This sets a fixed rotation angle - if you wish to animate this, see the
524        ControllerManager::createTextureRotater method.
525        @note
526        Has no effect in the programmable pipeline.
527        @param
528        angle The angle of rotation (anticlockwise).
529        */
530        void setTextureRotate(const Radian& angle);
531#ifndef OGRE_FORCE_ANGLE_TYPES
532        inline void setTextureRotate(Real angle) {
533            setTextureRotate ( Degree(angle) );
534        }
535#endif//OGRE_FORCE_ANGLE_TYPES
536        // get texture rotation effects angle value
537        const Radian& getTextureRotate(void) const;
538
539        /** Gets the texture addressing mode for a given coordinate,
540                        i.e. what happens at uv values above 1.0.
541        @note
542                The default is TAM_WRAP i.e. the texture repeats over values of 1.0.
543        */
544        const UVWAddressingMode& getTextureAddressingMode(void) const;
545
546        /** Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
547        @note
548        The default is TAM_WRAP i.e. the texture repeats over values of 1.0.
549                @note This is a shortcut method which sets the addressing mode for all
550                        coordinates at once; you can also call the more specific method
551                        to set the addressing mode per coordinate.
552        @note
553        This applies for both the fixed-function and programmable pipelines.
554        */
555        void setTextureAddressingMode( TextureAddressingMode tam);
556
557        /** Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
558        @note
559        The default is TAM_WRAP i.e. the texture repeats over values of 1.0.
560        @note
561        This applies for both the fixed-function and programmable pipelines.
562                */
563        void setTextureAddressingMode( TextureAddressingMode u,
564                        TextureAddressingMode v, TextureAddressingMode w);
565
566        /** Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
567        @note
568        The default is TAM_WRAP i.e. the texture repeats over values of 1.0.
569        @note
570        This applies for both the fixed-function and programmable pipelines.
571                */
572        void setTextureAddressingMode( const UVWAddressingMode& uvw);
573
574        /** Sets the texture border colour.
575        @note
576            The default is ColourValue::Black, and this value only used when addressing mode
577            is TAM_BORDER.
578        @note
579            This applies for both the fixed-function and programmable pipelines.
580                */
581        void setTextureBorderColour(const ColourValue& colour);
582
583        /** Sets the texture border colour.
584        @note
585            The default is ColourValue::Black, and this value only used when addressing mode
586            is TAM_BORDER.
587                */
588        const ColourValue& getTextureBorderColour(void) const;
589
590                /** Setting advanced blending options.
591        @remarks
592        This is an extended version of the TextureUnitState::setColourOperation method which allows
593        extremely detailed control over the blending applied between this and earlier layers.
594        See the IMPORTANT note below about the issues between mulitpass and multitexturing that
595        using this method can create.
596        @par
597        Texture colour operations determine how the final colour of the surface appears when
598        rendered. Texture units are used to combine colour values from various sources (ie. the
599        diffuse colour of the surface from lighting calculations, combined with the colour of
600        the texture). This method allows you to specify the 'operation' to be used, ie. the
601        calculation such as adds or multiplies, and which values to use as arguments, such as
602        a fixed value or a value from a previous calculation.
603        @par
604        The defaults for each layer are:
605        <ul>
606        <li>op = LBX_MODULATE</li>
607        <li>source1 = LBS_TEXTURE</li>
608        <li>source2 = LBS_CURRENT</li>
609        </ul>
610        ie. each layer takes the colour results of the previous layer, and multiplies them
611        with the new texture being applied. Bear in mind that colours are RGB values from
612        0.0 - 1.0 so multiplying them together will result in values in the same range,
613        'tinted' by the multiply. Note however that a straight multiply normally has the
614        effect of darkening the textures - for this reason there are brightening operations
615        like LBO_MODULATE_X2. See the LayerBlendOperation and LayerBlendSource enumerated
616        types for full details.
617        @note
618        Because of the limitations on some underlying APIs (Direct3D included)
619        the LBS_TEXTURE argument can only be used as the first argument, not the second.
620        @par
621        The final 3 parameters are only required if you decide to pass values manually
622        into the operation, i.e. you want one or more of the inputs to the colour calculation
623        to come from a fixed value that you supply. Hence you only need to fill these in if
624        you supply LBS_MANUAL to the corresponding source, or use the LBX_BLEND_MANUAL
625        operation.
626        @warning
627        Ogre tries to use multitexturing hardware to blend texture layers
628        together. However, if it runs out of texturing units (e.g. 2 of a GeForce2, 4 on a
629        GeForce3) it has to fall back on multipass rendering, i.e. rendering the same object
630        multiple times with different textures. This is both less efficient and there is a smaller
631        range of blending operations which can be performed. For this reason, if you use this method
632        you MUST also call TextureUnitState::setColourOpMultipassFallback to specify which effect you
633        want to fall back on if sufficient hardware is not available.
634        @note
635        This has no effect in the programmable pipeline.
636        @param
637        If you wish to avoid having to do this, use the simpler TextureUnitState::setColourOperation method
638        which allows less flexible blending options but sets up the multipass fallback automatically,
639        since it only allows operations which have direct multipass equivalents.
640        @param
641        op The operation to be used, e.g. modulate (multiply), add, subtract
642        @param
643        source1 The source of the first colour to the operation e.g. texture colour
644        @param
645        source2 The source of the second colour to the operation e.g. current surface colour
646        @param
647        arg1 Manually supplied colour value (only required if source1 = LBS_MANUAL)
648        @param
649        arg2 Manually supplied colour value (only required if source2 = LBS_MANUAL)
650        @param
651        manualBlend Manually supplied 'blend' value - only required for operations
652        which require manual blend e.g. LBX_BLEND_MANUAL
653        */
654        void setColourOperationEx(
655            LayerBlendOperationEx op,
656            LayerBlendSource source1 = LBS_TEXTURE,
657            LayerBlendSource source2 = LBS_CURRENT,
658
659            const ColourValue& arg1 = ColourValue::White,
660            const ColourValue& arg2 = ColourValue::White,
661
662            Real manualBlend = 0.0);
663
664        /** Determines how this texture layer is combined with the one below it (or the diffuse colour of
665        the geometry if this is layer 0).
666        @remarks
667        This method is the simplest way to blend tetxure layers, because it requires only one parameter,
668        gives you the most common blending types, and automatically sets up 2 blending methods: one for
669        if single-pass multitexturing hardware is available, and another for if it is not and the blending must
670        be achieved through multiple rendering passes. It is, however, quite limited and does not expose
671        the more flexible multitexturing operations, simply because these can't be automatically supported in
672        multipass fallback mode. If want to use the fancier options, use TextureUnitState::setColourOperationEx,
673        but you'll either have to be sure that enough multitexturing units will be available, or you should
674        explicitly set a fallback using TextureUnitState::setColourOpMultipassFallback.
675        @note
676        The default method is LBO_MODULATE for all layers.
677        @note
678        This option has no effect in the programmable pipeline.
679        @param
680        op One of the LayerBlendOperation enumerated blending types.
681        */
682        void setColourOperation( const LayerBlendOperation op);
683
684        /** Sets the multipass fallback operation for this layer, if you used TextureUnitState::setColourOperationEx
685        and not enough multitexturing hardware is available.
686        @remarks
687        Because some effects exposed using TextureUnitState::setColourOperationEx are only supported under
688        multitexturing hardware, if the hardware is lacking the system must fallback on multipass rendering,
689        which unfortunately doesn't support as many effects. This method is for you to specify the fallback
690        operation which most suits you.
691        @par
692        You'll notice that the interface is the same as the Material::setSceneBlending method; this is
693        because multipass rendering IS effectively scene blending, since each layer is rendered on top
694        of the last using the same mechanism as making an object transparent, it's just being rendered
695        in the same place repeatedly to get the multitexture effect.
696        @par
697        If you use the simpler (and hence less flexible) TextureUnitState::setColourOperation method you
698        don't need to call this as the system sets up the fallback for you.
699        @note
700        This option has no effect in the programmable pipeline, because there is no multipass fallback
701        and multitexture blending is handled by the fragment shader.
702        */
703        void setColourOpMultipassFallback( const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor);
704
705        /** Get multitexturing colour blending mode.
706        */
707        const LayerBlendModeEx& getColourBlendMode(void) const;
708
709        /** Get multitexturing alpha blending mode.
710        */
711        const LayerBlendModeEx& getAlphaBlendMode(void) const;
712
713        /** Get the multipass fallback for colour blending operation source factor.
714        */
715        SceneBlendFactor getColourBlendFallbackSrc(void) const;
716
717        /** Get the multipass fallback for colour blending operation destination factor.
718        */
719        SceneBlendFactor getColourBlendFallbackDest(void) const;
720
721        /** Sets the alpha operation to be applied to this texture.
722        @remarks
723        This works in exactly the same way as setColourOperation, except
724        that the effect is applied to the level of alpha (i.e. transparency)
725        of the texture rather than its colour. When the alpha of a texel (a pixel
726        on a texture) is 1.0, it is opaque, wheras it is fully transparent if the
727        alpha is 0.0. Please refer to the setColourOperation method for more info.
728        @param
729        op The operation to be used, e.g. modulate (multiply), add, subtract
730        @param
731        source1 The source of the first alpha value to the operation e.g. texture alpha
732        @param
733        source2 The source of the second alpha value to the operation e.g. current surface alpha
734        @param
735        arg1 Manually supplied alpha value (only required if source1 = LBS_MANUAL)
736        @param
737        arg2 Manually supplied alpha value (only required if source2 = LBS_MANUAL)
738        @param
739        manualBlend Manually supplied 'blend' value - only required for operations
740        which require manual blend e.g. LBX_BLEND_MANUAL
741        @see
742        setColourOperation
743        @note
744        This option has no effect in the programmable pipeline.
745        */
746        void setAlphaOperation(LayerBlendOperationEx op,
747            LayerBlendSource source1 = LBS_TEXTURE,
748            LayerBlendSource source2 = LBS_CURRENT,
749            Real arg1 = 1.0,
750            Real arg2 = 1.0,
751            Real manualBlend = 0.0);
752
753        /** Generic method for setting up texture effects.
754        @remarks
755        Allows you to specify effects directly by using the TextureEffectType enumeration. The
756        arguments that go with it depend on the effect type. Only one effect of
757        each type can be applied to a texture layer.
758        @par
759        This method is used internally by Ogre but it is better generally for applications to use the
760        more intuitive specialised methods such as setEnvironmentMap and setScroll.
761        @note
762        This option has no effect in the programmable pipeline.
763        */
764        void addEffect(TextureEffect& effect);
765
766        /** Turns on/off texture coordinate effect that makes this layer an environment map.
767        @remarks
768        Environment maps make an object look reflective by using the object's vertex normals relative
769        to the camera view to generate texture coordinates.
770        @par
771        The vectors generated can either be used to address a single 2D texture which
772        is a 'fish-eye' lens view of a scene, or a 3D cubic environment map which requires 6 textures
773        for each side of the inside of a cube. The type depends on what texture you set up - if you use the
774        setTextureName method then a 2D fisheye lens texture is required, whereas if you used setCubicTextureName
775        then a cubic environemnt map will be used.
776        @par
777        This effect works best if the object has lots of gradually changing normals. The texture also
778        has to be designed for this effect - see the example spheremap.png included with the sample
779        application for a 2D environment map; a cubic map can be generated by rendering 6 views of a
780        scene to each of the cube faces with orthoganal views.
781        @note
782        Enabling this disables any other texture coordinate generation effects.
783        However it can be combined with texture coordinate modification functions, which then operate on the
784        generated coordinates rather than static model texture coordinates.
785        @param
786        enable True to enable, false to disable
787        @param
788        planar If set to true, instead of being based on normals the environment effect is based on
789        vertex positions. This is good for planar surfaces.
790        @note
791        This option has no effect in the programmable pipeline.
792        */
793        void setEnvironmentMap(bool enable, EnvMapType envMapType = ENV_CURVED);
794
795        /** Sets up an animated scroll for the texture layer.
796        @note
797        Useful for creating constant scrolling effects on a texture layer (for varying scrolls, see setTransformAnimation).
798        @param
799        uSpeed The number of horizontal loops per second (+ve=moving right, -ve = moving left)
800        @param
801        vSpeed The number of vertical loops per second (+ve=moving up, -ve= moving down)
802        @note
803        This option has no effect in the programmable pipeline.
804        */
805        void setScrollAnimation(Real uSpeed, Real vSpeed);
806
807        /** Sets up an animated texture rotation for this layer.
808        @note
809        Useful for constant rotations (for varying rotations, see setTransformAnimation).
810        @param
811        speed The number of complete anticlockwise revolutions per second (use -ve for clockwise)
812        @note
813        This option has no effect in the programmable pipeline.
814        */
815        void setRotateAnimation(Real speed);
816
817        /** Sets up a general time-relative texture modification effect.
818        @note
819        This can be called multiple times for different values of ttype, but only the latest effect
820        applies if called multiple time for the same ttype.
821        @param
822        ttype The type of transform, either translate (scroll), scale (stretch) or rotate (spin)
823        @param
824        waveType The shape of the wave, see WaveformType enum for details
825        @param
826        base The base value for the function (range of output = {base, base + amplitude})
827        @param
828        frequency The speed of the wave in cycles per second
829        @param
830        phase The offset of the start of the wave, e.g. 0.5 to start half-way through the wave
831        @param
832        amplitude Scales the output so that instead of lying within 0..1 it lies within 0..1*amplitude for exaggerated effects
833        @note
834        This option has no effect in the programmable pipeline.
835        */
836        void setTransformAnimation( const TextureTransformType ttype,
837            const WaveformType waveType, Real base = 0, Real frequency = 1, Real phase = 0, Real amplitude = 1 );
838
839
840        /** Enables or disables projective texturing on this texture unit.
841        @remarks
842            Projective texturing allows you to generate texture coordinates
843            based on a Frustum, which gives the impression that a texture is
844            being projected onto the surface. Note that once you have called
845            this method, the texture unit continues to monitor the Frustum you
846            passed in and the projection will change if you can alter it. It also
847            means that you must ensure that the Frustum object you pass a pointer
848            to remains in existence for as long as this TextureUnitState does.
849        @par
850            This effect cannot be combined with other texture generation effects,
851            such as environment mapping. It also has no effect on passes which
852            have a vertex program enabled - projective texturing has to be done
853            in the vertex program instead.
854        @param enabled Whether to enable / disable
855        @param projectionSettings The Frustum which will be used to derive the
856            projection parameters.
857        */
858        void setProjectiveTexturing(bool enabled, const Frustum* projectionSettings = 0);
859
860        /** Removes all effects applied to this texture layer.
861        */
862        void removeAllEffects(void);
863
864        /** Removes a single effect applied to this texture layer.
865        @note
866        Because you can only have 1 effect of each type (e.g. 1 texture coordinate generation) applied
867        to a layer, only the effect type is required.
868        */
869        void removeEffect( const TextureEffectType type );
870
871        /** Determines if this texture layer is currently blank.
872        @note
873        This can happen if a texture fails to load or some other non-fatal error. Worth checking after
874        setting texture name.
875        */
876        bool isBlank(void) const;
877
878        /** Sets this texture layer to be blank.
879        */
880        void setBlank(void);
881
882        // get texture effects in a multimap paired array
883        const EffectMap& getEffects(void) const;
884        // get the animated-texture animation duration
885        Real getAnimationDuration(void) const;
886
887        /** Set the texture filtering for this unit, using the simplified interface.
888        @remarks
889            You also have the option of specifying the minification, magnification
890            and mip filter individually if you want more control over filtering
891            options. See the alternative setTextureFiltering methods for details.
892        @note
893        This option applies in both the fixed function and the programmable pipeline.
894        @param filterType The high-level filter type to use.
895        */
896        void setTextureFiltering(TextureFilterOptions filterType);
897        /** Set a single filtering option on this texture unit.
898        @params ftype The filtering type to set
899        @params opts The filtering option to set
900        */
901        void setTextureFiltering(FilterType ftype, FilterOptions opts);
902        /** Set a the detailed filtering options on this texture unit.
903        @params minFilter The filtering to use when reducing the size of the texture.
904            Can be FO_POINT, FO_LINEAR or FO_ANISOTROPIC
905        @params magFilter The filtering to use when increasing the size of the texture
906            Can be FO_POINT, FO_LINEAR or FO_ANISOTROPIC
907        @params mipFilter The filtering to use between mip levels
908            Can be FO_NONE (turns off mipmapping), FO_POINT or FO_LINEAR (trilinear filtering)
909        */
910        void setTextureFiltering(FilterOptions minFilter, FilterOptions magFilter, FilterOptions mipFilter);
911        // get the texture filtering for the given type
912        FilterOptions getTextureFiltering(FilterType ftpye) const;
913
914        /** Sets the anisotropy level to be used for this texture level.
915        @par maxAniso The maximal anisotropy level, should be between 2 and the maximum supported by hardware (1 is the default, ie. no anisotrophy).
916        @note
917        This option applies in both the fixed function and the programmable pipeline.
918        */
919        void setTextureAnisotropy(unsigned int maxAniso);
920        // get this layer texture anisotropy level
921        unsigned int getTextureAnisotropy() const;
922
923        /// Gets the parent Pass object
924        Pass* getParent(void) const { return mParent; }
925
926                /** Internal method for loading this object as part of Material::load */
927                void _load(void);
928                /** Internal method for unloading this object as part of Material::unload */
929                void _unload(void);
930        /// Returns whether this unit has texture coordinate generation that depends on the camera
931        bool hasViewRelativeTextureCoordinateGeneration(void);
932
933        // Is this loaded?
934        bool isLoaded(void);
935        /** Tells the class that it needs recompilation. */
936        void _notifyNeedsRecompile(void);
937
938        /** Set the name of the Texture Unit State
939        @remarks
940            The name of the Texture Unit State is optional.  Its usefull in material scripts where a material could inherit
941            from another material and only want to modify a particalar Texture Unit State.
942        */
943        void setName(const String& name);
944        /// get the name of the Texture Unit State
945        const String& getName(void) const { return mName; }
946
947        /** Set the alias name used for texture frame names
948        @param name can be any sequence of characters and does not have to be unique           
949        */
950        void setTextureNameAlias(const String& name);
951        /** gets the Texture Name Alias of the Texture Unit.
952        */
953        const String& getTextureNameAlias(void) const { return mTextureNameAlias;}
954
955        /** Applies texture names to Texture Unit State with matching texture name aliases.
956            If no matching aliases are found then the TUS state does not change.
957        @remarks
958            Cubic, 1d, 2d, and 3d textures are determined from current state of the Texture Unit.
959            Assumes animated frames are sequentially numbered in the name.
960            If matching texture aliases are found then true is returned.
961
962        @param
963            aliasList is a map container of texture alias, texture name pairs
964        @param
965            apply set true to apply the texture aliases else just test to see if texture alias matches are found.
966        @return
967            True if matching texture aliases were found in the Texture Unit State.
968        */
969        bool applyTextureAliases(const AliasTextureNamePairList& aliasList, const bool apply = true);
970
971                /** Notify this object that its parent has changed */
972                void _notifyParent(Pass* parent);
973       
974protected:
975        // State
976        /// The current animation frame.
977        unsigned int mCurrentFrame;
978
979        /// Duration of animation in seconds
980        Real mAnimDuration;           
981        bool mCubic; // is this a series of 6 2D textures to make up a cube?
982               
983        TextureType mTextureType;
984                int mTextureSrcMipmaps; // Request number of mipmaps
985
986        unsigned int mTextureCoordSetIndex;
987        UVWAddressingMode mAddressMode;
988        ColourValue mBorderColour;
989
990        LayerBlendModeEx colourBlendMode;
991        SceneBlendFactor colourBlendFallbackSrc;
992        SceneBlendFactor colourBlendFallbackDest;
993
994        LayerBlendModeEx alphaBlendMode;
995        bool mIsBlank;
996        bool mIsAlpha;
997
998        mutable bool mRecalcTexMatrix;
999        Real mUMod, mVMod;
1000        Real mUScale, mVScale;
1001        Radian mRotate;
1002        mutable Matrix4 mTexModMatrix;
1003
1004        // Animation, will be set up as Controllers
1005        Real mUScrollAnim, mVScrollAnim;
1006        Real mRotateAnim;
1007
1008        /// Texture filtering - minification
1009        FilterOptions mMinFilter;
1010        /// Texture filtering - magnification
1011        FilterOptions mMagFilter;
1012        /// Texture filtering - mipmapping
1013        FilterOptions mMipFilter;
1014        ///Texture anisotropy
1015        unsigned int mMaxAniso;
1016
1017        bool mIsDefaultAniso;
1018        bool mIsDefaultFiltering;
1019
1020
1021        //-----------------------------------------------------------------------------
1022        // Complex members (those that can't be copied using memcpy) are at the end to
1023        // allow for fast copying of the basic members.
1024        //
1025        std::vector<String> mFrames;
1026        String mName;               // optional name for the TUS
1027        String mTextureNameAlias;       // optional alias for texture frames
1028        EffectMap mEffects;
1029        //-----------------------------------------------------------------------------
1030
1031        //-----------------------------------------------------------------------------
1032        // Pointer members (those that can't be copied using memcpy), and MUST
1033        // preserving even if assign from others
1034        //
1035        Pass* mParent;
1036        Controller<Real>* mAnimController;
1037        //-----------------------------------------------------------------------------
1038
1039
1040        /** Internal method for calculating texture matrix.
1041        */
1042        void recalcTextureMatrix(void) const;
1043
1044        /** Internal method for creating animation controller.
1045        */
1046        void createAnimController(void);
1047
1048        /** Internal method for creating texture effect controller.
1049        */
1050        void createEffectController(TextureEffect& effect);
1051
1052
1053    };
1054
1055
1056}
1057
1058#endif
Note: See TracBrowser for help on using the repository browser.