/src/ogre/OgreMain/include/OgreBlendMode.h

Source (jump to first uncovered line)
/*
-----------------------------------------------------------------------------
This source file is part of OGRE
    (Object-oriented Graphics Rendering Engine)
For the latest info, see http://www.ogre3d.org/

Copyright (c) 2000-2014 Torus Knot Software Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
-----------------------------------------------------------------------------
*/
#ifndef __BLENDMODE_H__
#define __BLENDMODE_H__

#include "OgrePrerequisites.h"
#include "OgreColourValue.h"

namespace Ogre {
    /** \addtogroup Core
    *  @{
    */
    /** \addtogroup Materials
    *  @{
    */

    /** Type of texture blend mode.
    */
    enum LayerBlendType
    {
        LBT_COLOUR,
        LBT_ALPHA
    };

    /** List of valid texture blending operations, for use with TextureUnitState::setColourOperation.

        This list is a more limited list than LayerBlendOperationEx because it only
        includes operations that are supportable in both multipass and multitexture
        rendering and thus provides automatic fallback if multitexture hardware
        is lacking or insufficient.
    */
    enum LayerBlendOperation {
        /// Replace all colour with texture with no adjustment
        LBO_REPLACE,
        /// Add colour components together.
        LBO_ADD,
        /// Multiply colour components together.
        LBO_MODULATE,
        /// Blend based on texture alpha
        LBO_ALPHA_BLEND

    };

    /** Expert list of valid texture blending operations, for use with TextureUnitState::setColourOperationEx
        and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class. It's worth
        noting that these operations are for blending <i>between texture layers</i> and not between rendered objects
        and the existing scene. Because all of these modes are only supported in multitexture hardware it may be
        required to set up a fallback operation where this hardware is not available.
    */
    enum LayerBlendOperationEx {
        /// use source1 without modification
        LBX_SOURCE1,
        /// use source2 without modification
        LBX_SOURCE2,
        /// multiply source1 and source2 together
        LBX_MODULATE,
        /// as LBX_MODULATE but brighten afterwards (x2)
        LBX_MODULATE_X2,
        /// as LBX_MODULATE but brighten more afterwards (x4)
        LBX_MODULATE_X4,
        /// add source1 and source2 together
        LBX_ADD,
        /// as LBX_ADD, but subtract 0.5 from the result
        LBX_ADD_SIGNED,
        /// as LBX_ADD, but subtract product from the sum
        LBX_ADD_SMOOTH,
        /// subtract source2 from source1
        LBX_SUBTRACT,
        /// use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha)
        LBX_BLEND_DIFFUSE_ALPHA,
        /// as LBX_BLEND_DIFFUSE_ALPHA, but use alpha from texture
        LBX_BLEND_TEXTURE_ALPHA,
        /// as LBX_BLEND_DIFFUSE_ALPHA, but use current alpha from previous stages
        LBX_BLEND_CURRENT_ALPHA,
        /// as LBX_BLEND_DIFFUSE_ALPHA but use a constant manual blend value (0.0-1.0)
        LBX_BLEND_MANUAL,
        /// dot product of color1 and color2 
        LBX_DOTPRODUCT,
        /// use interpolated color values from vertices to scale source1, then add source2 scaled by (1-color)
        LBX_BLEND_DIFFUSE_COLOUR
    };

    /** List of valid sources of values for blending operations used
        in TextureUnitState::setColourOperation and TextureUnitState::setAlphaOperation,
        and internally in the LayerBlendModeEx class.
    */
    enum LayerBlendSource
    {
        /// the colour as built up from previous stages
        LBS_CURRENT,
        /// the colour derived from the texture assigned to this layer
        LBS_TEXTURE,
        /// the interpolated diffuse colour from the vertices
        LBS_DIFFUSE,
        /// the interpolated specular colour from the vertices
        LBS_SPECULAR,
        /// a colour supplied manually as a separate argument
        LBS_MANUAL
    };
    /** Class which manages blending of both colour and alpha components.

        This class is a utility class used by both TextureUnitState and
        RenderSystem to wrap up the details of a blending operation. This blending
        operation could be used for blending colour or alpha in a texture layer.
        This class is really only for use by OGRE, since apps can deal with
        blending modes through the TextureUnitState class methods
        setColourOperation and setAlphaOperation.
        @par
            It's worth noting that these operations are for blending <i>between texture
            layers</i> and not between rendered objects and the existing scene. If
            you wish to make an object blend with others in the scene, e.g. to make
            transparent objects etc, use the Material::setSceneBlending method.
    */
    class _OgreExport LayerBlendModeEx
    {
    public:
        /// The type of blending (colour or alpha)
        LayerBlendType blendType;
        /// The operation to be applied
        LayerBlendOperationEx operation;
        /// The first source of colour/alpha
        LayerBlendSource source1;
        /// The second source of colour/alpha
        LayerBlendSource source2;

