Wiki Page Content

SDL_BlitSurface

Use this function to perform a fast surface copy to a destination surface.

Syntax

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

Function 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 rectangle that is copied into

Return Value

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

Code Examples

SDL_BlitSurface(surface, &source_rect, temp_surface, NULL);

Remarks

You should call SDL_BlitSurface() unless you know exactly how SDL blitting works internally and how to use the other blit functions.

This is the public blit function, and it performs rectangle validation and clipping before passing it to SDL_LowerBlit().

The blit function should not be called on a locked surface.

The width and height in srcrect determine the size of the copied rectangle. Only the position is used in the dstrect (the width and height are ignored). Blits with negative dstrect coordinates will be clipped properly.

If srcrect is NULL, the entire surface is copied. If dstrect is NULL, then the destination position (upper left corner) is (0, 0).

The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).

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.


CategoryAPI, CategorySurface

None: SDL_BlitSurface (last edited 2014-03-30 21:07:59 by PhilippWiesemann)

(Page Info.)
Feedback
Please include your contact information if you'd like to receive a reply.
Submit