OpenSceneGraph/include/osg/StateSet

/* -*-c++-*- OpenSceneGraph - Copyright (C) 1998-2003 Robert Osfield
 *
 * This library is open source and may be redistributed and/or modified under
 * the terms of the OpenSceneGraph Public License (OSGPL) version 0.0 or
 * (at your option) any later version.  The full license is in LICENSE file
 * included with this distribution, and on the openscenegraph.org website.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * OpenSceneGraph Public License for more details.
*/

#ifndef OSG_STATESET
#define OSG_STATESET 1

#include <osg/Object>
#include <osg/StateAttribute>
#include <osg/ref_ptr>

#include <map>
#include <vector>
#include <string>

#ifndef GL_RESCALE_NORMAL
// allow compilation against GL1.1 headers.
#define GL_RESCALE_NORMAL                 0x803A
#endif

namespace osg {

/** Stores a set of modes and attributes which respresent a set of OpenGL state.
  *  Notice that a \c StateSet contains just a subset of the whole OpenGL state.
  * <p>In OSG, each \c Drawable and each \c Node has a reference to a
  * \c StateSet. These <tt>StateSet</tt>s can be shared between
  * different <tt>Drawable</tt>s and <tt>Node</tt>s (that is, several
  * <tt>Drawable</tt>s and <tt>Node</tt>s can reference the same \c StateSet).
  * Indeed, this practice is recommended whenever possible,
  * as this minimizes expensive state changes in the graphics pipeline.
*/
class SG_EXPORT StateSet : public Object
{
    public :


        StateSet();
        StateSet(const StateSet&,const CopyOp& copyop=CopyOp::SHALLOW_COPY);

        virtual Object* cloneType() const { return new StateSet(); }
        virtual Object* clone(const CopyOp& copyop) const { return new StateSet(*this,copyop); }
        virtual bool isSameKindAs(const Object* obj) const { return dynamic_cast<const StateSet*>(obj)!=NULL; }
        virtual const char* libraryName() const { return "osg"; }
        virtual const char* className() const { return "StateSet"; }

        /** return -1 if *this < *rhs, 0 if *this==*rhs, 1 if *this>*rhs.*/
        int compare(const StateSet& rhs,bool compareAttributeContents=false) const;

        bool operator <  (const StateSet& rhs) const { return compare(rhs)<0; }
        bool operator == (const StateSet& rhs) const { return compare(rhs)==0; }
        bool operator != (const StateSet& rhs) const { return compare(rhs)!=0; }

        /** Set all the modes to on or off so that it defines a
            complete state, typically used for a default global state.*/
        void setGlobalDefaults();

#ifdef USE_DEPRECATED_API
        /** Set all the modes to inherit, typically used to signify
            nodes which inherit all of their modes for the global state.*/
        void setAllToInherit() { clear(); }
#endif

        /** Clear the StateSet of all modes and attributes.*/
        void clear();

        /** Merge this \c StateSet with the \c StateSet passed as parameter.
          * Every mode and attribute in this \c StateSet that is marked with
          * \c StateAttribute::OVERRIDE is replaced with the
          * equivalent mode or attribute from \c rhs.
        */
        void merge(const StateSet& rhs);

        /** a container to map GLModes to their respective GLModeValues.*/
        typedef std::map<StateAttribute::GLMode,StateAttribute::GLModeValue>  ModeList;

        /** Set this \c StateSet to contain the specified \c GLMode with a given
          * value.
          * @note Don't use this method to set modes related to textures. For this
          *       purpose, use \c setTextureMode(), that accepts an extra parameter
          *       specifying which texture unit shall be affected by the call.
        */
        void setMode(StateAttribute::GLMode mode, StateAttribute::GLModeValue value);

#ifdef USE_DEPRECATED_API
        /** Set this StateSet to inherit specified GLMode type from parents.
          * Has the effect of deleting any GLMode of specified type from StateSet.*/
        void setModeToInherit(StateAttribute::GLMode mode) { removeMode(mode); }
#endif
        /** Remove \c mode from this \c StateSet.
          * @note Don't use this method to remove modes related to textures. For
          *       this purpose, use \c removeTextureMode(), that accepts an extra
          *       parameter specifying which texture unit shall be affected by
          *       the call.
        */
        void removeMode(StateAttribute::GLMode mode);

