3 <h3 id="TOP">Index</h3>
5 <ul><li><a href="#NAME">NAME</a></li>
6 <li><a href="#CATEGORY">CATEGORY</a></li>
7 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
8 <li><a href="#CONSTANTS">CONSTANTS</a></li>
9 <li><a href="#Core_Functions">Core Functions</a>
10 <ul><li><a href="#get_video_surface">get_video_surface</a></li>
11 <li><a href="#get_video_info">get_video_info</a></li>
12 <li><a href="#video_driver_name">video_driver_name</a></li>
13 <li><a href="#list_modes">list_modes</a></li>
14 <li><a href="#video_mode_ok">video_mode_ok</a></li>
15 <li><a href="#set_video_mode">set_video_mode</a>
16 <ul><li><a href="#List_of_avalaibles_flags">List of avalaibles flags</a></li>
19 <li><a href="#convert_surface">convert_surface</a></li>
20 <li><a href="#display_format">display_format</a></li>
21 <li><a href="#display_format_alpha">display_format_alpha</a></li>
22 <li><a href="#load_BMP">load_BMP</a></li>
23 <li><a href="#save_BMP">save_BMP</a></li>
24 <li><a href="#set_color_key">set_color_key</a></li>
25 <li><a href="#set_alpha">set_alpha</a></li>
26 <li><a href="#fill_rect">fill_rect</a></li>
29 <li><a href="#Surface_Locking_and_Unlocking">Surface Locking and Unlocking</a>
30 <ul><li><a href="#lock_surface">lock_surface</a></li>
31 <li><a href="#unlock_surface">unlock_surface</a></li>
32 <li><a href="#MUSTLOCK">MUSTLOCK</a></li>
35 <li><a href="#Screen_Updating_Functions">Screen Updating Functions</a>
36 <ul><li><a href="#set_clip_rect">set_clip_rect</a></li>
37 <li><a href="#get_clip_rect">get_clip_rect</a></li>
38 <li><a href="#blit_surface">blit_surface</a></li>
39 <li><a href="#update_rect">update_rect</a></li>
40 <li><a href="#update_rects">update_rects</a></li>
41 <li><a href="#flip">flip</a></li>
44 <li><a href="#Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</a>
45 <ul><li><a href="#set_colors">set_colors</a></li>
46 <li><a href="#set_palette">set_palette</a></li>
47 <li><a href="#set_gamma">set_gamma</a></li>
48 <li><a href="#get_gamma_ramp">get_gamma_ramp</a></li>
49 <li><a href="#set_gamma_ramp">set_gamma_ramp</a></li>
50 <li><a href="#map_RGB">map_RGB</a></li>
51 <li><a href="#map_RGBA">map_RGBA</a></li>
52 <li><a href="#get_RGB">get_RGB</a></li>
53 <li><a href="#get_RGBA">get_RGBA</a></li>
56 <li><a href="#GL_Methods">GL Methods</a>
57 <ul><li><a href="#GL_load_library">GL_load_library</a></li>
58 <li><a href="#GL_get_proc_address">GL_get_proc_address</a></li>
59 <li><a href="#GL_get_attribute">GL_get_attribute</a></li>
60 <li><a href="#GL_set_attribute">GL_set_attribute</a></li>
61 <li><a href="#GL_swap_buffers">GL_swap_buffers</a></li>
64 <li><a href="#Video_Overlay_Functions">Video Overlay Functions</a>
65 <ul><li><a href="#lock_YUV_overlay">lock_YUV_overlay</a></li>
66 <li><a href="#unlock_YUV_overlay">unlock_YUV_overlay</a></li>
67 <li><a href="#display_YUV_overlay">display_YUV_overlay</a></li>
70 <li><a href="#Window_Management_Functions">Window Management Functions</a>
71 <ul><li><a href="#wm_set_caption">wm_set_caption</a></li>
72 <li><a href="#wm_get_caption">wm_get_caption</a></li>
73 <li><a href="#wm_set_icon">wm_set_icon</a></li>
74 <li><a href="#wm_grab_input">wm_grab_input</a></li>
75 <li><a href="#wm_iconify_window">wm_iconify_window</a></li>
76 <li><a href="#wm_toggle_fullscreen">wm_toggle_fullscreen</a></li>
79 <li><a href="#AUTHOR">AUTHOR</a></li>
80 <li><a href="#SEE_ALSO">SEE ALSO</a>
81 <ul><li><a href="#Category_Objects">Category Objects</a>
86 <!-- INDEX END --><a href="assets/Video.png" target="_blank"><img src="assets/Video.png" style="height: 160px" alt="Video.png"/></a><a href="assets/Video_lock_surface.png" target="_blank"><img src="assets/Video_lock_surface.png" style="height: 160px" alt="Video_lock_surface.png"/></a><hr />
88 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
89 <div id="NAME_CONTENT">
90 <p>SDL::Video - Bindings to the video category in SDL API</p>
93 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
94 <div id="CATEGORY_CONTENT">
98 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
99 <div id="SYNOPSIS_CONTENT">
100 <pre> use SDL ':init';
101 use SDL::Video ':all';
105 # the size of the window box or the screen resolution if fullscreen
106 my $screen_width = 800;
107 my $screen_height = 600;
109 SDL::init(SDL_INIT_VIDEO);
112 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_ANYFORMAT);
114 # drawing something somewhere
115 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
116 SDL::Video::fill_rect($screen_surface,
117 SDL::Rect->new($screen_width / 4, $screen_height / 4,
118 $screen_width / 2, $screen_height / 2), $mapped_color);
120 # update an area on the screen so its visible
121 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
123 sleep(5); # just to have time to see it
130 <h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
131 <div id="CONSTANTS_CONTENT">
132 <p>The constants are exported by default. You can avoid this by doing:</p>
133 <pre> use SDL::Video ();
136 <p>and access them directly:</p>
137 <pre> SDL::Video::SDL_SWSURFACE;
140 <p>or by choosing the export tags below:</p>
141 <p>Export tag: ':surface'</p>
142 <pre> SDL_ASYNCBLIT Use asynchronous blit if possible
143 SDL_SWSURFACE Stored in the system memory.
144 SDL_HWSURFACE Stored in video memory
147 <p>Export tag: ':video'</p>
148 <pre> SDL_ANYFORMAT Allow any pixel-format
149 SDL_HWPALETTE Have an exclusive palette
150 SDL_DOUBLEBUF Double buffered
151 SDL_FULLSCREEN Full screen surface
152 SDL_OPENGL Have an OpenGL context
153 SDL_OPENGLBLIT Support OpenGL blitting.
154 NOTE: This option is kept for compatibility only, and is not recommended for new code.
155 SDL_RESIZABLE Resizable surface
156 SDL_NOFRAME No window caption or edge frame
157 SDL_HWACCEL Use Hardware acceleration blit
158 SDL_SRCCOLORKEY Use colorkey blitting
159 SDL_RLEACCELOK Private flag
160 SDL_RLEACCEL Accelerated colorkey blitting with RLE
161 SDL_SRCALPHA Use alpha blending blit
162 SDL_PREALLOC Use preallocated memory
165 <p>Export tag ':overlay'</p>
166 <pre> SDL_YV12_OVERLAY Planar mode: Y + V + U (3 planes)
167 SDL_IYUV_OVERLAY Planar mode: Y + U + V (3 planes)
168 SDL_YUY2_OVERLAY Packed mode: Y0+U0+Y1+V0 (1 plane)
169 SDL_UYVY_OVERLAY Packed mode: U0+Y0+V0+Y1 (1 plane)
170 SDL_YVYU_OVERLAY Packed mode: Y0+V0+Y1+U0 (1 plane)
173 <p>Export tag ':palette'</p>
174 <pre> SDL_LOGPAL Logical palette, which controls how blits are mapped to/from the surface
175 SDL_PHYSPAL Physical palette, which controls how pixels look on the screen
178 <p>Export tag ':grab'</p>
182 SDL_GRAB_FULLSCREEN Used interally
185 <p>Export tag ':gl'</p>
186 <pre> SDL_GL_RED_SIZE
194 SDL_GL_ACCUM_RED_SIZE
195 SDL_GL_ACCUM_GREEN_SIZE
196 SDL_GL_ACCUM_BLUE_SIZE
197 SDL_GL_ACCUM_ALPHA_SIZE
199 SDL_GL_MULTISAMPLEBUFFERS
200 SDL_GL_MULTISAMPLESAMPLES
201 SDL_GL_ACCELERATED_VISUAL
207 <h1 id="Core_Functions">Core Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
208 <div id="Core_Functions_CONTENT">
211 <h2 id="get_video_surface">get_video_surface</h2>
212 <div id="get_video_surface_CONTENT">
213 <pre> my $surface = SDL::Video::get_video_surface();
216 <p>This function returns the current display <a href="SDL-Surface.html">SDL::Surface</a>. If SDL is doing format conversion on the display surface, this
217 function returns the publicly visible surface, not the real video surface.</p>
219 <pre> # somewhere after you set the video mode
220 my $surface = SDL::Video::get_video_surface();
222 printf( "our screen is %d pixels wide and %d pixels high\n", $surface->w, $surface->h );
227 <h2 id="get_video_info">get_video_info</h2>
228 <div id="get_video_info_CONTENT">
229 <pre> my $video_info = SDL::Video::get_video_info();
232 <p>This function returns a read-only <a href="SDL-VideoInfo.html">SDL::VideoInfo</a> containing information about the video hardware. If it is called before
233 <a href="#set_video_mode">SDL::Video::set_video_mode</a>, the <code>vfmt</code> member of the returned structure will contain the pixel
234 format of the <strong>best</strong> video mode. </p>
239 use SDL::PixelFormat;
241 SDL::init(SDL_INIT_VIDEO);
243 my $video_info = SDL::Video::get_video_info();
245 printf( "we can have %dbits per pixel\n", $video_info->vfmt->BitsPerPixel );
252 <h2 id="video_driver_name">video_driver_name</h2>
253 <div id="video_driver_name_CONTENT">
254 <pre> my $driver_name = SDL::Video::video_driver_name();
257 <p>This function will return the name of the initialized video driver up to a maximum of 1024 characters. The driver name is a simple one
258 word identifier like <code>"x11"</code>, <code>"windib"</code> or <code>"directx"</code>.</p>
259 <p><strong>Note</strong>: Some platforms allow selection of the video driver through the <code>SDL_VIDEODRIVER</code> environment variable. </p>
264 SDL::init(SDL_INIT_VIDEO);
266 print SDL::Video::video_driver_name() . "\n";
273 <h2 id="list_modes">list_modes</h2>
274 <div id="list_modes_CONTENT">
275 <pre> my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
278 <p>Returns a ref to an array of available screen dimensions for the given format and video flags,
279 or it return undef if no modes are available.</p>
284 use SDL::PixelFormat;
287 SDL::init(SDL_INIT_VIDEO);
289 my $video_info = SDL::Video::get_video_info();
291 my @modes = @{ SDL::Video::list_modes($video_info->vfmt, SDL_NOFRAME) };
295 print("available modes:\n");
296 foreach my $index ( @modes )
298 printf("%03d: %d x %d\n", $index, $modes[$index]->w, $modes[$index]->h );
303 printf("%s video modes available\n", $modes[0]);
311 <h2 id="video_mode_ok">video_mode_ok</h2>
312 <div id="video_mode_ok_CONTENT">
313 <pre> my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
316 <p>This function is used to check whether the requested mode is supported by the current video device. The arguments passed to this function
317 are the same as those you would pass to <a href="#set_video_mode">SDL::Video::set_video_mode</a>.
318 It returns <code>0</code> if the mode is not supported at all, otherwise the suggested <code>bpp</code>.</p>
323 SDL::init(SDL_INIT_VIDEO);
325 my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
327 unless($video_mode_ok)
329 printf( "this video mode is not supported\n" );
337 <h2 id="set_video_mode">set_video_mode</h2>
338 <div id="set_video_mode_CONTENT">
339 <pre> my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
342 <p>Sets up a video mode with the specified width, height, bits-per-pixel and flags.
343 <code>set_video_mode</code> returns a <a href="SDL-Surface.html">SDL::Surface</a> on success otherwise it returns undef on error, the error message is retrieved
344 using <code>SDL::get_error</code>.</p>
347 <h3 id="List_of_avalaibles_flags">List of avalaibles flags</h3>
348 <div id="List_of_avalaibles_flags_CONTENT">
350 <dt><code>SDL_SWSURFACE</code></dt>
352 <p>Create the video surface in system memory</p>
354 <dt><code>SDL_HWSURFACE</code></dt>
356 <p>Create the video surface in video memory</p>
358 <dt><code>SDL_ASYNCBLIT</code></dt>
360 <p>Enables the use of asynchronous updates of the display surface.
361 This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.</p>
363 <dt><code>SDL_ANYFORMAT</code></dt>
365 <p>Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface.
366 Passing <code>SDL_ANYFORMAT</code> prevents this and causes SDL to use the video surface, regardless of its pixel depth.</p>
368 <dt><code>SDL_HWPALETTE</code></dt>
370 <p>Give SDL exclusive palette access. Without this flag you may not always get the colors you request with SDL::set_colors or SDL::set_palette.</p>
372 <dt><code>SDL_DOUBLEBUF</code></dt>
374 <p>Enable hardware double buffering; only valid with <code>SDL_HWSURFACE</code>. Calling <a href="#flip">SDL::Video::flip</a> will flip the buffers and update
376 All drawing will take place on the surface that is not displayed at the moment.
377 If double buffering could not be enabled then <a href="#flip">SDL::Video::flip</a> will just perform a
378 <a href="#update_rect">SDL::Video::update_rect</a> on the entire screen.</p>
380 <dt><code>SDL_FULLSCREEN</code></dt>
382 <p>SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason),
383 the next higher resolution will be used and the display window centered on a black background.</p>
385 <dt><code>SDL_OPENGL</code></dt>
387 <p>Create an OpenGL rendering context. You should have previously set OpenGL video attributes with
388 <a href="#GL_set_attribute">SDL::Video::GL_set_attribute</a>.</p>
390 <dt><code>SDL_OPENGLBLIT</code></dt>
392 <p>Create an OpenGL rendering context, like above, but allow normal blitting operations.
393 The screen (2D) surface may have an alpha channel, and SDL::update_rects must be used for updating changes to the screen surface.
394 NOTE: This option is kept for compatibility only, and will be removed in next versions. Is not recommended for new code.</p>
396 <dt><code>SDL_RESIZABLE</code></dt>
398 <p>Create a resizable window.
399 When the window is resized by the user a <code>SDL_VIDEORESIZE</code> event is generated and
400 <a href="#set_video_mode">SDL::Video::set_video_mode</a> can be called again with the new size.</p>
402 <dt><code>SDL_NOFRAME</code></dt>
404 <p>If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration.
405 Fullscreen modes automatically have this flag set.</p>
408 <p><strong>Note 1</strong>: Use <code>SDL_SWSURFACE</code> if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate.
409 When you use hardware surfaces (by passing the flag <code>SDL_HWSURFACE</code> as parameter), SDL copies the surfaces from video memory to system memory
410 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,
411 but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface
412 when using <code>SDL_FULLSCREEN</code>. The <code>SDL_HWSURFACE</code> flag is best used when the surfaces you'll be blitting can also be stored in video memory.</p>
413 <p><strong>Note 2</strong>: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment
414 variables <code>SDL_VIDEO_CENTERED=center</code> or <code>SDL_VIDEO_WINDOW_POS=x,y</code>. You can also set them via <code>SDL::putenv</code>.</p>
415 <p><strong>Note 3</strong>: This function should be called in the main thread of your application.</p>
416 <p><strong>User note 1</strong>: Some have found that enabling OpenGL attributes like <code>SDL_GL_STENCIL_SIZE</code> (the stencil buffer size) before the video mode has
417 been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.</p>
418 <p><strong>User note 2</strong>: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL
419 initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux,
420 however, it works fine, and the initialization code only needs to be executed after the first call to
421 <a href="#set_video_mode">SDL::Video::set_video_mode</a> (although there is no harm in executing the initialization code after
422 each call to <a href="#set_video_mode">SDL::Video::set_video_mode</a>, for example for a multiplatform application). </p>
425 <h2 id="convert_surface">convert_surface</h2>
426 <div id="convert_surface_CONTENT">
427 <pre> $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
430 <p>Creates a new SDL::surface of the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>, and then copies and maps the given surface to it.
431 It is also useful for making a copy of a surface.</p>
432 <p>The flags parameter is passed to <a href="SDL-Surface.html">SDL::Surface</a><code>->new</code> and has those semantics.
433 This function is used internally by <a href="#display_format">SDL::Video::display_format</a>.
434 This function can only be called after <code>SDL::init</code>. </p>
435 <p>it returns a <a href="SDL-Surface.html">SDL::Surface</a> on success or <code>undef</code> on error.</p>
438 <h2 id="display_format">display_format</h2>
439 <div id="display_format_CONTENT">
440 <pre> $new_surface = SDL::Video::display_format( $surface );
443 <p>This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast
444 blitting onto the display surface. It calls <a href="#conver_surface">SDL::Video::convert_surface</a>.</p>
445 <p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
447 <p>If you want an alpha channel, see <code>SDL::Video::display_format_alpha</code>.
449 <p><strong>Note</strong>: Remember to use a different variable for the returned surface, otherwise you have a memory leak, since the original surface isn't freed. </p>
452 <h2 id="display_format_alpha">display_format_alpha</h2>
453 <div id="display_format_alpha_CONTENT">
454 <pre> $new_surface = SDL::Video::display_format_alpha( $surface );
457 <p>This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer plus an alpha channel,
458 suitable for fast blitting onto the display surface. It calls <a href="#convert_surface">SDL::Video::convert_surface</a>.</p>
459 <p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
461 <p>This function can be used to convert a colorkey to an alpha channel, if the <code>SDL_SRCCOLORKEY</code> flag is set on the surface. The generated
462 surface will then be transparent (alpha=0) where the pixels match the colorkey, and opaque (alpha=255) elsewhere.</p>
463 <p><strong>Note</strong>: The video surface must be initialised using <a href="#set_video_mode">SDL::Video::set_video_mode</a> before this function is called, or it will
467 <h2 id="load_BMP">load_BMP</h2>
468 <div id="load_BMP_CONTENT">
469 <pre> $surface = SDL::Video::load_BMP( $filename );
472 <p>Loads a <a href="SDL-Surface.html">SDL::Surface</a> from a named Windows BMP file.
473 <code>SDL::Video::load_BMP</code> returns a <a href="SDL-Surface.html">SDL::Surface</a> on success or <code>undef</code> on error.</p>
474 <p><strong>Note</strong>: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect). </p>
480 my $screen_width = 640;
481 my $screen_height = 480;
483 SDL::init(SDL_INIT_VIDEO);
485 my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
487 my $picture = SDL::Video::load_BMP('test.bmp');
489 die(SDL::get_error) unless $picture;
491 my $rect = SDL::Rect->new(0, 0, $screen_width, $screen_height);
493 SDL::Video::blit_surface( $picture, SDL::Rect->new(0, 0, $picture->w, $picture->h),
494 $screen, SDL::Rect->new(0, 0, $screen->w, $screen->h) );
496 SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
505 <h2 id="save_BMP">save_BMP</h2>
506 <div id="save_BMP_CONTENT">
507 <pre> $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
510 <p>Saves the given <a href="SDL-Surface.html">SDL::Surface</a> as a Windows BMP file named filename.
511 it returns 0 on success or -1 on error.</p>
514 <h2 id="set_color_key">set_color_key</h2>
515 <div id="set_color_key_CONTENT">
516 <pre> $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
519 <p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
520 <p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match
522 The key must be of the same pixel format as the surface, <a href="#map_RGB">SDL::Video::map_RGB</a> is often useful for obtaining an acceptable value.
523 If flag is <code>SDL_SRCCOLORKEY</code> then key is the transparent pixel value in the source image of a blit.</p>
524 <p>If <code>flag</code> is OR'd with <code>SDL_RLEACCEL</code> then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface.
525 The surface will actually be encoded for RLE acceleration the first time <a href="#blit_surface">SDL::Video::blit_surface</a> or
526 <code>SDL::Video::display_format|/display_format</code> is called on the surface.
527 If <code>flag</code> is <code>0</code>, this function clears any current color key. </p>
528 <p><code>SDL::Video::set_color_key</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
531 <h2 id="set_alpha">set_alpha</h2>
532 <div id="set_alpha_CONTENT">
533 <pre> $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
536 <p><code>set_alpha</code> is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
537 <p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
538 flags is used to specify whether alpha blending should be used ( <code>SDL_SRCALPHA</code> ) and whether the surface should use RLE acceleration for
539 blitting ( <code>SDL_RLEACCEL</code> ).
540 flags can be an OR'd combination of these two options, one of these options or <code>0</code>.
541 If <code>SDL_SRCALPHA</code> is not passed as a flag then all alpha information is ignored when blitting the surface.
542 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
543 still be accelerated with <code>SDL_RLEACCEL</code>.</p>
544 <p><strong>Note</strong>: The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.</p>
545 <p>Alpha affects surface blitting in the following ways: </p>
547 <dt>RGBA->RGB with <code>SDL_SRCALPHA</code></dt>
549 <p>The source is alpha-blended with the destination, using the alpha channel.
550 SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
552 <dt>RGBA->RGB without <code>SDL_SRCALPHA</code></dt>
554 <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
555 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
557 <dt>RGB->RGBA with <code>SDL_SRCALPHA</code></dt>
559 <p>The source is alpha-blended with the destination using the per-surface alpha value.
560 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
561 The alpha channel of the copied pixels is set to opaque.</p>
563 <dt>RGB->RGBA without <code>SDL_SRCALPHA</code></dt>
565 <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
566 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
568 <dt>RGBA->RGBA with <code>SDL_SRCALPHA</code></dt>
570 <p>The source is alpha-blended with the destination using the source alpha channel.
571 The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
573 <dt>RGBA->RGBA without <code>SDL_SRCALPHA</code></dt>
575 <p>The RGBA data is copied to the destination surface.
576 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
578 <dt>RGB->RGB with <code>SDL_SRCALPHA</code></dt>
580 <p>The source is alpha-blended with the destination using the per-surface alpha value.
581 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
583 <dt>RGB->RGB without <code>SDL_SRCALPHA</code></dt>
585 <p>The RGB data is copied from the source.
586 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
589 <p><strong>Note</strong>: When blitting, the presence or absence of <code>SDL_SRCALPHA</code> is relevant only on the source surface, not the destination.
590 <strong>Note</strong>: Note that RGBA->RGBA blits (with <code>SDL_SRCALPHA</code> set) keep the alpha of the destination surface. This means that you cannot compose
591 two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask.</p>
592 <p><strong>Note</strong>: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available. </p>
593 <p><code>SDL::Video::set_alpha</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
596 <h2 id="fill_rect">fill_rect</h2>
597 <div id="fill_rect_CONTENT">
598 <pre> $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );
601 <p>This function performs a fast fill of the given <a href="SDL-Rect.html">SDL::Rect</a> with the given <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>. If dest_rect is NULL, the whole surface
602 will be filled with color.</p>
603 <p>The color should be a pixel of the format used by the surface, and can be generated by the <a href="#map_RGB">SDL::Video::map_RGB</a> or
604 <code>SDL::Video::map_RGBA|/map_RGBA</code> functions. If the color value contains an alpha value then the destination is simply "filled" with that
605 alpha information, no blending takes place.</p>
606 <p>If there is a clip rectangle set on the destination (set via <a href="#set_clip_rect">SDL::Video::set_clip_rect</a>), then this function will clip based
607 on the intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually
609 <p>If you call this on the video surface (ie: the value of <a href="#get_video_surface">SDL::Video::get_video_surface</a>) you may have to update the video
610 surface to see the result. This can happen if you are using a shadowed surface that is not double buffered in Windows XP using build 1.2.9. </p>
611 <p><code>SDL::Video::fill_rect</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
612 <p>for an example see <a href="#SYNOPSIS">SYNOPSIS</a>.</p>
615 <h1 id="Surface_Locking_and_Unlocking">Surface Locking and Unlocking</h1><p><a href="#TOP" class="toplink">Top</a></p>
616 <div id="Surface_Locking_and_Unlocking_CONTEN">
619 <h2 id="lock_surface">lock_surface</h2>
620 <div id="lock_surface_CONTENT">
621 <pre> int SDL::Video::lock_surface( $surface );
624 <p><code>SDL::Video::lock_surface</code> sets up the given <a href="SDL-Surface.html">SDL::Surface</a> for directly accessing the pixels.
625 Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to ( <code>surface-</code>set_pixels>) and read from ( <code>surface-</code>get_pixels> ),
626 using the pixel format stored in <code>surface-</code>format>.
627 Once you are done accessing the surface, you should use <a href="#unlock_surface">SDL::Video::unlock_surface</a> to release the lock.</p>
628 <p>Not all surfaces require locking. If <a href="#MUSTLOCK">SDL::Video::MUSTLOCK</a> evaluates to <code>0</code>, then reading and writing pixels to the surface can
629 be performed at any time, and the pixel format of the surface will not change.
630 No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
631 <code>SDL::Video::lock_surface</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
632 <p><strong>Note</strong>: Since SDL 1.1.8, the surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have
633 a matching unlock.</p>
648 my($x, $y, $color) = @_;
649 my $lineoffset = $y * ($screen->pitch / 4);
650 $screen->set_pixels( $lineoffset+ $x, $color);
655 if( SDL::Video::MUSTLOCK( $screen) )
657 return if (SDL::Video::lock_surface( $screen ) < 0)
660 my $ticks = SDL::get_ticks();
661 my ($i, $y, $yofs, $ofs) = (0,0,0,0);
662 for ($i = 0; $i < 480; $i++)
664 for (my $j = 0, $ofs = $yofs; $j < 640; $j++, $ofs++)
666 $screen->set_pixels( $ofs, ( $i * $i + $j * $j + $ticks ) );
668 $yofs += $screen->pitch / 4;
671 putpixel(10, 10, 0xff0000);
672 putpixel(11, 10, 0xff0000);
673 putpixel(10, 11, 0xff0000);
674 putpixel(11, 11, 0xff0000);
676 SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
678 SDL::Video::update_rect($screen, 0, 0, 640, 480);
685 carp 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) < 0);
687 $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
689 carp 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
695 my $event = SDL::Event->new();
697 while( SDL::Events::poll_event($event) )
699 my $type = $event->type;
700 return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
702 SDL::Events::pump_events();
713 <h2 id="unlock_surface">unlock_surface</h2>
714 <div id="unlock_surface_CONTENT">
715 <pre> SDL::Video::unlock_surface( $surface );
718 <p>Surfaces that were previously locked using <a href="#lock_sruface">SDL::Video::lock_surface</a> must be unlocked with <code>SDL::Video::unlock_surface</code>.
719 Surfaces should be unlocked as soon as possible.
720 <code>SDL::Video::unlock_surface</code> doesn't return anything.</p>
721 <p><strong>Note</strong>: Since 1.1.8, the surface locks are recursive. See <a href="#lock_sruface">SDL::Video::lock_surface</a> for more information. </p>
724 <h2 id="MUSTLOCK">MUSTLOCK</h2>
725 <div id="MUSTLOCK_CONTENT">
726 <pre> int SDL::Video::MUSTLOCK( $surface );
729 <p><code>MUSTLOCK</code> returns <code>0</code> if the surface does not have to be locked during pixel operations, otherwise <code>1</code>.</p>
732 <h1 id="Screen_Updating_Functions">Screen Updating Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
733 <div id="Screen_Updating_Functions_CONTENT">
736 <h2 id="set_clip_rect">set_clip_rect</h2>
737 <div id="set_clip_rect_CONTENT">
738 <pre> SDL::Video::set_clip_rect( $surface, $rect );
741 <p>Sets the clipping rectangle for the given <a href="SDL-Surface.html">SDL::Surface</a>. When this surface is the destination of a blit, only the area within the clip
742 rectangle will be drawn into.
743 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
744 outside the edges of the surface.
745 If rect is NULL the clipping rectangle will be set to the full size of the surface.
746 <code>SDL::Video::set_clip_rect</code> doesn't returns anything.</p>
749 <h2 id="get_clip_rect">get_clip_rect</h2>
750 <div id="get_clip_rect_CONTENT">
751 <pre> SDL::Video::get_clip_rect( $surface, $rect );
754 <p>Gets the clipping rectangle for the given <a href="SDL-Surface.html">SDL::Surface</a>. When this surface is the destination of a blit, only the area within the clip
755 rectangle is drawn into.
756 The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
757 <code>SDL::Video::get_clip_rect</code> doesn't returns anything;</p>
763 my $screen_width = 640;
764 my $screen_height = 480;
766 SDL::init(SDL_INIT_VIDEO);
768 my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
770 my $rect = SDL::Rect->new(0, 0, 0, 0);
772 SDL::Video::get_clip_rect($screen, $rect);
774 printf( "rect is %d, %d, %d, %d\n", $rect->x, $rect->y, $rect->w, $rect->h);
781 <h2 id="blit_surface">blit_surface</h2>
782 <div id="blit_surface_CONTENT">
783 <pre> SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
786 <p>This performs a fast blit from the given source <a href="SDL-Surface.html">SDL::Surface</a> to the given destination <a href="SDL-Surface.html">SDL::Surface</a>.
787 The width and height in <code>src_surface</code> determine the size of the copied rectangle. Only the position is used in the <code>dst_rect</code>
788 (the width and height are ignored). Blits with negative <code>dst_rect</code> coordinates will be clipped properly.
789 If <code>src_rect</code> is NULL, the entire surface is copied. If <code>dst_rect</code> is NULL, then the destination position (upper left corner) is (0, 0).
790 The final blit rectangle is saved in <code>dst_rect</code> after all clipping is performed (<code>src_rect</code> is not modified).
791 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,
792 but this is not the case with <code>SDL::Video::blit_surface</code>. Like most surface manipulation functions in SDL, it should not be used together
794 <p>The results of blitting operations vary greatly depending on whether <code>SDL_SRCALPHA</code> is set or not. See <a href="#set_alpha">SDL::Video::set_alpha</a>
795 for an explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
796 <code>SDL::Video::blit_surface</code> doesn't returns anything.</p>
797 <p>For an example see <a href="#load_BMP">SDL::Video::load_BMP</a>.</p>
800 <h2 id="update_rect">update_rect</h2>
801 <div id="update_rect_CONTENT">
802 <pre> update_rect( $surface, $left, $top, $width, $height );
805 <p>Makes sure the given area is updated on the given screen.
806 The rectangle must be confined within the screen boundaries because there's no clipping.
807 update_rect doesn't returns any value.</p>
808 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface">SDL::Video::lock_surface</a></p>
809 <p><strong>Note2</strong>: If <code>x</code>, <code>y</code>, <code>width</code> and <code>height</code> are all equal to 0, <code>update_rect</code> will update the entire screen. </p>
810 <p>For an example see <a href="#SYNOPSIS">SYNOPSIS</a></p>
813 <h2 id="update_rects">update_rects</h2>
814 <div id="update_rects_CONTENT">
815 <pre> update_rects( $surface, @rects );
818 <p>Makes sure the given list of rectangles is updated on the given screen.
819 The rectangle must be confined within the screen boundaries because there's no clipping.
820 <code>update_rects</code> doesn't returns any value.</p>
821 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface">SDL::Video::lock_surface</a>.</p>
828 # the size of the window box or the screen resolution if fullscreen
829 my $screen_width = 800;
830 my $screen_height = 600;
832 SDL::init(SDL_INIT_VIDEO);
835 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
837 # drawing the whole screen blue
838 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
839 SDL::Video::fill_rect($screen_surface,
840 SDL::Rect->new(0, 0, $screen_width, $screen_height),
844 push(@rects, SDL::Rect->new(200, 0, 400, 600));
845 push(@rects, SDL::Rect->new( 0, 150, 800, 300));
847 # updating parts of the screen (should look like a cross)
848 SDL::Video::update_rects($screen_surface, @rects);
857 <h2 id="flip">flip</h2>
858 <div id="flip_CONTENT">
859 <pre> $flip = SDL::Video::flip( $screen_surface );
862 <p>On hardware that supports double-buffering, this function sets up a flip and returns.
863 The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return.
864 On hardware that doesn't support double-buffering or if <code>SDL_SWSURFACE</code> was set, this is equivalent to calling
865 <code>SDL::Video::update_rect( $screen, 0, 0, 0, 0 )</code>.</p>
866 <p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by
867 restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in
868 contrast to a full screen software mode.</p>
869 <p>The <code>SDL_DOUBLEBUF</code> flag must have been passed to <a href="#set_video_mode">SDL::Video::set_video_mode</a>, when setting the video mode for this function
870 to perform hardware flipping.</p>
871 <p><code>flip</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
872 <p><strong>Note</strong>: If you want to swap the buffers of an initialized OpenGL context, use the function <a href="#GL_swap_buffers">SDL::Video::GL_swap_buffers</a>
879 # the size of the window box or the screen resolution if fullscreen
880 my $screen_width = 800;
881 my $screen_height = 600;
883 SDL::init(SDL_INIT_VIDEO);
886 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
888 # do some video operations here
890 # doing page flipping
891 unless( SDL::Video::flip($screen_surface) == 0 )
893 printf( STDERR "failed to swap buffers: %s\n", SDL::get_error() );
901 <h1 id="Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
902 <div id="Palette_Color_and_Pixel_Functions_CO">
905 <h2 id="set_colors">set_colors</h2>
906 <div id="set_colors_CONTENT">
907 <pre> $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
910 <p>Sets a portion of the colormap for the given 8-bit surface. </p>
911 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
912 If <code>SDL_HWPALETTE</code> was set in <a href="#set_video_mode">SDL::Video::set_video_mode</a> flags, <code>SDL::Video::set_colors</code> will always return 1, and the
913 palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
914 The color components of a <a href="SDL-Color.html">SDL::Color</a> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.
915 Palettized (8-bit) screen surfaces with the <code>SDL_HWPALETTE</code> flag have two palettes, a logical palette that is used for mapping blits to/from
916 the surface and a physical palette (that determines how the hardware will map the colors to the display).
917 <code>SDL::Video::set_colors</code> modifies both palettes (if present), and is equivalent to calling <a href="#set_palette">SDL::Video::set_palette</a> with the
918 flags set to ( <code>SDL_LOGPAL | SDL_PHYSPAL</code> ). </p>
919 <p>If <code>surface</code> is not a palettized surface, this function does nothing, returning 0.
920 If all of the colors were set as passed to <code>SDL::Video::set_colors</code>, it will return 1.
921 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
922 actual color palette.</p>
925 <h2 id="set_palette">set_palette</h2>
926 <div id="set_palette_CONTENT">
927 <pre> $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
930 <p>Sets a portion of the palette for the given 8-bit surface.</p>
931 <p>Palettized (8-bit) screen surfaces with the <code>SDL_HWPALETTE</code> flag have two palettes, a logical palette that is used for mapping blits to/from
932 the surface and a physical palette (that determines how the hardware will map the colors to the display).
933 Non screen surfaces have a logical palette only. <a href="#blit">SDL::Video::blit</a> always uses the logical palette when blitting surfaces (if it has to
934 convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various
935 special color effects (e.g., screen fading, color flashes, screen dimming).</p>
936 <p>This function can modify either the logical or physical palette by specifying <code>SDL_LOGPAL</code> or <code>SDL_PHYSPAL</code> the in the flags parameter.</p>
937 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
938 If <code>SDL_HWPALETTE</code> was set in <a href="#set_video_mode">SDL::Video::set_video_mode</a> flags, <code>SDL::Video::set_palette</code> will always return 1, and the
939 palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
940 The color components of a <code>SDL::Color</code> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
941 <p>If <code>surface</code> is not a palettized surface, this function does nothing, returning <code>0</code>. If all of the colors were set as passed to <code>set_palette</code>,
942 it will return <code>1</code>. If not all the color entries were set exactly as given, it will return <code>0</code>, and you should look at the surface palette
943 to determine the actual color palette.</p>
946 <h2 id="set_gamma">set_gamma</h2>
947 <div id="set_gamma_CONTENT">
948 <pre> $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
951 <p>Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen.
952 A gamma value of 1.0 is identity (i.e., no adjustment is made).</p>
953 <p>This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment
954 with SDL::set_gamma_ramp.</p>
955 <p><strong>Note</strong>: Not all display hardware is able to change gamma.</p>
956 <p><code>SDL::Video::set_gamma</code> returns <code>-1</code> on error.</p>
957 <p><strong>Warning</strong>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
963 use Time::HiRes qw( usleep );
965 # the size of the window box or the screen resolution if fullscreen
966 my $screen_width = 800;
967 my $screen_height = 600;
969 SDL::init(SDL_INIT_VIDEO);
972 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
974 # drawing something somewhere
975 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 128, 128, 128); # gray
976 SDL::Video::fill_rect($screen_surface,
977 SDL::Rect->new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
980 # update the whole screen
981 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
987 SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
993 SDL::Video::set_gamma( $_ / 20, 1, 1 );
997 SDL::Video::set_gamma( 1, 1, 1 );
1006 <h2 id="get_gamma_ramp">get_gamma_ramp</h2>
1007 <div id="get_gamma_ramp_CONTENT">
1008 <pre> $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
1011 <p>Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
1012 <code>SDL::Video::get_gamma_ramp</code> returns -1 on error.</p>
1016 SDL::init(SDL_INIT_VIDEO);
1018 my (@red, @green, @blue);
1020 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1024 print( "an error occoured" );
1028 printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
1029 printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
1030 printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
1038 <h2 id="set_gamma_ramp">set_gamma_ramp</h2>
1039 <div id="set_gamma_ramp_CONTENT">
1040 <pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
1043 <p>Sets the gamma lookup tables for the display for each color component. Each table is an array ref of 256 Uint16 values, representing a
1044 mapping between the input and output for that channel.
1045 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.
1046 You may pass NULL to any of the channels to leave them unchanged.</p>
1047 <p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter
1048 with <a href="#set_gamma">SDL::Video::set_gamma</a>.</p>
1049 <p>Not all display hardware is able to change gamma.
1050 <code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
1055 SDL::init(SDL_INIT_VIDEO);
1057 my (@red, @green, @blue);
1059 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1063 $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
1065 $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1069 print( "an error occoured" );
1073 printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
1074 printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
1075 printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
1083 <h2 id="map_RGB">map_RGB</h2>
1084 <div id="map_RGB_CONTENT">
1085 <pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
1088 <p>Maps the RGB color value to the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a> and returns the pixel value as a 32-bit int.
1089 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1090 If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
1091 <p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
1092 If the <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>'s bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored
1093 (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
1096 use SDL::PixelFormat;
1099 SDL::init(SDL_INIT_VIDEO);
1101 my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
1102 # ^-- 16 bits per pixel
1108 printf( "for 24bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b);
1110 my $_16bit = SDL::Video::map_RGB( $screen_surface->format, $r, $g, $b );
1112 # 16bpp is 5 bits red, 6 bits green and 5 bits blue
1113 # we will obtain the values for each color and calculating them back to 24/32bit color system
1114 ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface->format, $_16bit ) };
1116 printf( "for 16bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b );
1118 # so color #9CDC67 becomes #9CDF63
1125 <h2 id="map_RGBA">map_RGBA</h2>
1126 <div id="map_RGBA_CONTENT">
1127 <pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b, $a );
1130 <p>Maps the RGBA color value to the specified <a href="SDL-PixelFormat.html">SDL::PixelFormat</a> and returns the pixel value as a 32-bit int.
1131 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1132 If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette). </p>
1133 <p>A pixel value best approximating the given RGBA color value for a given pixel format.
1134 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.,
1135 with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
1138 <h2 id="get_RGB">get_RGB</h2>
1139 <div id="get_RGB_CONTENT">
1140 <pre> $rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel );
1143 <p>Returns RGB values from a pixel in the specified pixel format. The pixel is an integer (e.g. 16bit RGB565, 24/32bit RGB888).
1144 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1145 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
1146 <p>For an example see <a href="#map_RGB">SDL::Video::map_RGB</a>.</p>
1149 <h2 id="get_RGBA">get_RGBA</h2>
1150 <div id="get_RGBA_CONTENT">
1151 <pre> $rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel );
1154 <p>Gets RGBA values from a pixel in the specified pixel format.
1155 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1156 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
1157 <p>If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque). </p>
1160 <h1 id="GL_Methods">GL Methods</h1><p><a href="#TOP" class="toplink">Top</a></p>
1161 <div id="GL_Methods_CONTENT">
1164 <h2 id="GL_load_library">GL_load_library</h2>
1165 <div id="GL_load_library_CONTENT">
1166 <pre> $gl_load_lib = SDL::Video::GL_load_library( 'path/to/static/glfunctions.dll' );
1169 <p>If you wish, you may load the OpenGL library from the given path at runtime, this must be done before
1170 <a href="#set_video_mode">SDL::Video::set_video_mode</a> is called. You must then use <a href="#GL_get_proc_address">SDL::Video::GL_get_proc_address</a> to retrieve
1171 function pointers to GL functions. </p>
1172 <p><code>GL_load_library</code> returns <code>0</code> on success or <code>-1</code> or error.</p>
1175 <h2 id="GL_get_proc_address">GL_get_proc_address</h2>
1176 <div id="GL_get_proc_address_CONTENT">
1177 <pre> $proc_address = SDL::Video::GL_get_proc_address( $proc );
1180 <p>Returns the address of the GL function proc, or NULL if the function is not found. If the GL library is loaded at runtime, with
1181 <a href="#GL_load_library">SDL::Video::GL_load_library</a>, then all GL functions must be retrieved this way. Usually this is used to retrieve function
1182 pointers to OpenGL extensions. Note that this function needs an OpenGL context to function properly, so it should be called after
1183 <a href="#set_video_mode">SDL::Video::set_video_mode</a> has been called (with the <code>SDL_OPENGL</code> flag).</p>
1184 <p>It returns undef if the function is not found.</p>
1186 <pre> my $has_multitexture = 1;
1188 # Get function pointer
1189 $gl_active_texture_ARB_ptr = SDL::Video::GL_get_proc_address("glActiveTextureARB");
1191 # Check for a valid function ptr
1192 unless($gl_active_texture_ARB_ptr)
1194 printf( STDERR "Multitexture Extensions not present.\n" );
1195 $has_multitexture = 0;
1198 $gl_active_texture_ARB_ptr(GL_TEXTURE0_ARB) if $has_multitexture;
1203 <h2 id="GL_get_attribute">GL_get_attribute</h2>
1204 <div id="GL_get_attribute_CONTENT">
1205 <pre> $value = SDL::Video::GL_get_attribute( $attr );
1208 <p>It returns SDL/OpenGL attribute <code>attr</code>. This is useful after a call to <a href="#set_video_mode">SDL::Video::set_video_mode</a> to check whether your
1209 attributes have been set as you expected.
1210 <code>SDL::Video::GL_get_attribute</code> returns <code>undef</code> if the attribute is not found.</p>
1212 <pre> print( SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE) );
1217 <h2 id="GL_set_attribute">GL_set_attribute</h2>
1218 <div id="GL_set_attribute_CONTENT">
1219 <pre> $set_attr = SDL::Video::GL_set_attribute( $attr, $value );
1222 <p>This function sets the given OpenGL attribute <code>attr</code> to <code>value</code>. The requested attributes will take effect after a call to
1223 <a href="#set_video_mode">SDL::Video::set_video_mode</a>.
1224 You should use <code>SDL::Video::GL_get_attribute|/GL_get_attribute</code> to check the values after a <a href="#set_video_mode">SDL::Video::set_video_mode</a> call,
1225 since the values obtained can differ from the requested ones.</p>
1226 <p>Available attributes:</p>
1228 <li><code>SDL_GL_RED_SIZE</code> </li>
1229 <li><code>SDL_GL_GREEN_SIZE</code> </li>
1230 <li><code>SDL_GL_BLUE_SIZE</code> </li>
1231 <li><code>SDL_GL_ALPHA_SIZE</code> </li>
1232 <li><code>SDL_GL_BUFFER_SIZE</code> </li>
1233 <li><code>SDL_GL_DOUBLEBUFFER</code> </li>
1234 <li><code>SDL_GL_DEPTH_SIZE</code> </li>
1235 <li><code>SDL_GL_STENCIL_SIZE</code> </li>
1236 <li><code>SDL_GL_ACCUM_RED_SIZE</code> </li>
1237 <li><code>SDL_GL_ACCUM_GREEN_SIZE</code> </li>
1238 <li><code>SDL_GL_ACCUM_BLUE_SIZE</code> </li>
1239 <li><code>SDL_GL_ACCUM_ALPHA_SIZE</code> </li>
1240 <li><code>SDL_GL_STEREO</code> </li>
1241 <li><code>SDL_GL_MULTISAMPLEBUFFERS</code> </li>
1242 <li><code>SDL_GL_MULTISAMPLESAMPLES</code> </li>
1243 <li><code>SDL_GL_ACCELERATED_VISUAL</code> </li>
1244 <li><code>SDL_GL_SWAP_CONTROL</code></li>
1247 <p><code>GL_set_attribute</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
1248 <p><strong>Note</strong>: The <code>SDL_DOUBLEBUF</code> flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled
1249 or disabled using the <code>SDL_GL_DOUBLEBUFFER</code> attribute. </p>
1251 <pre> SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE, 5);
1256 <h2 id="GL_swap_buffers">GL_swap_buffers</h2>
1257 <div id="GL_swap_buffers_CONTENT">
1258 <pre> SDL::Video::GL_swap_buffers();
1261 <p>Swap the OpenGL buffers, if double-buffering is supported.
1262 <code>SDL::Video::GL_swap_buffers</code> doesn't returns any value.</p>
1265 <h1 id="Video_Overlay_Functions">Video Overlay Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
1266 <div id="Video_Overlay_Functions_CONTENT">
1267 <p>see <a href="SDL-Overlay.html">SDL::Overlay</a> </p>
1270 <h2 id="lock_YUV_overlay">lock_YUV_overlay</h2>
1271 <div id="lock_YUV_overlay_CONTENT">
1272 <pre> $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );
1275 <p>Much the same as <a href="#lock_surface">SDL::Video::lock_surface</a>, <code>lock_YUV_overlay</code> locks the overlay for direct access to pixel data.
1276 It returns <code>0</code> on success or <code>-1</code> on error.</p>
1279 <h2 id="unlock_YUV_overlay">unlock_YUV_overlay</h2>
1280 <div id="unlock_YUV_overlay_CONTENT">
1281 <pre> SDL::Video::unlock_YUV_overlay( $overlay );
1284 <p>The opposite to <a href="#sock_YUV_overlay">SDL::Video::lock_YUV_overlay</a>. Unlocks a previously locked overlay. An overlay must be unlocked before it
1285 can be displayed. <code>unlock_YUV_overlay</code> does not return anything.</p>
1288 <h2 id="display_YUV_overlay">display_YUV_overlay</h2>
1289 <div id="display_YUV_overlay_CONTENT">
1290 <pre> $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );
1293 <p>Blit the overlay to the display surface specified when the overlay was created. The <a href="SDL-Rect.html">SDL::Rect</a> structure, <code>dstrect</code>, specifies a rectangle
1294 on the display where the overlay is drawn. The <code>x</code> and <code>y</code> fields of <code>dstrect</code> specify the upper left location in display coordinates.
1295 The overlay is scaled (independently in x and y dimensions) to the size specified by dstrect, and is <code>optimized</code> for 2x scaling</p>
1296 <p>It returns <code>0</code> on success or <code>-1</code> on error.</p>
1299 <h1 id="Window_Management_Functions">Window Management Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
1300 <div id="Window_Management_Functions_CONTENT">
1303 <h2 id="wm_set_caption">wm_set_caption</h2>
1304 <div id="wm_set_caption_CONTENT">
1305 <pre> SDL::Video::wm_set_caption( $title, $icon );
1308 <p>Sets the title-bar and icon name of the display window.</p>
1309 <p><code>title</code> is a UTF-8 encoded null-terminated string which will serve as the window title (the text at the top of the window). The function
1310 does not change the string. You may free the string after the function returns.</p>
1311 <p><code>icon</code> is a UTF-8 encoded null-terminated string which will serve as the iconified window title (the text which is displayed in the menu
1312 bar or desktop when the window is minimized). As with title this string may be freed after the function returns. </p>
1318 SDL::init(SDL_INIT_VIDEO);
1320 my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1322 SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1331 <h2 id="wm_get_caption">wm_get_caption</h2>
1332 <div id="wm_get_caption_CONTENT">
1333 <pre> SDL::Video::wm_get_caption( $title, $icon );
1336 <p>Retrieves the title-bar and icon name of the display window.</p>
1342 SDL::init(SDL_INIT_VIDEO);
1344 my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1346 SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1348 my ($title, $icon) = @{ SDL::Video::wm_get_caption() };
1350 printf( "title is '%s' and icon is '%s'\n", $title, $icon );
1357 <h2 id="wm_set_icon">wm_set_icon</h2>
1358 <div id="wm_set_icon_CONTENT">
1359 <pre> SDL::Video::wm_set_icon( $icon );
1362 <p>Sets the icon for the display window. Win32 icons must be 32x32.</p>
1363 <p>This function must be called before the first call to <a href="#set_video_mode">SDL::Video::set_video_mode</a>. Note that this means <a href="SDL-Image.html">SDL::Image</a>
1365 <p>The shape is determined by the colorkey or alpha channel of the icon, if any. If neither of those are present, the icon is made opaque
1366 (no transparency).</p>
1368 <pre> SDL::Video::wm_set_icon(SDL::Video::load_BMP("icon.bmp"));
1371 <p>Another option, if your icon image does not have a colorkey set, is to use the SDL::Video::set_color_key to set the transparency.</p>
1373 <pre> my $image = SDL::Video::load_BMP("icon.bmp");
1375 my colorkey = SDL::Video::map_RGB($image->format, 255, 0, 255); # specify the color that will be transparent
1377 SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);
1379 SDL::Video::wm_set_icon($image);
1384 <h2 id="wm_grab_input">wm_grab_input</h2>
1385 <div id="wm_grab_input_CONTENT">
1386 <pre> $grab_mode = SDL::Video::wm_grab_input($mode);
1389 <p>Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application,
1390 and not interpreted by a window manager, if any.</p>
1391 <p>When mode is <code>SDL_GRAB_QUERY</code> the grab mode is not changed, but the current grab mode is returned.</p>
1392 <p><code>mode</code> and the return value of <code>wm_grab_input</code> can be one of the following:</p>
1394 <li><code>SDL_GRAB_QUERY</code> </li>
1395 <li><code>SDL_GRAB_OFF</code> </li>
1396 <li><code>SDL_GRAB_ON</code></li>
1401 <h2 id="wm_iconify_window">wm_iconify_window</h2>
1402 <div id="wm_iconify_window_CONTENT">
1403 <pre> $iconify_window = SDL::Video::wm_iconify_window();
1406 <p>If the application is running in a window managed environment SDL attempts to iconify/minimise it. If <code>wm_iconify_window</code> is successful,
1407 the application will receive a <code>SDL_APPACTIVE</code> loss event (see Application visibility events at <a href="SDL-Event.html">SDL::Event</a>).</p>
1408 <p>Returns non-zero on success or 0 if iconification is not supported or was refused by the window manager. </p>
1414 SDL::init(SDL_INIT_VIDEO);
1416 my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1420 SDL::Video::wm_iconify_window();
1429 <h2 id="wm_toggle_fullscreen">wm_toggle_fullscreen</h2>
1430 <div id="wm_toggle_fullscreen_CONTENT">
1431 <pre> $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
1434 <p>Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support
1435 is experimental).</p>
1438 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1439 <div id="AUTHOR_CONTENT">
1440 <p>magnet, Tobias Leich (FROGGS)</p>
1443 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
1444 <div id="SEE_ALSO_CONTENT">
1447 <h2 id="Category_Objects">Category Objects</h2>
1448 <div id="Category_Objects_CONTENT">
1449 <p><a href="SDL-Surface.html">SDL::Surface</a>, <a href="SDL-Overlay.html">SDL::Overlay</a>, <a href="SDL-Color.html">SDL::Color</a>,
1450 <a href="SDL-Rect.html">SDL::Rect</a>, <a href="SDL-Palette.html">SDL::Palette</a>, <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>,
1451 <a href="SDL-VideoInfo.html">SDL::VideoInfo</a></p>