SDL_BlitSurface(3)

💅 SDL_BlitSurface — bestie edition 💅

okay so this is a page from the SDL3 FUNCTIONS manual (yes the whole fam, we're in the SDL3 section) and it's about SDL_BlitSurface. it does a fast blit from the source surface to the destination surface, with clipping. no cap. 🦋

---

✨ NAME ✨

SDL_BlitSurface — Performs a fast blit from the source surface to the destination surface with clipping.

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

bool SDL_BlitSurface(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect);

---

💖 DESCRIPTION 💖

so here's the vibe. if srcrect or dstrect are NULL, the entire surface (src or dst) gets copied, while making sure everything stays clipped to dst->clip_rect. very demure, very mindful. 🎀

🚨 not me calling a blit on a locked surface — bestie, do NOT do that. the blit function should not be called on a locked surface. periodt.

the blit semantics for surfaces with and without blending and colorkey are defined as follows, and this is the part you're gonna wanna screenshot:

🌈 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 that do not match 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 that do not match 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 that do not match 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 that do not match the source color key.

---

🎀 FUNCTION PARAMETERS 🎀

• src — the SDL_Surface structure to be copied from. the source, the origin story, the main character. 👑
• srcrect — the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.
• dst — the SDL_Surface structure that is the blit target. it's getting the glow-up.
• dstrect — the SDL_Rect structure representing the x and y position in the destination surface, or NULL for (0,0). the width and height are ignored, and are copied from srcrect. so if you want a specific width and height, you should use SDL_BlitSurfaceScaled(). iykyk. 🫶

---

🫶 RETURN VALUE 🫶

Returns true on success or false on failure; call SDL_GetError() for more information. slay or flop, it's giving binary. 💀

---

🧵 THREAD SAFETY 🧵

Only one thread should be using the src and dst surfaces at any given time. no sharing, no passing them around the group chat while someone else is typing. 🙈

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0.

---

👑 SEE ALSO 👑

• SDL_BlitSurfaceScaled(3)

---

and that's the whole thing bestie, you ate 💅✨

— brought to you by the Simple Directmedia Layer girlies, running the SDL 3.4.18 era, and the page is literally just called SDL_BlitSurface(3). bye ily 🦋🌸💖