docs/html/sdlcreatergbsurface.html
changeset 3352 6dc250ebdd80
parent 3351 8e0182c236d8
child 3353 6b14223dd5c7
equal deleted inserted replaced
3351:8e0182c236d8 3352:6dc250ebdd80
     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 >