docs/html/sdlcreatergbsurface.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_CreateRGBSurface</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
   8 "><LINK
   9 REL="HOME"
  10 TITLE="SDL Library Documentation"
  11 HREF="index.html"><LINK
  12 REL="UP"
  13 TITLE="Video"
  14 HREF="video.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="SDL_GetRGBA"
  17 HREF="sdlgetrgba.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_CreateRGBSurfaceFrom"
  20 HREF="sdlcreatergbsurfacefrom.html"></HEAD
  21 ><BODY
  22 CLASS="REFENTRY"
  23 BGCOLOR="#FFF8DC"
  24 TEXT="#000000"
  25 LINK="#0000ee"
  26 VLINK="#551a8b"
  27 ALINK="#ff0000"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 SUMMARY="Header navigation table"
  32 WIDTH="100%"
  33 BORDER="0"
  34 CELLPADDING="0"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="3"
  39 ALIGN="center"
  40 >SDL Library Documentation</TH
  41 ></TR
  42 ><TR
  43 ><TD
  44 WIDTH="10%"
  45 ALIGN="left"
  46 VALIGN="bottom"
  47 ><A
  48 HREF="sdlgetrgba.html"
  49 ACCESSKEY="P"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 ></TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="sdlcreatergbsurfacefrom.html"
  63 ACCESSKEY="N"
  64 >Next</A
  65 ></TD
  66 ></TR
  67 ></TABLE
  68 ><HR
  69 ALIGN="LEFT"
  70 WIDTH="100%"></DIV
  71 ><H1
  72 ><A
  73 NAME="SDLCREATERGBSURFACE"
  74 ></A
  75 >SDL_CreateRGBSurface</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN1773"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_CreateRGBSurface&nbsp;--&nbsp;Create an empty SDL_Surface</DIV
  84 ><DIV
  85 CLASS="REFSYNOPSISDIV"
  86 ><A
  87 NAME="AEN1776"
  88 ></A
  89 ><H2
  90 >Synopsis</H2
  91 ><DIV
  92 CLASS="FUNCSYNOPSIS"
  93 ><A
  94 NAME="AEN1777"
  95 ></A
  96 ><P
  97 ></P
  98 ><PRE
  99 CLASS="FUNCSYNOPSISINFO"
 100 >#include "SDL.h"</PRE
 101 ><P
 102 ><CODE
 103 ><CODE
 104 CLASS="FUNCDEF"
 105 >SDL_Surface *<B
 106 CLASS="FSFUNC"
 107 >SDL_CreateRGBSurface</B
 108 ></CODE
 109 >(Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);</CODE
 110 ></P
 111 ><P
 112 ></P
 113 ></DIV
 114 ></DIV
 115 ><DIV
 116 CLASS="REFSECT1"
 117 ><A
 118 NAME="AEN1783"
 119 ></A
 120 ><H2
 121 >Description</H2
 122 ><P
 123 >Allocate an empty surface (must be called after <A
 124 HREF="sdlsetvideomode.html"
 125 >SDL_SetVideoMode</A
 126 >)</P
 127 ><P
 128 >If <TT
 129 CLASS="PARAMETER"
 130 ><I
 131 >depth</I
 132 ></TT
 133 > is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' <A
 134 HREF="sdlpixelformat.html"
 135 ><SPAN
 136 CLASS="STRUCTNAME"
 137 >SDL_PixelFormat</SPAN
 138 ></A
 139 > is created using the <TT
 140 CLASS="PARAMETER"
 141 ><I
 142 >[RGBA]mask</I
 143 ></TT
 144 >'s provided (see <A
 145 HREF="sdlpixelformat.html"
 146 ><SPAN
 147 CLASS="STRUCTNAME"
 148 >SDL_PixelFormat</SPAN
 149 ></A
 150 >). The <TT
 151 CLASS="PARAMETER"
 152 ><I
 153 >flags</I
 154 ></TT
 155 > specifies the type of surface that should be created, it is an OR'd combination of the following possible values.</P
 156 ><DIV
 157 CLASS="INFORMALTABLE"
 158 ><A
 159 NAME="AEN1795"
 160 ></A
 161 ><P
 162 ></P
 163 ><TABLE
 164 BORDER="1"
 165 CLASS="CALSTABLE"
 166 ><TBODY
 167 ><TR
 168 ><TD
 169 ALIGN="LEFT"
 170 VALIGN="TOP"
 171 ><TT
 172 CLASS="LITERAL"
 173 >SDL_SWSURFACE</TT
 174 ></TD
 175 ><TD
 176 ALIGN="LEFT"
 177 VALIGN="TOP"
 178 >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.</TD
 179 ></TR
 180 ><TR
 181 ><TD
 182 ALIGN="LEFT"
 183 VALIGN="TOP"
 184 ><TT
 185 CLASS="LITERAL"
 186 >SDL_HWSURFACE</TT
 187 ></TD
 188 ><TD
 189 ALIGN="LEFT"
 190 VALIGN="TOP"
 191 >SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video-&#62;Video blits (which are often accelerated).</TD
 192 ></TR
 193 ><TR
 194 ><TD
 195 ALIGN="LEFT"
 196 VALIGN="TOP"
 197 ><TT
 198 CLASS="LITERAL"
 199 >SDL_SRCCOLORKEY</TT
 200 ></TD
 201 ><TD
 202 ALIGN="LEFT"
 203 VALIGN="TOP"
 204 >This flag turns on colourkeying for blits from this surface. If
 205 <TT
 206 CLASS="LITERAL"
 207 >SDL_HWSURFACE</TT
 208 > is also specified and colourkeyed blits
 209 are hardware-accelerated, then SDL will attempt to place the surface in
 210 video memory.
 211 Use <A
 212 HREF="sdlsetcolorkey.html"
 213 ><TT
 214 CLASS="FUNCTION"
 215 >SDL_SetColorKey</TT
 216 ></A
 217 >
 218 to set or clear this flag after surface creation.</TD
 219 ></TR
 220 ><TR
 221 ><TD
 222 ALIGN="LEFT"
 223 VALIGN="TOP"
 224 ><TT
 225 CLASS="LITERAL"
 226 >SDL_SRCALPHA</TT
 227 ></TD
 228 ><TD
 229 ALIGN="LEFT"
 230 VALIGN="TOP"
 231 >This flag turns on alpha-blending for blits from this surface. If
 232 <TT
 233 CLASS="LITERAL"
 234 >SDL_HWSURFACE</TT
 235 > is also specified and alpha-blending blits
 236 are hardware-accelerated, then the surface will be placed in video memory if
 237 possible.
 238 Use <A
 239 HREF="sdlsetalpha.html"
 240 ><TT
 241 CLASS="FUNCTION"
 242 >SDL_SetAlpha</TT
 243 ></A
 244 > to
 245 set or clear this flag after surface creation.</TD
 246 ></TR
 247 ></TBODY
 248 ></TABLE
 249 ><P
 250 ></P
 251 ></DIV
 252 ><DIV
 253 CLASS="NOTE"
 254 ><BLOCKQUOTE
 255 CLASS="NOTE"
 256 ><P
 257 ><B
 258 >Note: </B
 259 >If an alpha-channel is specified (that is, if <TT
 260 CLASS="PARAMETER"
 261 ><I
 262 >Amask</I
 263 ></TT
 264 > is
 265 nonzero), then the <TT
 266 CLASS="LITERAL"
 267 >SDL_SRCALPHA</TT
 268 > flag is automatically
 269 set. You may remove this flag by calling
 270 <A
 271 HREF="sdlsetalpha.html"
 272 ><TT
 273 CLASS="FUNCTION"
 274 >SDL_SetAlpha</TT
 275 ></A
 276 >
 277 after surface creation.</P
 278 ></BLOCKQUOTE
 279 ></DIV
 280 ></DIV
 281 ><DIV
 282 CLASS="REFSECT1"
 283 ><A
 284 NAME="AEN1826"
 285 ></A
 286 ><H2
 287 >Return Value</H2
 288 ><P
 289 >Returns the created surface, or <SPAN
 290 CLASS="RETURNVALUE"
 291 >NULL</SPAN
 292 > upon error.</P
 293 ></DIV
 294 ><DIV
 295 CLASS="REFSECT1"
 296 ><A
 297 NAME="AEN1830"
 298 ></A
 299 ><H2
 300 >Example</H2
 301 ><PRE
 302 CLASS="PROGRAMLISTING"
 303 >    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
 304        as expected by OpenGL for textures */
 305     SDL_Surface *surface;
 306     Uint32 rmask, gmask, bmask, amask;
 307
 308     /* SDL interprets each pixel as a 32-bit number, so our masks must depend
 309        on the endianness (byte order) of the machine */
 310 #if SDL_BYTEORDER == SDL_BIG_ENDIAN
 311     rmask = 0xff000000;
 312     gmask = 0x00ff0000;
 313     bmask = 0x0000ff00;
 314     amask = 0x000000ff;
 315 #else
 316     rmask = 0x000000ff;
 317     gmask = 0x0000ff00;
 318     bmask = 0x00ff0000;
 319     amask = 0xff000000;
 320 #endif
 321
 322     surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
 323                                    rmask, gmask, bmask, amask);
 324     if(surface == NULL) {
 325         fprintf(stderr, "CreateRGBSurface failed: %s\n", SDL_GetError());
 326         exit(1);
 327     }</PRE
 328 ></DIV
 329 ><DIV
 330 CLASS="REFSECT1"
 331 ><A
 332 NAME="AEN1833"
 333 ></A
 334 ><H2
 335 >See Also</H2
 336 ><P
 337 ><A
 338 HREF="sdlcreatergbsurfacefrom.html"
 339 ><TT
 340 CLASS="FUNCTION"
 341 >SDL_CreateRGBSurfaceFrom</TT
 342 ></A
 343 >,
 344 <A
 345 HREF="sdlfreesurface.html"
 346 ><TT
 347 CLASS="FUNCTION"
 348 >SDL_FreeSurface</TT
 349 ></A
 350 >,
 351 <A
 352 HREF="sdlsetvideomode.html"
 353 ><TT
 354 CLASS="FUNCTION"
 355 >SDL_SetVideoMode</TT
 356 ></A
 357 >,
 358 <A
 359 HREF="sdllocksurface.html"
 360 ><TT
 361 CLASS="FUNCTION"
 362 >SDL_LockSurface</TT
 363 ></A
 364 >,
 365 <A
 366 HREF="sdlpixelformat.html"
 367 ><SPAN
 368 CLASS="STRUCTNAME"
 369 >SDL_PixelFormat</SPAN
 370 ></A
 371 >,
 372 <A
 373 HREF="sdlsurface.html"
 374 ><SPAN
 375 CLASS="STRUCTNAME"
 376 >SDL_Surface</SPAN
 377 ></A
 378 >
 379 <A
 380 HREF="sdlsetalpha.html"
 381 ><TT
 382 CLASS="FUNCTION"
 383 >SDL_SetAlpha</TT
 384 ></A
 385 >
 386 <A
 387 HREF="sdlsetcolorkey.html"
 388 ><TT
 389 CLASS="FUNCTION"
 390 >SDL_SetColorKey</TT
 391 ></A
 392 ></P
 393 ></DIV
 394 ><DIV
 395 CLASS="NAVFOOTER"
 396 ><HR
 397 ALIGN="LEFT"
 398 WIDTH="100%"><TABLE
 399 SUMMARY="Footer navigation table"
 400 WIDTH="100%"
 401 BORDER="0"
 402 CELLPADDING="0"
 403 CELLSPACING="0"
 404 ><TR
 405 ><TD
 406 WIDTH="33%"
 407 ALIGN="left"
 408 VALIGN="top"
 409 ><A
 410 HREF="sdlgetrgba.html"
 411 ACCESSKEY="P"
 412 >Prev</A
 413 ></TD
 414 ><TD
 415 WIDTH="34%"
 416 ALIGN="center"
 417 VALIGN="top"
 418 ><A
 419 HREF="index.html"
 420 ACCESSKEY="H"
 421 >Home</A
 422 ></TD
 423 ><TD
 424 WIDTH="33%"
 425 ALIGN="right"
 426 VALIGN="top"
 427 ><A
 428 HREF="sdlcreatergbsurfacefrom.html"
 429 ACCESSKEY="N"
 430 >Next</A
 431 ></TD
 432 ></TR
 433 ><TR
 434 ><TD
 435 WIDTH="33%"
 436 ALIGN="left"
 437 VALIGN="top"
 438 >SDL_GetRGBA</TD
 439 ><TD
 440 WIDTH="34%"
 441 ALIGN="center"
 442 VALIGN="top"
 443 ><A
 444 HREF="video.html"
 445 ACCESSKEY="U"
 446 >Up</A
 447 ></TD
 448 ><TD
 449 WIDTH="33%"
 450 ALIGN="right"
 451 VALIGN="top"
 452 >SDL_CreateRGBSurfaceFrom</TD
 453 ></TR
 454 ></TABLE
 455 ></DIV
 456 ></BODY
 457 ></HTML
 458 >