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.

> Note: The results of blitting operations vary greatly depending on whether `SDL_SRCAPLHA` is set or not. See SDL_SetAlpha.

## 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