        /** Get the value for a given \c GLMode.
          * @param mode The \c GLMode whose value is desired.
          * @return If \c mode is contained within this \c StateSet, returns the
          *         value associated with it. Otherwise, returns
          *         \c StateAttribute::INHERIT.
          * @note Don't use this method to get the value of modes related to
          *       textures. For this purpose, use \c removeTextureMode(), that
          *       accepts an extra parameter specifying which texture unit shall
          *       be affected by the call.
        */
        StateAttribute::GLModeValue getMode(StateAttribute::GLMode mode) const;

        /** Set the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
        inline void setModeList(ModeList& ml) { _modeList=ml; }

        /** Return the list of all <tt>GLMode</tt>s contained in this \c StateSet.*/
        inline ModeList& getModeList() { return _modeList; }

        /** Return the \c const list of all <tt>GLMode</tt>s contained in this
          * <tt>const StateSet</tt>.
        */
        inline const ModeList& getModeList() const { return _modeList; }



        /** Simple pairing between an attribute and its override flag.*/
        typedef std::pair<ref_ptr<StateAttribute>,StateAttribute::OverrideValue>    RefAttributePair;

        /** a container to map <StateAttribyte::Types,Member> to their respective RefAttributePair.*/
        typedef std::map<StateAttribute::TypeMemberPair,RefAttributePair>           AttributeList;

        /** Set this StateSet to contain specified attribute and override flag.*/
        void setAttribute(StateAttribute *attribute, StateAttribute::OverrideValue value=StateAttribute::OFF);

        /** Set this StateSet to contain specified attribute and set the associated GLMode's to specified value.*/
        void setAttributeAndModes(StateAttribute *attribute, StateAttribute::GLModeValue value=StateAttribute::ON);

#ifdef USE_DEPRECATED_API
        /** Set this StateSet to inherit specified attribute type from parents.
          * has the effect of deleting any state attributes of specified type from StateSet.*/
        void setAttributeToInherit(StateAttribute::Type type) { removeAttribute(type); }
#endif
        /** remove attribute of specified type from StateSet.*/
        void removeAttribute(StateAttribute::Type type, unsigned int member=0);

        /** remove attribute from StateSet.*/
        void removeAttribute(StateAttribute *attribute);

        /** Get specified StateAttribute for specified type.
          * Returns NULL if no type is contained within StateSet.*/
        StateAttribute* getAttribute(StateAttribute::Type type, unsigned int member = 0);

        /** Get specified const StateAttribute for specified type.
          * Returns NULL if no type is contained within const StateSet.*/
        const StateAttribute* getAttribute(StateAttribute::Type type, unsigned int member = 0) const;

        /** Get specified RefAttributePair for specified type.
          * Returns NULL if no type is contained within StateSet.*/
        const RefAttributePair* getAttributePair(StateAttribute::Type type, unsigned int member = 0) const;

        /** set the list of all StateAttributes contained in this StateSet.*/
        inline void setAttributeList(AttributeList& al) { _attributeList=al; }

        /** return the list of all StateAttributes contained in this StateSet.*/
        inline AttributeList& getAttributeList() { return _attributeList; }

        /** return the const list of all StateAttributes contained in this const StateSet.*/
        inline const AttributeList& getAttributeList() const { return _attributeList; }



        typedef std::vector<ModeList>       TextureModeList;

        /** Set this \c StateSet to contain specified \c GLMode with a given
         *  value.
         *  @param unit The texture unit to be affected (used with
         *         multi-texturing).
         *  @param mode The OpenGL mode to be added to the \c StateSet.
         *  @param value The value to be assigned to \c mode.
        */
        void setTextureMode(unsigned int unit,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);

#ifdef USE_DEPRECATED_API
        /** Set this StateSet to inherit specified GLMode type from parents.
          * has the effect of deleting any GLMode of specified type from StateSet.*/
        void setTextureModeToInherit(unsigned int unit,StateAttribute::GLMode mode) { removeTextureMode(unit,mode); }
#endif
        /** Remove texture mode from StateSet.*/
        void removeTextureMode(unsigned int unit,StateAttribute::GLMode mode);

