SDL 3.0
SDL_blendmode.h File Reference
+ Include dependency graph for SDL_blendmode.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define SDL_BLENDMODE_NONE   0x00000000u
 
#define SDL_BLENDMODE_BLEND   0x00000001u
 
#define SDL_BLENDMODE_BLEND_PREMULTIPLIED   0x00000010u
 
#define SDL_BLENDMODE_ADD   0x00000002u
 
#define SDL_BLENDMODE_ADD_PREMULTIPLIED   0x00000020u
 
#define SDL_BLENDMODE_MOD   0x00000004u
 
#define SDL_BLENDMODE_MUL   0x00000008u
 
#define SDL_BLENDMODE_INVALID   0x7FFFFFFFu
 

Typedefs

typedef Uint32 SDL_BlendMode
 

Enumerations

enum  SDL_BlendOperation {
  SDL_BLENDOPERATION_ADD = 0x1 ,
  SDL_BLENDOPERATION_SUBTRACT = 0x2 ,
  SDL_BLENDOPERATION_REV_SUBTRACT = 0x3 ,
  SDL_BLENDOPERATION_MINIMUM = 0x4 ,
  SDL_BLENDOPERATION_MAXIMUM = 0x5
}
 
enum  SDL_BlendFactor {
  SDL_BLENDFACTOR_ZERO = 0x1 ,
  SDL_BLENDFACTOR_ONE = 0x2 ,
  SDL_BLENDFACTOR_SRC_COLOR = 0x3 ,
  SDL_BLENDFACTOR_ONE_MINUS_SRC_COLOR = 0x4 ,
  SDL_BLENDFACTOR_SRC_ALPHA = 0x5 ,
  SDL_BLENDFACTOR_ONE_MINUS_SRC_ALPHA = 0x6 ,
  SDL_BLENDFACTOR_DST_COLOR = 0x7 ,
  SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR = 0x8 ,
  SDL_BLENDFACTOR_DST_ALPHA = 0x9 ,
  SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA = 0xA
}
 

Functions

SDL_BlendMode SDL_ComposeCustomBlendMode (SDL_BlendFactor srcColorFactor, SDL_BlendFactor dstColorFactor, SDL_BlendOperation colorOperation, SDL_BlendFactor srcAlphaFactor, SDL_BlendFactor dstAlphaFactor, SDL_BlendOperation alphaOperation)
 

Macro Definition Documentation

◆ SDL_BLENDMODE_ADD

#define SDL_BLENDMODE_ADD   0x00000002u

additive blending: dstRGB = (srcRGB * srcA) + dstRGB, dstA = dstA

Definition at line 57 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_ADD_PREMULTIPLIED

#define SDL_BLENDMODE_ADD_PREMULTIPLIED   0x00000020u

pre-multiplied additive blending: dstRGB = srcRGB + dstRGB, dstA = dstA

Definition at line 58 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_BLEND

#define SDL_BLENDMODE_BLEND   0x00000001u

alpha blending: dstRGB = (srcRGB * srcA) + (dstRGB * (1-srcA)), dstA = srcA + (dstA * (1-srcA))

Definition at line 55 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_BLEND_PREMULTIPLIED

#define SDL_BLENDMODE_BLEND_PREMULTIPLIED   0x00000010u

pre-multiplied alpha blending: dstRGBA = srcRGBA + (dstRGBA * (1-srcA))

Definition at line 56 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_INVALID

#define SDL_BLENDMODE_INVALID   0x7FFFFFFFu

Definition at line 61 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_MOD

#define SDL_BLENDMODE_MOD   0x00000004u

color modulate: dstRGB = srcRGB * dstRGB, dstA = dstA

Definition at line 59 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_MUL

#define SDL_BLENDMODE_MUL   0x00000008u

color multiply: dstRGB = (srcRGB * dstRGB) + (dstRGB * (1-srcA)), dstA = dstA

Definition at line 60 of file SDL_blendmode.h.

◆ SDL_BLENDMODE_NONE

#define SDL_BLENDMODE_NONE   0x00000000u

no blending: dstRGBA = srcRGBA

Definition at line 54 of file SDL_blendmode.h.

Typedef Documentation

◆ SDL_BlendMode

CategoryBlendmode

Blend modes decide how two colors will mix together. There are both standard modes for basic needs and a means to create custom modes, dictating what sort of math to do what on what color components. A set of blend modes used in drawing operations.

These predefined blend modes are supported everywhere.

