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