root/OpenSceneGraph/trunk/include/osg/StateSet @ 13041

Revision 13041, 24.0 kB (checked in by robert, 2 years ago)

Ran script to remove trailing spaces and tabs

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2008 Robert Osfield
2 *
3 * This library is open source and may be redistributed and/or modified under
4 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
5 * (at your option) any later version.  The full license is in LICENSE file
6 * included with this distribution, and on the openscenegraph.org website.
7 *
8 * This library is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 * OpenSceneGraph Public License for more details.
12*/
13
14#ifndef OSG_STATESET
15#define OSG_STATESET 1
16
17#include <osg/Object>
18#include <osg/StateAttribute>
19#include <osg/ref_ptr>
20#include <osg/Uniform>
21
22#include <map>
23#include <vector>
24#include <string>
25
26#ifndef GL_RESCALE_NORMAL
27// allow compilation against GL1.1 headers.
28#define GL_RESCALE_NORMAL                 0x803A
29#endif
30
31namespace osg {
32
33// forward declare for the purposes of the UpdateCallback.
34class NodeVisitor;
35
36/** Stores a set of modes and attributes which represent a set of OpenGL state.
37  *  Notice that a \c StateSet contains just a subset of the whole OpenGL state.
38  * <p>In OSG, each \c Drawable and each \c Node has a reference to a
39  * \c StateSet. These <tt>StateSet</tt>s can be shared between
40  * different <tt>Drawable</tt>s and <tt>Node</tt>s (that is, several
41  * <tt>Drawable</tt>s and <tt>Node</tt>s can reference the same \c StateSet).
42  * Indeed, this practice is recommended whenever possible,
43  * as this minimizes expensive state changes in the graphics pipeline.
44*/
45class OSG_EXPORT StateSet : public Object
46{
47    public :
48
49
50        StateSet();
51        StateSet(const StateSet&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);
52
53        virtual Object* cloneType() const { return new StateSet(); }
54        virtual Object* clone(const CopyOp& copyop) const { return new StateSet(*this,copyop); }
55        virtual bool isSameKindAs(const Object* obj) const { return dynamic_cast<const StateSet*>(obj)!=NULL; }
56        virtual const char* libraryName() const { return "osg"; }
57        virtual const char* className() const { return "StateSet"; }
58
59        /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/
60        int compare(const StateSet& rhs,bool compareAttributeContents=false) const;
61
62        bool operator <  (const StateSet& rhs) const { return compare(rhs)<0; }
63        bool operator == (const StateSet& rhs) const { return compare(rhs)==0; }
64        bool operator != (const StateSet& rhs) const { return compare(rhs)!=0; }
65
66
67        /** A vector of osg::Object pointers which is used to store the parent(s) of this Stateset, the parents could be osg::Node or osg::Drawable.*/
68        typedef std::vector<Object*> ParentList;
69
70        /** Get the parent list of this StateSet. */
71        inline const ParentList& getParents() const { return _parents; }
72
73        /** Get the a copy of parent list of node. A copy is returned to
74          * prevent modification of the parent list.*/
75        inline ParentList getParents() { return _parents; }
76
77        inline Object* getParent(unsigned int i)  { return _parents[i]; }
78        /**
79         * Get a single const parent of this StateSet.
80         * @param i index of the parent to get.
81         * @return the parent i.
82         */
83        inline const Object* getParent(unsigned int i) const  { return _parents[i]; }
84
85        /**
86         * Get the number of parents of this StateSet.
87         * @return the number of parents of this StateSet.
88         */
89        inline unsigned int getNumParents() const { return static_cast<unsigned int>(_parents.size()); }
90
91
92        /** Compute the DataVariance based on an assessment of callback etc.*/
93        virtual void computeDataVariance();
94
95
96        /** Set all the modes to on or off so that it defines a
97            complete state, typically used for a default global state.*/
98        void setGlobalDefaults();
99
100        /** Clear the StateSet of all modes and attributes.*/
101        void clear();
102
103        /** Merge this \c StateSet with the \c StateSet passed as parameter.
104          * Every mode and attribute in this \c StateSet that is marked with
105          * \c StateAttribute::OVERRIDE is replaced with the
106          * equivalent mode or attribute from \c rhs.
107        */
108        void merge(const StateSet& rhs);
109
110        /** a container to map GLModes to their respective GLModeValues.*/
111        typedef std::map<StateAttribute::GLMode,StateAttribute::GLModeValue>  ModeList;
112
113        /** Set this \c StateSet to contain the specified \c GLMode with a given
114          * value.
115          * @note Don't use this method to set modes related to textures. For this
116          *       purpose, use \c setTextureMode(), that accepts an extra parameter
117          *       specifying which texture unit shall be affected by the call.
118        */
119        void setMode(StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
120
121        /** Remove \c mode from this \c StateSet.
122          * @note Don't use this method to remove modes related to textures. For
123          *       this purpose, use \c removeTextureMode(), that accepts an extra
124          *       parameter specifying which texture unit shall be affected by
125          *       the call.
126        */
127        void removeMode(StateAttribute::GLMode mode);
128
129        /** Get the value for a given \c GLMode.
130          * @param mode The \c GLMode whose value is desired.
131          * @return If \c mode is contained within this \c StateSet, returns the
132          *         value associated with it. Otherwise, returns
133          *         \c StateAttribute::INHERIT.
134          * @note Don't use this method to get the value of modes related to
135          *       textures. For this purpose, use \c removeTextureMode(), that
136          *       accepts an extra parameter specifying which texture unit shall
137          *       be affected by the call.
138        */
139        StateAttribute::GLModeValue getMode(StateAttribute::GLMode mode) const;
140
141        /** Set the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
142        inline void setModeList(ModeList& ml) { _modeList=ml; }
143
144        /** Return the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
145        inline ModeList& getModeList() { return _modeList; }
146
147        /** Return the \c const list of all <tt>GLMode</tt>s contained in this
148          * <tt>const StateSet</tt>.
149        */
150        inline const ModeList& getModeList() const { return _modeList; }
151
152
153
154        /** Simple pairing between an attribute and its override flag.*/
155        typedef std::pair<ref_ptr<StateAttribute>,StateAttribute::OverrideValue>    RefAttributePair;
156
157        /** a container to map <StateAttribyte::Types,Member> to their respective RefAttributePair.*/
158        typedef std::map<StateAttribute::TypeMemberPair,RefAttributePair>           AttributeList;
159
160        /** Set this StateSet to contain specified attribute and override flag.*/
161        void setAttribute(StateAttribute *attribute, StateAttribute::OverrideValue value=StateAttribute::OFF);
162
163        /** Set this StateSet to contain specified attribute and set the associated GLMode's to specified value.*/
164        void setAttributeAndModes(StateAttribute *attribute, StateAttribute::GLModeValue value=StateAttribute::ON);
165
166        /** remove attribute of specified type from StateSet.*/
167        void removeAttribute(StateAttribute::Type type, unsigned int member=0);
168
169        /** remove attribute from StateSet.*/
170        void removeAttribute(StateAttribute *attribute);
171
172        /** Get specified StateAttribute for specified type.
173          * Returns NULL if no type is contained within StateSet.*/
174        StateAttribute* getAttribute(StateAttribute::Type type, unsigned int member = 0);
175
176        /** Get specified const StateAttribute for specified type.
177          * Returns NULL if no type is contained within const StateSet.*/
178        const StateAttribute* getAttribute(StateAttribute::Type type, unsigned int member = 0) const;
179
180        /** Get specified RefAttributePair for specified type.
181          * Returns NULL if no type is contained within StateSet.*/
182        const RefAttributePair* getAttributePair(StateAttribute::Type type, unsigned int member = 0) const;
183
184        /** set the list of all StateAttributes contained in this StateSet.*/
185        inline void setAttributeList(AttributeList& al) { _attributeList=al; }
186
187        /** return the list of all StateAttributes contained in this StateSet.*/
188        inline AttributeList& getAttributeList() { return _attributeList; }
189
190        /** return the const list of all StateAttributes contained in this const StateSet.*/
191        inline const AttributeList& getAttributeList() const { return _attributeList; }
192
193
194
195        typedef std::vector<ModeList>       TextureModeList;
196
197        /** Set this \c StateSet to contain specified \c GLMode with a given
198         *  value.
199         *  @param unit The texture unit to be affected (used with
200         *         multi-texturing).
201         *  @param mode The OpenGL mode to be added to the \c StateSet.
202         *  @param value The value to be assigned to \c mode.
203        */
204        void setTextureMode(unsigned int unit,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
205
206        /** Remove texture mode from StateSet.*/
207        void removeTextureMode(unsigned int unit,StateAttribute::GLMode mode);
208
209        /** Get specified GLModeValue for specified GLMode.
210          * returns INHERIT if no GLModeValue is contained within StateSet.*/
211        StateAttribute::GLModeValue getTextureMode(unsigned int unit,StateAttribute::GLMode mode) const;
212
213        /** set the list of all Texture related GLModes contained in this StateSet.*/
214        inline void setTextureModeList(TextureModeList& tml) { _textureModeList=tml; }
215
216        /** return the list of all Texture related GLModes contained in this StateSet.*/
217        inline TextureModeList& getTextureModeList() { return _textureModeList; }
218
219        /** return the const list of all Texture related GLModes contained in this const StateSet.*/
220        inline const TextureModeList& getTextureModeList() const  { return _textureModeList; }
221
222        /** Return the number texture units active in the TextureModeList.*/
223        inline unsigned int getNumTextureModeLists() const { return _textureModeList.size(); }
224
225        typedef std::vector<AttributeList>  TextureAttributeList;
226
227        /** Set this StateSet to contain specified attribute and override flag.*/
228        void setTextureAttribute(unsigned int unit,StateAttribute *attribute, StateAttribute::OverrideValue value=StateAttribute::OFF);
229        /** Set this StateSet to contain specified attribute and set the associated GLMode's to specified value.*/
230        void setTextureAttributeAndModes(unsigned int unit,StateAttribute *attribute, StateAttribute::GLModeValue value=StateAttribute::ON);
231
232        /** remove texture attribute of specified type from StateSet.*/
233        void removeTextureAttribute(unsigned int unit, StateAttribute::Type type);
234
235        /** remove texture attribute from StateSet.*/
236        void removeTextureAttribute(unsigned int unit, StateAttribute *attribute);
237
238        /** Get specified Texture related StateAttribute for specified type.
239          * Returns NULL if no type is contained within StateSet.*/
240        StateAttribute* getTextureAttribute(unsigned int unit,StateAttribute::Type type);
241
242        /** Get specified Texture related const StateAttribute for specified type.
243          * Returns NULL if no type is contained within const StateSet.*/
244        const StateAttribute* getTextureAttribute(unsigned int unit,StateAttribute::Type type) const;
245
246        /** Get specified Texture related RefAttributePair for specified type.
247          * Returns NULL if no type is contained within StateSet.*/
248        const RefAttributePair* getTextureAttributePair(unsigned int unit,StateAttribute::Type type) const;
249
250        /** Set the list of all Texture related StateAttributes contained in this StateSet.*/
251        inline void setTextureAttributeList(TextureAttributeList& tal) { _textureAttributeList=tal; }
252
253        /** Return the list of all Texture related StateAttributes contained in this StateSet.*/
254        inline TextureAttributeList& getTextureAttributeList() { return _textureAttributeList; }
255
256        /** Return the const list of all Texture related StateAttributes contained in this const StateSet.*/
257        inline const TextureAttributeList& getTextureAttributeList() const { return _textureAttributeList; }
258
259        /** Return the number of texture units active in the TextureAttributeList.*/
260        inline unsigned int getNumTextureAttributeLists() const { return _textureAttributeList.size(); }
261
262
263        void setAssociatedModes(const StateAttribute* attribute, StateAttribute::GLModeValue value);
264        void removeAssociatedModes(const StateAttribute* attribute);
265
266        void setAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute, StateAttribute::GLModeValue value);
267        void removeAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute);
268
269
270
271
272        /** Simple pairing between a Uniform and its override flag.*/
273        typedef std::pair<ref_ptr<Uniform>,StateAttribute::OverrideValue>  RefUniformPair;
274
275        /** a container to map Uniform name to its respective RefUniformPair.*/
276        typedef std::map<std::string,RefUniformPair> UniformList;
277
278        /** Set this StateSet to contain specified uniform and override flag.*/
279        void addUniform(Uniform* uniform, StateAttribute::OverrideValue value=StateAttribute::ON);
280
281        /** remove uniform of specified name from StateSet.*/
282        void removeUniform(const std::string& name);
283
284        /** remove Uniform from StateSet.*/
285        void removeUniform(Uniform* uniform);
286
287        /** Get Uniform for specified name.
288          * Returns NULL if no matching Uniform is contained within StateSet.*/
289        Uniform* getUniform(const std::string& name);
290
291        /** Get Uniform for specified name, if one is not available create it, add it to this StateSet and return a pointer to it.*/
292        Uniform* getOrCreateUniform(const std::string& name, Uniform::Type type, unsigned int numElements=1);
293
294        /** Get const Uniform for specified name.
295          * Returns NULL if no matching Uniform is contained within StateSet.*/
296        const Uniform* getUniform(const std::string& name) const;
297
298        /** Get specified RefUniformPair for specified Uniform name.
299          * Returns NULL if no Uniform is contained within StateSet.*/
300        const RefUniformPair* getUniformPair(const std::string& name) const;
301
302        /** set the list of all Uniforms contained in this StateSet.*/
303        inline void setUniformList(UniformList& al) { _uniformList=al; }
304
305        /** return the list of all Uniforms contained in this StateSet.*/
306        inline UniformList& getUniformList() { return _uniformList; }
307
308        /** return the const list of all Uniforms contained in this const StateSet.*/
309        inline const UniformList& getUniformList() const { return _uniformList; }
310
311        enum RenderingHint
312        {
313            DEFAULT_BIN = 0,
314            OPAQUE_BIN = 1,
315            TRANSPARENT_BIN = 2
316        };
317
318        /** Set the \c RenderingHint of this \c StateSet. \c RenderingHint is
319          * used by the renderer to determine which draw bin to drop associated
320          * <tt>osg::Drawable</tt>s in. Typically, users will set this to either
321          * \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN.
322          * <tt>Drawable</tt>s in the opaque bin are sorted by their
323          * \c StateSet, so that the number of expensive changes in the OpenGL
324          * state is minimized. <tt>Drawable</tt>s in the transparent bin are
325          * sorted by depth, so that objects farther from the viewer are
326          * rendered first (and hence alpha blending works nicely for
327          * translucent objects).
328        */
329        void setRenderingHint(int hint);
330
331        /** Get the \c RenderingHint of this \c StateSet.*/
332        inline int getRenderingHint() const      { return _renderingHint; }
333
334        enum RenderBinMode
335        {
336            INHERIT_RENDERBIN_DETAILS,
337            USE_RENDERBIN_DETAILS,
338            OVERRIDE_RENDERBIN_DETAILS
339        };
340
341        /** Set the render bin details.*/
342        void setRenderBinDetails(int binNum,const std::string& binName,RenderBinMode mode=USE_RENDERBIN_DETAILS);
343
344        /** Set the render bin details to inherit.*/
345        void setRenderBinToInherit();
346
347        /** Get whether the render bin details are set and should be used.*/
348        inline bool useRenderBinDetails() const { return _binMode!=INHERIT_RENDERBIN_DETAILS; }
349
350        /** Set the render bin mode.*/
351        inline void setRenderBinMode(RenderBinMode mode) { _binMode=mode; }
352
353        /** Get the render bin mode.*/
354        inline RenderBinMode getRenderBinMode() const { return _binMode; }
355
356        /** Set the render bin number.*/
357        inline void setBinNumber(int num) { _binNum=num; }
358
359        /** Get the render bin number.*/
360        inline int getBinNumber() const { return _binNum; }
361
362        /** Set the render bin name.*/
363        inline void setBinName(const std::string& name) { _binName=name; }
364
365        /** Get the render bin name.*/
366        inline const std::string& getBinName() const { return _binName; }
367
368        /** By default render bins will be nested within each other dependent
369          * upon where they are set in the scene graph. This can be problematic
370          * if a transparent render bin is attached to an opaque render bin
371          * which is attached to another transparent render bin as these render
372          * bins will be sorted separately, giving the wrong draw ordering for
373          * back-to-front transparency. Therefore, to prevent render bins being
374          * nested, call setNestRenderBins(false). */
375        inline void setNestRenderBins(bool val) { _nestRenderBins = val; }
376
377        /** Get whether associated RenderBin should be nested within parents RenderBin.*/
378        inline bool getNestRenderBins() const { return _nestRenderBins; }
379
380
381        struct Callback : public virtual osg::Object
382        {
383            Callback() {}
384
385            Callback(const Callback&,const CopyOp&) {}
386
387            META_Object(osg,Callback);
388
389            /** do customized callback code.*/
390            virtual void operator() (StateSet*, NodeVisitor*) {}
391        };
392
393        /** Set the Update Callback which allows users to attach customize the updating of an object during the update traversal.*/
394        void setUpdateCallback(Callback* ac);
395
396        /** Get the non const Update Callback.*/
397        Callback* getUpdateCallback() { return _updateCallback.get(); }
398
399        /** Get the const Update Callback.*/
400        const Callback* getUpdateCallback() const { return _updateCallback.get(); }
401
402        /** Return whether this StateSet has update callbacks associated with it, and therefore must be traversed.*/
403        bool requiresUpdateTraversal() const { return _updateCallback.valid() || getNumChildrenRequiringUpdateTraversal()!=0; }
404
405        /** Get the number of Objects of this StateSet which require Update traversal,
406          * since they have an Update Callback attached to them or their children.*/
407        inline unsigned int getNumChildrenRequiringUpdateTraversal() const { return _numChildrenRequiringUpdateTraversal; }
408
409        /** Run the update callbacks attached directly to this StateSet or to its children.*/
410        void runUpdateCallbacks(osg::NodeVisitor* nv);
411
412
413        /** Set the Event Callback which allows users to attach customize the updating of an object during the event traversal.*/
414        void setEventCallback(Callback* ac);
415
416        /** Get the non const Event Callback.*/
417        Callback* getEventCallback() { return _eventCallback.get(); }
418
419        /** Get the const Event Callback.*/
420        const Callback* getEventCallback() const { return _eventCallback.get(); }
421
422        /** Return whether this StateSet has event callbacks associated with it, and therefore must be traversed.*/
423        bool requiresEventTraversal() const { return _eventCallback.valid() || getNumChildrenRequiringEventTraversal()!=0; }
424
425        /** Get the number of Objects of this StateSet which require Event traversal,
426          * since they have an Eevnt Callback attached to them or their children.*/
427        inline unsigned int getNumChildrenRequiringEventTraversal() const { return _numChildrenRequiringEventTraversal; }
428
429        /** Run the event callbacks attached directly to this StateSet or to its children.*/
430        void runEventCallbacks(osg::NodeVisitor* nv);
431
432        /** Check the modes associated with this StateSet are supported by current OpenGL drivers,
433          * and if not set the associated mode in osg::State to be black listed/invalid.
434          * Return true if all associated modes are valid.*/
435        bool checkValidityOfAssociatedModes(State& state) const;
436
437        /** Set whether to use a mutex to ensure ref() and unref() are thread safe.*/
438        virtual void setThreadSafeRefUnref(bool threadSafe);
439
440        /** call compile on all StateAttributes contained within this StateSet.*/
441        void compileGLObjects(State& state) const;
442
443        /** Resize any per context GLObject buffers to specified size. */
444        virtual void resizeGLObjectBuffers(unsigned int maxSize);
445
446        /** call release on all StateAttributes contained within this StateSet.*/
447        virtual void releaseGLObjects(State* state=0) const;
448
449    protected :
450
451
452        virtual ~StateSet();
453
454        StateSet& operator = (const StateSet&) { return *this; }
455
456        void addParent(osg::Object* object);
457        void removeParent(osg::Object* object);
458
459        ParentList _parents;
460        friend class osg::Node;
461        friend class osg::Drawable;
462        friend class osg::Uniform;
463        friend class osg::StateAttribute;
464
465        ModeList                            _modeList;
466        AttributeList                       _attributeList;
467
468        TextureModeList                     _textureModeList;
469        TextureAttributeList                _textureAttributeList;
470
471        UniformList                         _uniformList;
472
473        inline ModeList& getOrCreateTextureModeList(unsigned int unit)
474        {
475            if (unit>=_textureModeList.size()) _textureModeList.resize(unit+1);
476            return _textureModeList[unit];
477        }
478
479        inline AttributeList& getOrCreateTextureAttributeList(unsigned int unit)
480        {
481            if (unit>=_textureAttributeList.size()) _textureAttributeList.resize(unit+1);
482            return _textureAttributeList[unit];
483        }
484
485        int compareModes(const ModeList& lhs,const ModeList& rhs);
486        int compareAttributePtrs(const AttributeList& lhs,const AttributeList& rhs);
487        int compareAttributeContents(const AttributeList& lhs,const AttributeList& rhs);
488
489        void setMode(ModeList& modeList,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
490        void setModeToInherit(ModeList& modeList,StateAttribute::GLMode mode);
491        StateAttribute::GLModeValue getMode(const ModeList& modeList,StateAttribute::GLMode mode) const;
492
493        void setAttribute(AttributeList& attributeList,StateAttribute *attribute, const StateAttribute::OverrideValue value=StateAttribute::OFF);
494
495        StateAttribute* getAttribute(AttributeList& attributeList,const StateAttribute::Type type, unsigned int member);
496        const StateAttribute* getAttribute(const AttributeList& attributeList,const StateAttribute::Type type, unsigned int member) const;
497        const RefAttributePair* getAttributePair(const AttributeList& attributeList,const StateAttribute::Type type, unsigned int member) const;
498
499        int                                 _renderingHint;
500
501        RenderBinMode                       _binMode;
502        int                                 _binNum;
503        std::string                         _binName;
504        bool                                _nestRenderBins;
505
506        ref_ptr<Callback> _updateCallback;
507        unsigned int _numChildrenRequiringUpdateTraversal;
508        void setNumChildrenRequiringUpdateTraversal(unsigned int num);
509
510        ref_ptr<Callback> _eventCallback;
511        unsigned int _numChildrenRequiringEventTraversal;
512        void setNumChildrenRequiringEventTraversal(unsigned int num);
513
514};
515
516extern OSG_EXPORT bool isTextureMode(StateAttribute::GLMode mode);
517
518}
519
520#endif
Note: See TracBrowser for help on using the browser.