From 1af0b398334bae6ae93d327dfb5f1aecebe5e0ca Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Sun, 20 Oct 2024 00:51:30 +0000
Subject: [PATCH] Sync SDL2 wiki -> header
[ci skip]
---
include/SDL_surface.h | 39 +++++++++++++++++++++++++++++++++++++++
1 file changed, 39 insertions(+)
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index a38e964e54c74..527016209b5b6 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -817,6 +817,45 @@ extern DECLSPEC int SDLCALL SDL_FillRects
* The blit semantics for surfaces with and without blending and colorkey are
* defined as follows:
*
+ * RGBA to RGB:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ * (using the source alpha-channel and per-surface alpha) SDL_SRCCOLORKEY
+ * ignored.
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB. * if
+ * SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the
+ * source color key, ignoring alpha in the comparison.
+ *
+ * RGB to RGBA:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ * (using the source per-surface alpha)
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB, set
+ * destination alpha to source per-surface alpha value.
+ * - both: * if SDL_SRCCOLORKEY set, only copy the pixels matching the source
+ * color key.
+ *
+ * RGBA to RGBA:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ * (using the source alpha-channel and per-surface alpha) * SDL_SRCCOLORKEY
+ * ignored.
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy all of RGBA
+ * to the destination. * if SDL_SRCCOLORKEY set, only copy the pixels
+ * matching the RGB values of the source color key, ignoring alpha in the
+ * comparison.
+ *
+ * RGB to RGB:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ * (using the source per-surface alpha)
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB.
+ * - both: * if SDL_SRCCOLORKEY set, only copy the pixels matching the source
+ * color key.
+ *
+ * You should call SDL_BlitSurface() unless you know exactly how SDL blitting
+ * works internally and how to use the other blit functions.
+ *
* \returns 0 if the blit is successful, otherwise it returns -1.
*/
#define SDL_BlitSurface SDL_UpperBlit