(See SDL3/SDL_BlitSurface for the SDL3 version.)

SDL_BlitSurface

Performs a fast blit from the source surface to the destination surface.

Header File

Defined in SDL_surface.h

Syntax

#define SDL_BlitSurface SDL_UpperBlit

Macro Parameters

src	the SDL_Surface structure to be copied from.
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.
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. If you want a specific width and height, you should use SDL_BlitScaled().

Return Value

Returns 0 if the blit is successful or a negative error code on failure; call SDL_GetError() for more information.

Remarks

This assumes that the source and destination rectangles are the same size. dstrect's width and height are ignored, only its position is used. If either srcrect or dstrect are NULL, the entire surface (src or dst) is copied. The final blit rectangle is saved in 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.

---

CategoryAPI, CategoryAPIMacro, CategorySurface

All wiki content is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).
Wiki powered by ghwikipp.