From 4ca7a193484eaaf98d99f6d68aa0313dad16b72c Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <icculus-sdlwikibot@icculus.org>
Date: Sat, 19 Oct 2024 18:04:39 +0000
Subject: [PATCH] Sync SDL2 wiki -> header

[ci skip]
---
 include/SDL_surface.h | 52 +++++--------------------------------------
 1 file changed, 5 insertions(+), 47 deletions(-)

diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index 9123422b4f..a38e964e54 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -806,59 +806,17 @@ extern DECLSPEC int SDLCALL SDL_FillRects
 /**
  * Performs a fast blit from the source surface to the destination surface.
  *
- * 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 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.
  *
  * 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->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.
- *
  * \returns 0 if the blit is successful, otherwise it returns -1.
  */
 #define SDL_BlitSurface SDL_UpperBlit