SDL_ComposeCustomBlendMode(3)

💖 SDL_ComposeCustomBlendMode 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today's main character is SDL_ComposeCustomBlendMode(3) — the girl who lets you build your very own blend mode from scratch. no cap. 🎀

---

✨ NAME ✨

SDL_ComposeCustomBlendMode — compose a custom blend mode for renderers. it's giving "make it yourself, babe". 💅

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_blendmode.h>

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

six whole arguments, she's high maintenance but worth it 🫶

---

✨ DESCRIPTION ✨

so like. the functions SDL_SetRenderDrawBlendMode and SDL_SetTextureBlendMode will happily accept the SDL_BlendMode that this function hands you — but only if the renderer supports it. vibe check first, always. 🌸

a blend mode is literally just the rules for how the pixels from a drawing operation (source) get combined with the pixels already chillin' in the render target (destination). here's the tea:

1. first, the components of the source and destination pixels get multiplied by their blend factors.
2. then the blend operation takes those two products and calculates the result that gets stored in the render target.

expressed in pseudocode, it looks 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)

slay. five options, all iconic. ⭐

the red, green, and blue components are always multiplied with the first, second, and third components of the SDL_BlendFactor, respectively. the fourth component? not used. she said "i'm not in this scene". 💀

the alpha component is always multiplied with the fourth component of the SDL_BlendFactor. the other components are not used in the alpha calculation. fair's fair. 🙈

⚠️ 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. no silent failures, she tells you to your face. 😭

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. (not me trusting those two 💀)
• 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. they just show up and do nothing, main character energy but make it unemployed. 🧚

---

✨ FUNCTION PARAMETERS ✨

• srcColorFactor — the SDL_BlendFactor applied to the red, green, and blue components of the source pixels.
• dstColorFactor — the SDL_BlendFactor applied to the red, green, and blue components of the destination pixels.
• colorOperation — the SDL_BlendOperation used to combine the red, green, and blue components of the source and destination pixels.
• srcAlphaFactor — the SDL_BlendFactor applied to the alpha component of the source pixels.
• dstAlphaFactor — the SDL_BlendFactor applied to the alpha component of the destination pixels.
• alphaOperation — the SDL_BlendOperation used to combine the alpha component of the source and destination pixels.

six parameters, six chances to mess it up, but you won't, bestie. 🫶

---

✨ RETURN VALUE ✨

returns an SDL_BlendMode that represents the chosen factors and operations. that's it, that's the gift. 🎁

---

✨ THREAD SAFETY ✨

it is safe to call this function from any thread. go off, multithreaded queen. 👑

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. old enough to be trusted, young enough to be fun. ⭐

---

✨ SEE ALSO ✨

• SDL_SetRenderDrawBlendMode(3)
• SDL_GetRenderDrawBlendMode(3)
• SDL_SetTextureBlendMode(3)
• SDL_GetTextureBlendMode(3)

---

and that's the whole page, periodt. 💜

this has been Simple Directmedia Layer, SDL 3.4.18, and yes — SDL_ComposeCustomBlendMode(3) — that's the one, that's her. go compose something gorgeous. 💖✨🌈