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

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