docs/html/video.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Video</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="SDL Reference"
  14 HREF="reference.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="SDL_envvars"
  17 HREF="sdlenvvars.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_GetVideoSurface"
  20 HREF="sdlgetvideosurface.html"><META
  21 NAME="KEYWORD"
  22 CONTENT="video"><META
  23 NAME="KEYWORD"
  24 CONTENT="function"></HEAD
  25 ><BODY
  26 CLASS="CHAPTER"
  27 BGCOLOR="#FFF8DC"
  28 TEXT="#000000"
  29 LINK="#0000ee"
  30 VLINK="#551a8b"
  31 ALINK="#ff0000"
  32 ><DIV
  33 CLASS="NAVHEADER"
  34 ><TABLE
  35 SUMMARY="Header navigation table"
  36 WIDTH="100%"
  37 BORDER="0"
  38 CELLPADDING="0"
  39 CELLSPACING="0"
  40 ><TR
  41 ><TH
  42 COLSPAN="3"
  43 ALIGN="center"
  44 >SDL Library Documentation</TH
  45 ></TR
  46 ><TR
  47 ><TD
  48 WIDTH="10%"
  49 ALIGN="left"
  50 VALIGN="bottom"
  51 ><A
  52 HREF="sdlenvvars.html"
  53 ACCESSKEY="P"
  54 >Prev</A
  55 ></TD
  56 ><TD
  57 WIDTH="80%"
  58 ALIGN="center"
  59 VALIGN="bottom"
  60 ></TD
  61 ><TD
  62 WIDTH="10%"
  63 ALIGN="right"
  64 VALIGN="bottom"
  65 ><A
  66 HREF="sdlgetvideosurface.html"
  67 ACCESSKEY="N"
  68 >Next</A
  69 ></TD
  70 ></TR
  71 ></TABLE
  72 ><HR
  73 ALIGN="LEFT"
  74 WIDTH="100%"></DIV
  75 ><DIV
  76 CLASS="CHAPTER"
  77 ><H1
  78 ><A
  79 NAME="VIDEO"
  80 ></A
  81 >Chapter 6. Video</H1
  82 ><DIV
  83 CLASS="TOC"
  84 ><DL
  85 ><DT
  86 ><B
  87 >Table of Contents</B
  88 ></DT
  89 ><DT
  90 ><A
  91 HREF="sdlgetvideosurface.html"
  92 >SDL_GetVideoSurface</A
  93 >&nbsp;--&nbsp;returns a pointer to the current display surface</DT
  94 ><DT
  95 ><A
  96 HREF="sdlgetvideoinfo.html"
  97 >SDL_GetVideoInfo</A
  98 >&nbsp;--&nbsp;returns a pointer to information about the video hardware</DT
  99 ><DT
 100 ><A
 101 HREF="sdlvideodrivername.html"
 102 >SDL_VideoDriverName</A
 103 >&nbsp;--&nbsp;Obtain the name of the video driver</DT
 104 ><DT
 105 ><A
 106 HREF="sdllistmodes.html"
 107 >SDL_ListModes</A
 108 >&nbsp;--&nbsp;Returns a pointer to an array of available screen dimensions for
 109 the given format and video flags</DT
 110 ><DT
 111 ><A
 112 HREF="sdlvideomodeok.html"
 113 >SDL_VideoModeOK</A
 114 >&nbsp;--&nbsp;Check to see if a particular video mode is supported.</DT
 115 ><DT
 116 ><A
 117 HREF="sdlsetvideomode.html"
 118 >SDL_SetVideoMode</A
 119 >&nbsp;--&nbsp;Set up a video mode with the specified width, height and bits-per-pixel.</DT
 120 ><DT
 121 ><A
 122 HREF="sdlupdaterect.html"
 123 >SDL_UpdateRect</A
 124 >&nbsp;--&nbsp;Makes sure the given area is updated on the given screen.</DT
 125 ><DT
 126 ><A
 127 HREF="sdlupdaterects.html"
 128 >SDL_UpdateRects</A
 129 >&nbsp;--&nbsp;Makes sure the given list of rectangles is updated on the given screen.</DT
 130 ><DT
 131 ><A
 132 HREF="sdlflip.html"
 133 >SDL_Flip</A
 134 >&nbsp;--&nbsp;Swaps screen buffers</DT
 135 ><DT
 136 ><A
 137 HREF="sdlsetcolors.html"
 138 >SDL_SetColors</A
 139 >&nbsp;--&nbsp;Sets a portion of the colormap for the given 8-bit surface.</DT
 140 ><DT
 141 ><A
 142 HREF="sdlsetpalette.html"
 143 >SDL_SetPalette</A
 144 >&nbsp;--&nbsp;Sets the colors in the palette of an 8-bit surface.</DT
 145 ><DT
 146 ><A
 147 HREF="sdlsetgamma.html"
 148 >SDL_SetGamma</A
 149 >&nbsp;--&nbsp;Sets the color gamma function for the display</DT
 150 ><DT
 151 ><A
 152 HREF="sdlgetgammaramp.html"
 153 >SDL_GetGammaRamp</A
 154 >&nbsp;--&nbsp;Gets the color gamma lookup tables for the display</DT
 155 ><DT
 156 ><A
 157 HREF="sdlsetgammaramp.html"
 158 >SDL_SetGammaRamp</A
 159 >&nbsp;--&nbsp;Sets the color gamma lookup tables for the display</DT
 160 ><DT
 161 ><A
 162 HREF="sdlmaprgb.html"
 163 >SDL_MapRGB</A
 164 >&nbsp;--&nbsp;Map a RGB color value to a pixel format.</DT
 165 ><DT
 166 ><A
 167 HREF="sdlmaprgba.html"
 168 >SDL_MapRGBA</A
 169 >&nbsp;--&nbsp;Map a RGBA color value to a pixel format.</DT
 170 ><DT
 171 ><A
 172 HREF="sdlgetrgb.html"
 173 >SDL_GetRGB</A
 174 >&nbsp;--&nbsp;Get RGB values from a pixel in the specified pixel format.</DT
 175 ><DT
 176 ><A
 177 HREF="sdlgetrgba.html"
 178 >SDL_GetRGBA</A
 179 >&nbsp;--&nbsp;Get RGBA values from a pixel in the specified pixel format.</DT
 180 ><DT
 181 ><A
 182 HREF="sdlcreatergbsurface.html"
 183 >SDL_CreateRGBSurface</A
 184 >&nbsp;--&nbsp;Create an empty SDL_Surface</DT
 185 ><DT
 186 ><A
 187 HREF="sdlcreatergbsurfacefrom.html"
 188 >SDL_CreateRGBSurfaceFrom</A
 189 >&nbsp;--&nbsp;Create an SDL_Surface from pixel data</DT
 190 ><DT
 191 ><A
 192 HREF="sdlfreesurface.html"
 193 >SDL_FreeSurface</A
 194 >&nbsp;--&nbsp;Frees (deletes) a SDL_Surface</DT
 195 ><DT
 196 ><A
 197 HREF="sdllocksurface.html"
 198 >SDL_LockSurface</A
 199 >&nbsp;--&nbsp;Lock a surface for directly access.</DT
 200 ><DT
 201 ><A
 202 HREF="sdlunlocksurface.html"
 203 >SDL_UnlockSurface</A
 204 >&nbsp;--&nbsp;Unlocks a previously locked surface.</DT
 205 ><DT
 206 ><A
 207 HREF="sdlloadbmp.html"
 208 >SDL_LoadBMP</A
 209 >&nbsp;--&nbsp;Load a Windows BMP file into an SDL_Surface.</DT
 210 ><DT
 211 ><A
 212 HREF="sdlsavebmp.html"
 213 >SDL_SaveBMP</A
 214 >&nbsp;--&nbsp;Save an SDL_Surface as a Windows BMP file.</DT
 215 ><DT
 216 ><A
 217 HREF="sdlsetcolorkey.html"
 218 >SDL_SetColorKey</A
 219 >&nbsp;--&nbsp;Sets the color key (transparent pixel) in a blittable surface and
 220 RLE acceleration.</DT
 221 ><DT
 222 ><A
 223 HREF="sdlsetalpha.html"
 224 >SDL_SetAlpha</A
 225 >&nbsp;--&nbsp;Adjust the alpha properties of a surface</DT
 226 ><DT
 227 ><A
 228 HREF="sdlsetcliprect.html"
 229 >SDL_SetClipRect</A
 230 >&nbsp;--&nbsp;Sets the clipping rectangle for a surface.</DT
 231 ><DT
 232 ><A
 233 HREF="sdlgetcliprect.html"
 234 >SDL_GetClipRect</A
 235 >&nbsp;--&nbsp;Gets the clipping rectangle for a surface.</DT
 236 ><DT
 237 ><A
 238 HREF="sdlconvertsurface.html"
 239 >SDL_ConvertSurface</A
 240 >&nbsp;--&nbsp;Converts a surface to the same format as another surface.</DT
 241 ><DT
 242 ><A
 243 HREF="sdlblitsurface.html"
 244 >SDL_BlitSurface</A
 245 >&nbsp;--&nbsp;This performs a fast blit from the source surface to the destination surface.</DT
 246 ><DT
 247 ><A
 248 HREF="sdlfillrect.html"
 249 >SDL_FillRect</A
 250 >&nbsp;--&nbsp;This function performs a fast fill of the given rectangle with some color</DT
 251 ><DT
 252 ><A
 253 HREF="sdldisplayformat.html"
 254 >SDL_DisplayFormat</A
 255 >&nbsp;--&nbsp;Convert a surface to the display format</DT
 256 ><DT
 257 ><A
 258 HREF="sdldisplayformatalpha.html"
 259 >SDL_DisplayFormatAlpha</A
 260 >&nbsp;--&nbsp;Convert a surface to the display format</DT
 261 ><DT
 262 ><A
 263 HREF="sdlwarpmouse.html"
 264 >SDL_WarpMouse</A
 265 >&nbsp;--&nbsp;Set the position of the mouse cursor.</DT
 266 ><DT
 267 ><A
 268 HREF="sdlcreatecursor.html"
 269 >SDL_CreateCursor</A
 270 >&nbsp;--&nbsp;Creates a new mouse cursor.</DT
 271 ><DT
 272 ><A
 273 HREF="sdlfreecursor.html"
 274 >SDL_FreeCursor</A
 275 >&nbsp;--&nbsp;Frees a cursor created with SDL_CreateCursor.</DT
 276 ><DT
 277 ><A
 278 HREF="sdlsetcursor.html"
 279 >SDL_SetCursor</A
 280 >&nbsp;--&nbsp;Set the currently active mouse cursor.</DT
 281 ><DT
 282 ><A
 283 HREF="sdlgetcursor.html"
 284 >SDL_GetCursor</A
 285 >&nbsp;--&nbsp;Get the currently active mouse cursor.</DT
 286 ><DT
 287 ><A
 288 HREF="sdlshowcursor.html"
 289 >SDL_ShowCursor</A
 290 >&nbsp;--&nbsp;Toggle whether or not the cursor is shown on the screen.</DT
 291 ><DT
 292 ><A
 293 HREF="sdlglloadlibrary.html"
 294 >SDL_GL_LoadLibrary</A
 295 >&nbsp;--&nbsp;Specify an OpenGL library</DT
 296 ><DT
 297 ><A
 298 HREF="sdlglgetprocaddress.html"
 299 >SDL_GL_GetProcAddress</A
 300 >&nbsp;--&nbsp;Get the address of a GL function</DT
 301 ><DT
 302 ><A
 303 HREF="sdlglgetattribute.html"
 304 >SDL_GL_GetAttribute</A
 305 >&nbsp;--&nbsp;Get the value of a special SDL/OpenGL attribute</DT
 306 ><DT
 307 ><A
 308 HREF="sdlglsetattribute.html"
 309 >SDL_GL_SetAttribute</A
 310 >&nbsp;--&nbsp;Set a special SDL/OpenGL attribute</DT
 311 ><DT
 312 ><A
 313 HREF="sdlglswapbuffers.html"
 314 >SDL_GL_SwapBuffers</A
 315 >&nbsp;--&nbsp;Swap OpenGL framebuffers/Update Display</DT
 316 ><DT
 317 ><A
 318 HREF="sdlcreateyuvoverlay.html"
 319 >SDL_CreateYUVOverlay</A
 320 >&nbsp;--&nbsp;Create a YUV video overlay</DT
 321 ><DT
 322 ><A
 323 HREF="sdllockyuvoverlay.html"
 324 >SDL_LockYUVOverlay</A
 325 >&nbsp;--&nbsp;Lock an overlay</DT
 326 ><DT
 327 ><A
 328 HREF="sdlunlockyuvoverlay.html"
 329 >SDL_UnlockYUVOverlay</A
 330 >&nbsp;--&nbsp;Unlock an overlay</DT
 331 ><DT
 332 ><A
 333 HREF="sdldisplayyuvoverlay.html"
 334 >SDL_DisplayYUVOverlay</A
 335 >&nbsp;--&nbsp;Blit the overlay to the display</DT
 336 ><DT
 337 ><A
 338 HREF="sdlfreeyuvoverlay.html"
 339 >SDL_FreeYUVOverlay</A
 340 >&nbsp;--&nbsp;Free a YUV video overlay</DT
 341 ><DT
 342 ><A
 343 HREF="sdlglattr.html"
 344 >SDL_GLattr</A
 345 >&nbsp;--&nbsp;SDL GL Attributes</DT
 346 ><DT
 347 ><A
 348 HREF="sdlrect.html"
 349 >SDL_Rect</A
 350 >&nbsp;--&nbsp;Defines a rectangular area</DT
 351 ><DT
 352 ><A
 353 HREF="sdlcolor.html"
 354 >SDL_Color</A
 355 >&nbsp;--&nbsp;Format independent color description</DT
 356 ><DT
 357 ><A
 358 HREF="sdlpalette.html"
 359 >SDL_Palette</A
 360 >&nbsp;--&nbsp;Color palette for 8-bit pixel formats</DT
 361 ><DT
 362 ><A
 363 HREF="sdlpixelformat.html"
 364 >SDL_PixelFormat</A
 365 >&nbsp;--&nbsp;Stores surface format information</DT
 366 ><DT
 367 ><A
 368 HREF="sdlsurface.html"
 369 >SDL_Surface</A
 370 >&nbsp;--&nbsp;Graphical Surface Structure</DT
 371 ><DT
 372 ><A
 373 HREF="sdlvideoinfo.html"
 374 >SDL_VideoInfo</A
 375 >&nbsp;--&nbsp;Video Target information</DT
 376 ><DT
 377 ><A
 378 HREF="sdloverlay.html"
 379 >SDL_Overlay</A
 380 >&nbsp;--&nbsp;YUV video overlay</DT
 381 ></DL
 382 ></DIV
 383 ><P
 384 >SDL presents a very simple interface to the display framebuffer.  The
 385 framebuffer is represented as an offscreen surface to which you can write
 386 directly.  If you want the screen to show what you have written, call the <A
 387 HREF="sdlupdaterects.html"
 388 >update</A
 389 > function which will
 390 guarantee that the desired portion of the screen is updated.</P
 391 ><P
 392 >Before you call any of the SDL video functions, you must first call
 393 <SPAN
 394 CLASS="TOKEN"
 395 >SDL_Init(SDL_INIT_VIDEO)</SPAN
 396 >, which initializes the video
 397 and events in the SDL library.  Check the return code, which should be
 398 <SPAN
 399 CLASS="RETURNVALUE"
 400 >0</SPAN
 401 >, to see if there were any errors in starting up.</P
 402 ><P
 403 >If you use both sound and video in your application, you need to call
 404 <SPAN
 405 CLASS="TOKEN"
 406 >SDL_Init(SDL_INIT_AUDIO | SDL_INIT_VIDEO)</SPAN
 407 > before opening the
 408 sound device, otherwise under Win32 DirectX, you won't be able to set
 409 full-screen display modes.</P
 410 ><P
 411 >After you have initialized the library, you can start up the video display in a
 412 number of ways.  The easiest way is to pick a common screen resolution and
 413 depth and just initialize the video, checking for errors.  You will probably
 414 get what you want, but SDL may be emulating your requested mode and converting
 415 the display on update.  The best way is to
 416 <A
 417 HREF="sdlgetvideoinfo.html"
 418 >query</A
 419 >, for the best
 420 video mode closest to the desired one, and then
 421 <A
 422 HREF="sdldisplayformat.html"
 423 >convert</A
 424 >
 425 your images to that pixel format.</P
 426 ><P
 427 >SDL currently supports any bit depth &gt;= 8 bits per pixel.  8 bpp formats are
 428 considered 8-bit palettized modes, while 12, 15, 16, 24, and 32 bits per pixel
 429 are considered "packed pixel" modes, meaning each pixel contains the RGB color
 430 components packed in the bits of the pixel.</P
 431 ><P
 432 >After you have initialized your video mode, you can take the surface that was
 433 returned, and write to it like any other framebuffer, calling the update
 434 routine as you go.</P
 435 ><P
 436 >When you have finished your video access and are ready to quit your
 437 application, you should call "<SPAN
 438 CLASS="TOKEN"
 439 >SDL_Quit()</SPAN
 440 >" to shutdown the
 441 video and events.</P
 442 ></DIV
 443 ><DIV
 444 CLASS="NAVFOOTER"
 445 ><HR
 446 ALIGN="LEFT"
 447 WIDTH="100%"><TABLE
 448 SUMMARY="Footer navigation table"
 449 WIDTH="100%"
 450 BORDER="0"
 451 CELLPADDING="0"
 452 CELLSPACING="0"
 453 ><TR
 454 ><TD
 455 WIDTH="33%"
 456 ALIGN="left"
 457 VALIGN="top"
 458 ><A
 459 HREF="sdlenvvars.html"
 460 ACCESSKEY="P"
 461 >Prev</A
 462 ></TD
 463 ><TD
 464 WIDTH="34%"
 465 ALIGN="center"
 466 VALIGN="top"
 467 ><A
 468 HREF="index.html"
 469 ACCESSKEY="H"
 470 >Home</A
 471 ></TD
 472 ><TD
 473 WIDTH="33%"
 474 ALIGN="right"
 475 VALIGN="top"
 476 ><A
 477 HREF="sdlgetvideosurface.html"
 478 ACCESSKEY="N"
 479 >Next</A
 480 ></TD
 481 ></TR
 482 ><TR
 483 ><TD
 484 WIDTH="33%"
 485 ALIGN="left"
 486 VALIGN="top"
 487 >SDL_envvars</TD
 488 ><TD
 489 WIDTH="34%"
 490 ALIGN="center"
 491 VALIGN="top"
 492 ><A
 493 HREF="reference.html"
 494 ACCESSKEY="U"
 495 >Up</A
 496 ></TD
 497 ><TD
 498 WIDTH="33%"
 499 ALIGN="right"
 500 VALIGN="top"
 501 >SDL_GetVideoSurface</TD
 502 ></TR
 503 ></TABLE
 504 ></DIV
 505 ></BODY
 506 ></HTML
 507 >