        /** Get specified GLModeValue for specified GLMode.
          * returns INHERIT if no GLModeValue is contained within StateSet.*/
        StateAttribute::GLModeValue getTextureMode(unsigned int unit,StateAttribute::GLMode mode) const;

        /** set the list of all Texture related GLModes contained in this StateSet.*/
        inline void setTextureModeList(TextureModeList& tml) { _textureModeList=tml; }

        /** return the list of all Texture related GLModes contained in this StateSet.*/
        inline TextureModeList& getTextureModeList() { return _textureModeList; }

        /** return the const list of all Texture related GLModes contained in this const StateSet.*/
        inline const TextureModeList& getTextureModeList() const  { return _textureModeList; }


        typedef std::vector<AttributeList>  TextureAttributeList;

        /** Set this StateSet to contain specified attribute and override flag.*/
        void setTextureAttribute(unsigned int unit,StateAttribute *attribute, StateAttribute::OverrideValue value=StateAttribute::OFF);
        /** Set this StateSet to contain specified attribute and set the associated GLMode's to specified value.*/
        void setTextureAttributeAndModes(unsigned int unit,StateAttribute *attribute, StateAttribute::GLModeValue value=StateAttribute::ON);

#ifdef USE_DEPRECATED_API
        /** Set this StateSet to inherit specified attribute type from parents.
          * Has the effect of deleting any state attributes of specified type from StateSet.*/
        void setTextureAttributeToInherit(unsigned int unit,StateAttribute::Type type) { removeTextureAttribute(unit,type); }
#endif

        /** remove texture attribute of specified type from StateSet.*/
        void removeTextureAttribute(unsigned int unit, StateAttribute::Type type);

        /** remove texture attribute from StateSet.*/
        void removeTextureAttribute(unsigned int unit, StateAttribute *attribute);

        /** Get specified Texture related StateAttribute for specified type.
          * Returns NULL if no type is contained within StateSet.*/
        StateAttribute* getTextureAttribute(unsigned int unit,StateAttribute::Type type);

        /** Get specified Texture related const StateAttribute for specified type.
          * Returns NULL if no type is contained within const StateSet.*/
        const StateAttribute* getTextureAttribute(unsigned int unit,StateAttribute::Type type) const;

        /** Get specified Texture related RefAttributePair for specified type.
          * Returns NULL if no type is contained within StateSet.*/
        const RefAttributePair* getTextureAttributePair(unsigned int unit,StateAttribute::Type type) const;

        /** Set the list of all Texture related StateAttributes contained in this StateSet.*/
        inline void setTextureAttributeList(TextureAttributeList& tal) { _textureAttributeList=tal; }

        /** Return the list of all Texture related StateAttributes contained in this StateSet.*/
        inline TextureAttributeList& getTextureAttributeList() { return _textureAttributeList; }

        /** Return the const list of all Texture related StateAttributes contained in this const StateSet.*/
        inline const TextureAttributeList& getTextureAttributeList() const { return _textureAttributeList; }


        void setAssociatedModes(const StateAttribute* attribute, StateAttribute::GLModeValue value);

        void setAssociatedTextureModes(unsigned int unit,const StateAttribute* attribute, StateAttribute::GLModeValue value);

        enum RenderingHint
        {
            DEFAULT_BIN = 0,
            OPAQUE_BIN = 1,
            TRANSPARENT_BIN = 2
        };

