Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreTextureUnitState.h @ 5

Last change on this file since 5 was 5, checked in by anonymous, 17 years ago

=hoffentlich gehts jetzt

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