        /// Manual colour value for manual source1
        ColourValue colourArg1;
        /// Manual colour value for manual source2
        ColourValue colourArg2;
        /// Manual alpha value for manual source1
        Real alphaArg1;
        /// Manual alpha value for manual source2
        Real alphaArg2;
        /// Manual blending factor
        Real factor;

        bool operator==(const LayerBlendModeEx& rhs) const
        {
            if (blendType != rhs.blendType) return false;

            if (blendType == LBT_COLOUR)
            {

                if (operation == rhs.operation &&
                    source1 == rhs.source1 &&
                    source2 == rhs.source2 &&
                    colourArg1 == rhs.colourArg1 &&
                    colourArg2 == rhs.colourArg2 &&
                    factor == rhs.factor)
                {
                    return true;
                }
            }
            else // if (blendType == LBT_ALPHA)
            {
                if (operation == rhs.operation &&
                    source1 == rhs.source1 &&
                    source2 == rhs.source2 &&
                    alphaArg1 == rhs.alphaArg1 &&
                    alphaArg2 == rhs.alphaArg2 &&
                    factor == rhs.factor)
                {
                    return true;
                }
            }
            return false;
        }

        bool operator!=(const LayerBlendModeEx& rhs) const
        {
            return !(*this == rhs);
        }



    };

    /** Types of blending that you can specify between an object and the existing contents of the scene.

        As opposed to the LayerBlendType, which classifies blends between texture layers, these blending
        types blend between the output of the texture units and the pixels already in the viewport,
        allowing for object transparency, glows, etc.

        These types are provided to give quick and easy access to common effects. You can also use
        the more manual method of supplying source and destination blending factors.
        See Material::setSceneBlending for more details.
        @see
            Pass::setSceneBlending
    */
    enum SceneBlendType
    {
        SBT_TRANSPARENT_ALPHA, //!< The alpha value of the rendering output is used as a mask.
        SBT_TRANSPARENT_COLOUR, //!< Colour the scene based on the brightness of the input colours, but don’t darken.
        SBT_ADD, //!< The colour of the rendering output is added to the scene. Good for explosions, flares, lights, ghosts etc. 
        SBT_MODULATE, //!< The colour of the rendering output is multiplied with the scene contents. Generally colours and darkens the scene, good for smoked glass, semi-transparent objects etc.
        SBT_REPLACE //!< The default blend mode where source replaces destination
        // TODO : more
    };

    /** Blending factors for manually blending objects with the scene. If there isn't a predefined
        SceneBlendType that you like, then you can specify the blending factors directly to affect the
        combination of object and the existing scene. See Material::setSceneBlending for more details.
    */
    enum SceneBlendFactor
    {
        SBF_ONE, //!< Constant value of 1.0
        SBF_ZERO, //!< Constant value of 0.0
        SBF_DEST_COLOUR, //!< The existing pixel colour
        SBF_SOURCE_COLOUR, //!< The texture pixel (texel) colour
        SBF_ONE_MINUS_DEST_COLOUR, //!< 1 - SBF_DEST_COLOUR
        SBF_ONE_MINUS_SOURCE_COLOUR, //!< 1 - SBF_SOURCE_COLOUR
        SBF_DEST_ALPHA, //!< The existing pixel alpha value
        SBF_SOURCE_ALPHA, //!< The texel alpha value
        SBF_ONE_MINUS_DEST_ALPHA, //!< 1 - SBF_DEST_ALPHA
        SBF_ONE_MINUS_SOURCE_ALPHA //!< 1 - SBF_SOURCE_ALPHA
    };

    /** Blending operations controls how objects are blended into the scene. The default operation
        is add (+) but by changing this you can change how drawn objects are blended into the
        existing scene.
    */
    enum SceneBlendOperation
    {
        SBO_ADD,
        SBO_SUBTRACT,
        SBO_REVERSE_SUBTRACT,
        SBO_MIN,
        SBO_MAX
    };

    /** Describes the global blending factors for combining subsequent renders with the existing frame contents.

    By default the operation is Ogre::SBO_ADD, which creates this equation

    $$final = (passOutput * sourceFactor) + (frameBuffer * destFactor)$$

    Each of the factors is specified as one of Ogre::SceneBlendFactor.

    By setting a different Ogre::SceneBlendOperation you can achieve a different effect.
    */
    struct _OgreExport ColourBlendState
    {
        /** @name Write Mask
         * Whether writing is enabled for each of the 4 colour channels */
        /// @{
        bool writeR : 1;
        bool writeG : 1;
        bool writeB : 1;
        bool writeA : 1;
        /// @}

