From bcf1397e330f38f6fe4cf1fec980acea4d37d8d1 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Sun, 20 Oct 2024 01:02:07 +0000
Subject: [PATCH] Sync SDL2 wiki -> header
[ci skip]
---
include/SDL_surface.h | 83 ++++++++++++++++++++++---------------------
1 file changed, 43 insertions(+), 40 deletions(-)
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index 527016209b5b6..9123422b4f752 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -806,52 +806,55 @@ extern DECLSPEC int SDLCALL SDL_FillRects
/**
* Performs a fast blit from the source surface to the destination surface.
*
- * This is defined as a macro to SDL_UpperBlit to be less confusing.This
- * assumes that the source and destination rectangles are the same size. If
- * either `srcrect` or `dstrect` are NULL, the entire surface (`src` or `dst`)
- * is copied. The final blit rectangles are saved in `srcrect` and `dstrect`
- * after all clipping is performed.
+ * This assumes that the source and destination rectangles are the same size.
+ * If either `srcrect` or `dstrect` are NULL, the entire surface (`src` or
+ * `dst`) is copied. The final blit rectangles are saved in `srcrect` and
+ * `dstrect` after all clipping is performed.
*
* The blit function should not be called on a locked surface.
*
* 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.
+ * ```
+ * RGBA->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->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->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->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.