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.

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 function should not be called on a locked surface. I.e. when you use your own drawing functions you may need to lock a surface, but this is not the case with SDL_BlitSurface. Like most surface manipulation functions in SDL, it should not be used together with OpenGL.

The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL_SetAlpha for an explanation 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 )
                        SDL_Delay(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.

Note: the SDL blitter does not (yet) have the capability of scaling the blitted surfaces up or down like it is the case with other more sophisticated blitting mechanisms. You have to figure something out for yourself if you want to scale images (e.g. use SDL_gfx).

Note: when you're blitting between two alpha surfaces, normally the alpha of the destination acts as a mask. If you want to just do a "dumb copy" that doesn't blend, you have to turn off the SDL_SRCALPHA flag on the source surface. This is how it's supposed to work, but can be surprising when you're trying to combine one image with another and both have transparent backgrounds.

See Also

SDL_FillRect, SDL_LockSurface, SDL_Rect, SDL_SetAlpha, SDL_SetColorKey, SDL_Surface

SDL_BlitSurface (last edited 2010-05-02 16:04:36 by 80)