| e14743d1 |
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 |
notaz.gp2x.de / sdl_omap.git / blame