SDL Library Documentation
Prev |  | Next

# SDL_BlitSurface

## Name

SDL_BlitSurface -- This performs a fast blit from the source surface to the destination surface.

## Synopsis

    #include "SDL.h"

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

## Description

This performs a fast blit from the source surface to the destination surface.

Only the position is used in the `dstrect` (the width and height are ignored).

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 (`srcrect` is not modified).

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

The results of blitting operations vary greatly depending on whether `SDL_SRCAPLHA` is set or not. See SDL_SetAlpha for an explaination of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting, as the following pseudo-code should hopefully explain.

    if (source surface has SDL_SRCALPHA set) {
        if (source surface has alpha channel (that is, format->Amask != 0))
            blit using per-pixel alpha, ignoring any colour key
        else {
            if (source surface has SDL_SRCCOLORKEY set)
                blit using the colour key AND the per-surface alpha value
            else
                blit using the per-surface alpha value
        }
    } else {
        if (source surface has SDL_SRCCOLORKEY set)
            blit using the colour key
        else
            ordinary opaque rectangular blit
    }

## Return Value

If the blit is successful, it returns 0, otherwise it returns -1.

If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost, so it should be reloaded with artwork and re-blitted:

            while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
                    while ( SDL_LockSurface(image)) < 0 )
                            Sleep(10);
                    -- Write image pixels to image->pixels --
                    SDL_UnlockSurface(image);
            }

This happens under DirectX 5.0 when the system switches away from your fullscreen application. Locking the surface will also fail until you have access to the video memory again.

## See Also

`SDL_LockSurface`, `SDL_FillRect`, SDL_Surface, SDL_Rect

Prev | Home | Next
SDL_ConvertSurface | Up | SDL_FillRect