pages/SDL-Video.html-inc

   1 <div class="pod">
   2 <!-- INDEX START -->
   3 <h3 id="TOP">Index</h3>
   4
   5 <ul><li><a href="#NAME">NAME</a></li>
   6 <li><a href="#CATEGORY">CATEGORY</a></li>
   7 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
   8 <li><a href="#CONSTANTS">CONSTANTS</a></li>
   9 <li><a href="#Core_Functions">Core Functions</a>
  10 <ul><li><a href="#get_video_surface">get_video_surface</a></li>
  11 <li><a href="#get_video_info">get_video_info</a></li>
  12 <li><a href="#video_driver_name">video_driver_name</a></li>
  13 <li><a href="#list_modes">list_modes</a></li>
  14 <li><a href="#video_mode_ok">video_mode_ok</a></li>
  15 <li><a href="#set_video_mode">set_video_mode</a>
  16 <ul><li><a href="#List_of_avalaibles_flags">List of avalaibles flags</a></li>
  17 </ul>
  18 </li>
  19 <li><a href="#convert_surface">convert_surface</a></li>
  20 <li><a href="#display_format">display_format</a></li>
  21 <li><a href="#display_format_alpha">display_format_alpha</a></li>
  22 <li><a href="#load_BMP">load_BMP</a></li>
  23 <li><a href="#save_BMP">save_BMP</a></li>
  24 <li><a href="#set_color_key">set_color_key</a></li>
  25 <li><a href="#set_alpha">set_alpha</a></li>
  26 <li><a href="#fill_rect">fill_rect</a></li>
  27 </ul>
  28 </li>
  29 <li><a href="#Surface_Locking_and_Unlocking">Surface Locking and Unlocking</a>
  30 <ul><li><a href="#lock_surface">lock_surface</a></li>
  31 <li><a href="#unlock_surface">unlock_surface</a></li>
  32 <li><a href="#MUSTLOCK">MUSTLOCK</a></li>
  33 </ul>
  34 </li>
  35 <li><a href="#Screen_Updating_Functions">Screen Updating Functions</a>
  36 <ul><li><a href="#set_clip_rect">set_clip_rect</a></li>
  37 <li><a href="#get_clip_rect">get_clip_rect</a></li>
  38 <li><a href="#blit_surface">blit_surface</a></li>
  39 <li><a href="#update_rect">update_rect</a></li>
  40 <li><a href="#update_rects">update_rects</a></li>
  41 <li><a href="#flip">flip</a></li>
  42 </ul>
  43 </li>
  44 <li><a href="#Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</a>
  45 <ul><li><a href="#set_colors">set_colors</a></li>
  46 <li><a href="#set_palette">set_palette</a></li>
  47 <li><a href="#set_gamma">set_gamma</a></li>
  48 <li><a href="#get_gamma_ramp">get_gamma_ramp</a></li>
  49 <li><a href="#set_gamma_ramp">set_gamma_ramp</a></li>
  50 <li><a href="#map_RGB">map_RGB</a></li>
  51 <li><a href="#map_RGBA">map_RGBA</a></li>
  52 <li><a href="#get_RGB">get_RGB</a></li>
  53 <li><a href="#get_RGBA">get_RGBA</a></li>
  54 </ul>
  55 </li>
  56 <li><a href="#GL_Methods">GL Methods</a>
  57 <ul><li><a href="#GL_load_library">GL_load_library</a></li>
  58 <li><a href="#GL_get_proc_address">GL_get_proc_address</a></li>
  59 <li><a href="#GL_get_attribute">GL_get_attribute</a></li>
  60 <li><a href="#GL_set_attribute">GL_set_attribute</a></li>
  61 <li><a href="#GL_swap_buffers">GL_swap_buffers</a></li>
  62 </ul>
  63 </li>
  64 <li><a href="#Video_Overlay_Functions">Video Overlay Functions</a>
  65 <ul><li><a href="#lock_YUV_overlay">lock_YUV_overlay</a></li>
  66 <li><a href="#unlock_YUV_overlay">unlock_YUV_overlay</a></li>
  67 <li><a href="#display_YUV_overlay">display_YUV_overlay</a></li>
  68 </ul>
  69 </li>
  70 <li><a href="#Window_Management_Functions">Window Management Functions</a>
  71 <ul><li><a href="#wm_set_caption">wm_set_caption</a></li>
  72 <li><a href="#wm_get_caption">wm_get_caption</a></li>
  73 <li><a href="#wm_set_icon">wm_set_icon</a></li>
  74 <li><a href="#wm_grab_input">wm_grab_input</a></li>
  75 <li><a href="#wm_iconify_window">wm_iconify_window</a></li>
  76 <li><a href="#wm_toggle_fullscreen">wm_toggle_fullscreen</a></li>
  77 </ul>
  78 </li>
  79 <li><a href="#AUTHOR">AUTHOR</a></li>
  80 <li><a href="#SEE_ALSO">SEE ALSO</a>
  81 <ul><li><a href="#Category_Objects">Category Objects</a>
  82 </li>
  83 </ul>
  84 </li>
  85 </ul><hr />
  86 <!-- INDEX END --><a href="assets/Video.png" target="_blank"><img src="assets/Video.png" style="height: 160px" alt="Video.png"/></a><a href="assets/Video_lock_surface.png" target="_blank"><img src="assets/Video_lock_surface.png" style="height: 160px" alt="Video_lock_surface.png"/></a><hr />
  87
  88 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  89 <div id="NAME_CONTENT">
  90 <p>SDL::Video - Bindings to the video category in SDL API</p>
  91
  92 </div>
  93 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
  94 <div id="CATEGORY_CONTENT">
  95 <p>Core, Video</p>
  96
  97 </div>
  98 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  99 <div id="SYNOPSIS_CONTENT">
 100 <pre> use SDL;
 101  use SDL::Video;
 102  use SDL::Surface;
 103  use SDL::Rect;
 104
 105  # the size of the window box or the screen resolution if fullscreen
 106  my $screen_width   = 800;
 107  my $screen_height  = 600;
 108
 109  SDL::init(SDL_INIT_VIDEO);
 110
 111  # setting video mode
 112  my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_ANYFORMAT);
 113
 114  # drawing something somewhere
 115  my $mapped_color   = SDL::Video::map_RGB($screen_surface-&gt;format(), 0, 0, 255); # blue
 116  SDL::Video::fill_rect($screen_surface,
 117                        SDL::Rect-&gt;new($screen_width / 4, $screen_height / 4,
 118                                       $screen_width / 2, $screen_height / 2), $mapped_color);
 119
 120  # update an area on the screen so its visible
 121  SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
 122
 123  sleep(5); # just to have time to see it
 124
 125  SDL::quit();
 126
 127 </pre>
 128
 129 </div>
 130 <h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 131 <div id="CONSTANTS_CONTENT">
 132 <p>The constants are exported by default. You can avoid this by doing:</p>
 133 <pre> use SDL::Video ();
 134
 135 </pre>
 136 <p>and access them directly:</p>
 137 <pre> SDL::Video::SDL_SWSURFACE;
 138
 139 </pre>
 140 <p>or by choosing the export tags below:</p>
 141 <p>Export tag: ':surface'</p>
 142 <pre> SDL_ASYNCBLIT       Use asynchronous blit if possible
 143  SDL_SWSURFACE       Stored in the system memory.
 144  SDL_HWSURFACE       Stored in video memory
 145
 146 </pre>
 147 <p>Export tag: ':video'</p>
 148 <pre> SDL_ANYFORMAT       Allow any pixel-format
 149  SDL_HWPALETTE       Have an exclusive palette
 150  SDL_DOUBLEBUF       Double buffered
 151  SDL_FULLSCREEN      Full screen surface
 152  SDL_OPENGL          Have an OpenGL context
 153  SDL_OPENGLBLIT      Support OpenGL blitting.
 154                      NOTE: This option is kept for compatibility only, and is not recommended for new code.
 155  SDL_RESIZABLE       Resizable surface
 156  SDL_NOFRAME         No window caption or edge frame
 157  SDL_HWACCEL Use     Hardware acceleration blit
 158  SDL_SRCCOLORKEY     Use colorkey blitting
 159  SDL_RLEACCELOK      Private flag
 160  SDL_RLEACCEL        Accelerated colorkey blitting with RLE
 161  SDL_SRCALPHA        Use alpha blending blit
 162  SDL_PREALLOC        Use preallocated memory
 163
 164 </pre>
 165 <p>Export tag ':overlay'</p>
 166 <pre> SDL_YV12_OVERLAY    Planar mode: Y + V + U  (3 planes)
 167  SDL_IYUV_OVERLAY    Planar mode: Y + U + V  (3 planes)
 168  SDL_YUY2_OVERLAY    Packed mode: Y0+U0+Y1+V0 (1 plane)
 169  SDL_UYVY_OVERLAY    Packed mode: U0+Y0+V0+Y1 (1 plane)
 170  SDL_YVYU_OVERLAY    Packed mode: Y0+V0+Y1+U0 (1 plane)
 171
 172 </pre>
 173 <p>Export tag ':palette'</p>
 174 <pre> SDL_LOGPAL          Logical palette, which controls how blits are mapped to/from the surface
 175  SDL_PHYSPAL         Physical palette, which controls how pixels look on the screen
 176
 177 </pre>
 178 <p>Export tag ':grab'</p>
 179 <pre> SDL_GRAB_QUERY
 180  SDL_GRAB_OFF
 181  SDL_GRAB_ON
 182  SDL_GRAB_FULLSCREEN Used interally
 183
 184 </pre>
 185 <p>Export tag ':gl'</p>
 186 <pre> SDL_GL_RED_SIZE
 187  SDL_GL_GREEN_SIZE
 188  SDL_GL_BLUE_SIZE
 189  SDL_GL_ALPHA_SIZE
 190  SDL_GL_BUFFER_SIZE
 191  SDL_GL_DOUBLEBUFFER
 192  SDL_GL_DEPTH_SIZE
 193  SDL_GL_STENCIL_SIZE
 194  SDL_GL_ACCUM_RED_SIZE
 195  SDL_GL_ACCUM_GREEN_SIZE
 196  SDL_GL_ACCUM_BLUE_SIZE
 197  SDL_GL_ACCUM_ALPHA_SIZE
 198  SDL_GL_STEREO
 199  SDL_GL_MULTISAMPLEBUFFERS
 200  SDL_GL_MULTISAMPLESAMPLES
 201  SDL_GL_ACCELERATED_VISUAL
 202  SDL_GL_SWAP_CONTROL
 203
 204 </pre>
 205
 206 </div>
 207 <h1 id="Core_Functions">Core Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
 208 <div id="Core_Functions_CONTENT">
 209
 210 </div>
 211 <h2 id="get_video_surface">get_video_surface</h2>
 212 <div id="get_video_surface_CONTENT">
 213 <pre> my $surface = SDL::Video::get_video_surface();
 214
 215 </pre>
 216 <p>This function returns the current display <a href="SDL-Surface.html">SDL::Surface</a>. If SDL is doing format conversion on the display surface, this
 217 function returns the publicly visible surface, not the real video surface.</p>
 218 <p>Example:</p>
 219 <pre> # somewhere after you set the video mode
 220  my $surface = SDL::Video::get_video_surface();
 221
 222  printf( &quot;our screen is %d pixels wide and %d pixels high\n&quot;, $surface-&gt;w, $surface-&gt;h );
 223
 224 </pre>
 225
 226 </div>
 227 <h2 id="get_video_info">get_video_info</h2>
 228 <div id="get_video_info_CONTENT">
 229 <pre> my $video_info = SDL::Video::get_video_info();
 230
 231 </pre>
 232 <p>This function returns a read-only <a href="SDL-VideoInfo.html">SDL::VideoInfo</a> containing information about the video hardware. If it is called before
 233 <a href="#set_video_mode">SDL::Video::set_video_mode</a>, the <code>vfmt</code> member of the returned structure will contain the pixel
 234 format of the <strong>best</strong> video mode. </p>
 235 <p>Example:</p>
 236 <pre> use SDL;
 237  use SDL::Video;
 238  use SDL::VideoInfo;
 239  use SDL::PixelFormat;
 240
 241  SDL::init(SDL_INIT_VIDEO);
 242
 243  my $video_info = SDL::Video::get_video_info();
 244
 245  printf( &quot;we can have %dbits per pixel\n&quot;, $video_info-&gt;vfmt-&gt;BitsPerPixel );
 246
 247  SDL::quit();
 248
 249 </pre>
 250
 251 </div>
 252 <h2 id="video_driver_name">video_driver_name</h2>
 253 <div id="video_driver_name_CONTENT">
 254 <pre> my $driver_name = SDL::Video::video_driver_name();
 255
 256 </pre>
 257 <p>This function will return the name of the initialized video driver up to a maximum of 1024 characters. The driver name is a simple one
 258 word identifier like <code>&quot;x11&quot;</code>, <code>&quot;windib&quot;</code> or <code>&quot;directx&quot;</code>.</p>
 259 <p><strong>Note</strong>: Some platforms allow selection of the video driver through the <code>SDL_VIDEODRIVER</code> environment variable. </p>
 260 <p>Example:</p>
 261 <pre> use SDL;
 262  use SDL::Video;
 263
 264  SDL::init(SDL_INIT_VIDEO);
 265
 266  print SDL::Video::video_driver_name() . &quot;\n&quot;;
 267
 268  SDL::quit();
 269
 270 </pre>
 271
 272 </div>
 273 <h2 id="list_modes">list_modes</h2>
 274 <div id="list_modes_CONTENT">
 275 <pre> my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
 276
 277 </pre>
 278 <p>Returns a reference to an array:</p>
 279 <dl>
 280         <dt>*
 281 of available screen dimensions (as <code>SDL::Rect</code>'s) for the given format and video flags. </dt>
 282         <dt>*
 283 with first array element 'all'. In this case you can set all modes.</dt>
 284         <dt>*
 285 with first array element 'none' if no mode is available.</dt>
 286 </dl>
 287 <p><strong>Note</strong>: &lt;list_modes&gt; should be called before the video_mode ist set. Otherwise you will always get 'all'.</p>
 288 <p>Example:</p>
 289 <pre> use SDL;
 290  use SDL::Video;
 291  use SDL::VideoInfo;
 292  use SDL::PixelFormat;
 293  use SDL::Rect;
 294
 295  SDL::init(SDL_INIT_VIDEO);
 296
 297  my $video_info = SDL::Video::get_video_info();
 298
 299  my @modes = @{ SDL::Video::list_modes($video_info-&gt;vfmt, SDL_NOFRAME) };
 300
 301  if($#modes &gt; 0)
 302  {
 303      print(&quot;available modes:\n&quot;);
 304      foreach my $mode ( @modes )
 305      {
 306          printf(&quot;%d x %d\n&quot;, $mode-&gt;w, $mode-&gt;h );
 307      }
 308  }
 309  elsif($#modes == 0)
 310  {
 311      printf(&quot;%s video modes available\n&quot;, $modes[0]);
 312  }
 313
 314  SDL::quit();
 315
 316 </pre>
 317
 318 </div>
 319 <h2 id="video_mode_ok">video_mode_ok</h2>
 320 <div id="video_mode_ok_CONTENT">
 321 <pre> my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
 322
 323 </pre>
 324 <p>This function is used to check whether the requested mode is supported by the current video device. The arguments passed to this function
 325 are the same as those you would pass to <a href="#set_video_mode">SDL::Video::set_video_mode</a>.
 326 It returns <code>0</code> if the mode is not supported at all, otherwise the suggested <code>bpp</code>.</p>
 327 <p>Example:</p>
 328 <pre> use SDL;
 329  use SDL::Video;
 330
 331  SDL::init(SDL_INIT_VIDEO);
 332
 333  my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
 334
 335  unless($video_mode_ok)
 336  {
 337      printf( &quot;this video mode is not supported\n&quot; );
 338  }
 339
 340  SDL::quit();
 341
 342 </pre>
 343
 344 </div>
 345 <h2 id="set_video_mode">set_video_mode</h2>
 346 <div id="set_video_mode_CONTENT">
 347 <pre> my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
 348
 349 </pre>
 350 <p>Sets up a video mode with the specified width, height, bits-per-pixel and flags.
 351 <code>set_video_mode</code> returns a <a href="SDL-Surface.html">SDL::Surface</a> on success otherwise it returns undef on error, the error message is retrieved
 352 using <code>SDL::get_error</code>.</p>
 353
 354 </div>
 355 <h3 id="List_of_avalaibles_flags">List of avalaibles flags</h3>
 356 <div id="List_of_avalaibles_flags_CONTENT">
 357 <dl>
 358         <dt><code>SDL_SWSURFACE</code></dt>
 359         <dd>
 360                 <p>Create the video surface in system memory</p>
 361         </dd>
 362         <dt><code>SDL_HWSURFACE</code></dt>
 363         <dd>
 364                 <p>Create the video surface in video memory</p>
 365         </dd>
 366         <dt><code>SDL_ASYNCBLIT</code></dt>
 367         <dd>
 368                 <p>Enables the use of asynchronous updates of the display surface.
 369 This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.</p>
 370         </dd>
 371         <dt><code>SDL_ANYFORMAT</code></dt>
 372         <dd>
 373                 <p>Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface.
 374 Passing <code>SDL_ANYFORMAT</code> prevents this and causes SDL to use the video surface, regardless of its pixel depth.</p>
 375         </dd>
 376         <dt><code>SDL_HWPALETTE</code></dt>
 377         <dd>
 378                 <p>Give SDL exclusive palette access. Without this flag you may not always get the colors you request with SDL::set_colors or SDL::set_palette.</p>
 379         </dd>
 380         <dt><code>SDL_DOUBLEBUF</code></dt>
 381         <dd>
 382                 <p>Enable hardware double buffering; only valid with <code>SDL_HWSURFACE</code>. Calling <a href="#flip">SDL::Video::flip</a> will flip the buffers and update
 383 the screen.
 384 All drawing will take place on the surface that is not displayed at the moment.
 385 If double buffering could not be enabled then <a href="#flip">SDL::Video::flip</a> will just perform a
 386 <a href="#update_rect">SDL::Video::update_rect</a> on the entire screen.</p>
 387         </dd>
 388         <dt><code>SDL_FULLSCREEN</code></dt>
 389         <dd>
 390                 <p>SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason),
 391 the next higher resolution will be used and the display window centered on a black background.</p>
 392         </dd>
 393         <dt><code>SDL_OPENGL</code></dt>
 394         <dd>
 395                 <p>Create an OpenGL rendering context. You should have previously set OpenGL video attributes with
 396 <a href="#GL_set_attribute">SDL::Video::GL_set_attribute</a>.</p>
 397         </dd>
 398         <dt><code>SDL_OPENGLBLIT</code></dt>
 399         <dd>
 400                 <p>Create an OpenGL rendering context, like above, but allow normal blitting operations.
 401 The screen (2D) surface may have an alpha channel, and SDL::update_rects must be used for updating changes to the screen surface.
 402 NOTE: This option is kept for compatibility only, and will be removed in next versions. Is not recommended for new code.</p>
 403         </dd>
 404         <dt><code>SDL_RESIZABLE</code></dt>
 405         <dd>
 406                 <p>Create a resizable window.
 407 When the window is resized by the user a <code>SDL_VIDEORESIZE</code> event is generated and
 408 <a href="#set_video_mode">SDL::Video::set_video_mode</a> can be called again with the new size.</p>
 409         </dd>
 410         <dt><code>SDL_NOFRAME</code></dt>
 411         <dd>
 412                 <p>If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration.
 413 Fullscreen modes automatically have this flag set.</p>
 414         </dd>
 415 </dl>
 416 <p><strong>Note 1</strong>: Use <code>SDL_SWSURFACE</code> if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate.
 417 When you use hardware surfaces (by passing the flag <code>SDL_HWSURFACE</code> as parameter), SDL copies the surfaces from video memory to system memory
 418 when you lock them, and back when you unlock them. This can cause a major performance hit. Be aware that you may request a hardware surface,
 419 but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface
 420 when using <code>SDL_FULLSCREEN</code>. The <code>SDL_HWSURFACE</code> flag is best used when the surfaces you'll be blitting can also be stored in video memory.</p>
 421 <p><strong>Note 2</strong>: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment
 422 variables <code>SDL_VIDEO_CENTERED=center</code> or <code>SDL_VIDEO_WINDOW_POS=x,y</code>. You can also set them via <code>SDL::putenv</code>.</p>
 423 <p><strong>Note 3</strong>: This function should be called in the main thread of your application.</p>
 424 <p><strong>User note 1</strong>: Some have found that enabling OpenGL attributes like <code>SDL_GL_STENCIL_SIZE</code> (the stencil buffer size) before the video mode has
 425 been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.</p>
 426 <p><strong>User note 2</strong>: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL
 427 initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux,
 428 however, it works fine, and the initialization code only needs to be executed after the first call to
 429 <a href="#set_video_mode">SDL::Video::set_video_mode</a> (although there is no harm in executing the initialization code after
 430 each call to <a href="#set_video_mode">SDL::Video::set_video_mode</a>, for example for a multiplatform application). </p>
 431
 432 </div>
 433 <h2 id="convert_surface">convert_surface</h2>
 434 <div id="convert_surface_CONTENT">
 435 <pre> $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
 436
 437 </pre>
 438 <p>Creates a new SDL::surface of the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>, and then copies and maps the given surface to it.
 439 It is also useful for making a copy of a surface.</p>
 440 <p>The flags parameter is passed to <a href="SDL-Surface.html">SDL::Surface</a><code>-&gt;new</code> and has those semantics.
 441 This function is used internally by <a href="#display_format">SDL::Video::display_format</a>.
 442 This function can only be called after <code>SDL::init</code>. </p>
 443 <p>it returns a <a href="SDL-Surface.html">SDL::Surface</a> on success or <code>undef</code> on error.</p>
 444
 445 </div>
 446 <h2 id="display_format">display_format</h2>
 447 <div id="display_format_CONTENT">
 448 <pre> $new_surface = SDL::Video::display_format( $surface );
 449
 450 </pre>
 451 <p>This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast
 452 blitting onto the display surface. It calls <a href="#conver_surface">SDL::Video::convert_surface</a>.</p>
 453 <p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
 454 this function.</p>
 455 <p>If you want an alpha channel, see <code>SDL::Video::display_format_alpha</code>.
 456 Return Value</p>
 457 <p><strong>Note</strong>: Remember to use a different variable for the returned surface, otherwise you have a memory leak, since the original surface isn't freed. </p>
 458
 459 </div>
 460 <h2 id="display_format_alpha">display_format_alpha</h2>
 461 <div id="display_format_alpha_CONTENT">
 462 <pre> $new_surface = SDL::Video::display_format_alpha( $surface );
 463
 464 </pre>
 465 <p>This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer plus an alpha channel,
 466 suitable for fast blitting onto the display surface. It calls <a href="#convert_surface">SDL::Video::convert_surface</a>.</p>
 467 <p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
 468 this function.</p>
 469 <p>This function can be used to convert a colorkey to an alpha channel, if the <code>SDL_SRCCOLORKEY</code> flag is set on the surface. The generated
 470 surface will then be transparent (alpha=0) where the pixels match the colorkey, and opaque (alpha=255) elsewhere.</p>
 471 <p><strong>Note</strong>: The video surface must be initialised using <a href="#set_video_mode">SDL::Video::set_video_mode</a> before this function is called, or it will
 472 segfault.</p>
 473
 474 </div>
 475 <h2 id="load_BMP">load_BMP</h2>
 476 <div id="load_BMP_CONTENT">
 477 <pre> $surface = SDL::Video::load_BMP( $filename );
 478
 479 </pre>
 480 <p>Loads a <a href="SDL-Surface.html">SDL::Surface</a> from a named Windows BMP file.
 481 <code>SDL::Video::load_BMP</code> returns a <a href="SDL-Surface.html">SDL::Surface</a> on success or <code>undef</code> on error.</p>
 482 <p><strong>Note</strong>: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect). </p>
 483 <pre> use SDL;
 484  use SDL::Video;
 485  use SDL::Rect;
 486  use SDL::Surface;
 487
 488  my $screen_width  = 640;
 489  my $screen_height = 480;
 490
 491  SDL::init(SDL_INIT_VIDEO);
 492
 493  my $screen  = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
 494
 495  my $picture = SDL::Video::load_BMP('test.bmp');
 496
 497  die(SDL::get_error) unless $picture;
 498
 499  my $rect    = SDL::Rect-&gt;new(0, 0, $screen_width, $screen_height);
 500
 501  SDL::Video::blit_surface( $picture, SDL::Rect-&gt;new(0, 0, $picture-&gt;w, $picture-&gt;h),
 502                            $screen,  SDL::Rect-&gt;new(0, 0, $screen-&gt;w,  $screen-&gt;h) );
 503
 504  SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
 505
 506  sleep(2);
 507
 508  SDL::quit;
 509
 510 </pre>
 511
 512 </div>
 513 <h2 id="save_BMP">save_BMP</h2>
 514 <div id="save_BMP_CONTENT">
 515 <pre> $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
 516
 517 </pre>
 518 <p>Saves the given <a href="SDL-Surface.html">SDL::Surface</a> as a Windows BMP file named filename.
 519 it returns 0 on success or -1 on error.</p>
 520
 521 </div>
 522 <h2 id="set_color_key">set_color_key</h2>
 523 <div id="set_color_key_CONTENT">
 524 <pre> $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
 525
 526 </pre>
 527 <p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
 528 <p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match
 529 the key value).
 530 The key must be of the same pixel format as the surface, <a href="#map_RGB">SDL::Video::map_RGB</a> is often useful for obtaining an acceptable value.
 531 If flag is <code>SDL_SRCCOLORKEY</code> then key is the transparent pixel value in the source image of a blit.</p>
 532 <p>If <code>flag</code> is OR'd with <code>SDL_RLEACCEL</code> then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface.
 533 The surface will actually be encoded for RLE acceleration the first time <a href="#blit_surface">SDL::Video::blit_surface</a> or
 534 <code>SDL::Video::display_format|/display_format</code> is called on the surface.
 535 If <code>flag</code> is <code>0</code>, this function clears any current color key. </p>
 536 <p><code>SDL::Video::set_color_key</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
 537
 538 </div>
 539 <h2 id="set_alpha">set_alpha</h2>
 540 <div id="set_alpha_CONTENT">
 541 <pre> $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
 542
 543 </pre>
 544 <p><code>set_alpha</code> is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
 545 <p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
 546 flags is used to specify whether alpha blending should be used ( <code>SDL_SRCALPHA</code> ) and whether the surface should use RLE acceleration for
 547 blitting ( <code>SDL_RLEACCEL</code> ).
 548 flags can be an OR'd combination of these two options, one of these options or <code>0</code>.
 549 If <code>SDL_SRCALPHA</code> is not passed as a flag then all alpha information is ignored when blitting the surface.
 550 The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can
 551 still be accelerated with <code>SDL_RLEACCEL</code>.</p>
 552 <p><strong>Note</strong>: The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.</p>
 553 <p>Alpha affects surface blitting in the following ways: </p>
 554 <dl>
 555         <dt>RGBA-&gt;RGB with <code>SDL_SRCALPHA</code></dt>
 556         <dd>
 557                 <p>The source is alpha-blended with the destination, using the alpha channel.
 558 SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
 559         </dd>
 560         <dt>RGBA-&gt;RGB without <code>SDL_SRCALPHA</code></dt>
 561         <dd>
 562                 <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
 563 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
 564         </dd>
 565         <dt>RGB-&gt;RGBA with <code>SDL_SRCALPHA</code></dt>
 566         <dd>
 567                 <p>The source is alpha-blended with the destination using the per-surface alpha value.
 568 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
 569 The alpha channel of the copied pixels is set to opaque.</p>
 570         </dd>
 571         <dt>RGB-&gt;RGBA without <code>SDL_SRCALPHA</code></dt>
 572         <dd>
 573                 <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
 574 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
 575         </dd>
 576         <dt>RGBA-&gt;RGBA with <code>SDL_SRCALPHA</code></dt>
 577         <dd>
 578                 <p>The source is alpha-blended with the destination using the source alpha channel.
 579 The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
 580         </dd>
 581         <dt>RGBA-&gt;RGBA without <code>SDL_SRCALPHA</code></dt>
 582         <dd>
 583                 <p>The RGBA data is copied to the destination surface.
 584 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
 585         </dd>
 586         <dt>RGB-&gt;RGB with <code>SDL_SRCALPHA</code></dt>
 587         <dd>
 588                 <p>The source is alpha-blended with the destination using the per-surface alpha value.
 589 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
 590         </dd>
 591         <dt>RGB-&gt;RGB without <code>SDL_SRCALPHA</code></dt>
 592         <dd>
 593                 <p>The RGB data is copied from the source.
 594 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
 595         </dd>
 596 </dl>
 597 <p><strong>Note</strong>: When blitting, the presence or absence of <code>SDL_SRCALPHA</code> is relevant only on the source surface, not the destination.
 598 <strong>Note</strong>: Note that RGBA-&gt;RGBA blits (with <code>SDL_SRCALPHA</code> set) keep the alpha of the destination surface. This means that you cannot compose
 599 two arbitrary RGBA surfaces this way and get the result you would expect from &quot;overlaying&quot; them; the destination alpha will work as a mask.</p>
 600 <p><strong>Note</strong>: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available. </p>
 601 <p><code>SDL::Video::set_alpha</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
 602
 603 </div>
 604 <h2 id="fill_rect">fill_rect</h2>
 605 <div id="fill_rect_CONTENT">
 606 <pre> $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );
 607
 608 </pre>
 609 <p>This function performs a fast fill of the given <a href="SDL-Rect.html">SDL::Rect</a> with the given <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>. If dest_rect is NULL, the whole surface
 610 will be filled with color.</p>
 611 <p>The color should be a pixel of the format used by the surface, and can be generated by the <a href="#map_RGB">SDL::Video::map_RGB</a> or
 612 <code>SDL::Video::map_RGBA|/map_RGBA</code> functions. If the color value contains an alpha value then the destination is simply &quot;filled&quot; with that
 613 alpha information, no blending takes place.</p>
 614 <p>If there is a clip rectangle set on the destination (set via <a href="#set_clip_rect">SDL::Video::set_clip_rect</a>), then this function will clip based
 615 on the intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually
 616 filled.</p>
 617 <p>If you call this on the video surface (ie: the value of <a href="#get_video_surface">SDL::Video::get_video_surface</a>) you may have to update the video
 618 surface to see the result. This can happen if you are using a shadowed surface that is not double buffered in Windows XP using build 1.2.9. </p>
 619 <p><code>SDL::Video::fill_rect</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
 620 <p>for an example see <a href="#SYNOPSIS">SYNOPSIS</a>.</p>
 621
 622 </div>
 623 <h1 id="Surface_Locking_and_Unlocking">Surface Locking and Unlocking</h1><p><a href="#TOP" class="toplink">Top</a></p>
 624 <div id="Surface_Locking_and_Unlocking_CONTEN">
 625
 626 </div>
 627 <h2 id="lock_surface">lock_surface</h2>
 628 <div id="lock_surface_CONTENT">
 629 <pre> int SDL::Video::lock_surface( $surface );
 630
 631 </pre>
 632 <p><code>SDL::Video::lock_surface</code> sets up the given <a href="SDL-Surface.html">SDL::Surface</a> for directly accessing the pixels.
 633 Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to ( <code>surface-</code>set_pixels&gt;) and read from ( <code>surface-</code>get_pixels&gt; ),
 634 using the pixel format stored in <code>surface-</code>format&gt;.
 635 Once you are done accessing the surface, you should use <a href="#unlock_surface">SDL::Video::unlock_surface</a> to release the lock.</p>
 636 <p>Not all surfaces require locking. If <a href="#MUSTLOCK">SDL::Video::MUSTLOCK</a> evaluates to <code>0</code>, then reading and writing pixels to the surface can
 637 be performed at any time, and the pixel format of the surface will not change.
 638 No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
 639 <code>SDL::Video::lock_surface</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
 640 <p><strong>Note</strong>: Since SDL 1.1.8, the surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have
 641 a matching unlock.</p>
 642 <pre> use strict;
 643  use warnings;
 644  use Carp;
 645
 646  use SDL v2.3;
 647  use SDL::Video;
 648  use SDL::Event;
 649  use SDL::Events;
 650  use SDL::Surface;
 651
 652  my $screen;
 653
 654  sub putpixel
 655  {
 656      my($x, $y, $color) = @_;
 657      my $lineoffset     = $y * ($screen-&gt;pitch / 4);
 658      $screen-&gt;set_pixels( $lineoffset+ $x, $color);
 659  }
 660
 661  sub render
 662  {
 663      if( SDL::Video::MUSTLOCK( $screen) )
 664      {
 665          return if (SDL::Video::lock_surface( $screen ) &lt; 0)
 666      }
 667
 668      my $ticks                = SDL::get_ticks();
 669      my ($i, $y, $yofs, $ofs) = (0,0,0,0);
 670      for ($i = 0; $i &lt; 480; $i++)
 671      {
 672          for (my $j = 0, $ofs = $yofs; $j &lt; 640; $j++, $ofs++)
 673          {
 674              $screen-&gt;set_pixels( $ofs, (  $i * $i + $j * $j + $ticks ) );
 675          }
 676          $yofs += $screen-&gt;pitch / 4;
 677      }
 678
 679      putpixel(10, 10, 0xff0000);
 680      putpixel(11, 10, 0xff0000);
 681      putpixel(10, 11, 0xff0000);
 682      putpixel(11, 11, 0xff0000);
 683
 684      SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
 685
 686      SDL::Video::update_rect($screen, 0, 0, 640, 480);
 687
 688      return 0;
 689  }
 690
 691  sub main
 692  {
 693      carp 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) &lt; 0);
 694
 695      $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
 696
 697      carp 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
 698
 699      while(1)
 700      {
 701          render();
 702
 703          my $event = SDL::Event-&gt;new();
 704
 705          while( SDL::Events::poll_event($event) )
 706          {
 707              my $type = $event-&gt;type;
 708              return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
 709          }
 710          SDL::Events::pump_events();
 711      }
 712  }
 713
 714  main();
 715
 716  SDL::quit;
 717
 718 </pre>
 719
 720 </div>
 721 <h2 id="unlock_surface">unlock_surface</h2>
 722 <div id="unlock_surface_CONTENT">
 723 <pre> SDL::Video::unlock_surface( $surface );
 724
 725 </pre>
 726 <p>Surfaces that were previously locked using <a href="#lock_sruface">SDL::Video::lock_surface</a> must be unlocked with <code>SDL::Video::unlock_surface</code>.
 727 Surfaces should be unlocked as soon as possible.
 728 <code>SDL::Video::unlock_surface</code> doesn't return anything.</p>
 729 <p><strong>Note</strong>: Since 1.1.8, the surface locks are recursive. See <a href="#lock_sruface">SDL::Video::lock_surface</a> for more information. </p>
 730
 731 </div>
 732 <h2 id="MUSTLOCK">MUSTLOCK</h2>
 733 <div id="MUSTLOCK_CONTENT">
 734 <pre> int SDL::Video::MUSTLOCK( $surface );
 735
 736 </pre>
 737 <p><code>MUSTLOCK</code> returns <code>0</code> if the surface does not have to be locked during pixel operations, otherwise <code>1</code>.</p>
 738
 739 </div>
 740 <h1 id="Screen_Updating_Functions">Screen Updating Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
 741 <div id="Screen_Updating_Functions_CONTENT">
 742
 743 </div>
 744 <h2 id="set_clip_rect">set_clip_rect</h2>
 745 <div id="set_clip_rect_CONTENT">
 746 <pre> SDL::Video::set_clip_rect( $surface, $rect );
 747
 748 </pre>
 749 <p>Sets the clipping rectangle for the given <a href="SDL-Surface.html">SDL::Surface</a>. When this surface is the destination of a blit, only the area within the clip
 750 rectangle will be drawn into.
 751 The rectangle pointed to by rect will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall
 752 outside the edges of the surface.
 753 If rect is NULL the clipping rectangle will be set to the full size of the surface.
 754 <code>SDL::Video::set_clip_rect</code> doesn't returns anything.</p>
 755
 756 </div>
 757 <h2 id="get_clip_rect">get_clip_rect</h2>
 758 <div id="get_clip_rect_CONTENT">
 759 <pre> SDL::Video::get_clip_rect( $surface, $rect );
 760
 761 </pre>
 762 <p>Gets the clipping rectangle for the given <a href="SDL-Surface.html">SDL::Surface</a>. When this surface is the destination of a blit, only the area within the clip
 763 rectangle is drawn into.
 764 The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
 765 <code>SDL::Video::get_clip_rect</code> doesn't returns anything;</p>
 766 <pre> use SDL;
 767  use SDL::Video;
 768  use SDL::Rect;
 769  use SDL::Surface;
 770
 771  my $screen_width  = 640;
 772  my $screen_height = 480;
 773
 774  SDL::init(SDL_INIT_VIDEO);
 775
 776  my $screen  = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
 777
 778  my $rect = SDL::Rect-&gt;new(0, 0, 0, 0);
 779
 780  SDL::Video::get_clip_rect($screen, $rect);
 781
 782  printf( &quot;rect is %d, %d, %d, %d\n&quot;, $rect-&gt;x, $rect-&gt;y, $rect-&gt;w, $rect-&gt;h);
 783
 784  SDL::quit;
 785
 786 </pre>
 787
 788 </div>
 789 <h2 id="blit_surface">blit_surface</h2>
 790 <div id="blit_surface_CONTENT">
 791 <pre> SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
 792
 793 </pre>
 794 <p>This performs a fast blit from the given source <a href="SDL-Surface.html">SDL::Surface</a> to the given destination <a href="SDL-Surface.html">SDL::Surface</a>.
 795 The width and height in <code>src_surface</code> determine the size of the copied rectangle. Only the position is used in the <code>dst_rect</code>
 796 (the width and height are ignored). Blits with negative <code>dst_rect</code> coordinates will be clipped properly.
 797 If <code>src_rect</code> is NULL, the entire surface is copied. If <code>dst_rect</code> is NULL, then the destination position (upper left corner) is (0, 0).
 798 The final blit rectangle is saved in <code>dst_rect</code> after all clipping is performed (<code>src_rect</code> is not modified).
 799 The blit function should not be called on a locked surface. I.e. when you use your own drawing functions you may need to lock a surface,
 800 but this is not the case with <code>SDL::Video::blit_surface</code>. Like most surface manipulation functions in SDL, it should not be used together
 801 with OpenGL.</p>
 802 <p>The results of blitting operations vary greatly depending on whether <code>SDL_SRCALPHA</code> is set or not. See <a href="#set_alpha">SDL::Video::set_alpha</a>
 803 for an explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
 804 <code>SDL::Video::blit_surface</code> doesn't returns anything.</p>
 805 <p>For an example see <a href="#load_BMP">SDL::Video::load_BMP</a>.</p>
 806
 807 </div>
 808 <h2 id="update_rect">update_rect</h2>
 809 <div id="update_rect_CONTENT">
 810 <pre> update_rect( $surface, $left, $top, $width, $height );
 811
 812 </pre>
 813 <p>Makes sure the given area is updated on the given screen.
 814 The rectangle must be confined within the screen boundaries because there's no clipping.
 815 update_rect doesn't returns any value.</p>
 816 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface">SDL::Video::lock_surface</a></p>
 817 <p><strong>Note2</strong>: If <code>x</code>, <code>y</code>, <code>width</code> and <code>height</code> are all equal to 0, <code>update_rect</code> will update the entire screen. </p>
 818 <p>For an example see <a href="#SYNOPSIS">SYNOPSIS</a></p>
 819
 820 </div>
 821 <h2 id="update_rects">update_rects</h2>
 822 <div id="update_rects_CONTENT">
 823 <pre> update_rects( $surface, @rects );
 824
 825 </pre>
 826 <p>Makes sure the given list of rectangles is updated on the given screen.
 827 The rectangle must be confined within the screen boundaries because there's no clipping.
 828 <code>update_rects</code> doesn't returns any value.</p>
 829 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface">SDL::Video::lock_surface</a>.</p>
 830 <p>Example:</p>
 831 <pre> use SDL;
 832  use SDL::Video;
 833  use SDL::Surface;
 834  use SDL::Rect;
 835
 836  # the size of the window box or the screen resolution if fullscreen
 837  my $screen_width   = 800;
 838  my $screen_height  = 600;
 839
 840  SDL::init(SDL_INIT_VIDEO);
 841
 842  # setting video mode
 843  my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
 844
 845  # drawing the whole screen blue
 846  my $mapped_color   = SDL::Video::map_RGB($screen_surface-&gt;format(), 0, 0, 255); # blue
 847  SDL::Video::fill_rect($screen_surface,
 848                        SDL::Rect-&gt;new(0, 0, $screen_width, $screen_height),
 849                        $mapped_color);
 850
 851  my @rects = ();
 852  push(@rects, SDL::Rect-&gt;new(200,   0, 400, 600));
 853  push(@rects, SDL::Rect-&gt;new(  0, 150, 800, 300));
 854
 855  # updating parts of the screen (should look like a cross)
 856  SDL::Video::update_rects($screen_surface, @rects);
 857
 858  sleep(2);
 859
 860  SDL::quit();
 861
 862 </pre>
 863
 864 </div>
 865 <h2 id="flip">flip</h2>
 866 <div id="flip_CONTENT">
 867 <pre> $flip = SDL::Video::flip( $screen_surface );
 868
 869 </pre>
 870 <p>On hardware that supports double-buffering, this function sets up a flip and returns.
 871 The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return.
 872 On hardware that doesn't support double-buffering or if <code>SDL_SWSURFACE</code> was set, this is equivalent to calling
 873 <code>SDL::Video::update_rect( $screen, 0, 0, 0, 0 )</code>.</p>
 874 <p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by
 875 restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in
 876 contrast to a full screen software mode.</p>
 877 <p>The <code>SDL_DOUBLEBUF</code> flag must have been passed to <a href="#set_video_mode">SDL::Video::set_video_mode</a>, when setting the video mode for this function
 878 to perform hardware flipping.</p>
 879 <p><code>flip</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
 880 <p><strong>Note</strong>: If you want to swap the buffers of an initialized OpenGL context, use the function <a href="#GL_swap_buffers">SDL::Video::GL_swap_buffers</a>
 881 instead. </p>
 882 <p>Example:</p>
 883 <pre> use SDL;
 884  use SDL::Video;
 885  use SDL::Surface;
 886
 887  # the size of the window box or the screen resolution if fullscreen
 888  my $screen_width   = 800;
 889  my $screen_height  = 600;
 890
 891  SDL::init(SDL_INIT_VIDEO);
 892
 893  # setting video mode
 894  my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
 895
 896  # do some video operations here
 897
 898  # doing page flipping
 899  unless( SDL::Video::flip($screen_surface) == 0 )
 900  {
 901      printf( STDERR &quot;failed to swap buffers: %s\n&quot;, SDL::get_error() );
 902  }
 903
 904  SDL::quit();
 905
 906 </pre>
 907
 908 </div>
 909 <h1 id="Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
 910 <div id="Palette_Color_and_Pixel_Functions_CO">
 911
 912 </div>
 913 <h2 id="set_colors">set_colors</h2>
 914 <div id="set_colors_CONTENT">
 915 <pre> $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
 916
 917 </pre>
 918 <p>Sets a portion of the colormap for the given 8-bit surface. </p>
 919 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
 920 If <code>SDL_HWPALETTE</code> was set in <a href="#set_video_mode">SDL::Video::set_video_mode</a> flags, <code>SDL::Video::set_colors</code> will always return 1, and the
 921 palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
 922 The color components of a <a href="SDL-Color.html">SDL::Color</a> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.
 923 Palettized (8-bit) screen surfaces with the <code>SDL_HWPALETTE</code> flag have two palettes, a logical palette that is used for mapping blits to/from
 924 the surface and a physical palette (that determines how the hardware will map the colors to the display).
 925 <code>SDL::Video::set_colors</code> modifies both palettes (if present), and is equivalent to calling <a href="#set_palette">SDL::Video::set_palette</a> with the
 926 flags set to ( <code>SDL_LOGPAL | SDL_PHYSPAL</code> ). </p>
 927 <p>If <code>surface</code> is not a palettized surface, this function does nothing, returning 0.
 928 If all of the colors were set as passed to <code>SDL::Video::set_colors</code>, it will return 1.
 929 If not all the color entries were set exactly as given, it will return 0, and you should look at the surface palette to determine the
 930 actual color palette.</p>
 931
 932 </div>
 933 <h2 id="set_palette">set_palette</h2>
 934 <div id="set_palette_CONTENT">
 935 <pre> $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
 936
 937 </pre>
 938 <p>Sets a portion of the palette for the given 8-bit surface.</p>
 939 <p>Palettized (8-bit) screen surfaces with the <code>SDL_HWPALETTE</code> flag have two palettes, a logical palette that is used for mapping blits to/from
 940 the surface and a physical palette (that determines how the hardware will map the colors to the display).
 941 Non screen surfaces have a logical palette only. <a href="#blit">SDL::Video::blit</a> always uses the logical palette when blitting surfaces (if it has to
 942 convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various
 943 special color effects (e.g., screen fading, color flashes, screen dimming).</p>
 944 <p>This function can modify either the logical or physical palette by specifying <code>SDL_LOGPAL</code> or <code>SDL_PHYSPAL</code> the in the flags parameter.</p>
 945 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
 946 If <code>SDL_HWPALETTE</code> was set in <a href="#set_video_mode">SDL::Video::set_video_mode</a> flags, <code>SDL::Video::set_palette</code> will always return 1, and the
 947 palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
 948 The color components of a <code>SDL::Color</code> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
 949 <p>If <code>surface</code> is not a palettized surface, this function does nothing, returning <code>0</code>. If all of the colors were set as passed to <code>set_palette</code>,
 950 it will return <code>1</code>. If not all the color entries were set exactly as given, it will return <code>0</code>, and you should look at the surface palette
 951 to determine the actual color palette.</p>
 952
 953 </div>
 954 <h2 id="set_gamma">set_gamma</h2>
 955 <div id="set_gamma_CONTENT">
 956 <pre> $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
 957
 958 </pre>
 959 <p>Sets the &quot;gamma function&quot; for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen.
 960 A gamma value of 1.0 is identity (i.e., no adjustment is made).</p>
 961 <p>This function adjusts the gamma based on the &quot;gamma function&quot; parameter, you can directly specify lookup tables for gamma adjustment
 962 with SDL::set_gamma_ramp.</p>
 963 <p><strong>Note</strong>: Not all display hardware is able to change gamma.</p>
 964 <p><code>SDL::Video::set_gamma</code> returns <code>-1</code> on error.</p>
 965 <p><strong>Warning</strong>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
 966 <p>Example:</p>
 967 <pre> use SDL;
 968  use SDL::Video;
 969  use SDL::Surface;
 970  use SDL::Rect;
 971  use Time::HiRes qw( usleep );
 972
 973  # the size of the window box or the screen resolution if fullscreen
 974  my $screen_width   = 800;
 975  my $screen_height  = 600;
 976
 977  SDL::init(SDL_INIT_VIDEO);
 978
 979  # setting video mode
 980  my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
 981
 982  # drawing something somewhere
 983  my $mapped_color   = SDL::Video::map_RGB($screen_surface-&gt;format(), 128, 128, 128); # gray
 984  SDL::Video::fill_rect($screen_surface,
 985                        SDL::Rect-&gt;new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
 986                        $mapped_color);
 987
 988  # update the whole screen
 989  SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
 990
 991  usleep(500000);
 992
 993  for(1..20)
 994  {
 995     SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
 996         usleep(40000);
 997  }
 998
 999  for(1..20)
1000  {
1001     SDL::Video::set_gamma( $_ / 20, 1, 1 );
1002         usleep(40000);
1003  }
1004
1005  SDL::Video::set_gamma( 1, 1, 1 );
1006
1007  usleep(500000);
1008
1009  SDL::quit();
1010
1011 </pre>
1012
1013 </div>
1014 <h2 id="get_gamma_ramp">get_gamma_ramp</h2>
1015 <div id="get_gamma_ramp_CONTENT">
1016 <pre> $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
1017
1018 </pre>
1019 <p>Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
1020 <code>SDL::Video::get_gamma_ramp</code> returns -1 on error.</p>
1021 <pre> use SDL;
1022  use SDL::Video;
1023
1024  SDL::init(SDL_INIT_VIDEO);
1025
1026  my (@red, @green, @blue);
1027
1028  my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1029
1030  if( -1 == $ret )
1031  {
1032      print( &quot;an error occoured&quot; );
1033  }
1034  else
1035  {
1036      printf( &quot;for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[255], $green[255], $blue[255] );
1037      printf( &quot;for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[127], $green[127], $blue[127] );
1038      printf( &quot;for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[0],   $green[0],   $blue[0]   );
1039  }
1040
1041  SDL::quit();
1042
1043 </pre>
1044
1045 </div>
1046 <h2 id="set_gamma_ramp">set_gamma_ramp</h2>
1047 <div id="set_gamma_ramp_CONTENT">
1048 <pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
1049
1050 </pre>
1051 <p>Sets the gamma lookup tables for the display for each color component. Each table is an array ref of 256 Uint16 values, representing a
1052 mapping between the input and output for that channel.
1053 The input is the index into the array, and the output is the 16-bit gamma value at that index, scaled to the output color precision.
1054 You may pass NULL to any of the channels to leave them unchanged.</p>
1055 <p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a &quot;gamma function&quot; parameter
1056 with <a href="#set_gamma">SDL::Video::set_gamma</a>.</p>
1057 <p>Not all display hardware is able to change gamma.
1058 <code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
1059 <p>Example:</p>
1060 <pre> use SDL;
1061  use SDL::Video;
1062
1063  SDL::init(SDL_INIT_VIDEO);
1064
1065  my (@red, @green, @blue);
1066
1067  my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1068
1069  $red[127] = 0xFF00;
1070
1071     $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
1072
1073     $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1074
1075  if( -1 == $ret )
1076  {
1077      print( &quot;an error occoured&quot; );
1078  }
1079  else
1080  {
1081      printf( &quot;for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[255], $green[255], $blue[255] );
1082      printf( &quot;for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[127], $green[127], $blue[127] );
1083      printf( &quot;for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[0],   $green[0],   $blue[0]   );
1084  }
1085
1086  SDL::quit();
1087
1088 </pre>
1089
1090 </div>
1091 <h2 id="map_RGB">map_RGB</h2>
1092 <div id="map_RGB_CONTENT">
1093 <pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
1094
1095 </pre>
1096 <p>Maps the RGB color value to the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a> and returns the pixel value as a 32-bit int.
1097 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1098 If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
1099 <p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
1100 If the <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>'s  bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored
1101 (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
1102 <pre> use SDL;
1103  use SDL::Video;
1104  use SDL::PixelFormat;
1105  use SDL::Surface;
1106
1107  SDL::init(SDL_INIT_VIDEO);
1108
1109  my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
1110  #                                                          ^-- 16 bits per pixel
1111
1112  $r = 0x9C;
1113  $g = 0xDC;
1114  $b = 0x67;
1115
1116  printf( &quot;for 24bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b);
1117
1118  my $_16bit = SDL::Video::map_RGB( $screen_surface-&gt;format, $r, $g, $b );
1119
1120  # 16bpp is 5 bits red, 6 bits green and 5 bits blue
1121  # we will obtain the values for each color and calculating them back to 24/32bit color system
1122  ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface-&gt;format, $_16bit ) };
1123
1124  printf( &quot;for 16bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b );
1125
1126  # so color #9CDC67 becomes #9CDF63
1127
1128  SDL::quit();
1129
1130 </pre>
1131
1132 </div>
1133 <h2 id="map_RGBA">map_RGBA</h2>
1134 <div id="map_RGBA_CONTENT">
1135 <pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b, $a );
1136
1137 </pre>
1138 <p>Maps the RGBA color value to the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a> and returns the pixel value as a 32-bit int.
1139 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1140 If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette). </p>
1141 <p>A pixel value best approximating the given RGBA color value for a given pixel format.
1142 If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g.,
1143 with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
1144
1145 </div>
1146 <h2 id="get_RGB">get_RGB</h2>
1147 <div id="get_RGB_CONTENT">
1148 <pre> $rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel );
1149
1150 </pre>
1151 <p>Returns RGB values from a pixel in the specified pixel format. The pixel is an integer (e.g. 16bit RGB565, 24/32bit RGB888).
1152 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1153 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
1154 <p>For an example see <a href="#map_RGB">SDL::Video::map_RGB</a>.</p>
1155
1156 </div>
1157 <h2 id="get_RGBA">get_RGBA</h2>
1158 <div id="get_RGBA_CONTENT">
1159 <pre> $rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel );
1160
1161 </pre>
1162 <p>Gets RGBA values from a pixel in the specified pixel format.
1163 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1164 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
1165 <p>If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque). </p>
1166
1167 </div>
1168 <h1 id="GL_Methods">GL Methods</h1><p><a href="#TOP" class="toplink">Top</a></p>
1169 <div id="GL_Methods_CONTENT">
1170
1171 </div>
1172 <h2 id="GL_load_library">GL_load_library</h2>
1173 <div id="GL_load_library_CONTENT">
1174 <pre> $gl_load_lib = SDL::Video::GL_load_library( 'path/to/static/glfunctions.dll' );
1175
1176 </pre>
1177 <p>If you wish, you may load the OpenGL library from the given path at runtime, this must be done before
1178 <a href="#set_video_mode">SDL::Video::set_video_mode</a> is called. You must then use <a href="#GL_get_proc_address">SDL::Video::GL_get_proc_address</a> to retrieve
1179 function pointers to GL functions. </p>
1180 <p><code>GL_load_library</code> returns <code>0</code> on success or <code>-1</code> or error.</p>
1181
1182 </div>
1183 <h2 id="GL_get_proc_address">GL_get_proc_address</h2>
1184 <div id="GL_get_proc_address_CONTENT">
1185 <pre> $proc_address = SDL::Video::GL_get_proc_address( $proc );
1186
1187 </pre>
1188 <p>Returns the address of the GL function proc, or NULL if the function is not found. If the GL library is loaded at runtime, with
1189 <a href="#GL_load_library">SDL::Video::GL_load_library</a>, then all GL functions must be retrieved this way. Usually this is used to retrieve function
1190 pointers to OpenGL extensions. Note that this function needs an OpenGL context to function properly, so it should be called after
1191 <a href="#set_video_mode">SDL::Video::set_video_mode</a> has been called (with the <code>SDL_OPENGL</code> flag).</p>
1192 <p>It returns undef if the function is not found.</p>
1193 <p>Example:</p>
1194 <pre> my $has_multitexture = 1;
1195
1196  # Get function pointer
1197  $gl_active_texture_ARB_ptr = SDL::Video::GL_get_proc_address(&quot;glActiveTextureARB&quot;);
1198
1199  # Check for a valid function ptr
1200  unless($gl_active_texture_ARB_ptr)
1201  {
1202      printf( STDERR &quot;Multitexture Extensions not present.\n&quot; );
1203      $has_multitexture = 0;
1204  }
1205
1206  $gl_active_texture_ARB_ptr(GL_TEXTURE0_ARB) if $has_multitexture;
1207
1208 </pre>
1209
1210 </div>
1211 <h2 id="GL_get_attribute">GL_get_attribute</h2>
1212 <div id="GL_get_attribute_CONTENT">
1213 <pre> $value = SDL::Video::GL_get_attribute( $attr );
1214
1215 </pre>
1216 <p>It returns SDL/OpenGL attribute <code>attr</code>. This is useful after a call to <a href="#set_video_mode">SDL::Video::set_video_mode</a> to check whether your
1217 attributes have been set as you expected.
1218 <code>SDL::Video::GL_get_attribute</code> returns <code>undef</code> if the attribute is not found.</p>
1219 <p>Example:</p>
1220 <pre> print( SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE) );
1221
1222 </pre>
1223
1224 </div>
1225 <h2 id="GL_set_attribute">GL_set_attribute</h2>
1226 <div id="GL_set_attribute_CONTENT">
1227 <pre> $set_attr = SDL::Video::GL_set_attribute( $attr, $value );
1228
1229 </pre>
1230 <p>This function sets the given OpenGL attribute <code>attr</code> to <code>value</code>. The requested attributes will take effect after a call to
1231 <a href="#set_video_mode">SDL::Video::set_video_mode</a>.
1232 You should use <code>SDL::Video::GL_get_attribute|/GL_get_attribute</code> to check the values after a <a href="#set_video_mode">SDL::Video::set_video_mode</a> call,
1233 since the values obtained can differ from the requested ones.</p>
1234 <p>Available attributes:</p>
1235 <ul>
1236                 <li><code>SDL_GL_RED_SIZE</code>        </li>
1237                 <li><code>SDL_GL_GREEN_SIZE</code>      </li>
1238                 <li><code>SDL_GL_BLUE_SIZE</code>       </li>
1239                 <li><code>SDL_GL_ALPHA_SIZE</code>      </li>
1240                 <li><code>SDL_GL_BUFFER_SIZE</code>     </li>
1241                 <li><code>SDL_GL_DOUBLEBUFFER</code>    </li>
1242                 <li><code>SDL_GL_DEPTH_SIZE</code>      </li>
1243                 <li><code>SDL_GL_STENCIL_SIZE</code>    </li>
1244                 <li><code>SDL_GL_ACCUM_RED_SIZE</code>  </li>
1245                 <li><code>SDL_GL_ACCUM_GREEN_SIZE</code>        </li>
1246                 <li><code>SDL_GL_ACCUM_BLUE_SIZE</code> </li>
1247                 <li><code>SDL_GL_ACCUM_ALPHA_SIZE</code>        </li>
1248                 <li><code>SDL_GL_STEREO</code>  </li>
1249                 <li><code>SDL_GL_MULTISAMPLEBUFFERS</code>      </li>
1250                 <li><code>SDL_GL_MULTISAMPLESAMPLES</code>      </li>
1251                 <li><code>SDL_GL_ACCELERATED_VISUAL</code>      </li>
1252                 <li><code>SDL_GL_SWAP_CONTROL</code></li>
1253 </ul>
1254
1255 <p><code>GL_set_attribute</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
1256 <p><strong>Note</strong>: The <code>SDL_DOUBLEBUF</code> flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled
1257 or disabled using the <code>SDL_GL_DOUBLEBUFFER</code> attribute. </p>
1258 <p>Example:</p>
1259 <pre> SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE, 5);
1260
1261 </pre>
1262
1263 </div>
1264 <h2 id="GL_swap_buffers">GL_swap_buffers</h2>
1265 <div id="GL_swap_buffers_CONTENT">
1266 <pre> SDL::Video::GL_swap_buffers();
1267
1268 </pre>
1269 <p>Swap the OpenGL buffers, if double-buffering is supported.
1270 <code>SDL::Video::GL_swap_buffers</code> doesn't returns any value.</p>
1271
1272 </div>
1273 <h1 id="Video_Overlay_Functions">Video Overlay Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
1274 <div id="Video_Overlay_Functions_CONTENT">
1275 <p>see <a href="SDL-Overlay.html">SDL::Overlay</a> </p>
1276
1277 </div>
1278 <h2 id="lock_YUV_overlay">lock_YUV_overlay</h2>
1279 <div id="lock_YUV_overlay_CONTENT">
1280 <pre> $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );
1281
1282 </pre>
1283 <p>Much the same as <a href="#lock_surface">SDL::Video::lock_surface</a>, <code>lock_YUV_overlay</code> locks the overlay for direct access to pixel data.
1284 It returns <code>0</code> on success or <code>-1</code> on error.</p>
1285
1286 </div>
1287 <h2 id="unlock_YUV_overlay">unlock_YUV_overlay</h2>
1288 <div id="unlock_YUV_overlay_CONTENT">
1289 <pre> SDL::Video::unlock_YUV_overlay( $overlay );
1290
1291 </pre>
1292 <p>The opposite to <a href="#sock_YUV_overlay">SDL::Video::lock_YUV_overlay</a>. Unlocks a previously locked overlay. An overlay must be unlocked before it
1293 can be displayed. <code>unlock_YUV_overlay</code> does not return anything.</p>
1294
1295 </div>
1296 <h2 id="display_YUV_overlay">display_YUV_overlay</h2>
1297 <div id="display_YUV_overlay_CONTENT">
1298 <pre> $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );
1299
1300 </pre>
1301 <p>Blit the overlay to the display surface specified when the overlay was created. The <a href="SDL-Rect.html">SDL::Rect</a> structure, <code>dstrect</code>, specifies a rectangle
1302 on the display where the overlay is drawn. The <code>x</code> and <code>y</code> fields of <code>dstrect</code> specify the upper left location in display coordinates.
1303 The overlay is scaled (independently in x and y dimensions) to the size specified by dstrect, and is <code>optimized</code> for 2x scaling</p>
1304 <p>It returns <code>0</code> on success or <code>-1</code> on error.</p>
1305
1306 </div>
1307 <h1 id="Window_Management_Functions">Window Management Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
1308 <div id="Window_Management_Functions_CONTENT">
1309
1310 </div>
1311 <h2 id="wm_set_caption">wm_set_caption</h2>
1312 <div id="wm_set_caption_CONTENT">
1313 <pre> SDL::Video::wm_set_caption( $title, $icon );
1314
1315 </pre>
1316 <p>Sets the title-bar and icon name of the display window.</p>
1317 <p><code>title</code> is a UTF-8 encoded null-terminated string which will serve as the window title (the text at the top of the window). The function
1318 does not change the string. You may free the string after the function returns.</p>
1319 <p><code>icon</code> is a UTF-8 encoded null-terminated string which will serve as the iconified window title (the text which is displayed in the menu
1320 bar or desktop when the window is minimized). As with title this string may be freed after the function returns. </p>
1321 <p>Example:</p>
1322 <pre> use SDL;
1323  use SDL::Video;
1324  use SDL::Surface;
1325
1326  SDL::init(SDL_INIT_VIDEO);
1327
1328  my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1329
1330  SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1331
1332  sleep(2);
1333
1334  SDL::quit;
1335
1336 </pre>
1337
1338 </div>
1339 <h2 id="wm_get_caption">wm_get_caption</h2>
1340 <div id="wm_get_caption_CONTENT">
1341 <pre> SDL::Video::wm_get_caption( $title, $icon );
1342
1343 </pre>
1344 <p>Retrieves the title-bar and icon name of the display window.</p>
1345 <p>Example:</p>
1346 <pre> use SDL;
1347  use SDL::Video;
1348  use SDL::Surface;
1349
1350  SDL::init(SDL_INIT_VIDEO);
1351
1352  my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1353
1354  SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1355
1356  my ($title, $icon) = @{ SDL::Video::wm_get_caption() };
1357
1358  printf( &quot;title is '%s' and icon is '%s'\n&quot;, $title, $icon );
1359
1360  SDL::quit;
1361
1362 </pre>
1363
1364 </div>
1365 <h2 id="wm_set_icon">wm_set_icon</h2>
1366 <div id="wm_set_icon_CONTENT">
1367 <pre> SDL::Video::wm_set_icon( $icon );
1368
1369 </pre>
1370 <p>Sets the icon for the display window. Win32 icons must be 32x32.</p>
1371 <p>This function must be called before the first call to <a href="#set_video_mode">SDL::Video::set_video_mode</a>. Note that this means <a href="SDL-Image.html">SDL::Image</a>
1372 cannot be used.</p>
1373 <p>The shape is determined by the colorkey or alpha channel of the icon, if any. If neither of those are present, the icon is made opaque
1374 (no transparency).</p>
1375 <p>Example:</p>
1376 <pre> SDL::Video::wm_set_icon(SDL::Video::load_BMP(&quot;icon.bmp&quot;));
1377
1378 </pre>
1379 <p>Another option, if your icon image does not have a colorkey set, is to use the SDL::Video::set_color_key to set the transparency.</p>
1380 <p>Example:</p>
1381 <pre> my $image = SDL::Video::load_BMP(&quot;icon.bmp&quot;);
1382
1383  my colorkey = SDL::Video::map_RGB($image-&gt;format, 255, 0, 255); # specify the color that will be transparent
1384
1385  SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);
1386
1387  SDL::Video::wm_set_icon($image);
1388
1389 </pre>
1390
1391 </div>
1392 <h2 id="wm_grab_input">wm_grab_input</h2>
1393 <div id="wm_grab_input_CONTENT">
1394 <pre> $grab_mode = SDL::Video::wm_grab_input($mode);
1395
1396 </pre>
1397 <p>Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application,
1398 and not interpreted by a window manager, if any.</p>
1399 <p>When mode is <code>SDL_GRAB_QUERY</code> the grab mode is not changed, but the current grab mode is returned.</p>
1400 <p><code>mode</code> and the return value of <code>wm_grab_input</code> can be one of the following:</p>
1401 <ul>
1402                 <li><code>SDL_GRAB_QUERY</code> </li>
1403                 <li><code>SDL_GRAB_OFF</code>   </li>
1404                 <li><code>SDL_GRAB_ON</code></li>
1405 </ul>
1406
1407
1408 </div>
1409 <h2 id="wm_iconify_window">wm_iconify_window</h2>
1410 <div id="wm_iconify_window_CONTENT">
1411 <pre> $iconify_window = SDL::Video::wm_iconify_window();
1412
1413 </pre>
1414 <p>If the application is running in a window managed environment SDL attempts to iconify/minimise it. If <code>wm_iconify_window</code> is successful,
1415 the application will receive a <code>SDL_APPACTIVE</code> loss event (see Application visibility events at <a href="SDL-Event.html">SDL::Event</a>).</p>
1416 <p>Returns non-zero on success or 0 if iconification is not supported or was refused by the window manager. </p>
1417 <p>Example:</p>
1418 <pre> use SDL;
1419  use SDL::Video;
1420  use SDL::Surface;
1421
1422  SDL::init(SDL_INIT_VIDEO);
1423
1424  my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1425
1426  sleep(2);
1427
1428  SDL::Video::wm_iconify_window();
1429
1430  sleep(2);
1431
1432  SDL::quit;
1433
1434 </pre>
1435
1436 </div>
1437 <h2 id="wm_toggle_fullscreen">wm_toggle_fullscreen</h2>
1438 <div id="wm_toggle_fullscreen_CONTENT">
1439 <pre> $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
1440
1441 </pre>
1442 <p>Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support
1443 is experimental).</p>
1444
1445 </div>
1446 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1447 <div id="AUTHOR_CONTENT">
1448 <p>magnet, Tobias Leich (FROGGS)</p>
1449
1450 </div>
1451 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
1452 <div id="SEE_ALSO_CONTENT">
1453
1454 </div>
1455 <h2 id="Category_Objects">Category Objects</h2>
1456 <div id="Category_Objects_CONTENT">
1457 <p><a href="SDL-Surface.html">SDL::Surface</a>, <a href="SDL-Overlay.html">SDL::Overlay</a>, <a href="SDL-Color.html">SDL::Color</a>,
1458 <a href="SDL-Rect.html">SDL::Rect</a>, <a href="SDL-Palette.html">SDL::Palette</a>, <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>,
1459 <a href="SDL-VideoInfo.html">SDL::VideoInfo</a></p>
1460
1461 </div>
1462 </div>