        /** Set the \c RenderingHint of this \c StateSet. \c RenderingHint is
          * used by the renderer to determine which draw bin to drop associated
          * <tt>osg::Drawable</tt>s in. Typically, users will set this to either
          * \c StateSet::OPAQUE_BIN or \c StateSet::TRANSPARENT_BIN.
          * <tt>Drawable</tt>s in the opaque bin are sorted by their
          * \c StateSet, so that the number of expensive changes in the OpenGL
          * state is minimized. <tt>Drawable</tt>s in the transparent bin are
          * sorted by depth, so that objects farther from the viewer are
          * rendered first (and hence alpha blending works nicely for
          * translucent objects).
        */
        void setRenderingHint(int hint);

        /** Get the \c RenderingHint of this \c StateSet.*/
        inline int getRenderingHint() const      { return _renderingHint; }

        enum RenderBinMode
        {
            INHERIT_RENDERBIN_DETAILS,
            USE_RENDERBIN_DETAILS,
            OVERRIDE_RENDERBIN_DETAILS,
            ENCLOSE_RENDERBIN_DETAILS
        };

        /** Set the render bin details.*/
        void setRenderBinDetails(int binNum,const std::string& binName,RenderBinMode mode=USE_RENDERBIN_DETAILS);

        /** Set the render bin details to inherit.*/
        void setRenderBinToInherit();

        /** Get whether the render bin details are set and should be used.*/
        inline bool useRenderBinDetails() const { return _binMode!=INHERIT_RENDERBIN_DETAILS; }

        /** Set the render bin mode.*/
        inline void setRenderBinMode(RenderBinMode mode) { _binMode=mode; }

        /** Get the render bin mode.*/
        inline RenderBinMode getRenderBinMode() const { return _binMode; }

        /** Set the render bin number.*/
        inline void setBinNumber(int num) { _binNum=num; }

        /** Get the render bin number.*/
        inline int getBinNumber() const { return _binNum; }

        /** Set the render bin name.*/
        inline void setBinName(const std::string& name) { _binName=name; }

        /** Get the render bin name.*/
        inline const std::string& getBinName() const { return _binName; }


        /** call compile on all StateAttributes contained within this StateSet.*/
        void compileGLObjects(State& state) const;

        /** call release on all StateAttributes contained within this StateSet.*/
        virtual void releaseGLObjects(State* state=0) const;

    protected :


        virtual ~StateSet();

        StateSet& operator = (const StateSet&) { return *this; }

        ModeList                            _modeList;
        AttributeList                       _attributeList;

        TextureModeList                     _textureModeList;
        TextureAttributeList                _textureAttributeList;

        inline ModeList& getOrCreateTextureModeList(unsigned int unit)
        {
            if (unit>=_textureModeList.size()) _textureModeList.resize(unit+1);
            return _textureModeList[unit];
        }

        inline AttributeList& getOrCreateTextureAttributeList(unsigned int unit)
        {
            if (unit>=_textureAttributeList.size()) _textureAttributeList.resize(unit+1);
            return _textureAttributeList[unit];
        }

        int compareModes(const ModeList& lhs,const ModeList& rhs);
        int compareAttributePtrs(const AttributeList& lhs,const AttributeList& rhs);
        int compareAttributeContents(const AttributeList& lhs,const AttributeList& rhs);

        void setMode(ModeList& modeList,StateAttribute::GLMode mode, StateAttribute::GLModeValue value);
        void setModeToInherit(ModeList& modeList,StateAttribute::GLMode mode);
        StateAttribute::GLModeValue getMode(const ModeList& modeList,StateAttribute::GLMode mode) const;

        void setAttribute(AttributeList& attributeList,StateAttribute *attribute, const StateAttribute::OverrideValue value=StateAttribute::OFF);

        StateAttribute* getAttribute(AttributeList& attributeList,const StateAttribute::Type type, unsigned int member);
        const StateAttribute* getAttribute(const AttributeList& attributeList,const StateAttribute::Type type, unsigned int member) const;
        const RefAttributePair* getAttributePair(const AttributeList& attributeList,const StateAttribute::Type type, unsigned int member) const;

        int                                 _renderingHint;

        RenderBinMode                       _binMode;
        int                                 _binNum;
        std::string                         _binName;

};

}

#endif