.TH "SDL_CreateRGBSurface" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference" +
−
.SH "NAME"+
−
SDL_CreateRGBSurface\- Create an empty SDL_Surface+
−
.SH "SYNOPSIS"+
−
.PP+
−
\fB#include "SDL\&.h"+
−
.sp+
−
\fBSDL_Surface *\fBSDL_CreateRGBSurface\fP\fR(\fBUint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask\fR);+
−
.SH "DESCRIPTION"+
−
.PP+
−
Allocate an empty surface (must be called after \fISDL_SetVideoMode\fR)+
−
.PP+
−
If \fBdepth\fR is 8 bits an empty palette is allocated for the surface, otherwise a \&'packed-pixel\&' \fI\fBSDL_PixelFormat\fR\fR is created using the \fB[RGBA]mask\fR\&'s provided (see \fI\fBSDL_PixelFormat\fR\fR)\&. The \fBflags\fR specifies the type of surface that should be created, it is an OR\&'d combination of the following possible values\&.+
−
.TP 20+
−
\fBSDL_SWSURFACE\fP+
−
SDL will create the surface in system memory\&. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting\&.+
−
.TP 20+
−
\fBSDL_HWSURFACE\fP+
−
SDL will attempt to create the surface in video memory\&. This will allow SDL to take advantage of Video->Video blits (which are often accelerated)\&.+
−
.TP 20+
−
\fBSDL_SRCCOLORKEY\fP+
−
This flag turns on colourkeying for blits from this surface\&. If \fBSDL_HWSURFACE\fP is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory\&. Use \fI\fBSDL_SetColorKey\fP\fR to set or clear this flag after surface creation\&.+
−
.TP 20+
−
\fBSDL_SRCALPHA\fP+
−
This flag turns on alpha-blending for blits from this surface\&. If \fBSDL_HWSURFACE\fP is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible\&. Use \fI\fBSDL_SetAlpha\fP\fR to set or clear this flag after surface creation\&.+
−
.PP+
−
.RS+
−
\fBNote:  +
−
.PP+
−
If an alpha-channel is specified (that is, if \fBAmask\fR is nonzero), then the \fBSDL_SRCALPHA\fP flag is automatically set\&. You may remove this flag by calling \fI\fBSDL_SetAlpha\fP\fR after surface creation\&.+
−
.RE+
−
.SH "RETURN VALUE"+
−
.PP+
−
Returns the created surface, or \fBNULL\fR upon error\&.+
−
.SH "EXAMPLE"+
−
.PP+
−
.nf+
−
\f(CW    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,+
−
       as expected by OpenGL for textures */+
−
    SDL_Surface *surface;+
−
    Uint32 rmask, gmask, bmask, amask;+
−
+
−
    /* SDL interprets each pixel as a 32-bit number, so our masks must depend+
−
       on the endianness (byte order) of the machine */+
−
#if SDL_BYTEORDER == SDL_BIG_ENDIAN+
−
    rmask = 0xff000000;+
−
    gmask = 0x00ff0000;+
−
    bmask = 0x0000ff00;+
−
    amask = 0x000000ff;+
−
#else+
−
    rmask = 0x000000ff;+
−
    gmask = 0x0000ff00;+
−
    bmask = 0x00ff0000;+
−
    amask = 0xff000000;+
−
#endif+
−
+
−
    surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,+
−
                                   rmask, gmask, bmask, amask);+
−
    if(surface == NULL) {+
−
        fprintf(stderr, "CreateRGBSurface failed: %s+
−
", SDL_GetError());+
−
        exit(1);+
−
    }\fR+
−
.fi+
−
.PP+
−
.SH "SEE ALSO"+
−
.PP+
−
\fI\fBSDL_CreateRGBSurfaceFrom\fP\fR, \fI\fBSDL_FreeSurface\fP\fR, \fI\fBSDL_SetVideoMode\fP\fR, \fI\fBSDL_LockSurface\fP\fR, \fI\fBSDL_PixelFormat\fR\fR, \fI\fBSDL_Surface\fR\fR \fI\fBSDL_SetAlpha\fP\fR \fI\fBSDL_SetColorKey\fP\fR+
−
...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01+
−