Additional values may be obtained from SDL_ComposeCustomBlendMode.

Since
This datatype is available since SDL 3.1.3.
See also
SDL_ComposeCustomBlendMode

Definition at line 52 of file SDL_blendmode.h.

Enumeration Type Documentation

◆ SDL_BlendFactor

The normalized factor used to multiply pixel components.

The blend factors are multiplied with the pixels from a drawing operation (src) and the pixels from the render target (dst) before the blend operation. The comma-separated factors listed above are always applied in the component order red, green, blue, and alpha.

Since
This enum is available since SDL 3.1.3.
Enumerator
SDL_BLENDFACTOR_ZERO 

0, 0, 0, 0

SDL_BLENDFACTOR_ONE 

1, 1, 1, 1

SDL_BLENDFACTOR_SRC_COLOR 

srcR, srcG, srcB, srcA

SDL_BLENDFACTOR_ONE_MINUS_SRC_COLOR 

1-srcR, 1-srcG, 1-srcB, 1-srcA

SDL_BLENDFACTOR_SRC_ALPHA 

srcA, srcA, srcA, srcA

SDL_BLENDFACTOR_ONE_MINUS_SRC_ALPHA 

1-srcA, 1-srcA, 1-srcA, 1-srcA

SDL_BLENDFACTOR_DST_COLOR 

dstR, dstG, dstB, dstA

SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR 

1-dstR, 1-dstG, 1-dstB, 1-dstA

SDL_BLENDFACTOR_DST_ALPHA 

dstA, dstA, dstA, dstA

SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA 

1-dstA, 1-dstA, 1-dstA, 1-dstA

Definition at line 88 of file SDL_blendmode.h.

