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="#Core_Functions">Core Functions</a>
9 <ul><li><a href="#get_video_surface">get_video_surface</a></li>
10 <li><a href="#get_video_info">get_video_info</a></li>
11 <li><a href="#video_driver_name">video_driver_name</a></li>
12 <li><a href="#list_modes_formats_flags">list_modes(formats,flags)</a></li>
13 <li><a href="#video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</a></li>
14 <li><a href="#set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</a>
15 <ul><li><a href="#List_of_avalaibles_flags">List of avalaibles flags</a></li>
18 <li><a href="#update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</a></li>
19 <li><a href="#update_rects_surface_rects">update_rects(surface,rects) </a></li>
20 <li><a href="#flip_surface">flip(surface)</a></li>
21 <li><a href="#set_colors_surface_start_colors">set_colors(surface,start,colors)</a></li>
22 <li><a href="#set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</a></li>
23 <li><a href="#set_gamma_r_g_b">set_gamma(r,g,b)</a></li>
24 <li><a href="#get_gamma_ramp_rt_gt_bt">get_gamma_ramp(rt,gt,bt)</a></li>
25 <li><a href="#set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</a></li>
26 <li><a href="#map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</a></li>
27 <li><a href="#map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</a></li>
28 <li><a href="#get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</a></li>
29 <li><a href="#get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</a></li>
30 <li><a href="#lock_surface_surface">lock_surface(surface)</a></li>
31 <li><a href="#unlock_surface_surface">unlock_surface(surface)</a></li>
32 <li><a href="#convert_surface_surface_format_flags">convert_surface(surface,format,flags)</a></li>
33 <li><a href="#display_format">display_format</a></li>
34 <li><a href="#display_format_alpha">display_format_alpha</a></li>
35 <li><a href="#load_BMP_filename">load_BMP(filename)</a></li>
36 <li><a href="#save_BMP_surface_filename">save_BMP(surface,filename)</a></li>
37 <li><a href="#set_color_key_surface_flag_key">set_color_key(surface,flag,key)</a></li>
38 <li><a href="#set_alpha_surface_flag_key">set_alpha(surface,flag,key)</a></li>
39 <li><a href="#set_clip_rect_surface_rect">set_clip_rect(surface,rect)</a></li>
40 <li><a href="#get_clip_rect_surface_rect">get_clip_rect(surface,rect)</a></li>
41 <li><a href="#blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</a></li>
42 <li><a href="#fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</a></li>
45 <li><a href="#GL_Methods">GL Methods</a>
46 <ul><li><a href="#GL_load_library_path">GL_load_library(path)</a></li>
47 <li><a href="#GL_get_proc_address_proc">GL_get_proc_address(proc)</a></li>
48 <li><a href="#GL_get_attribute_attr">GL_get_attribute(attr)</a></li>
49 <li><a href="#GL_set_attribute_attr_value">GL_set_attribute(attr,value)</a></li>
50 <li><a href="#GL_swap_buffers">GL_swap_buffers</a></li>
51 <li><a href="#GL_attr_to_be_coded">GL_attr *** to be coded</a></li>
54 <li><a href="#a_href_SDL_Overlay_html_SDL_Overlay_"><a href="/SDL-Overlay.html">SDL::Overlay</a> Functions</a>
55 <ul><li><a href="#lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</a></li>
56 <li><a href="#unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</a></li>
57 <li><a href="#display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</a></li>
60 <li><a href="#SEE_ALSO">SEE ALSO</a>
61 <ul><li><a href="#Category_Objects">Category Objects</a>
66 <!-- INDEX END --><a href="assets/Video.png" target="_blank"><img src="assets/Video.png" style="height: 160px" alt="Video.png"/></a><hr />
68 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
69 <div id="NAME_CONTENT">
70 <p>SDL::Video - Bindings to the video category in SDL API</p>
73 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
74 <div id="CATEGORY_CONTENT">
78 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
79 <div id="SYNOPSIS_CONTENT">
85 # the size of the window box or the screen resolution if fullscreen
86 my $screen_width = 800;
87 my $screen_height = 600;
89 SDL::init(SDL_INIT_VIDEO);
92 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
94 # drawing something somewhere
95 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
96 SDL::Video::fill_rect($screen_surface,
97 SDL::Rect->new($screen_width / 4, $screen_height / 4,
98 $screen_width / 2, $screen_height / 2), $mapped_color);
100 # update an area on the screen so its visible
101 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
103 sleep(5); # just to have time to see it
110 <h1 id="Core_Functions">Core Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
111 <div id="Core_Functions_CONTENT">
114 <h2 id="get_video_surface">get_video_surface</h2>
115 <div id="get_video_surface_CONTENT">
116 <pre> my $surface = SDL::Video::get_video_surface();
119 <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
120 function returns the publicly visible surface, not the real video surface.</p>
122 <pre> # somewhere after you set the video mode
123 my $surface = SDL::Video::get_video_surface();
125 printf( "our screen is %d pixels wide and %d pixels high\n", $surface->w, $surface->h );
130 <h2 id="get_video_info">get_video_info</h2>
131 <div id="get_video_info_CONTENT">
132 <pre> my $video_info = SDL::Video::get_video_info();
135 <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
136 <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>, the <code>vfmt</code> member of the returned structure will contain the pixel
137 format of the <strong>best</strong> video mode. </p>
142 use SDL::PixelFormat;
144 SDL::init(SDL_INIT_VIDEO);
146 my $video_info = SDL::Video::get_video_info();
148 printf( "we can have %dbits per pixel\n", $video_info->vfmt->BitsPerPixel );
155 <h2 id="video_driver_name">video_driver_name</h2>
156 <div id="video_driver_name_CONTENT">
157 <pre> my $driver_name = SDL::Video::video_driver_name();
160 <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
161 word identifier like <code>"x11"</code>, <code>"windib"</code> or <code>"directx"</code>.</p>
162 <p><strong>Note</strong>: Some platforms allow selection of the video driver through the <code>SDL_VIDEODRIVER</code> environment variable. </p>
167 SDL::init(SDL_INIT_VIDEO);
169 print SDL::Video::video_driver_name() . "\n";
176 <h2 id="list_modes_formats_flags">list_modes(formats,flags)</h2>
177 <div id="list_modes_formats_flags_CONTENT">
178 <pre> my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
181 <p>Returns a ref to an array of available screen dimensions for the given format and video flags,
182 or it return undef if no modes are available.</p>
187 use SDL::PixelFormat;
190 SDL::init(SDL_INIT_VIDEO);
192 my $video_info = SDL::Video::get_video_info();
194 my @modes = @{ SDL::Video::list_modes($video_info->vfmt, SDL_NOFRAME) };
198 print("available modes:\n");
199 foreach my $index ( @modes )
201 printf("%03d: %d x %d\n", $index, $modes[$index]->w, $modes[$index]->h );
206 printf("%s video modes available\n", $modes[0]);
214 <h2 id="video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</h2>
215 <div id="video_mode_ok_width_height_bpp_flags-2">
216 <pre> my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
219 <p>This function is used to check whether the requested mode is supported by the current video device. The arguments passed to this function
220 are the same as those you would pass to <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>.
221 It returns <code>0</code> if the mode is not supported at all, otherwise the suggested <code>bpp</code>.</p>
226 SDL::init(SDL_INIT_VIDEO);
228 my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
230 unless($video_mode_ok)
232 printf("this video mode ist not supported\n" );
243 <h2 id="set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</h2>
244 <div id="set_video_mode_width_height_bpp_flag-2">
245 <pre> my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
248 <p>Sets up a video mode with the specified width, height, bits-per-pixel and flags.
249 <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
250 using <code>SDL::get_error</code>.</p>
253 <h3 id="List_of_avalaibles_flags">List of avalaibles flags</h3>
254 <div id="List_of_avalaibles_flags_CONTENT">
256 <dt><code>SDL_SWSURFACE</code></dt>
258 <p>Create the video surface in system memory</p>
260 <dt><code>SDL_HWSURFACE</code></dt>
262 <p>Create the video surface in video memory</p>
264 <dt><code>SDL_ASYNCBLIT</code></dt>
266 <p>Enables the use of asynchronous updates of the display surface.
267 This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.</p>
269 <dt><code>SDL_ANYFORMAT</code></dt>
271 <p>Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface.
272 Passing <code>SDL_ANYFORMAT</code> prevents this and causes SDL to use the video surface, regardless of its pixel depth.</p>
274 <dt><code>SDL_HWPALETTE</code></dt>
276 <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>
278 <dt><code>SDL_DOUBLEBUF</code></dt>
280 <p>Enable hardware double buffering; only valid with <code>SDL_HWSURFACE</code>. Calling <a href="#flip_surface">SDL::Video::flip</a> will flip the buffers and update
282 All drawing will take place on the surface that is not displayed at the moment.
283 If double buffering could not be enabled then <a href="#flip_surface">SDL::Video::flip</a> will just perform a
284 <a href="#update_rect_surface_x_y_width_height">SDL::Video::update_rect</a> on the entire screen.</p>
286 <dt><code>SDL_FULLSCREEN</code></dt>
288 <p>SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason),
289 the next higher resolution will be used and the display window centered on a black background.</p>
291 <dt><code>SDL_OPENGL</code></dt>
293 <p>Create an OpenGL rendering context. You should have previously set OpenGL video attributes with
294 <a href="#GL_set_attribute_attr_value">SDL::Video::GL_set_attribute</a>.</p>
296 <dt><code>SDL_OPENGLBLIT</code></dt>
298 <p>Create an OpenGL rendering context, like above, but allow normal blitting operations.
299 The screen (2D) surface may have an alpha channel, and SDL::update_rects must be used for updating changes to the screen surface.
300 NOTE: This option is kept for compatibility only, and will be removed in next versions. Is not recommended for new code.</p>
302 <dt><code>SDL_RESIZABLE</code></dt>
304 <p>Create a resizable window.
305 When the window is resized by the user a <code>SDL_VIDEORESIZE</code> event is generated and
306 <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a> can be called again with the new size.</p>
308 <dt><code>SDL_NOFRAME</code></dt>
310 <p>If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration.
311 Fullscreen modes automatically have this flag set.</p>
314 <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.
315 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
316 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,
317 but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface
318 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>
319 <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
320 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>
321 <p><strong>Note 3</strong>: This function should be called in the main thread of your application.</p>
322 <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
323 been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.</p>
324 <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
325 initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux,
326 however, it works fine, and the initialization code only needs to be executed after the first call to
327 <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a> (although there is no harm in executing the initialization code after
328 each call to <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>, for example for a multiplatform application). </p>
331 <h2 id="update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</h2>
332 <div id="update_rect_surface_x_y_width_height-2">
333 <pre> update_rect( $surface, $left, $top, $width, $height );
336 <p>Makes sure the given area is updated on the given screen.
337 The rectangle must be confined within the screen boundaries because there's no clipping.
338 update_rect doesn't returns any value.</p>
339 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface_surface">SDL::Video::lock_surface</a></p>
340 <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>
341 <p>For an example see <a href="#SYNOPSIS">SYNOPSIS</a></p>
344 <h2 id="update_rects_surface_rects">update_rects(surface,rects) </h2>
345 <div id="update_rects_surface_rects_CONTENT">
346 <pre> update_rects( $surface, @rects );
349 <p>Makes sure the given list of rectangles is updated on the given screen.
350 The rectangle must be confined within the screen boundaries because there's no clipping.
351 <code>update_rects</code> doesn't returns any value.</p>
352 <p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface_surface">SDL::Video::lock_surface</a>.</p>
359 # the size of the window box or the screen resolution if fullscreen
360 my $screen_width = 800;
361 my $screen_height = 600;
363 SDL::init(SDL_INIT_VIDEO);
366 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
368 # drawing the whole screen blue
369 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
370 SDL::Video::fill_rect($screen_surface,
371 SDL::Rect->new(0, 0, $screen_width, $screen_height),
375 push(@rects, SDL::Rect->new(200, 0, 400, 600));
376 push(@rects, SDL::Rect->new( 0, 150, 800, 300));
378 # updating parts of the screen (should look like a cross)
379 SDL::Video::update_rects($screen_surface, @rects);
388 <h2 id="flip_surface">flip(surface)</h2>
389 <div id="flip_surface_CONTENT">
390 <pre> $flip = SDL::Video::flip( $screen_surface );
393 <p>On hardware that supports double-buffering, this function sets up a flip and returns.
394 The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return.
395 On hardware that doesn't support double-buffering or if <code>SDL_SWSURFACE</code> was set, this is equivalent to calling
396 <code>SDL::Video::update_rect( $screen, 0, 0, 0, 0 )</code>.</p>
397 <p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by
398 restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in
399 contrast to a full screen software mode.</p>
400 <p>The <code>SDL_DOUBLEBUF</code> flag must have been passed to <code>SDL::Video::set_video_mode</code>, when setting the video mode for this function to
401 perform hardware flipping.</p>
402 <p><code>flip</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
403 <p><strong>Note</strong>: If you want to swap the buffers of an initialized OpenGL context, use the function <code>SDL::Video::GL_swap_buffers</code> instead. </p>
409 # the size of the window box or the screen resolution if fullscreen
410 my $screen_width = 800;
411 my $screen_height = 600;
413 SDL::init(SDL_INIT_VIDEO);
416 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
418 # do some video operations here
420 # doing page flipping
421 unless( SDL::Video::flip($screen_surface) == 0 )
423 printf( STDERR "failed to swap buffers: %s\n", SDL::get_error() );
431 <h2 id="set_colors_surface_start_colors">set_colors(surface,start,colors)</h2>
432 <div id="set_colors_surface_start_colors_CONT">
433 <pre> $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
436 <p>Sets a portion of the colormap for the given 8-bit surface. </p>
437 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
438 If <code>SDL_HWPALETTE</code> was set in <code>SDL::Video::set_video_mode</code> flags, <code>SDL::Video::set_colors</code> will always return 1, and the palette is
439 guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
440 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.
441 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
442 the surface and a physical palette (that determines how the hardware will map the colors to the display).
443 <code>SDL::Video::set_colors</code> modifies both palettes (if present), and is equivalent to calling <code>SDL::Video::set_palette</code> with the flags set to
444 ( <code>SDL_LOGPAL | SDL_PHYSPAL</code> ). </p>
445 <p>If <code>surface</code> is not a palettized surface, this function does nothing, returning 0.
446 If all of the colors were set as passed to <code>SDL::Video::set_colors</code>, it will return 1.
447 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
448 actual color palette.</p>
451 <h2 id="set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</h2>
452 <div id="set_palette_surface_flags_start_colo-2">
453 <pre> $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
456 <p>Sets a portion of the palette for the given 8-bit surface.</p>
457 <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
458 the surface and a physical palette (that determines how the hardware will map the colors to the display).
459 Non screen surfaces have a logical palette only. <code>SDL::Video::blit</code> always uses the logical palette when blitting surfaces (if it has to
460 convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various
461 special color effects (e.g., screen fading, color flashes, screen dimming).</p>
462 <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>
463 <p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
464 If <code>SDL_HWPALETTE</code> was set in <code>SDL::Video::set_video_mode</code> flags, <code>SDL::Video::set_palette</code> will always return 1, and the palette is
465 guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
466 The color components of a <code>SDL::Color</code> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
467 <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>,
468 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
469 to determine the actual color palette.</p>
472 <h2 id="set_gamma_r_g_b">set_gamma(r,g,b)</h2>
473 <div id="set_gamma_r_g_b_CONTENT">
474 <pre> $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
477 <p>Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen.
478 A gamma value of 1.0 is identity (i.e., no adjustment is made).</p>
479 <p>This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment
480 with SDL::set_gamma_ramp.</p>
481 <p><strong>Note</strong>: Not all display hardware is able to change gamma.</p>
482 <p><code>SDL::Video::set_gamma</code> returns <code>-1</code> on error.</p>
483 <p><strong>Warning</strong>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
489 use Time::HiRes qw( usleep );
491 # the size of the window box or the screen resolution if fullscreen
492 my $screen_width = 800;
493 my $screen_height = 600;
495 SDL::init(SDL_INIT_VIDEO);
498 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
500 # drawing something somewhere
501 my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 128, 128, 128); # gray
502 SDL::Video::fill_rect($screen_surface,
503 SDL::Rect->new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
506 # update the whole screen
507 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
513 SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
519 SDL::Video::set_gamma( $_ / 20, 1, 1 );
523 SDL::Video::set_gamma( 1, 1, 1 );
532 <h2 id="get_gamma_ramp_rt_gt_bt">get_gamma_ramp(rt,gt,bt)</h2>
533 <div id="get_gamma_ramp_rt_gt_bt_CONTENT">
534 <pre> $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
537 <p>Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
538 SDL::get_gamma_ramp returns -1 on error.</p>
542 SDL::init(SDL_INIT_VIDEO);
544 my (@red, @green, @blue);
546 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
550 print( "an error occoured" );
554 printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
555 printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
556 printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
564 <h2 id="set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</h2>
565 <div id="set_gamma_ramp_rt_gt_bt_CONTENT">
566 <pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
569 <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
570 mapping between the input and output for that channel.
571 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.
572 You may pass NULL to any of the channels to leave them unchanged.</p>
573 <p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter
574 with <code>SDL::Video::set_gamma</code>.</p>
575 <p>Not all display hardware is able to change gamma.
576 <code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
581 SDL::init(SDL_INIT_VIDEO);
583 my (@red, @green, @blue);
585 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
589 $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
591 $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
595 print( "an error occoured" );
599 printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
600 printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
601 printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
609 <h2 id="map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</h2>
610 <div id="map_RGB_pixel_format_r_g_b_CONTENT">
611 <pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
614 <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.
615 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
616 If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
617 <p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
618 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
619 (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>
622 use SDL::PixelFormat;
625 SDL::init(SDL_INIT_VIDEO);
627 my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
628 # ^-- 16 bits per pixel
634 printf( "for 24bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b);
636 my $_16bit = SDL::Video::map_RGB( $screen_surface->format, $r, $g, $b );
638 # 16bpp is 5 bits red, 6 bits green and 5 bits blue
639 # we will obtain the values for each color and calculating them back to 24bit color system
640 $r = (($_16bit & 0b1111100000000000) >> 11) / 0b11111 * 0b11111111;
641 $g = (($_16bit & 0b0000011111100000) >> 5) / 0b111111 * 0b11111111;
642 $b = ($_16bit & 0b0000000000011111) / 0b11111 * 0b11111111;
644 printf( "for 16bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b );
646 # so color #9CDC67 becomes #9CDE62
653 <h2 id="map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</h2>
654 <div id="map_RGBA_pixel_format_r_g_b_a_CONTEN">
655 <p>Maps the RGBA color value to the specified SDL::pixel_format and returns the pixel value as a 32-bit int.
656 If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
657 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>
658 <p>A pixel value best approximating the given RGBA color value for a given pixel format.
659 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.,
660 with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
663 <h2 id="get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</h2>
664 <div id="get_RGB_pixel_format_pixel_CONTENT">
665 <p>Returns RGB values from a pixel in the specified pixel format.
666 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
667 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
670 <h2 id="get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</h2>
671 <div id="get_RGBA_pixel_format_pixel_CONTENT">
672 <p>Gets RGBA values from a pixel in the specified pixel format.
673 This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
674 component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
675 <p>If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque). </p>
678 <h2 id="lock_surface_surface">lock_surface(surface)</h2>
679 <div id="lock_surface_surface_CONTENT">
680 <p>SDL::lock_surface sets up the given SDL::surface for directly accessing the pixels.
681 Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to and read from surface->pixels, using the pixel format stored
682 in surface->format.
683 Once you are done accessing the surface, you should use SDL::unlock_surface to release the lock.</p>
684 <p>Not all surfaces require locking. If SDL::MUSTLOCK(surface) evaluates to 0, then reading and writing pixels to the surface can be performed
685 at any time, and the pixel format of the surface will not change.
686 No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
687 SDL::lock_surface returns 0 on success or -1 on error.</p>
688 <p>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
689 a matching unlock.</p>
692 <h2 id="unlock_surface_surface">unlock_surface(surface)</h2>
693 <div id="unlock_surface_surface_CONTENT">
694 <p>Surfaces that were previously locked using SDL::lock_surface must be unlocked with SDL::unlock_surface. Surfaces should be unlocked as
696 SDL::unlock_surface doesn't return anything.</p>
697 <p>Note : Since 1.1.8, the surface locks are recursive. See <code>SDL::lock_surface</code> for more information. </p>
700 <h2 id="convert_surface_surface_format_flags">convert_surface(surface,format,flags)</h2>
701 <div id="convert_surface_surface_format_flags-2">
702 <p>Creates a new SDL::surface of the specified SDL::pixel_format, and then copies and maps the given surface to it.
703 It is also useful for making a copy of a surface.</p>
704 <p>The flags parameter is passed to SDL::create_RGB_surface and has those semantics.
705 This function is used internally by SDL::display_format.
706 This function can only be called after SDL::init. </p>
707 <p>it returns a SDL::surface on success or undef on error.</p>
710 <h2 id="display_format">display_format</h2>
711 <div id="display_format_CONTENT">
712 <p>Converts a surface to the display format </p>
715 <h2 id="display_format_alpha">display_format_alpha</h2>
716 <div id="display_format_alpha_CONTENT">
717 <p>Converts a surface to the display format </p>
720 <h2 id="load_BMP_filename">load_BMP(filename)</h2>
721 <div id="load_BMP_filename_CONTENT">
722 <p>Loads a SDL::surface from a named Windows BMP file.
723 SDL::load_BMP returns a SDL::surface on success or undef on error.</p>
724 <p>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). </p>
731 <h2 id="save_BMP_surface_filename">save_BMP(surface,filename)</h2>
732 <div id="save_BMP_surface_filename_CONTENT">
733 <p>Saves the given SDL::Surface surface as a Windows BMP file named filename.
734 it returns 0 on success or -1 on error.</p>
737 <h2 id="set_color_key_surface_flag_key">set_color_key(surface,flag,key)</h2>
738 <div id="set_color_key_surface_flag_key_CONTE">
739 <p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
740 <p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match
742 The key must be of the same pixel format as the surface, SDL::map_RGB is often useful for obtaining an acceptable value.
743 If flag is SDL_SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.</p>
744 <p>If flag is OR'd with SDL_RLEACCEL then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface.
745 The surface will actually be encoded for RLE acceleration the first time SDL::blit_surface or SDL::display_format is called on the surface.
746 If flag is 0, this function clears any current color key. </p>
747 <p>SDL::set_color_key returns 0 on success or -1 on error.</p>
754 <h2 id="set_alpha_surface_flag_key">set_alpha(surface,flag,key)</h2>
755 <div id="set_alpha_surface_flag_key_CONTENT">
756 <p>SDL::set_alpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
757 <p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
758 flags is used to specify whether alpha blending should be used (SDL_SRCALPHA) and whether the surface should use RLE acceleration for
759 blitting (SDL_RLEACCEL).
760 flags can be an OR'd combination of these two options, one of these options or 0.
761 If SDL_SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface.
762 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
763 still be accelerated with SDL_RLEACCEL.</p>
764 <p>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.</p>
765 <p>Alpha affects surface blitting in the following ways: </p>
767 <dt>RGBA->RGB with SDL_SRCALPHA</dt>
769 <p>The source is alpha-blended with the destination, using the alpha channel.
770 SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
772 <dt>RGBA->RGB without SDL_SRCALPHA</dt>
774 <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
775 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
777 <dt>RGB->RGBA with SDL_SRCALPHA</dt>
779 <p>The source is alpha-blended with the destination using the per-surface alpha value.
780 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
781 The alpha channel of the copied pixels is set to opaque.</p>
783 <dt>RGB->RGBA without SDL_SRCALPHA</dt>
785 <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
786 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
788 <dt>RGBA->RGBA with SDL_SRCALPHA</dt>
790 <p>The source is alpha-blended with the destination using the source alpha channel.
791 The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
793 <dt>RGBA->RGBA without SDL_SRCALPHA</dt>
795 <p>The RGBA data is copied to the destination surface.
796 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
798 <dt>RGB->RGB with SDL_SRCALPHA</dt>
800 <p>The source is alpha-blended with the destination using the per-surface alpha value.
801 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
803 <dt>RGB->RGB without SDL_SRCALPHA</dt>
805 <p>The RGB data is copied from the source.
806 If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
809 <p>Note: When blitting, the presence or absence of SDL_SRCALPHA is relevant only on the source surface, not the destination.
810 Note: Note that RGBA->RGBA blits (with SDL_SRCALPHA set) keep the alpha of the destination surface. This means that you cannot compose
811 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>
812 <p>Note: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available. </p>
813 <p>SDL::set_alpha returns 0 on success or -1 on error.</p>
816 <h2 id="set_clip_rect_surface_rect">set_clip_rect(surface,rect)</h2>
817 <div id="set_clip_rect_surface_rect_CONTENT">
818 <p>Sets the clipping rectangle for the given SDL::surface. When this surface is the destination of a blit, only the area within the clip
819 rectangle will be drawn into.
820 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
821 outside the edges of the surface.
822 If rect is NULL the clipping rectangle will be set to the full size of the surface.
823 SDL::set_clip_rect doesn't returns anything.</p>
826 <h2 id="get_clip_rect_surface_rect">get_clip_rect(surface,rect)</h2>
827 <div id="get_clip_rect_surface_rect_CONTENT">
828 <p>Gets the clipping rectangle for the given SDL::surface. When this surface is the destination of a blit, only the area within the clip
829 rectangle is drawn into.
830 The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
831 SDL::get_clip_rect doesn't returns anything;</p>
838 <h2 id="blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</h2>
839 <div id="blit_surface_src_src_rect_dest_dest_-2">
840 <p>This performs a fast blit from the given source SDL::surface to the given destination SDL::surface.
841 The width and height in srcrect determine the size of the copied rectangle. Only the position is used in the dstrect (the width and height
842 are ignored). Blits with negative dstrect coordinates will be clipped properly.
843 If srcrect is NULL, the entire surface is copied. If dstrect is NULL, then the destination position (upper left corner) is (0, 0).
844 The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).
845 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,
846 but this is not the case with SDL::blit_surface. Like most surface manipulation functions in SDL, it should not be used together with OpenGL.</p>
847 <p>The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL::set_alpha for an explanation of
848 how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
849 SDL::blit_surface doesn't returns anything.</p>
852 <h2 id="fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</h2>
853 <div id="fill_rect_dest_dest_rect_pixel_CONTE">
854 <p>This function performs a fast fill of the given SDL::rectangle with the given SDL::pixel_format. If dstrect is NULL, the whole surface
855 will be filled with color.</p>
856 <p>The color should be a pixel of the format used by the surface, and can be generated by the SDL::MapRGB or SDL::map_RGBA functions.
857 If the color value contains an alpha value then the destination is simply "filled" with that alpha information, no blending takes place.</p>
858 <p>If there is a clip rectangle set on the destination (set via SDL::set_clip_rect), then this function will clip based on the intersection
859 of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually filled.</p>
860 <p>If you call this on the video surface (ie: the value of SDL::get_video_surface()) you may have to update the video surface to see the
861 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>
862 <p>SDL::fill_rect returns 0 on success or -1 on error.</p>
865 <h1 id="GL_Methods">GL Methods</h1><p><a href="#TOP" class="toplink">Top</a></p>
866 <div id="GL_Methods_CONTENT">
869 <h2 id="GL_load_library_path">GL_load_library(path)</h2>
870 <div id="GL_load_library_path_CONTENT">
871 <p>If you wish, you may load the OpenGL library from the given path at runtime, this must be done before SDL::set_video_mode is called.
872 The path of the GL library is passed to SDL::GL_load_library and it returns 0 on success, or -1 on an error. You must then use
873 SDL::GL_get_proc_address to retrieve function pointers to GL functions. </p>
874 <p>SDL::GL_load_library returns 0 on success or -1 or error.</p>
877 <h2 id="GL_get_proc_address_proc">GL_get_proc_address(proc)</h2>
878 <div id="GL_get_proc_address_proc_CONTENT">
879 <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
880 SDL::GL_load_library, then all GL functions must be retrieved this way. Usually this is used to retrieve function pointers to OpenGL
881 extensions. Note that this function needs an OpenGL context to function properly, so it should be called after SDL::set_video_mode
882 has been called (with the SDL_OPENGL flag).</p>
883 <p>OpenGL function pointers must be declared APIENTRY . This will ensure the proper calling convention is followed on platforms where this
884 matters (Win32) thereby avoiding stack corruption. In a Win32 build environment, APIENTRY should be defined as __stdcall. </p>
885 <p>it returns undef if the function is not found.</p>
888 <h2 id="GL_get_attribute_attr">GL_get_attribute(attr)</h2>
889 <div id="GL_get_attribute_attr_CONTENT">
890 <p>It returns SDL/OpenGL attribute attr . This is useful after a call to SDL::set_video_mode to check whether your attributes have been set
892 SDL::GL_get_attribute returns undef if the attribute is not found.</p>
895 <h2 id="GL_set_attribute_attr_value">GL_set_attribute(attr,value)</h2>
896 <div id="GL_set_attribute_attr_value_CONTENT">
897 <p>This function sets the given OpenGL attribute attr to value. The requested attributes will take effect after a call to SDL::set_video_mode.
898 You should use SDL::GL_get_attribute to check the values after a SDL::set_video_mode call, since the values obtained can differ from the
900 See SDL_GLattr for the full list of available attributes.
901 SDL::GL_set_attribute returns 0 on success or -1 on error.</p>
902 <p>Note : The SDL_DOUBLEBUF flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled
903 or disabled using the SDL_GL_DOUBLEBUFFER attribute. </p>
906 <h2 id="GL_swap_buffers">GL_swap_buffers</h2>
907 <div id="GL_swap_buffers_CONTENT">
908 <p>Swap the OpenGL buffers, if double-buffering is supported.
909 SDL::GL_swap_buffers doesn't returns any value.</p>
912 <h2 id="GL_attr_to_be_coded">GL_attr *** to be coded</h2>
913 <div id="GL_attr_to_be_coded_CONTENT">
920 <h1 id="a_href_SDL_Overlay_html_SDL_Overlay_"><a href="/SDL-Overlay.html">SDL::Overlay</a> Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
921 <div id="a_href_SDL_Overlay_html_SDL_Overlay_-2">
928 <h2 id="lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</h2>
929 <div id="lock_YUV_overlay_overlay_CONTENT">
930 <p>Much the same as <code>SDL::lock_surface</code>, SDL::lock_YUV_overlay locks the overlay for direct access to pixel data.
931 It returns 0 on success or -1 on error.</p>
934 <h2 id="unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</h2>
935 <div id="unlock_YUV_overlay_overlay_CONTENT">
936 <p>The opposite to <code>SDL::lock_YUV_overlay</code>. Unlocks a previously locked overlay. An overlay must be unlocked before it can be displayed.
937 It returns 0 on success or -1 on error.</p>
940 <h2 id="display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</h2>
941 <div id="display_YUV_overlay_overlay_dstrect_">
942 <p>Blit the overlay to the display surface specified when the overlay was created. The SDL::rect structure, dstrect, specifies a rectangle
943 on the display where the overlay is drawn. The .x and .y fields of dstrect specify the upper left location in display coordinates.
944 The overlay is scaled (independently in x and y dimensions) to the size specified by dstrect, and is optimized for 2x scaling</p>
945 <p>It returns 0 on success or -1 on error.</p>
952 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
953 <div id="SEE_ALSO_CONTENT">
956 <h2 id="Category_Objects">Category Objects</h2>
957 <div id="Category_Objects_CONTENT">
958 <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>,
959 <a href="/SDL-Rect.html">SDL::Rect</a>, <a href="/SDL-Palette.html">SDL::Palette</a>, <a href="/SDL-PixelFormat.html">SDL::PixelFormat</a>,
960 <a href="/SDL-VideoInfo.html">SDL::VideoInfo</a></p>