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

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

added ogre dependencies and patched ogre sources

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