89{
90 SDL_BLENDFACTOR_ZERO = 0x1, /**< 0, 0, 0, 0 */
91 SDL_BLENDFACTOR_ONE = 0x2, /**< 1, 1, 1, 1 */
92 SDL_BLENDFACTOR_SRC_COLOR = 0x3, /**< srcR, srcG, srcB, srcA */
93 SDL_BLENDFACTOR_ONE_MINUS_SRC_COLOR = 0x4, /**< 1-srcR, 1-srcG, 1-srcB, 1-srcA */
94 SDL_BLENDFACTOR_SRC_ALPHA = 0x5, /**< srcA, srcA, srcA, srcA */
95 SDL_BLENDFACTOR_ONE_MINUS_SRC_ALPHA = 0x6, /**< 1-srcA, 1-srcA, 1-srcA, 1-srcA */
96 SDL_BLENDFACTOR_DST_COLOR = 0x7, /**< dstR, dstG, dstB, dstA */
97 SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR = 0x8, /**< 1-dstR, 1-dstG, 1-dstB, 1-dstA */
98 SDL_BLENDFACTOR_DST_ALPHA = 0x9, /**< dstA, dstA, dstA, dstA */
99 SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA = 0xA /**< 1-dstA, 1-dstA, 1-dstA, 1-dstA */
SDL_BlendFactor
@ SDL_BLENDFACTOR_ONE_MINUS_SRC_COLOR
@ SDL_BLENDFACTOR_ZERO
@ SDL_BLENDFACTOR_SRC_COLOR
@ SDL_BLENDFACTOR_SRC_ALPHA
@ SDL_BLENDFACTOR_ONE_MINUS_DST_COLOR
@ SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA
@ SDL_BLENDFACTOR_ONE_MINUS_SRC_ALPHA
@ SDL_BLENDFACTOR_DST_ALPHA
@ SDL_BLENDFACTOR_DST_COLOR
@ SDL_BLENDFACTOR_ONE

◆ SDL_BlendOperation

The blend operation used when combining source and destination pixel components.

Since
This enum is available since SDL 3.1.3.
Enumerator
SDL_BLENDOPERATION_ADD 

dst + src: supported by all renderers

SDL_BLENDOPERATION_SUBTRACT 

src - dst : supported by D3D, OpenGL, OpenGLES, and Vulkan

SDL_BLENDOPERATION_REV_SUBTRACT 

dst - src : supported by D3D, OpenGL, OpenGLES, and Vulkan

SDL_BLENDOPERATION_MINIMUM 

min(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan

SDL_BLENDOPERATION_MAXIMUM 

max(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan

Definition at line 69 of file SDL_blendmode.h.

70{
71 SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */
72 SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D, OpenGL, OpenGLES, and Vulkan */
73 SDL_BLENDOPERATION_REV_SUBTRACT = 0x3, /**< dst - src : supported by D3D, OpenGL, OpenGLES, and Vulkan */
74 SDL_BLENDOPERATION_MINIMUM = 0x4, /**< min(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */
75 SDL_BLENDOPERATION_MAXIMUM = 0x5 /**< max(dst, src) : supported by D3D, OpenGL, OpenGLES, and Vulkan */
SDL_BlendOperation
@ SDL_BLENDOPERATION_MAXIMUM
@ SDL_BLENDOPERATION_MINIMUM
@ SDL_BLENDOPERATION_REV_SUBTRACT
@ SDL_BLENDOPERATION_ADD
@ SDL_BLENDOPERATION_SUBTRACT

Function Documentation

◆ SDL_ComposeCustomBlendMode()

SDL_BlendMode SDL_ComposeCustomBlendMode ( SDL_BlendFactor  srcColorFactor,
SDL_BlendFactor  dstColorFactor,
SDL_BlendOperation  colorOperation,
SDL_BlendFactor  srcAlphaFactor,
SDL_BlendFactor  dstAlphaFactor,
SDL_BlendOperation  alphaOperation 
)
extern

Compose a custom blend mode for renderers.

The functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode accept the SDL_BlendMode returned by this function if the renderer supports it.

A blend mode controls how the pixels from a drawing operation (source) get combined with the pixels from the render target (destination). First, the components of the source and destination pixels get multiplied with their blend factors. Then, the blend operation takes the two products and calculates the result that will get stored in the render target.

Expressed in pseudocode, it would look like this:

dstRGB = colorOperation(srcRGB * srcColorFactor, dstRGB * dstColorFactor);
dstA = alphaOperation(srcA * srcAlphaFactor, dstA * dstAlphaFactor);

Where the functions colorOperation(src, dst) and alphaOperation(src, dst) can return one of the following:

  • src + dst
  • src - dst
  • dst - src
  • min(src, dst)
  • max(src, dst)

The red, green, and blue components are always multiplied with the first, second, and third components of the SDL_BlendFactor, respectively. The fourth component is not used.

The alpha component is always multiplied with the fourth component of the SDL_BlendFactor. The other components are not used in the alpha calculation.

Support for these blend modes varies for each renderer. To check if a specific SDL_BlendMode is supported, create a renderer and pass it to either SDL_SetRenderDrawBlendMode or SDL_SetTextureBlendMode. They will return with an error if the blend mode is not supported.

This list describes the support of custom blend modes for each renderer. All renderers support the four blend modes listed in the SDL_BlendMode enumeration.

  • direct3d: Supports all operations with all factors. However, some factors produce unexpected results with SDL_BLENDOPERATION_MINIMUM and SDL_BLENDOPERATION_MAXIMUM.
  • direct3d11: Same as Direct3D 9.
  • opengl: Supports the SDL_BLENDOPERATION_ADD operation with all factors. OpenGL versions 1.1, 1.2, and 1.3 do not work correctly here.
  • opengles2: Supports the SDL_BLENDOPERATION_ADD, SDL_BLENDOPERATION_SUBTRACT, SDL_BLENDOPERATION_REV_SUBTRACT operations with all factors.
  • psp: No custom blend mode support.
  • software: No custom blend mode support.

Some renderers do not provide an alpha component for the default render target. The SDL_BLENDFACTOR_DST_ALPHA and SDL_BLENDFACTOR_ONE_MINUS_DST_ALPHA factors do not have an effect in this case.

Parameters
srcColorFactorthe SDL_BlendFactor applied to the red, green, and blue components of the source pixels.
dstColorFactorthe SDL_BlendFactor applied to the red, green, and blue components of the destination pixels.
colorOperationthe SDL_BlendOperation used to combine the red, green, and blue components of the source and destination pixels.
srcAlphaFactorthe SDL_BlendFactor applied to the alpha component of the source pixels.
dstAlphaFactorthe SDL_BlendFactor applied to the alpha component of the destination pixels.
alphaOperationthe SDL_BlendOperation used to combine the alpha component of the source and destination pixels.
Returns
an SDL_BlendMode that represents the chosen factors and operations.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.1.3.
See also
SDL_SetRenderDrawBlendMode
SDL_GetRenderDrawBlendMode
SDL_SetTextureBlendMode
SDL_GetTextureBlendMode