docs/man3/SDL_CreateRGBSurface.3
author Sam Lantinga <slouken@libsdl.org>
Wed, 08 Mar 2006 18:30:12 +0000
changeset 1486 9d77fc9d0ace
parent 181 e5bc29de3f0a
child 2283 546f7c1eb755
permissions -rw-r--r--
Re-added C runtime support for Visual C++ 5,6
     1 .TH "SDL_CreateRGBSurface" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference" 
     2 .SH "NAME"
     3 SDL_CreateRGBSurface\- Create an empty SDL_Surface
     4 .SH "SYNOPSIS"
     5 .PP
     6 \fB#include "SDL\&.h"
     7 .sp
     8 \fBSDL_Surface *\fBSDL_CreateRGBSurface\fP\fR(\fBUint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask\fR);
     9 .SH "DESCRIPTION"
    10 .PP
    11 Allocate an empty surface (must be called after \fISDL_SetVideoMode\fR)
    12 .PP
    13 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\&.
    14 .TP 20
    15 \fBSDL_SWSURFACE\fP
    16 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\&.
    17 .TP 20
    18 \fBSDL_HWSURFACE\fP
    19 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)\&.
    20 .TP 20
    21 \fBSDL_SRCCOLORKEY\fP
    22 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\&.
    23 .TP 20
    24 \fBSDL_SRCALPHA\fP
    25 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\&.
    26 .PP
    27 .RS
    28 \fBNote:  
    29 .PP
    30 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\&.
    31 .RE
    32 .SH "RETURN VALUE"
    33 .PP
    34 Returns the created surface, or \fBNULL\fR upon error\&.
    35 .SH "EXAMPLE"
    36 .PP
    37 .nf
    38 \f(CW    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
    39        as expected by OpenGL for textures */
    40     SDL_Surface *surface;
    41     Uint32 rmask, gmask, bmask, amask;
    42 
    43     /* SDL interprets each pixel as a 32-bit number, so our masks must depend
    44        on the endianness (byte order) of the machine */
    45 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
    46     rmask = 0xff000000;
    47     gmask = 0x00ff0000;
    48     bmask = 0x0000ff00;
    49     amask = 0x000000ff;
    50 #else
    51     rmask = 0x000000ff;
    52     gmask = 0x0000ff00;
    53     bmask = 0x00ff0000;
    54     amask = 0xff000000;
    55 #endif
    56 
    57     surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
    58                                    rmask, gmask, bmask, amask);
    59     if(surface == NULL) {
    60         fprintf(stderr, "CreateRGBSurface failed: %s
    61 ", SDL_GetError());
    62         exit(1);
    63     }\fR
    64 .fi
    65 .PP
    66 .SH "SEE ALSO"
    67 .PP
    68 \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
    69 ...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01