Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Blend.h
1 /*
2  * Gamedev Framework (gf)
3  * Copyright (C) 2016 Julien Bernard
4  *
5  * This software is provided 'as-is', without any express or implied
6  * warranty. In no event will the authors be held liable for any damages
7  * arising from the use of this software.
8  *
9  * Permission is granted to anyone to use this software for any purpose,
10  * including commercial applications, and to alter it and redistribute it
11  * freely, subject to the following restrictions:
12  *
13  * 1. The origin of this software must not be misrepresented; you must not
14  * claim that you wrote the original software. If you use this software
15  * in a product, an acknowledgment in the product documentation would be
16  * appreciated but is not required.
17  * 2. Altered source versions must be plainly marked as such, and must not be
18  * misrepresented as being the original software.
19  * 3. This notice may not be removed or altered from any source distribution.
20  *
21  * Part of this file comes from SFML, with the same license:
22  * Copyright (C) 2007-2015 Laurent Gomila (laurent@sfml-dev.org)
23  */
24 #ifndef GF_BLEND_H
25 #define GF_BLEND_H
26 
27 #include "Portability.h"
28 
29 namespace gf {
30 #ifndef DOXYGEN_SHOULD_SKIP_THIS
31 inline namespace v1 {
32 #endif
33 
34  /**
35  * @ingroup graphics
36  * @brief Enumeration of the blending equations
37  *
38  * The equations are mapped directly to their OpenGL equivalents,
39  * specified by [glBlendEquation()](http://docs.gl/es2/glBlendEquation) or
40  * [glBlendEquationSeparate()](http://docs.gl/es2/glBlendEquationSeparate).
41  *
42  * @sa gf::BlendMode
43  */
44  enum class BlendEquation {
45  Add, ///< Pixel = Src * SrcFactor + Dst * DstFactor
46  Substract, ///< Pixel = Src * SrcFactor - Dst * DstFactor
47  ReverseSubstract, ///< Pixel = Dst * DstFactor - Src * SrcFactor
48  };
49 
50  /**
51  * @ingroup graphics
52  * @brief Enumeration of the blending factors
53  *
54  * The factors are mapped directly to their OpenGL equivalents,
55  * specified by [glBlendFunc()](http://docs.gl/es2/glBlendFunc) or
56  * [glBlendFuncSeparate()](http://docs.gl/es2/glBlendFuncSeparate).
57  *
58  * @sa gf::BlendMode
59  */
60  enum class BlendFactor {
61  Zero, ///< (0, 0, 0, 0)
62  One, ///< (1, 1, 1, 1)
63  SrcColor, ///< (src.r, src.g, src.b, src.a)
64  OneMinusSrcColor, ///< (1, 1, 1, 1) - (src.r, src.g, src.b, src.a)
65  DstColor, ///< (dst.r, dst.g, dst.b, dst.a)
66  OneMinusDstColor, ///< (1, 1, 1, 1) - (dst.r, dst.g, dst.b, dst.a)
67  SrcAlpha, ///< (src.a, src.a, src.a, src.a)
68  OneMinusSrcAlpha, ///< (1, 1, 1, 1) - (src.a, src.a, src.a, src.a)
69  DstAlpha, ///< (dst.a, dst.a, dst.a, dst.a)
70  OneMinusDstAlpha ///< (1, 1, 1, 1) - (dst.a, dst.a, dst.a, dst.a)
71  };
72 
73  /**
74  * @ingroup graphics
75  * @brief Blending modes for drawing.
76  *
77  * gf::BlendMode is a class that represents a
78  * [blend mode](https://www.opengl.org/wiki/Blending). A blend
79  * mode determines how the colors of an object you draw are
80  * mixed with the colors that are already in the buffer.
81  *
82  * The class is composed of 6 components, each of which has its
83  * own public member variable:
84  *
85  * - color source factor (@ref colorSrcFactor)
86  * - color destination Factor (@ref colorDstFactor)
87  * - color blend equation (@ref colorEquation)
88  * - alpha source factor (@ref alphaSrcFactor)
89  * - alpha destination factor (@ref alphaDstFactor)
90  * - alpha blend equation (@ref alphaEquation)
91  *
92  * The source factor specifies how the pixel you are drawing contributes
93  * to the final color. The destination factor specifies how the pixel
94  * already drawn in the buffer contributes to the final color.
95  *
96  * The color channels RGB (red, green, blue; simply referred to as
97  * color) and A (alpha; the transparency) can be treated separately. This
98  * separation can be useful for specific blend modes, but most often you
99  * won't need it and will simply treat the color as a single unit.
100  *
101  * The blend factors and equations correspond to their OpenGL equivalents.
102  * In general, the color of the resulting pixel is calculated according
103  * to the following formula (`src` is the color of the source pixel, `dst`
104  * the color of the destination pixel, the other variables correspond to the
105  * public members, with the equations being + or - operators):
106  *
107  * ~~~
108  * dst.rgb = colorSrcFactor * src.rgb (colorEquation) colorDstFactor * dst.rgb
109  * dst.a = alphaSrcFactor * src.a (alphaEquation) alphaDstFactor * dst.a
110  * ~~~
111  *
112  * All factors and colors are represented as floating point numbers between
113  * 0 and 1. Where necessary, the result is clamped to fit in that range.
114  *
115  * The most common blending modes are defined as constants
116  * in the `gf::PredefinedBlendMonde` namespace:
117  *
118  * ~~~{.cc}
119  * gf::BlendMode alphaBlending = gf::BlendAlpha;
120  * gf::BlendMode additiveBlending = gf::BlendAdd;
121  * gf::BlendMode multiplicativeBlending = gf::BlendMultiply;
122  * gf::BlendMode noBlending = gf::BlendNone;
123  * ~~~
124  *
125  * A blend mode can be specified every time you draw a gf::Drawable
126  * object to a gf::RenderWindow. It is part of the gf::RenderStates compound
127  * that is passed to the member function gf::RenderTarget::draw().
128  *
129  * @sa gf::BlendFactor, gf::BlendEquation, gf::RenderStates, gf::RenderWindow
130  *
131  */
132  struct GF_API BlendMode {
133 
134  /**
135  * @brief Default constructor
136  *
137  * Constructs a blending mode that does alpha blending.
138  */
139  constexpr BlendMode()
146  {
147 
148  }
149 
150  /**
151  * @brief Construct the blend mode given the factors and equation.
152  *
153  * This constructor uses the same factors and equation for both
154  * color and alpha components. It also defaults to the Add equation.
155  *
156  * @param sourceFactor Specifies how to compute the source factor for the color and alpha channels.
157  * @param destinationFactor Specifies how to compute the destination factor for the color and alpha channels.
158  * @param equation Specifies how to combine the source and destination colors and alpha.
159  */
160  constexpr BlendMode(BlendFactor sourceFactor, BlendFactor destinationFactor, BlendEquation equation = BlendEquation::Add)
161  : colorSrcFactor(sourceFactor)
162  , colorDstFactor(destinationFactor)
163  , colorEquation(equation)
164  , alphaSrcFactor(sourceFactor)
165  , alphaDstFactor(destinationFactor)
166  , alphaEquation(equation)
167  {
168 
169  }
170 
171  /**
172  * @brief Construct the blend mode given the factors and equation.
173  *
174  * @param colorSourceFactor Specifies how to compute the source function for the color channels.
175  * @param colorDestinationFactor Specifies how to compute the destination factor for the color channels.
176  * @param colorBlendEquation Specifies how to combine the source and destination colors.
177  * @param alphaSourceFactor Specifies how to compute the source factor.
178  * @param alphaDestinationFactor Specifies how to compute the destination factor.
179  * @param alphaBlendEquation Specifies how to combine the source and destination alphas.
180  */
181  constexpr BlendMode(BlendFactor colorSourceFactor, BlendFactor colorDestinationFactor, BlendEquation colorBlendEquation,
182  BlendFactor alphaSourceFactor, BlendFactor alphaDestinationFactor, BlendEquation alphaBlendEquation)
183  : colorSrcFactor(colorSourceFactor)
184  , colorDstFactor(colorDestinationFactor)
185  , colorEquation(colorBlendEquation)
186  , alphaSrcFactor(alphaSourceFactor)
187  , alphaDstFactor(alphaDestinationFactor)
188  , alphaEquation(alphaBlendEquation)
189  {
190 
191  }
192 
193  BlendFactor colorSrcFactor; ///< Source blending factor for the color channels
194  BlendFactor colorDstFactor; ///< Destination blending factor for the color channels
195  BlendEquation colorEquation; ///< Blending equation for the color channels
196  BlendFactor alphaSrcFactor; ///< Source blending factor for the alpha channel
197  BlendFactor alphaDstFactor; ///< Destination blending factor for the alpha channel
198  BlendEquation alphaEquation; ///< Blending equation for the alpha channel
199  };
200 
201  /**
202  * @ingroup graphics
203  * @brief Alpha blend mode
204  *
205  * Blend source and dest according to dest alpha. Also known as
206  * [alpha blending](https://en.wikipedia.org/wiki/Alpha_compositing#Alpha_blending).
207  *
208  * @sa gf::BlendMode
209  */
210  constexpr BlendMode BlendAlpha
211  #ifndef DOXYGEN_SHOULD_SKIP_THIS
212  = BlendMode(
215  )
216  #endif
217  ;
218 
219  /**
220  * @ingroup graphics
221  * @brief Additive blend mode
222  *
223  * Add source to dest.
224  *
225  * @sa gf::BlendMode
226  */
227  constexpr BlendMode BlendAdd
228  #ifndef DOXYGEN_SHOULD_SKIP_THIS
229  = BlendMode(
232  )
233  #endif
234  ;
235 
236  /**
237  * @ingroup graphics
238  * @brief Multiplicative blend mode
239  *
240  * Multiply source and dest.
241  *
242  * @sa gf::BlendMode
243  */
244  constexpr BlendMode BlendMultiply
245  #ifndef DOXYGEN_SHOULD_SKIP_THIS
247  #endif
248  ;
249 
250  /**
251  * @ingroup graphics
252  * @brief No blend mode
253  *
254  * Overwrite dest with source.
255  *
256  * @sa gf::BlendMode
257  */
258  constexpr BlendMode BlendNone
259  #ifndef DOXYGEN_SHOULD_SKIP_THIS
261  #endif
262  ;
263 
264 
265  /**
266  * @relates BlendMode
267  * @brief Equality operator
268  *
269  * @param lhs First blend mode
270  * @param rhs Second blend mode
271  * @return True if the blend modes are the same
272  */
273  constexpr bool operator==(const BlendMode& lhs, const BlendMode& rhs) {
274  return lhs.colorSrcFactor == rhs.colorSrcFactor
275  && lhs.colorDstFactor == rhs.colorDstFactor
276  && lhs.colorEquation == rhs.colorEquation
277  && lhs.alphaSrcFactor == rhs.alphaSrcFactor
278  && lhs.alphaDstFactor == rhs.alphaDstFactor
279  && lhs.alphaEquation == rhs.alphaEquation;
280  }
281 
282 #ifndef DOXYGEN_SHOULD_SKIP_THIS
283 }
284 #endif
285 }
286 
287 #endif // GF_BLEND_H
Pixel = Dst * DstFactor - Src * SrcFactor.
BlendEquation alphaEquation
Blending equation for the alpha channel.
Definition: Blend.h:198
(1, 1, 1, 1) - (src.r, src.g, src.b, src.a)
(1, 1, 1, 1) - (dst.r, dst.g, dst.b, dst.a)
BlendFactor colorSrcFactor
Source blending factor for the color channels.
Definition: Blend.h:193
constexpr BlendMode BlendAlpha
Alpha blend mode.
Definition: Blend.h:217
constexpr BlendMode BlendNone
No blend mode.
Definition: Blend.h:262
Pixel = Src * SrcFactor - Dst * DstFactor.
(1, 1, 1, 1) - (src.a, src.a, src.a, src.a)
BlendFactor colorDstFactor
Destination blending factor for the color channels.
Definition: Blend.h:194
BlendFactor alphaDstFactor
Destination blending factor for the alpha channel.
Definition: Blend.h:197
BlendEquation colorEquation
Blending equation for the color channels.
Definition: Blend.h:195
(dst.r, dst.g, dst.b, dst.a)
constexpr BlendMode(BlendFactor colorSourceFactor, BlendFactor colorDestinationFactor, BlendEquation colorBlendEquation, BlendFactor alphaSourceFactor, BlendFactor alphaDestinationFactor, BlendEquation alphaBlendEquation)
Construct the blend mode given the factors and equation.
Definition: Blend.h:181
Definition: Action.h:34
BlendFactor alphaSrcFactor
Source blending factor for the alpha channel.
Definition: Blend.h:196
constexpr BlendMode BlendMultiply
Multiplicative blend mode.
Definition: Blend.h:248
Pixel = Src * SrcFactor + Dst * DstFactor.
Blending modes for drawing.
Definition: Blend.h:132
(src.a, src.a, src.a, src.a)
constexpr BlendMode BlendAdd
Additive blend mode.
Definition: Blend.h:234
(1, 1, 1, 1) - (dst.a, dst.a, dst.a, dst.a)
constexpr BlendMode()
Default constructor.
Definition: Blend.h:139
constexpr bool operator==(const BlendMode &lhs, const BlendMode &rhs)
Equality operator.
Definition: Blend.h:273
BlendFactor
Enumeration of the blending factors.
Definition: Blend.h:60
(src.r, src.g, src.b, src.a)
BlendEquation
Enumeration of the blending equations.
Definition: Blend.h:44
constexpr BlendMode(BlendFactor sourceFactor, BlendFactor destinationFactor, BlendEquation equation=BlendEquation::Add)
Construct the blend mode given the factors and equation.
Definition: Blend.h:160
(dst.a, dst.a, dst.a, dst.a)
#define GF_API
Definition: Portability.h:35