        /** @name Blending factors
         * used to weight the render colour components and the frame colour components */
        /// @{
        SceneBlendFactor sourceFactor;
        SceneBlendFactor destFactor;
        SceneBlendFactor sourceFactorAlpha;
        SceneBlendFactor destFactorAlpha;
        /// @}

        /** @name Blending operations
         * The blend operation mode for combining colour values */
        /// @{
        SceneBlendOperation operation;
        SceneBlendOperation alphaOperation;
        /// @}

        ColourBlendState()
            : writeR(true), writeG(true), writeB(true), writeA(true), sourceFactor(SBF_ONE),
              destFactor(SBF_ZERO), sourceFactorAlpha(SBF_ONE), destFactorAlpha(SBF_ZERO),
              operation(SBO_ADD), alphaOperation(SBO_ADD)
        {
        }

        /// can we simply overwrite the existing pixels or do we have to blend
        bool blendingEnabled() const
        {
            return !(sourceFactor == SBF_ONE && destFactor == SBF_ZERO &&
                     sourceFactorAlpha == SBF_ONE && destFactorAlpha == SBF_ZERO);
        }
    };
    /** @} */
    /** @} */

}

#endif

Coverage Report

Created: 2025-07-18 07:08

Line	Count	Source (jump to first uncovered line)
1		/*
2		-----------------------------------------------------------------------------
3		This source file is part of OGRE
4		(Object-oriented Graphics Rendering Engine)
5		For the latest info, see http://www.ogre3d.org/
6
7		Copyright (c) 2000-2014 Torus Knot Software Ltd
8
9		Permission is hereby granted, free of charge, to any person obtaining a copy
10		of this software and associated documentation files (the "Software"), to deal
11		in the Software without restriction, including without limitation the rights
12		to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13		copies of the Software, and to permit persons to whom the Software is
14		furnished to do so, subject to the following conditions:
15
16		The above copyright notice and this permission notice shall be included in
17		all copies or substantial portions of the Software.
18
19		THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20		IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21		FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22		AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25		THE SOFTWARE.
26		-----------------------------------------------------------------------------
27		*/
28		#ifndef __BLENDMODE_H__
29		#define __BLENDMODE_H__
30
31		#include "OgrePrerequisites.h"
32		#include "OgreColourValue.h"
33
34		namespace Ogre {
35		/** \addtogroup Core
36		* @{
37		*/
38		/** \addtogroup Materials
39		* @{
40		*/
41
42		/** Type of texture blend mode.
43		*/
44		enum LayerBlendType
45		{
46		LBT_COLOUR,
47		LBT_ALPHA
48		};
49
50		/** List of valid texture blending operations, for use with TextureUnitState::setColourOperation.
51
52		This list is a more limited list than LayerBlendOperationEx because it only
53		includes operations that are supportable in both multipass and multitexture
54		rendering and thus provides automatic fallback if multitexture hardware
55		is lacking or insufficient.
56		*/
57		enum LayerBlendOperation {
58		/// Replace all colour with texture with no adjustment
59		LBO_REPLACE,
60		/// Add colour components together.
61		LBO_ADD,
62		/// Multiply colour components together.
63		LBO_MODULATE,
64		/// Blend based on texture alpha
65		LBO_ALPHA_BLEND
66
67		};
68
69		/** Expert list of valid texture blending operations, for use with TextureUnitState::setColourOperationEx
70		and TextureUnitState::setAlphaOperation, and internally in the LayerBlendModeEx class. It's worth
71		noting that these operations are for blending <i>between texture layers</i> and not between rendered objects
72		and the existing scene. Because all of these modes are only supported in multitexture hardware it may be
73		required to set up a fallback operation where this hardware is not available.
74		*/
75		enum LayerBlendOperationEx {
76		/// use source1 without modification
77		LBX_SOURCE1,
78		/// use source2 without modification
79		LBX_SOURCE2,
80		/// multiply source1 and source2 together
81		LBX_MODULATE,
82		/// as LBX_MODULATE but brighten afterwards (x2)
83		LBX_MODULATE_X2,
84		/// as LBX_MODULATE but brighten more afterwards (x4)
85		LBX_MODULATE_X4,
86		/// add source1 and source2 together
87		LBX_ADD,
88		/// as LBX_ADD, but subtract 0.5 from the result
89		LBX_ADD_SIGNED,
90		/// as LBX_ADD, but subtract product from the sum
91		LBX_ADD_SMOOTH,
92		/// subtract source2 from source1
93		LBX_SUBTRACT,
94		/// use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha)
95		LBX_BLEND_DIFFUSE_ALPHA,
96		/// as LBX_BLEND_DIFFUSE_ALPHA, but use alpha from texture
97		LBX_BLEND_TEXTURE_ALPHA,
98		/// as LBX_BLEND_DIFFUSE_ALPHA, but use current alpha from previous stages
99		LBX_BLEND_CURRENT_ALPHA,
100		/// as LBX_BLEND_DIFFUSE_ALPHA but use a constant manual blend value (0.0-1.0)
101		LBX_BLEND_MANUAL,
102		/// dot product of color1 and color2
103		LBX_DOTPRODUCT,
104		/// use interpolated color values from vertices to scale source1, then add source2 scaled by (1-color)
105		LBX_BLEND_DIFFUSE_COLOUR
106		};
107
108		/** List of valid sources of values for blending operations used
109		in TextureUnitState::setColourOperation and TextureUnitState::setAlphaOperation,
110		and internally in the LayerBlendModeEx class.
111		*/
112		enum LayerBlendSource
113		{
114		/// the colour as built up from previous stages
115		LBS_CURRENT,
116		/// the colour derived from the texture assigned to this layer
117		LBS_TEXTURE,
118		/// the interpolated diffuse colour from the vertices
119		LBS_DIFFUSE,
120		/// the interpolated specular colour from the vertices
121		LBS_SPECULAR,
122		/// a colour supplied manually as a separate argument
123		LBS_MANUAL
124		};
125		/** Class which manages blending of both colour and alpha components.
126
127		This class is a utility class used by both TextureUnitState and
128		RenderSystem to wrap up the details of a blending operation. This blending
129		operation could be used for blending colour or alpha in a texture layer.
130		This class is really only for use by OGRE, since apps can deal with
131		blending modes through the TextureUnitState class methods
132		setColourOperation and setAlphaOperation.
133		@par
134		It's worth noting that these operations are for blending <i>between texture
135		layers</i> and not between rendered objects and the existing scene. If
136		you wish to make an object blend with others in the scene, e.g. to make
137		transparent objects etc, use the Material::setSceneBlending method.
138		*/
139		class _OgreExport LayerBlendModeEx
140		{
141		public:
142		/// The type of blending (colour or alpha)
143		LayerBlendType blendType;
144		/// The operation to be applied
145		LayerBlendOperationEx operation;
146		/// The first source of colour/alpha
147		LayerBlendSource source1;
148		/// The second source of colour/alpha
149		LayerBlendSource source2;
150
151		/// Manual colour value for manual source1
152		ColourValue colourArg1;
153		/// Manual colour value for manual source2
154		ColourValue colourArg2;
155		/// Manual alpha value for manual source1
156		Real alphaArg1;
157		/// Manual alpha value for manual source2
158		Real alphaArg2;
159		/// Manual blending factor
160		Real factor;
161
162		bool operator==(const LayerBlendModeEx& rhs) const
163	0	{
164	0	if (blendType != rhs.blendType) return false;
165	0
166	0	if (blendType == LBT_COLOUR)
167	0	{
168	0
169	0	if (operation == rhs.operation &&
170	0	source1 == rhs.source1 &&
171	0	source2 == rhs.source2 &&
172	0	colourArg1 == rhs.colourArg1 &&
173	0	colourArg2 == rhs.colourArg2 &&
174	0	factor == rhs.factor)
175	0	{
176	0	return true;
177	0	}
178	0	}
179	0	else // if (blendType == LBT_ALPHA)
180	0	{
181	0	if (operation == rhs.operation &&
182	0	source1 == rhs.source1 &&
183	0	source2 == rhs.source2 &&
184	0	alphaArg1 == rhs.alphaArg1 &&
185	0	alphaArg2 == rhs.alphaArg2 &&
186	0	factor == rhs.factor)
187	0	{
188	0	return true;
189	0	}
190	0	}
191	0	return false;
192	0	}
193
194		bool operator!=(const LayerBlendModeEx& rhs) const
195	0	{
196	0	return !(*this == rhs);
197	0	}
198
199
200
201		};
202
203		/** Types of blending that you can specify between an object and the existing contents of the scene.
204
205		As opposed to the LayerBlendType, which classifies blends between texture layers, these blending
206		types blend between the output of the texture units and the pixels already in the viewport,
207		allowing for object transparency, glows, etc.
208
209		These types are provided to give quick and easy access to common effects. You can also use
210		the more manual method of supplying source and destination blending factors.
211		See Material::setSceneBlending for more details.
212		@see
213		Pass::setSceneBlending
214		*/
215		enum SceneBlendType
216		{
217		SBT_TRANSPARENT_ALPHA, //!< The alpha value of the rendering output is used as a mask.
218		SBT_TRANSPARENT_COLOUR, //!< Colour the scene based on the brightness of the input colours, but don’t darken.
219		SBT_ADD, //!< The colour of the rendering output is added to the scene. Good for explosions, flares, lights, ghosts etc.
220		SBT_MODULATE, //!< The colour of the rendering output is multiplied with the scene contents. Generally colours and darkens the scene, good for smoked glass, semi-transparent objects etc.
221		SBT_REPLACE //!< The default blend mode where source replaces destination
222		// TODO : more
223		};
224
225		/** Blending factors for manually blending objects with the scene. If there isn't a predefined
226		SceneBlendType that you like, then you can specify the blending factors directly to affect the
227		combination of object and the existing scene. See Material::setSceneBlending for more details.
228		*/
229		enum SceneBlendFactor
230		{
231		SBF_ONE, //!< Constant value of 1.0
232		SBF_ZERO, //!< Constant value of 0.0
233		SBF_DEST_COLOUR, //!< The existing pixel colour
234		SBF_SOURCE_COLOUR, //!< The texture pixel (texel) colour
235		SBF_ONE_MINUS_DEST_COLOUR, //!< 1 - SBF_DEST_COLOUR
236		SBF_ONE_MINUS_SOURCE_COLOUR, //!< 1 - SBF_SOURCE_COLOUR
237		SBF_DEST_ALPHA, //!< The existing pixel alpha value
238		SBF_SOURCE_ALPHA, //!< The texel alpha value
239		SBF_ONE_MINUS_DEST_ALPHA, //!< 1 - SBF_DEST_ALPHA
240		SBF_ONE_MINUS_SOURCE_ALPHA //!< 1 - SBF_SOURCE_ALPHA
241		};
242
243		/** Blending operations controls how objects are blended into the scene. The default operation
244		is add (+) but by changing this you can change how drawn objects are blended into the
245		existing scene.
246		*/
247		enum SceneBlendOperation
248		{
249		SBO_ADD,
250		SBO_SUBTRACT,
251		SBO_REVERSE_SUBTRACT,
252		SBO_MIN,
253		SBO_MAX
254		};
255
256		/** Describes the global blending factors for combining subsequent renders with the existing frame contents.
257
258		By default the operation is Ogre::SBO_ADD, which creates this equation
259
260		$$final = (passOutput * sourceFactor) + (frameBuffer * destFactor)$$
261
262		Each of the factors is specified as one of Ogre::SceneBlendFactor.
263
264		By setting a different Ogre::SceneBlendOperation you can achieve a different effect.
265		*/
266		struct _OgreExport ColourBlendState
267		{
268		/** @name Write Mask
269		* Whether writing is enabled for each of the 4 colour channels */
270		/// @{
271		bool writeR : 1;
272		bool writeG : 1;
273		bool writeB : 1;
274		bool writeA : 1;
275		/// @}
276
277		/** @name Blending factors
278		* used to weight the render colour components and the frame colour components */
279		/// @{
280		SceneBlendFactor sourceFactor;
281		SceneBlendFactor destFactor;
282		SceneBlendFactor sourceFactorAlpha;
283		SceneBlendFactor destFactorAlpha;
284		/// @}
285
286		/** @name Blending operations
287		* The blend operation mode for combining colour values */
288		/// @{
289		SceneBlendOperation operation;
290		SceneBlendOperation alphaOperation;
291		/// @}
292
293		ColourBlendState()
294		: writeR(true), writeG(true), writeB(true), writeA(true), sourceFactor(SBF_ONE),
295		destFactor(SBF_ZERO), sourceFactorAlpha(SBF_ONE), destFactorAlpha(SBF_ZERO),
296		operation(SBO_ADD), alphaOperation(SBO_ADD)
297	0	{
298	0	}
299
300		/// can we simply overwrite the existing pixels or do we have to blend
301		bool blendingEnabled() const
302	0	{
303	0	return !(sourceFactor == SBF_ONE && destFactor == SBF_ZERO &&
304	0	sourceFactorAlpha == SBF_ONE && destFactorAlpha == SBF_ZERO);
305	0	}
306		};
307		/** @} */
308		/** @} */
309
310		}
311
312		#endif