From bcf1397e330f38f6fe4cf1fec980acea4d37d8d1 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <icculus-sdlwikibot@icculus.org>
Date: Sun, 20 Oct 2024 01:02:07 +0000
Subject: [PATCH] Sync SDL2 wiki -> header

[ci skip]
---
 include/SDL_surface.h | 77 ++++++++++++++++++++++---------------------
 1 file changed, 40 insertions(+), 37 deletions(-)

diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index 527016209b..9123422b4f 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:
+ * ```
+ *   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.
  *
- * - 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.
  *
- * RGB to RGBA:
+ *   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.
  *
- * - 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.
+ *   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.