docs/html/sdlsetalpha.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_SetAlpha</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_SetColorKey"
  17 HREF="sdlsetcolorkey.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_SetClipRect"
  20 HREF="sdlsetcliprect.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="sdlsetcolorkey.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="sdlsetcliprect.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="SDLSETALPHA"
  74 ></A
  75 >SDL_SetAlpha</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN2096"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_SetAlpha&nbsp;--&nbsp;Adjust the alpha properties of a surface</DIV
  84 ><DIV
  85 CLASS="REFSYNOPSISDIV"
  86 ><A
  87 NAME="AEN2099"
  88 ></A
  89 ><H2
  90 >Synopsis</H2
  91 ><DIV
  92 CLASS="FUNCSYNOPSIS"
  93 ><A
  94 NAME="AEN2100"
  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 >int <B
 106 CLASS="FSFUNC"
 107 >SDL_SetAlpha</B
 108 ></CODE
 109 >(SDL_Surface *surface, Uint32 flag, Uint8 alpha);</CODE
 110 ></P
 111 ><P
 112 ></P
 113 ></DIV
 114 ></DIV
 115 ><DIV
 116 CLASS="REFSECT1"
 117 ><A
 118 NAME="AEN2106"
 119 ></A
 120 ><H2
 121 >Description</H2
 122 ><DIV
 123 CLASS="NOTE"
 124 ><BLOCKQUOTE
 125 CLASS="NOTE"
 126 ><P
 127 ><B
 128 >Note: </B
 129 >This function and the semantics of SDL alpha blending have changed since version 1.1.4. Up until version 1.1.5, an alpha value of 0 was considered opaque and a value of 255 was considered transparent. This has now been inverted: 0 (<TT
 130 CLASS="LITERAL"
 131 >SDL_ALPHA_TRANSPARENT</TT
 132 >) is now considered transparent and 255 (<TT
 133 CLASS="LITERAL"
 134 >SDL_ALPHA_OPAQUE</TT
 135 >) is now considered opaque.</P
 136 ></BLOCKQUOTE
 137 ></DIV
 138 ><P
 139 ><TT
 140 CLASS="FUNCTION"
 141 >SDL_SetAlpha</TT
 142 > is used for setting the per-surface alpha
 143 value and/or enabling and disabling alpha blending.</P
 144 ><P
 145 >The<TT
 146 CLASS="PARAMETER"
 147 ><I
 148 >surface</I
 149 ></TT
 150 > parameter specifies which surface whose alpha
 151 attributes you wish to adjust. <TT
 152 CLASS="PARAMETER"
 153 ><I
 154 >flags</I
 155 ></TT
 156 > is used to specify
 157 whether alpha blending should be used (<TT
 158 CLASS="LITERAL"
 159 >SDL_SRCALPHA</TT
 160 >) and
 161 whether the surface should use RLE acceleration for blitting
 162 (<TT
 163 CLASS="LITERAL"
 164 >SDL_RLEACCEL</TT
 165 >). <TT
 166 CLASS="PARAMETER"
 167 ><I
 168 >flags</I
 169 ></TT
 170 > can be an OR'd
 171 combination of these two options, one of these options or 0. If
 172 <TT
 173 CLASS="LITERAL"
 174 >SDL_SRCALPHA</TT
 175 > is not passed as a flag then all alpha
 176 information is ignored when blitting the surface. The
 177 <TT
 178 CLASS="PARAMETER"
 179 ><I
 180 >alpha</I
 181 ></TT
 182 > parameter is the per-surface alpha value; a
 183 surface need not have an alpha channel to use per-surface alpha and blitting
 184 can still be accelerated with <TT
 185 CLASS="LITERAL"
 186 >SDL_RLEACCEL</TT
 187 >.</P
 188 ><DIV
 189 CLASS="NOTE"
 190 ><BLOCKQUOTE
 191 CLASS="NOTE"
 192 ><P
 193 ><B
 194 >Note: </B
 195 >The per-surface alpha value of 128 is considered a special case and
 196 is optimised, so it's much faster than other per-surface values.</P
 197 ></BLOCKQUOTE
 198 ></DIV
 199 ><P
 200 >Alpha effects surface blitting in the following ways:</P
 201 ><DIV
 202 CLASS="INFORMALTABLE"
 203 ><A
 204 NAME="AEN2126"
 205 ></A
 206 ><P
 207 ></P
 208 ><TABLE
 209 BORDER="0"
 210 CLASS="CALSTABLE"
 211 ><TBODY
 212 ><TR
 213 ><TD
 214 ALIGN="LEFT"
 215 VALIGN="TOP"
 216 >RGBA-&#62;RGB with <TT
 217 CLASS="LITERAL"
 218 >SDL_SRCALPHA</TT
 219 ></TD
 220 ><TD
 221 ALIGN="LEFT"
 222 VALIGN="TOP"
 223 ><P
 224 >The source is alpha-blended with the destination, using the alpha channel. <TT
 225 CLASS="LITERAL"
 226 >SDL_SRCCOLORKEY</TT
 227 > and the per-surface alpha are ignored.</P
 228 ></TD
 229 ></TR
 230 ><TR
 231 ><TD
 232 ALIGN="LEFT"
 233 VALIGN="TOP"
 234 >RGBA-&#62;RGB without <TT
 235 CLASS="LITERAL"
 236 >SDL_SRCALPHA</TT
 237 ></TD
 238 ><TD
 239 ALIGN="LEFT"
 240 VALIGN="TOP"
 241 ><P
 242 >The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.</P
 243 ></TD
 244 ></TR
 245 ><TR
 246 ><TD
 247 ALIGN="LEFT"
 248 VALIGN="TOP"
 249 >RGB-&#62;RGBA with <TT
 250 CLASS="LITERAL"
 251 >SDL_SRCALPHA</TT
 252 ></TD
 253 ><TD
 254 ALIGN="LEFT"
 255 VALIGN="TOP"
 256 ><P
 257 >The source is alpha-blended with the destination using the per-surface alpha
 258 value. If <TT
 259 CLASS="LITERAL"
 260 >SDL_SRCCOLORKEY</TT
 261 > is set, only the pixels not
 262 matching the colorkey value are copied. The alpha channel of the copied pixels
 263 is set to opaque.</P
 264 ></TD
 265 ></TR
 266 ><TR
 267 ><TD
 268 ALIGN="LEFT"
 269 VALIGN="TOP"
 270 >RGB-&#62;RGBA without <TT
 271 CLASS="LITERAL"
 272 >SDL_SRCALPHA</TT
 273 ></TD
 274 ><TD
 275 ALIGN="LEFT"
 276 VALIGN="TOP"
 277 ><P
 278 >The RGB data is copied from the source and the alpha value of the copied pixels
 279 is set to opaque. If <TT
 280 CLASS="LITERAL"
 281 >SDL_SRCCOLORKEY</TT
 282 > is set, only the pixels
 283 not matching the colorkey value are copied. </P
 284 ></TD
 285 ></TR
 286 ><TR
 287 ><TD
 288 ALIGN="LEFT"
 289 VALIGN="TOP"
 290 >RGBA-&#62;RGBA with <TT
 291 CLASS="LITERAL"
 292 >SDL_SRCALPHA</TT
 293 ></TD
 294 ><TD
 295 ALIGN="LEFT"
 296 VALIGN="TOP"
 297 ><P
 298 >The source is alpha-blended with the destination using the source alpha
 299 channel. The alpha channel in the destination surface is left untouched.
 300 <TT
 301 CLASS="LITERAL"
 302 >SDL_SRCCOLORKEY</TT
 303 > is ignored.</P
 304 ></TD
 305 ></TR
 306 ><TR
 307 ><TD
 308 ALIGN="LEFT"
 309 VALIGN="TOP"
 310 >RGBA-&#62;RGBA without <TT
 311 CLASS="LITERAL"
 312 >SDL_SRCALPHA</TT
 313 ></TD
 314 ><TD
 315 ALIGN="LEFT"
 316 VALIGN="TOP"
 317 ><P
 318 >The RGBA data is copied to the destination surface. If <TT
 319 CLASS="LITERAL"
 320 >SDL_SRCCOLORKEY</TT
 321 > is set, only the pixels not matching the colorkey value are copied.</P
 322 ></TD
 323 ></TR
 324 ><TR
 325 ><TD
 326 ALIGN="LEFT"
 327 VALIGN="TOP"
 328 >RGB-&#62;RGB with <TT
 329 CLASS="LITERAL"
 330 >SDL_SRCALPHA</TT
 331 ></TD
 332 ><TD
 333 ALIGN="LEFT"
 334 VALIGN="TOP"
 335 ><P
 336 >The source is alpha-blended with the destination using the per-surface alpha value. If <TT
 337 CLASS="LITERAL"
 338 >SDL_SRCCOLORKEY</TT
 339 > is set, only the pixels not matching the colorkey value are copied.</P
 340 ></TD
 341 ></TR
 342 ><TR
 343 ><TD
 344 ALIGN="LEFT"
 345 VALIGN="TOP"
 346 >RGB-&#62;RGB without <TT
 347 CLASS="LITERAL"
 348 >SDL_SRCALPHA</TT
 349 ></TD
 350 ><TD
 351 ALIGN="LEFT"
 352 VALIGN="TOP"
 353 ><P
 354 >The RGB data is copied from the source. If <TT
 355 CLASS="LITERAL"
 356 >SDL_SRCCOLORKEY</TT
 357 > is set, only the pixels not matching the colorkey value are copied.</P
 358 ></TD
 359 ></TR
 360 ></TBODY
 361 ></TABLE
 362 ><P
 363 ></P
 364 ></DIV
 365 ><DIV
 366 CLASS="NOTE"
 367 ><BLOCKQUOTE
 368 CLASS="NOTE"
 369 ><P
 370 ><B
 371 >Note: </B
 372 > Note that RGBA-&#62;RGBA blits (with SDL_SRCALPHA set) keep the alpha
 373 of the destination surface. This means that you cannot compose two arbitrary
 374 RGBA surfaces this way and get the result you would expect from "overlaying"
 375 them; the destination alpha will work as a mask.</P
 376 ><P
 377 >Also note that per-pixel and per-surface alpha cannot be combined;
 378 the per-pixel alpha is always used if available</P
 379 ></BLOCKQUOTE
 380 ></DIV
 381 ></DIV
 382 ><DIV
 383 CLASS="REFSECT1"
 384 ><A
 385 NAME="AEN2179"
 386 ></A
 387 ><H2
 388 >Return Value</H2
 389 ><P
 390 >This function returns <SPAN
 391 CLASS="RETURNVALUE"
 392 >0</SPAN
 393 >, or
 394 <SPAN
 395 CLASS="RETURNVALUE"
 396 >-1</SPAN
 397 > if there was an error.</P
 398 ></DIV
 399 ><DIV
 400 CLASS="REFSECT1"
 401 ><A
 402 NAME="AEN2184"
 403 ></A
 404 ><H2
 405 >See Also</H2
 406 ><P
 407 ><A
 408 HREF="sdlmaprgba.html"
 409 ><TT
 410 CLASS="FUNCTION"
 411 >SDL_MapRGBA</TT
 412 ></A
 413 >,
 414 <A
 415 HREF="sdlgetrgba.html"
 416 ><TT
 417 CLASS="FUNCTION"
 418 >SDL_GetRGBA</TT
 419 ></A
 420 >,
 421 <A
 422 HREF="sdldisplayformatalpha.html"
 423 ><TT
 424 CLASS="FUNCTION"
 425 >SDL_DisplayFormatAlpha</TT
 426 ></A
 427 >,
 428 <A
 429 HREF="sdlblitsurface.html"
 430 ><TT
 431 CLASS="FUNCTION"
 432 >SDL_BlitSurface</TT
 433 ></A
 434 ></P
 435 ></DIV
 436 ><DIV
 437 CLASS="NAVFOOTER"
 438 ><HR
 439 ALIGN="LEFT"
 440 WIDTH="100%"><TABLE
 441 SUMMARY="Footer navigation table"
 442 WIDTH="100%"
 443 BORDER="0"
 444 CELLPADDING="0"
 445 CELLSPACING="0"
 446 ><TR
 447 ><TD
 448 WIDTH="33%"
 449 ALIGN="left"
 450 VALIGN="top"
 451 ><A
 452 HREF="sdlsetcolorkey.html"
 453 ACCESSKEY="P"
 454 >Prev</A
 455 ></TD
 456 ><TD
 457 WIDTH="34%"
 458 ALIGN="center"
 459 VALIGN="top"
 460 ><A
 461 HREF="index.html"
 462 ACCESSKEY="H"
 463 >Home</A
 464 ></TD
 465 ><TD
 466 WIDTH="33%"
 467 ALIGN="right"
 468 VALIGN="top"
 469 ><A
 470 HREF="sdlsetcliprect.html"
 471 ACCESSKEY="N"
 472 >Next</A
 473 ></TD
 474 ></TR
 475 ><TR
 476 ><TD
 477 WIDTH="33%"
 478 ALIGN="left"
 479 VALIGN="top"
 480 >SDL_SetColorKey</TD
 481 ><TD
 482 WIDTH="34%"
 483 ALIGN="center"
 484 VALIGN="top"
 485 ><A
 486 HREF="video.html"
 487 ACCESSKEY="U"
 488 >Up</A
 489 ></TD
 490 ><TD
 491 WIDTH="33%"
 492 ALIGN="right"
 493 VALIGN="top"
 494 >SDL_SetClipRect</TD
 495 ></TR
 496 ></TABLE
 497 ></DIV
 498 ></BODY
 499 ></HTML
 500 >