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