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