<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#CATEGORY">CATEGORY</a></li>
-<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
-<li><a href="#METHODS">METHODS</a>
+<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#CONSTANTS">CONSTANTS</a></li>
+<li><a href="#Core_Functions">Core Functions</a>
<ul><li><a href="#get_video_surface">get_video_surface</a></li>
<li><a href="#get_video_info">get_video_info</a></li>
<li><a href="#video_driver_name">video_driver_name</a></li>
-<li><a href="#list_modes_formats_flags">list_modes(formats,flags)</a></li>
-<li><a href="#video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</a></li>
-<li><a href="#set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</a>
+<li><a href="#list_modes">list_modes</a></li>
+<li><a href="#video_mode_ok">video_mode_ok</a></li>
+<li><a href="#set_video_mode">set_video_mode</a>
<ul><li><a href="#List_of_avalaibles_flags">List of avalaibles flags</a></li>
</ul>
</li>
-<li><a href="#update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</a></li>
-<li><a href="#update_rects_surface_rects">update_rects(surface,rects) </a></li>
-<li><a href="#flip_surface">flip(surface)</a></li>
-<li><a href="#set_colors_surface_start_colors">set_colors(surface,start,colors)</a></li>
-<li><a href="#set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</a></li>
-<li><a href="#set_gamma_r_g_b">set_gamma(r,g,b)</a></li>
-<li><a href="#get_gamma_ramp_rt_gt_bt_to_be_coded">get_gamma_ramp(rt,gt,bt) * to be coded</a></li>
-<li><a href="#set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</a></li>
-<li><a href="#map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</a></li>
-<li><a href="#map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</a></li>
-<li><a href="#get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</a></li>
-<li><a href="#get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</a></li>
-<li><a href="#create_RGB_surface_from">create_RGB_surface_from ***</a></li>
-<li><a href="#lock_surface_surface">lock_surface(surface)</a></li>
-<li><a href="#unlock_surface_surface">unlock_surface(surface)</a></li>
-<li><a href="#convert_surface_surface_format_flags">convert_surface(surface,format,flags)</a></li>
+<li><a href="#convert_surface">convert_surface</a></li>
<li><a href="#display_format">display_format</a></li>
<li><a href="#display_format_alpha">display_format_alpha</a></li>
-<li><a href="#load_BMP_filename">load_BMP(filename)</a></li>
-<li><a href="#save_BMP_surface_filename">save_BMP(surface,filename)</a></li>
-<li><a href="#set_color_key_surface_flag_key">set_color_key(surface,flag,key)</a></li>
-<li><a href="#set_alpha_surface_flag_key">set_alpha(surface,flag,key)</a></li>
-<li><a href="#set_clip_rect_surface_rect">set_clip_rect(surface,rect)</a></li>
-<li><a href="#get_clip_rect_surface_rect">get_clip_rect(surface,rect)</a></li>
-<li><a href="#blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</a></li>
-<li><a href="#fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</a></li>
-<li><a href="#GL_load_library_path">GL_load_library(path)</a></li>
-<li><a href="#GL_get_proc_address_proc">GL_get_proc_address(proc)</a></li>
-<li><a href="#GL_get_attribute_attr">GL_get_attribute(attr)</a></li>
-<li><a href="#GL_set_attribute_attr_value">GL_set_attribute(attr,value)</a></li>
+<li><a href="#load_BMP">load_BMP</a></li>
+<li><a href="#save_BMP">save_BMP</a></li>
+<li><a href="#set_color_key">set_color_key</a></li>
+<li><a href="#set_alpha">set_alpha</a></li>
+<li><a href="#fill_rect">fill_rect</a></li>
+</ul>
+</li>
+<li><a href="#Surface_Locking_and_Unlocking">Surface Locking and Unlocking</a>
+<ul><li><a href="#lock_surface">lock_surface</a></li>
+<li><a href="#unlock_surface">unlock_surface</a></li>
+<li><a href="#MUSTLOCK">MUSTLOCK</a></li>
+</ul>
+</li>
+<li><a href="#Screen_Updating_Functions">Screen Updating Functions</a>
+<ul><li><a href="#set_clip_rect">set_clip_rect</a></li>
+<li><a href="#get_clip_rect">get_clip_rect</a></li>
+<li><a href="#blit_surface">blit_surface</a></li>
+<li><a href="#update_rect">update_rect</a></li>
+<li><a href="#update_rects">update_rects</a></li>
+<li><a href="#flip">flip</a></li>
+</ul>
+</li>
+<li><a href="#Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</a>
+<ul><li><a href="#set_colors">set_colors</a></li>
+<li><a href="#set_palette">set_palette</a></li>
+<li><a href="#set_gamma">set_gamma</a></li>
+<li><a href="#get_gamma_ramp">get_gamma_ramp</a></li>
+<li><a href="#set_gamma_ramp">set_gamma_ramp</a></li>
+<li><a href="#map_RGB">map_RGB</a></li>
+<li><a href="#map_RGBA">map_RGBA</a></li>
+<li><a href="#get_RGB">get_RGB</a></li>
+<li><a href="#get_RGBA">get_RGBA</a></li>
+</ul>
+</li>
+<li><a href="#GL_Methods">GL Methods</a>
+<ul><li><a href="#GL_load_library">GL_load_library</a></li>
+<li><a href="#GL_get_proc_address">GL_get_proc_address</a></li>
+<li><a href="#GL_get_attribute">GL_get_attribute</a></li>
+<li><a href="#GL_set_attribute">GL_set_attribute</a></li>
<li><a href="#GL_swap_buffers">GL_swap_buffers</a></li>
-<li><a href="#GL_attr_to_be_coded">GL_attr *** to be coded</a></li>
-<li><a href="#lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</a></li>
-<li><a href="#unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</a></li>
-<li><a href="#display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</a></li>
</ul>
</li>
+<li><a href="#Video_Overlay_Functions">Video Overlay Functions</a>
+<ul><li><a href="#lock_YUV_overlay">lock_YUV_overlay</a></li>
+<li><a href="#unlock_YUV_overlay">unlock_YUV_overlay</a></li>
+<li><a href="#display_YUV_overlay">display_YUV_overlay</a></li>
+</ul>
+</li>
+<li><a href="#Window_Management_Functions">Window Management Functions</a>
+<ul><li><a href="#wm_set_caption">wm_set_caption</a></li>
+<li><a href="#wm_get_caption">wm_get_caption</a></li>
+<li><a href="#wm_set_icon">wm_set_icon</a></li>
+<li><a href="#wm_grab_input">wm_grab_input</a></li>
+<li><a href="#wm_iconify_window">wm_iconify_window</a></li>
+<li><a href="#wm_toggle_fullscreen">wm_toggle_fullscreen</a></li>
+</ul>
+</li>
+<li><a href="#AUTHORS">AUTHORS</a></li>
<li><a href="#SEE_ALSO">SEE ALSO</a>
<ul><li><a href="#Category_Objects">Category Objects</a>
</li>
</ul>
</li>
</ul><hr />
-<!-- INDEX END -->
+<!-- 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 />
<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>Core, Video</p>
</div>
-<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="DESCRIPTION_CONTENT">
+<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="SYNOPSIS_CONTENT">
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ use SDL::Rect;
+
+ # the size of the window box or the screen resolution if fullscreen
+ my $screen_width = 800;
+ my $screen_height = 600;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ # setting video mode
+ my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_ANYFORMAT);
+ # drawing something somewhere
+ my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
+ SDL::Video::fill_rect($screen_surface,
+ SDL::Rect->new($screen_width / 4, $screen_height / 4,
+ $screen_width / 2, $screen_height / 2), $mapped_color);
+ # update an area on the screen so its visible
+ SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
+ sleep(5); # just to have time to see it
+ SDL::quit();
+
+</pre>
+
+</div>
+<h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="CONSTANTS_CONTENT">
+<p>The constants are exported by default. You can avoid this by doing:</p>
+<pre> use SDL::Video ();
+
+</pre>
+<p>and access them directly:</p>
+<pre> SDL::Video::SDL_SWSURFACE;
+
+</pre>
+<p>or by choosing the export tags below:</p>
+<p>Export tag: ':surface'</p>
+<pre> SDL_ASYNCBLIT Use asynchronous blit if possible
+ SDL_SWSURFACE Stored in the system memory.
+ SDL_HWSURFACE Stored in video memory
+
+</pre>
+<p>Export tag: ':video'</p>
+<pre> SDL_ANYFORMAT Allow any pixel-format
+ SDL_HWPALETTE Have an exclusive palette
+ SDL_DOUBLEBUF Double buffered
+ SDL_FULLSCREEN Full screen surface
+ SDL_OPENGL Have an OpenGL context
+ SDL_OPENGLBLIT Support OpenGL blitting.
+ NOTE: This option is kept for compatibility only, and is not recommended for new code.
+ SDL_RESIZABLE Resizable surface
+ SDL_NOFRAME No window caption or edge frame
+ SDL_HWACCEL Use Hardware acceleration blit
+ SDL_SRCCOLORKEY Use colorkey blitting
+ SDL_RLEACCELOK Private flag
+ SDL_RLEACCEL Accelerated colorkey blitting with RLE
+ SDL_SRCALPHA Use alpha blending blit
+ SDL_PREALLOC Use preallocated memory
+
+</pre>
+<p>Export tag ':overlay'</p>
+<pre> SDL_YV12_OVERLAY Planar mode: Y + V + U (3 planes)
+ SDL_IYUV_OVERLAY Planar mode: Y + U + V (3 planes)
+ SDL_YUY2_OVERLAY Packed mode: Y0+U0+Y1+V0 (1 plane)
+ SDL_UYVY_OVERLAY Packed mode: U0+Y0+V0+Y1 (1 plane)
+ SDL_YVYU_OVERLAY Packed mode: Y0+V0+Y1+U0 (1 plane)
+
+</pre>
+<p>Export tag ':palette'</p>
+<pre> SDL_LOGPAL Logical palette, which controls how blits are mapped to/from the surface
+ SDL_PHYSPAL Physical palette, which controls how pixels look on the screen
+
+</pre>
+<p>Export tag ':grab'</p>
+<pre> SDL_GRAB_QUERY
+ SDL_GRAB_OFF
+ SDL_GRAB_ON
+ SDL_GRAB_FULLSCREEN Used interally
+
+</pre>
+<p>Export tag ':gl'</p>
+<pre> SDL_GL_RED_SIZE
+ SDL_GL_GREEN_SIZE
+ SDL_GL_BLUE_SIZE
+ SDL_GL_ALPHA_SIZE
+ SDL_GL_BUFFER_SIZE
+ SDL_GL_DOUBLEBUFFER
+ SDL_GL_DEPTH_SIZE
+ SDL_GL_STENCIL_SIZE
+ SDL_GL_ACCUM_RED_SIZE
+ SDL_GL_ACCUM_GREEN_SIZE
+ SDL_GL_ACCUM_BLUE_SIZE
+ SDL_GL_ACCUM_ALPHA_SIZE
+ SDL_GL_STEREO
+ SDL_GL_MULTISAMPLEBUFFERS
+ SDL_GL_MULTISAMPLESAMPLES
+ SDL_GL_ACCELERATED_VISUAL
+ SDL_GL_SWAP_CONTROL
+
+</pre>
</div>
-<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
-<div id="METHODS_CONTENT">
+<h1 id="Core_Functions">Core Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Core_Functions_CONTENT">
</div>
<h2 id="get_video_surface">get_video_surface</h2>
<div id="get_video_surface_CONTENT">
-<p>It return the current SDL::Surface on succés or undef on error.
-get_video_surface doesn't take any parameters.</p>
+<pre> my $surface = SDL::Video::get_video_surface();
+
+</pre>
+<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
+function returns the publicly visible surface, not the real video surface.</p>
+<p>Example:</p>
+<pre> # somewhere after you set the video mode
+ my $surface = SDL::Video::get_video_surface();
+
+ printf( "our screen is %d pixels wide and %d pixels high\n", $surface->w, $surface->h );
+
+</pre>
</div>
<h2 id="get_video_info">get_video_info</h2>
<div id="get_video_info_CONTENT">
-<p>Returns a SDL::VideoInfo about the video hardware.
-It doesn't take any parameters.</p>
+<pre> my $video_info = SDL::Video::get_video_info();
+
+</pre>
+<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
+<a href="#set_video_mode">SDL::Video::set_video_mode</a>, the <code>vfmt</code> member of the returned structure will contain the pixel
+format of the <strong>best</strong> video mode. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::VideoInfo;
+ use SDL::PixelFormat;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $video_info = SDL::Video::get_video_info();
+
+ printf( "we can have %dbits per pixel\n", $video_info->vfmt->BitsPerPixel );
+
+ SDL::quit();
+
+</pre>
</div>
<h2 id="video_driver_name">video_driver_name</h2>
<div id="video_driver_name_CONTENT">
-<p>Return the 1024 first char of name of the video driver.
-It doesn't take any parameters.</p>
+<pre> my $driver_name = SDL::Video::video_driver_name();
+
+</pre>
+<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
+word identifier like <code>"x11"</code>, <code>"windib"</code> or <code>"directx"</code>.</p>
+<p><strong>Note</strong>: Some platforms allow selection of the video driver through the <code>SDL_VIDEODRIVER</code> environment variable. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ print SDL::Video::video_driver_name() . "\n";
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="list_modes_formats_flags">list_modes(formats,flags)</h2>
-<div id="list_modes_formats_flags_CONTENT">
-<p>Returns a pointer to an array of available screen dimensions for the given format and video flags,
-or it return undef if no modes are avalaibles.</p>
+<h2 id="list_modes">list_modes</h2>
+<div id="list_modes_CONTENT">
+<pre> my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
+
+</pre>
+<p>Returns a reference to an array:</p>
+<ul>
+ <li>of available screen dimensions (as <code>SDL::Rect</code>'s) for the given format and video flags. </li>
+ <li>with first array element 'all'. In this case you can set all modes. </li>
+ <li>with first array element 'none' if no mode is available.</li>
+</ul>
+
+<p><strong>Note</strong>: <list_modes> should be called before the video_mode ist set. Otherwise you will always get 'all'.</p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::VideoInfo;
+ use SDL::PixelFormat;
+ use SDL::Rect;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $video_info = SDL::Video::get_video_info();
+
+ my @modes = @{ SDL::Video::list_modes($video_info->vfmt, SDL_NOFRAME) };
+
+ if($#modes > 0)
+ {
+ print("available modes:\n");
+ foreach my $mode ( @modes )
+ {
+ printf("%d x %d\n", $mode->w, $mode->h );
+ }
+ }
+ elsif($#modes == 0)
+ {
+ printf("%s video modes available\n", $modes[0]);
+ }
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</h2>
-<div id="video_mode_ok_width_height_bpp_flags-2">
-<p>Checks to see if a particular video mode of the given width,height,bpp and flags is supported.
-It returns 0 if the mode is not supported at all, or the suggested bpp.</p>
+<h2 id="video_mode_ok">video_mode_ok</h2>
+<div id="video_mode_ok_CONTENT">
+<pre> my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
+
+</pre>
+<p>This function is used to check whether the requested mode is supported by the current video device. The arguments passed to this function
+are the same as those you would pass to <a href="#set_video_mode">SDL::Video::set_video_mode</a>.
+It returns <code>0</code> if the mode is not supported at all, otherwise the suggested <code>bpp</code>.</p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
+
+ unless($video_mode_ok)
+ {
+ printf( "this video mode is not supported\n" );
+ }
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</h2>
-<div id="set_video_mode_width_height_bpp_flag-2">
-<p>Sets up a video mode with the specified width, height, bits-per-pixel and flags.
-set_video_mode returns a SDL::Surface on succés or it returns undef on error, the error message is retrieved using <code>SDL::get_error</code>.</p>
+<h2 id="set_video_mode">set_video_mode</h2>
+<div id="set_video_mode_CONTENT">
+<pre> my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
+
+</pre>
+<p>Sets up a video mode with the specified width, height, bits-per-pixel and flags.
+<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
+using <code>SDL::get_error</code>.</p>
</div>
<h3 id="List_of_avalaibles_flags">List of avalaibles flags</h3>
<div id="List_of_avalaibles_flags_CONTENT">
<dl>
- <dt>SDL_SWSURFACE</dt>
+ <dt><code>SDL_SWSURFACE</code></dt>
<dd>
<p>Create the video surface in system memory</p>
</dd>
- <dt>SDL_HWSURFACE</dt>
+ <dt><code>SDL_HWSURFACE</code></dt>
<dd>
<p>Create the video surface in video memory</p>
</dd>
- <dt>SDL_ASYNCBLIT</dt>
+ <dt><code>SDL_ASYNCBLIT</code></dt>
<dd>
<p>Enables the use of asynchronous updates of the display surface.
This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.</p>
</dd>
- <dt>SDL_ANYFORMAT</dt>
+ <dt><code>SDL_ANYFORMAT</code></dt>
<dd>
<p>Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface.
-Passing SDL_ANYFORMAT prevents this and causes SDL to use the video surface, regardless of its pixel depth.</p>
+Passing <code>SDL_ANYFORMAT</code> prevents this and causes SDL to use the video surface, regardless of its pixel depth.</p>
</dd>
- <dt>SDL_HWPALETTE</dt>
+ <dt><code>SDL_HWPALETTE</code></dt>
<dd>
<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>
</dd>
- <dt>SDL_DOUBLEBUF</dt>
+ <dt><code>SDL_DOUBLEBUF</code></dt>
<dd>
- <p>Enable hardware double buffering; only valid with SDL_HWSURFACE. Calling SDL::flip will flip the buffers and update the screen.
+ <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
+the screen.
All drawing will take place on the surface that is not displayed at the moment.
-If double buffering could not be enabled then SDL_Flip will just perform a SDL::update_rect on the entire screen.</p>
+If double buffering could not be enabled then <a href="#flip">SDL::Video::flip</a> will just perform a
+<a href="#update_rect">SDL::Video::update_rect</a> on the entire screen.</p>
</dd>
- <dt>SDL_FULLSCREEN</dt>
+ <dt><code>SDL_FULLSCREEN</code></dt>
<dd>
<p>SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason),
the next higher resolution will be used and the display window centered on a black background.</p>
</dd>
- <dt>SDL_OPENGL</dt>
+ <dt><code>SDL_OPENGL</code></dt>
<dd>
- <p>Create an OpenGL rendering context. You should have previously set OpenGL video attributes with SDL::gl_setattribute.</p>
+ <p>Create an OpenGL rendering context. You should have previously set OpenGL video attributes with
+<a href="#GL_set_attribute">SDL::Video::GL_set_attribute</a>.</p>
</dd>
- <dt>SDL_OPENGLBLIT</dt>
+ <dt><code>SDL_OPENGLBLIT</code></dt>
<dd>
<p>Create an OpenGL rendering context, like above, but allow normal blitting operations.
The screen (2D) surface may have an alpha channel, and SDL::update_rects must be used for updating changes to the screen surface.
NOTE: This option is kept for compatibility only, and will be removed in next versions. Is not recommended for new code.</p>
</dd>
- <dt>SDL_RESIZABLE</dt>
+ <dt><code>SDL_RESIZABLE</code></dt>
<dd>
<p>Create a resizable window.
-When the window is resized by the user a SDL_VIDEORESIZE event is generated and SDL::set_video_mode can be called again with the new size.</p>
+When the window is resized by the user a <code>SDL_VIDEORESIZE</code> event is generated and
+<a href="#set_video_mode">SDL::Video::set_video_mode</a> can be called again with the new size.</p>
+ </dd>
+ <dt><code>SDL_NOFRAME</code></dt>
+ <dd>
+ <p>If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration.
+Fullscreen modes automatically have this flag set.</p>
+ </dd>
+</dl>
+<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.
+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
+when you lock them, and back when you unlock them. This can cause a major performance hit. Be aware that you may request a hardware surface,
+but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface
+when using <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>
+<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
+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>
+<p><strong>Note 3</strong>: This function should be called in the main thread of your application.</p>
+<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
+been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.</p>
+<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
+initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux,
+however, it works fine, and the initialization code only needs to be executed after the first call to
+<a href="#set_video_mode">SDL::Video::set_video_mode</a> (although there is no harm in executing the initialization code after
+each call to <a href="#set_video_mode">SDL::Video::set_video_mode</a>, for example for a multiplatform application). </p>
+
+</div>
+<h2 id="convert_surface">convert_surface</h2>
+<div id="convert_surface_CONTENT">
+<pre> $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
+
+</pre>
+<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.
+It is also useful for making a copy of a surface.</p>
+<p>The flags parameter is passed to <a href="SDL-Surface.html">SDL::Surface</a><code>->new</code> and has those semantics.
+This function is used internally by <a href="#display_format">SDL::Video::display_format</a>.
+This function can only be called after <code>SDL::init</code>. </p>
+<p>it returns a <a href="SDL-Surface.html">SDL::Surface</a> on success or <code>undef</code> on error.</p>
+
+</div>
+<h2 id="display_format">display_format</h2>
+<div id="display_format_CONTENT">
+<pre> $new_surface = SDL::Video::display_format( $surface );
+
+</pre>
+<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
+blitting onto the display surface. It calls <a href="#conver_surface">SDL::Video::convert_surface</a>.</p>
+<p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
+this function.</p>
+<p>If you want an alpha channel, see <code>SDL::Video::display_format_alpha</code>.
+Return Value</p>
+<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>
+
+</div>
+<h2 id="display_format_alpha">display_format_alpha</h2>
+<div id="display_format_alpha_CONTENT">
+<pre> $new_surface = SDL::Video::display_format_alpha( $surface );
+
+</pre>
+<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,
+suitable for fast blitting onto the display surface. It calls <a href="#convert_surface">SDL::Video::convert_surface</a>.</p>
+<p>If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling
+this function.</p>
+<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
+surface will then be transparent (alpha=0) where the pixels match the colorkey, and opaque (alpha=255) elsewhere.</p>
+<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
+segfault.</p>
+
+</div>
+<h2 id="load_BMP">load_BMP</h2>
+<div id="load_BMP_CONTENT">
+<pre> $surface = SDL::Video::load_BMP( $filename );
+
+</pre>
+<p>Loads a <a href="SDL-Surface.html">SDL::Surface</a> from a named Windows BMP file.
+<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>
+<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>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Rect;
+ use SDL::Surface;
+
+ my $screen_width = 640;
+ my $screen_height = 480;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
+
+ my $picture = SDL::Video::load_BMP('test.bmp');
+
+ die(SDL::get_error) unless $picture;
+
+ my $rect = SDL::Rect->new(0, 0, $screen_width, $screen_height);
+
+ SDL::Video::blit_surface( $picture, SDL::Rect->new(0, 0, $picture->w, $picture->h),
+ $screen, SDL::Rect->new(0, 0, $screen->w, $screen->h) );
+ SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
+ sleep(2);
+ SDL::quit;
+</pre>
+
+</div>
+<h2 id="save_BMP">save_BMP</h2>
+<div id="save_BMP_CONTENT">
+<pre> $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
+
+</pre>
+<p>Saves the given <a href="SDL-Surface.html">SDL::Surface</a> as a Windows BMP file named filename.
+it returns 0 on success or -1 on error.</p>
+
+</div>
+<h2 id="set_color_key">set_color_key</h2>
+<div id="set_color_key_CONTENT">
+<pre> $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
+
+</pre>
+<p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
+<p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match
+the key value).
+The key must be of the same pixel format as the surface, <a href="#map_RGB">SDL::Video::map_RGB</a> is often useful for obtaining an acceptable value.
+If flag is <code>SDL_SRCCOLORKEY</code> then key is the transparent pixel value in the source image of a blit.</p>
+<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.
+The surface will actually be encoded for RLE acceleration the first time <a href="#blit_surface">SDL::Video::blit_surface</a> or
+<code>SDL::Video::display_format|/display_format</code> is called on the surface.
+If <code>flag</code> is <code>0</code>, this function clears any current color key. </p>
+<p><code>SDL::Video::set_color_key</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+
+</div>
+<h2 id="set_alpha">set_alpha</h2>
+<div id="set_alpha_CONTENT">
+<pre> $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
+
+</pre>
+<p><code>set_alpha</code> is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
+<p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
+flags is used to specify whether alpha blending should be used ( <code>SDL_SRCALPHA</code> ) and whether the surface should use RLE acceleration for
+blitting ( <code>SDL_RLEACCEL</code> ).
+flags can be an OR'd combination of these two options, one of these options or <code>0</code>.
+If <code>SDL_SRCALPHA</code> is not passed as a flag then all alpha information is ignored when blitting the surface.
+The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can
+still be accelerated with <code>SDL_RLEACCEL</code>.</p>
+<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>
+<p>Alpha affects surface blitting in the following ways: </p>
+<dl>
+ <dt>RGBA->RGB with <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The source is alpha-blended with the destination, using the alpha channel.
+SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
</dd>
- <dt>SDL_NOFRAME</dt>
+ <dt>RGBA->RGB without <code>SDL_SRCALPHA</code></dt>
<dd>
- <p>If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration.
-Fullscreen modes automatically have this flag set.</p>
+ <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
+ </dd>
+ <dt>RGB->RGBA with <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The source is alpha-blended with the destination using the per-surface alpha value.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
+The alpha channel of the copied pixels is set to opaque.</p>
+ </dd>
+ <dt>RGB->RGBA without <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
+ </dd>
+ <dt>RGBA->RGBA with <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The source is alpha-blended with the destination using the source alpha channel.
+The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
+ </dd>
+ <dt>RGBA->RGBA without <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The RGBA data is copied to the destination surface.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
+ </dd>
+ <dt>RGB->RGB with <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The source is alpha-blended with the destination using the per-surface alpha value.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
+ </dd>
+ <dt>RGB->RGB without <code>SDL_SRCALPHA</code></dt>
+ <dd>
+ <p>The RGB data is copied from the source.
+If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
</dd>
</dl>
-<p>Note 1: Use SDL_SWSURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. When you use hardware surfaces (by passing the flag SDL_HWSURFACE as parameter), SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them. This can cause a major performance hit. Be aware that you may request a hardware surface, but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface when using SDL_FULLSCREEN. The SDL_HWSURFACE flag is best used when the surfaces you'll be blitting can also be stored in video memory.</p>
-<p>Note 2: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment variables SDL_VIDEO_CENTERED=center or SDL_VIDEO_WINDOW_POS=x,y. You can also set them via <code>SDL::putenv</code>.</p>
-<p>Note 3: This function should be called in the main thread of your application.</p>
-<p>User note 1: Some have found that enabling OpenGL attributes like SDL_GL_STENCIL_SIZE (the stencil buffer size) before the video mode has been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.</p>
-<p>User note 2: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux, however, it works fine, and the initialization code only needs to be executed after the first call to SDL::set_video_mode (although there is no harm in executing the initialization code after each call to SDL::set_video_mode, for example for a multiplatform application). </p>
+<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.
+<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
+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>
+<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>
+<p><code>SDL::Video::set_alpha</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+</div>
+<h2 id="fill_rect">fill_rect</h2>
+<div id="fill_rect_CONTENT">
+<pre> $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );
+
+</pre>
+<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
+will be filled with color.</p>
+<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
+<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
+alpha information, no blending takes place.</p>
+<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
+on the intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually
+filled.</p>
+<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
+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>
+<p><code>SDL::Video::fill_rect</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+<p>for an example see <a href="#SYNOPSIS">SYNOPSIS</a>.</p>
+</div>
+<h1 id="Surface_Locking_and_Unlocking">Surface Locking and Unlocking</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Surface_Locking_and_Unlocking_CONTEN">
+</div>
+<h2 id="lock_surface">lock_surface</h2>
+<div id="lock_surface_CONTENT">
+<pre> int SDL::Video::lock_surface( $surface );
+
+</pre>
+<p><code>SDL::Video::lock_surface</code> sets up the given <a href="SDL-Surface.html">SDL::Surface</a> for directly accessing the pixels.
+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> ),
+using the pixel format stored in <code>surface-</code>format>.
+Once you are done accessing the surface, you should use <a href="#unlock_surface">SDL::Video::unlock_surface</a> to release the lock.</p>
+<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
+be performed at any time, and the pixel format of the surface will not change.
+No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
+<code>SDL::Video::lock_surface</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+<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
+a matching unlock.</p>
+<pre> use strict;
+ use warnings;
+ use Carp;
+
+ use SDL v2.3;
+ use SDL::Video;
+ use SDL::Event;
+ use SDL::Events;
+ use SDL::Surface;
+
+ my $screen;
+
+ sub putpixel
+ {
+ my($x, $y, $color) = @_;
+ my $lineoffset = $y * ($screen->pitch / 4);
+ $screen->set_pixels( $lineoffset+ $x, $color);
+ }
+
+ sub render
+ {
+ if( SDL::Video::MUSTLOCK( $screen) )
+ {
+ return if (SDL::Video::lock_surface( $screen ) < 0)
+ }
+
+ my $ticks = SDL::get_ticks();
+ my ($i, $y, $yofs, $ofs) = (0,0,0,0);
+ for ($i = 0; $i < 480; $i++)
+ {
+ for (my $j = 0, $ofs = $yofs; $j < 640; $j++, $ofs++)
+ {
+ $screen->set_pixels( $ofs, ( $i * $i + $j * $j + $ticks ) );
+ }
+ $yofs += $screen->pitch / 4;
+ }
+
+ putpixel(10, 10, 0xff0000);
+ putpixel(11, 10, 0xff0000);
+ putpixel(10, 11, 0xff0000);
+ putpixel(11, 11, 0xff0000);
+
+ SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
+
+ SDL::Video::update_rect($screen, 0, 0, 640, 480);
+
+ return 0;
+ }
+
+ sub main
+ {
+ carp 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) < 0);
+
+ $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
+
+ carp 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
+
+ while(1)
+ {
+ render();
+
+ my $event = SDL::Event->new();
+
+ while( SDL::Events::poll_event($event) )
+ {
+ my $type = $event->type;
+ return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
+ }
+ SDL::Events::pump_events();
+ }
+ }
+
+ main();
+
+ SDL::quit;
+
+</pre>
+</div>
+<h2 id="unlock_surface">unlock_surface</h2>
+<div id="unlock_surface_CONTENT">
+<pre> SDL::Video::unlock_surface( $surface );
+</pre>
+<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>.
+Surfaces should be unlocked as soon as possible.
+<code>SDL::Video::unlock_surface</code> doesn't return anything.</p>
+<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>
+</div>
+<h2 id="MUSTLOCK">MUSTLOCK</h2>
+<div id="MUSTLOCK_CONTENT">
+<pre> int SDL::Video::MUSTLOCK( $surface );
+</pre>
+<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>
+</div>
+<h1 id="Screen_Updating_Functions">Screen Updating Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Screen_Updating_Functions_CONTENT">
+</div>
+<h2 id="set_clip_rect">set_clip_rect</h2>
+<div id="set_clip_rect_CONTENT">
+<pre> SDL::Video::set_clip_rect( $surface, $rect );
+
+</pre>
+<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
+rectangle will be drawn into.
+The rectangle pointed to by rect will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall
+outside the edges of the surface.
+If rect is NULL the clipping rectangle will be set to the full size of the surface.
+<code>SDL::Video::set_clip_rect</code> doesn't returns anything.</p>
+
+</div>
+<h2 id="get_clip_rect">get_clip_rect</h2>
+<div id="get_clip_rect_CONTENT">
+<pre> SDL::Video::get_clip_rect( $surface, $rect );
+</pre>
+<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
+rectangle is drawn into.
+The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
+<code>SDL::Video::get_clip_rect</code> doesn't returns anything;</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Rect;
+ use SDL::Surface;
+
+ my $screen_width = 640;
+ my $screen_height = 480;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
+
+ my $rect = SDL::Rect->new(0, 0, 0, 0);
+
+ SDL::Video::get_clip_rect($screen, $rect);
+
+ printf( "rect is %d, %d, %d, %d\n", $rect->x, $rect->y, $rect->w, $rect->h);
+
+ SDL::quit;
+
+</pre>
+
+</div>
+<h2 id="blit_surface">blit_surface</h2>
+<div id="blit_surface_CONTENT">
+<pre> SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
+
+</pre>
+<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>.
+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>
+(the width and height are ignored). Blits with negative <code>dst_rect</code> coordinates will be clipped properly.
+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).
+The final blit rectangle is saved in <code>dst_rect</code> after all clipping is performed (<code>src_rect</code> is not modified).
+The blit function should not be called on a locked surface. I.e. when you use your own drawing functions you may need to lock a surface,
+but this is not the case with <code>SDL::Video::blit_surface</code>. Like most surface manipulation functions in SDL, it should not be used together
+with OpenGL.</p>
+<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>
+for an explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
+<code>SDL::Video::blit_surface</code> doesn't returns anything.</p>
+<p>For an example see <a href="#load_BMP">SDL::Video::load_BMP</a>.</p>
</div>
-<h2 id="update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</h2>
-<div id="update_rect_surface_x_y_width_height-2">
+<h2 id="update_rect">update_rect</h2>
+<div id="update_rect_CONTENT">
+<pre> update_rect( $surface, $left, $top, $width, $height );
+
+</pre>
<p>Makes sure the given area is updated on the given screen.
The rectangle must be confined within the screen boundaries because there's no clipping.
update_rect doesn't returns any value.</p>
-<p>Note : This function should not be called while screen is locked by SDL::lock_surface
-Note2 : If x, y, width and height are all equal to 0, SDL_UpdateRect will update the entire screen. </p>
+<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>
+<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>
+<p>For an example see <a href="#SYNOPSIS">SYNOPSIS</a></p>
</div>
-<h2 id="update_rects_surface_rects">update_rects(surface,rects) </h2>
-<div id="update_rects_surface_rects_CONTENT">
+<h2 id="update_rects">update_rects</h2>
+<div id="update_rects_CONTENT">
+<pre> update_rects( $surface, @rects );
+
+</pre>
<p>Makes sure the given list of rectangles is updated on the given screen.
The rectangle must be confined within the screen boundaries because there's no clipping.
-update_rects doesn't returns any value.</p>
-<p>Note : This function should not be called while screen is locked by SDL::lock_surface</p>
+<code>update_rects</code> doesn't returns any value.</p>
+<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>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ use SDL::Rect;
+
+ # the size of the window box or the screen resolution if fullscreen
+ my $screen_width = 800;
+ my $screen_height = 600;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ # setting video mode
+ my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
+
+ # drawing the whole screen blue
+ my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
+ SDL::Video::fill_rect($screen_surface,
+ SDL::Rect->new(0, 0, $screen_width, $screen_height),
+ $mapped_color);
+
+ my @rects = ();
+ push(@rects, SDL::Rect->new(200, 0, 400, 600));
+ push(@rects, SDL::Rect->new( 0, 150, 800, 300));
+
+ # updating parts of the screen (should look like a cross)
+ SDL::Video::update_rects($screen_surface, @rects);
+
+ sleep(2);
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="flip_surface">flip(surface)</h2>
-<div id="flip_surface_CONTENT">
+<h2 id="flip">flip</h2>
+<div id="flip_CONTENT">
+<pre> $flip = SDL::Video::flip( $screen_surface );
+
+</pre>
<p>On hardware that supports double-buffering, this function sets up a flip and returns.
The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return.
-On hardware that doesn't support double-buffering or if SDL_SWSURFACE was set, this is equivalent to calling SDL::update_rect(screen, 0, 0, 0, 0)</p>
-<p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in contrast to a full screen software mode.</p>
-<p>The SDL_DOUBLEBUF flag must have been passed to SDL::set_video_mode, when setting the video mode for this function to perform hardware flipping.
-flip returns 0 on succés or -1 on error.</p>
-<p>Note : If you want to swap the buffers of an initialized OpenGL context, use the function SDL::gl_swap_buffers instead. </p>
+On hardware that doesn't support double-buffering or if <code>SDL_SWSURFACE</code> was set, this is equivalent to calling
+<code>SDL::Video::update_rect( $screen, 0, 0, 0, 0 )</code>.</p>
+<p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by
+restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in
+contrast to a full screen software mode.</p>
+<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
+to perform hardware flipping.</p>
+<p><code>flip</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+<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>
+instead. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+
+ # the size of the window box or the screen resolution if fullscreen
+ my $screen_width = 800;
+ my $screen_height = 600;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ # setting video mode
+ my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
+
+ # do some video operations here
+
+ # doing page flipping
+ unless( SDL::Video::flip($screen_surface) == 0 )
+ {
+ printf( STDERR "failed to swap buffers: %s\n", SDL::get_error() );
+ }
+
+ SDL::quit();
+
+</pre>
+
+</div>
+<h1 id="Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Palette_Color_and_Pixel_Functions_CO">
</div>
-<h2 id="set_colors_surface_start_colors">set_colors(surface,start,colors)</h2>
-<div id="set_colors_surface_start_colors_CONT">
+<h2 id="set_colors">set_colors</h2>
+<div id="set_colors_CONTENT">
+<pre> $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
+
+</pre>
<p>Sets a portion of the colormap for the given 8-bit surface. </p>
<p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
-If SDL_HWPALETTE was set in SDL::set_video_mode flags, SDL::set_colors will always return 1, and the palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
-The color components of a SDL::Color structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.
-Palettized (8-bit) screen surfaces with the SDL_HWPALETTE flag have two palettes, a logical palette that is used for mapping blits to/from the surface and a physical palette (that determines how the hardware will map the colors to the display).
-SDL::SetColors modifies both palettes (if present), and is equivalent to calling SDL::SetPalette with the flags set to (SDL_LOGPAL | SDL_PHYSPAL). </p>
-<p>If surface is not a palettized surface, this function does nothing, returning 0.
-If all of the colors were set as passed to SDL::set_colors, it will return 1.
-If not all the color entries were set exactly as given, it will return 0, and you should look at the surface palette to determine the actual color palette.</p>
+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
+palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
+The color components of a <a href="SDL-Color.html">SDL::Color</a> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.
+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
+the surface and a physical palette (that determines how the hardware will map the colors to the display).
+<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
+flags set to ( <code>SDL_LOGPAL | SDL_PHYSPAL</code> ). </p>
+<p>If <code>surface</code> is not a palettized surface, this function does nothing, returning 0.
+If all of the colors were set as passed to <code>SDL::Video::set_colors</code>, it will return 1.
+If not all the color entries were set exactly as given, it will return 0, and you should look at the surface palette to determine the
+actual color palette.</p>
</div>
-<h2 id="set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</h2>
-<div id="set_palette_surface_flags_start_colo-2">
+<h2 id="set_palette">set_palette</h2>
+<div id="set_palette_CONTENT">
+<pre> $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
+
+</pre>
<p>Sets a portion of the palette for the given 8-bit surface.</p>
-<p>Palettized (8-bit) screen surfaces with the SDL_HWPALETTE flag have two palettes, a logical palette that is used for mapping blits to/from the surface and a physical palette (that determines how the hardware will map the colors to the display).
-Non screen surfaces have a logical palette only. SDL::blit_surface always uses the logical palette when blitting surfaces (if it has to convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various special color effects (e.g., screen fading, color flashes, screen dimming).</p>
-<p>This function can modify either the logical or physical palette by specifying SDL_LOGPAL or SDL_PHYSPAL the in the flags parameter.</p>
+<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
+the surface and a physical palette (that determines how the hardware will map the colors to the display).
+Non screen surfaces have a logical palette only. <a href="#blit">SDL::Video::blit</a> always uses the logical palette when blitting surfaces (if it has to
+convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various
+special color effects (e.g., screen fading, color flashes, screen dimming).</p>
+<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>
<p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
-If SDL_HWPALETTE was set in SDL::set_video_mode flags, SDL::set_palette will always return 1, and the palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
-The color components of a SDL::Color structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
-<p>If surface is not a palettized surface, this function does nothing, returning 0. If all of the colors were set as passed to SDL_SetPalette, it will return 1. If not all the color entries were set exactly as given, it will return 0, and you should look at the surface palette to determine the actual color palette.</p>
+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
+palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
+The color components of a <code>SDL::Color</code> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
+<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>,
+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
+to determine the actual color palette.</p>
</div>
-<h2 id="set_gamma_r_g_b">set_gamma(r,g,b)</h2>
-<div id="set_gamma_r_g_b_CONTENT">
+<h2 id="set_gamma">set_gamma</h2>
+<div id="set_gamma_CONTENT">
+<pre> $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
+
+</pre>
<p>Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen.
A gamma value of 1.0 is identity (i.e., no adjustment is made).</p>
-<p>This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment with SDL::set_gamma_ramp.</p>
-<p>Not all display hardware is able to change gamma.
-SDL::set_gamma returns -1 on error.</p>
-<p>Warning: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
+<p>This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment
+with SDL::set_gamma_ramp.</p>
+<p><strong>Note</strong>: Not all display hardware is able to change gamma.</p>
+<p><code>SDL::Video::set_gamma</code> returns <code>-1</code> on error.</p>
+<p><strong>Warning</strong>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ use SDL::Rect;
+ use Time::HiRes qw( usleep );
+
+ # the size of the window box or the screen resolution if fullscreen
+ my $screen_width = 800;
+ my $screen_height = 600;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ # setting video mode
+ my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
+
+ # drawing something somewhere
+ my $mapped_color = SDL::Video::map_RGB($screen_surface->format(), 128, 128, 128); # gray
+ SDL::Video::fill_rect($screen_surface,
+ SDL::Rect->new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
+ $mapped_color);
+
+ # update the whole screen
+ SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
+
+ usleep(500000);
+
+ for(1..20)
+ {
+ SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
+ usleep(40000);
+ }
+
+ for(1..20)
+ {
+ SDL::Video::set_gamma( $_ / 20, 1, 1 );
+ usleep(40000);
+ }
+
+ SDL::Video::set_gamma( 1, 1, 1 );
+
+ usleep(500000);
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="get_gamma_ramp_rt_gt_bt_to_be_coded">get_gamma_ramp(rt,gt,bt) * to be coded</h2>
-<div id="get_gamma_ramp_rt_gt_bt_to_be_coded_">
+<h2 id="get_gamma_ramp">get_gamma_ramp</h2>
+<div id="get_gamma_ramp_CONTENT">
+<pre> $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
+
+</pre>
<p>Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
-SDL::get_gamma_ramp returns -1 on error.</p>
+<code>SDL::Video::get_gamma_ramp</code> returns -1 on error.</p>
+<pre> use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my (@red, @green, @blue);
+
+ my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
+
+ if( -1 == $ret )
+ {
+ print( "an error occoured" );
+ }
+ else
+ {
+ printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
+ printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
+ printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
+ }
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</h2>
-<div id="set_gamma_ramp_rt_gt_bt_CONTENT">
-<p>Sets the gamma lookup tables for the display for each color component. Each table is an array of 256 Uint16 values, representing a mapping between the input and output for that channel.
+<h2 id="set_gamma_ramp">set_gamma_ramp</h2>
+<div id="set_gamma_ramp_CONTENT">
+<pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
+
+</pre>
+<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
+mapping between the input and output for that channel.
The input is the index into the array, and the output is the 16-bit gamma value at that index, scaled to the output color precision.
You may pass NULL to any of the channels to leave them unchanged.</p>
-<p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter with SDL::set_gamma.</p>
+<p>This function adjusts the gamma based on lookup tables, you can also have the gamma calculated based on a "gamma function" parameter
+with <a href="#set_gamma">SDL::Video::set_gamma</a>.</p>
<p>Not all display hardware is able to change gamma.
-SDL::set_gamma_ramp returns -1 on error.</p>
+<code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my (@red, @green, @blue);
+
+ my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
+
+ $red[127] = 0xFF00;
+
+ $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
+
+ $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
+
+ if( -1 == $ret )
+ {
+ print( "an error occoured" );
+ }
+ else
+ {
+ printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
+ printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
+ printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0], $green[0], $blue[0] );
+ }
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</h2>
-<div id="map_RGB_pixel_format_r_g_b_CONTENT">
-<p>Maps the RGB color value to the specified SDL::pixel_format and returns the pixel value as a 32-bit int.
+<h2 id="map_RGB">map_RGB</h2>
+<div id="map_RGB_CONTENT">
+<pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
+
+</pre>
+<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.
If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
-<p>SDL::map_RGP returns a pixel value best approximating the given RGB color value for a given pixel format.
-If the SDL::pixel_format's bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
+<p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
+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
+(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>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::PixelFormat;
+ use SDL::Surface;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
+ # ^-- 16 bits per pixel
+
+ $r = 0x9C;
+ $g = 0xDC;
+ $b = 0x67;
+
+ printf( "for 24bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b);
+
+ my $_16bit = SDL::Video::map_RGB( $screen_surface->format, $r, $g, $b );
+
+ # 16bpp is 5 bits red, 6 bits green and 5 bits blue
+ # we will obtain the values for each color and calculating them back to 24/32bit color system
+ ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface->format, $_16bit ) };
+
+ printf( "for 16bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b );
+
+ # so color #9CDC67 becomes #9CDF63
+
+ SDL::quit();
+
+</pre>
</div>
-<h2 id="map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</h2>
-<div id="map_RGBA_pixel_format_r_g_b_a_CONTEN">
-<p>Maps the RGBA color value to the specified SDL::pixel_format and returns the pixel value as a 32-bit int.
+<h2 id="map_RGBA">map_RGBA</h2>
+<div id="map_RGBA_CONTENT">
+<pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b, $a );
+
+</pre>
+<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.
If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette). </p>
<p>A pixel value best approximating the given RGBA color value for a given pixel format.
-If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
+If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g.,
+with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
</div>
-<h2 id="get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</h2>
-<div id="get_RGB_pixel_format_pixel_CONTENT">
-<p>Returns RGB values from a pixel in the specified pixel format.
-This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
+<h2 id="get_RGB">get_RGB</h2>
+<div id="get_RGB_CONTENT">
+<pre> $rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel );
+
+</pre>
+<p>Returns RGB values from a pixel in the specified pixel format. The pixel is an integer (e.g. 16bit RGB565, 24/32bit RGB888).
+This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
+component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
+<p>For an example see <a href="#map_RGB">SDL::Video::map_RGB</a>.</p>
</div>
-<h2 id="get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</h2>
-<div id="get_RGBA_pixel_format_pixel_CONTENT">
+<h2 id="get_RGBA">get_RGBA</h2>
+<div id="get_RGBA_CONTENT">
+<pre> $rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel );
+
+</pre>
<p>Gets RGBA values from a pixel in the specified pixel format.
-This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
+This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
+component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
<p>If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque). </p>
</div>
-<h2 id="create_RGB_surface_from">create_RGB_surface_from ***</h2>
-<div id="create_RGB_surface_from_CONTENT">
-<p>Creates an empty SDL::Surface from pixel data
-Allocate an empty surface (must be called after SDL::set_video_mode)
-If bitsPerPixel is 8 an empty palette is allocated for the surface, otherwise a 'packed-pixel' SDL::pixel_format is created using the [RGBA]mask's provided (see SDL::pixel_format). The flags specifies the type of surface that should be created, it is an OR'd combination of the following possible values. </p>
-<dl>
- <dt>SDL_SWSURFACE</dt>
- <dd>
- <p>SDL will create the surface in system memory.
-This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.</p>
- </dd>
- <dt>SDL_HWSURFACE</dt>
- <dd>
- <p>SDL will attempt to create the surface in video memory.
-This will allow SDL to take advantage of Video->Video blits (which are often accelerated).</p>
- </dd>
- <dt>SDL_SRCCOLORKEY</dt>
- <dd>
- <p>This flag turns on color keying for blits from this surface.
-If SDL_HWSURFACE is also specified and color keyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory.
-If the screen is a hardware surface and color keyed blits are hardware-accelerated then the SDL_HWSURFACE flag will be set.
-Use SDL_SetColorKey to set or clear this flag after surface creation.</p>
- </dd>
- <dt>SDL_SRCALPHA</dt>
- <dd>
- <p>This flag turns on alpha-blending for blits from this surface.
-If SDL_HWSURFACE is also specified and alpha-blending blits are hardware-accelerated,
-then the surface will be placed in video memory if possible.
-If the screen is a hardware surface and alpha-blending blits are hardware-accelerated then the SDL_HWSURFACE flag will be set.
-Use SDL_SetAlpha to set or clear this flag after surface creation.</p>
- </dd>
-</dl>
+<h1 id="GL_Methods">GL Methods</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="GL_Methods_CONTENT">
+</div>
+<h2 id="GL_load_library">GL_load_library</h2>
+<div id="GL_load_library_CONTENT">
+<pre> $gl_load_lib = SDL::Video::GL_load_library( 'path/to/static/glfunctions.dll' );
+</pre>
+<p>If you wish, you may load the OpenGL library from the given path at runtime, this must be done before
+<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
+function pointers to GL functions. </p>
+<p><code>GL_load_library</code> returns <code>0</code> on success or <code>-1</code> or error.</p>
+</div>
+<h2 id="GL_get_proc_address">GL_get_proc_address</h2>
+<div id="GL_get_proc_address_CONTENT">
+<pre> $proc_address = SDL::Video::GL_get_proc_address( $proc );
-<p>[RGBA]mask are the bitmasks used to extract that colour from a pixel.
-For instance, Rmask being FF000000 means the red data is stored in the most significant byte.
-Using zeros for the RGB masks sets a default value, based on the depth. (e.g. SDL::create_RGB_surface(flags,w,h,32,0,0,0,0);).
-However, using zero for the Amask results in an Amask of 0.
-It returns a SDL::Surface on success or undef on error.
-Notes: If an alpha-channel is specified (that is, if Amask is nonzero), then the SDL_SRCALPHA flag is automatically set.
-You may remove this flag by calling SDL::set_alpha after surface creation.
-Also, if the SDL_HWSURFACE flag is set on the returned surface, its format might not match the requested format. </p>
-<p>Notes: Sometimes specifying an Alpha mask value could cause strange results.
-This can be worked around by setting the Amask parameter to 0, but still including the SDL_SRCALPHA flag, and then using SDL::set_alpha, also with the SDL_SRCALPHA flag. </p>
+</pre>
+<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
+<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
+pointers to OpenGL extensions. Note that this function needs an OpenGL context to function properly, so it should be called after
+<a href="#set_video_mode">SDL::Video::set_video_mode</a> has been called (with the <code>SDL_OPENGL</code> flag).</p>
+<p>It returns undef if the function is not found.</p>
+<p>Example:</p>
+<pre> my $has_multitexture = 1;
-</div>
-<h2 id="lock_surface_surface">lock_surface(surface)</h2>
-<div id="lock_surface_surface_CONTENT">
-<p>SDL::lock_surface sets up the given SDL::surface for directly accessing the pixels.
-Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to and read from surface->pixels, using the pixel format stored in surface->format.
-Once you are done accessing the surface, you should use SDL::unlock_surface to release the lock.</p>
-<p>Not all surfaces require locking. If SDL::MUSTLOCK(surface) evaluates to 0, then reading and writing pixels to the surface can be performed at any time, and the pixel format of the surface will not change.
-No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
-SDL::lock_surface returns 0 on succés or -1 on error.</p>
-<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 a matching unlock.</p>
+ # Get function pointer
+ $gl_active_texture_ARB_ptr = SDL::Video::GL_get_proc_address("glActiveTextureARB");
-</div>
-<h2 id="unlock_surface_surface">unlock_surface(surface)</h2>
-<div id="unlock_surface_surface_CONTENT">
-<p>Surfaces that were previously locked using SDL::lock_surface must be unlocked with SDL::unlock_surface. Surfaces should be unlocked as soon as possible.
-SDL::unlock_surface doesn't return anything.</p>
-<p>Note : Since 1.1.8, the surface locks are recursive. See <code>SDL::lock_surface</code> for more information. </p>
+ # Check for a valid function ptr
+ unless($gl_active_texture_ARB_ptr)
+ {
+ printf( STDERR "Multitexture Extensions not present.\n" );
+ $has_multitexture = 0;
+ }
-</div>
-<h2 id="convert_surface_surface_format_flags">convert_surface(surface,format,flags)</h2>
-<div id="convert_surface_surface_format_flags-2">
-<p>Creates a new SDL::surface of the specified SDL::pixel_format, and then copies and maps the given surface to it.
-It is also useful for making a copy of a surface.</p>
-<p>The flags parameter is passed to SDL::create_RGB_surface and has those semantics.
-This function is used internally by SDL::display_format.
-This function can only be called after SDL::init. </p>
-<p>it returns a SDL::surface on succés or undef on error.</p>
+ $gl_active_texture_ARB_ptr(GL_TEXTURE0_ARB) if $has_multitexture;
+
+</pre>
</div>
-<h2 id="display_format">display_format</h2>
-<div id="display_format_CONTENT">
-<p>Converts a surface to the display format </p>
+<h2 id="GL_get_attribute">GL_get_attribute</h2>
+<div id="GL_get_attribute_CONTENT">
+<pre> $value = SDL::Video::GL_get_attribute( $attr );
+
+</pre>
+<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
+attributes have been set as you expected.
+<code>SDL::Video::GL_get_attribute</code> returns <code>undef</code> if the attribute is not found.</p>
+<p>Example:</p>
+<pre> print( SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE) );
+
+</pre>
</div>
-<h2 id="display_format_alpha">display_format_alpha</h2>
-<div id="display_format_alpha_CONTENT">
-<p>Converts a surface to the display format </p>
+<h2 id="GL_set_attribute">GL_set_attribute</h2>
+<div id="GL_set_attribute_CONTENT">
+<pre> $set_attr = SDL::Video::GL_set_attribute( $attr, $value );
+
+</pre>
+<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
+<a href="#set_video_mode">SDL::Video::set_video_mode</a>.
+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,
+since the values obtained can differ from the requested ones.</p>
+<p>Available attributes:</p>
+<ul>
+ <li><code>SDL_GL_RED_SIZE</code> </li>
+ <li><code>SDL_GL_GREEN_SIZE</code> </li>
+ <li><code>SDL_GL_BLUE_SIZE</code> </li>
+ <li><code>SDL_GL_ALPHA_SIZE</code> </li>
+ <li><code>SDL_GL_BUFFER_SIZE</code> </li>
+ <li><code>SDL_GL_DOUBLEBUFFER</code> </li>
+ <li><code>SDL_GL_DEPTH_SIZE</code> </li>
+ <li><code>SDL_GL_STENCIL_SIZE</code> </li>
+ <li><code>SDL_GL_ACCUM_RED_SIZE</code> </li>
+ <li><code>SDL_GL_ACCUM_GREEN_SIZE</code> </li>
+ <li><code>SDL_GL_ACCUM_BLUE_SIZE</code> </li>
+ <li><code>SDL_GL_ACCUM_ALPHA_SIZE</code> </li>
+ <li><code>SDL_GL_STEREO</code> </li>
+ <li><code>SDL_GL_MULTISAMPLEBUFFERS</code> </li>
+ <li><code>SDL_GL_MULTISAMPLESAMPLES</code> </li>
+ <li><code>SDL_GL_ACCELERATED_VISUAL</code> </li>
+ <li><code>SDL_GL_SWAP_CONTROL</code></li>
+</ul>
+
+<p><code>GL_set_attribute</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
+<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
+or disabled using the <code>SDL_GL_DOUBLEBUFFER</code> attribute. </p>
+<p>Example:</p>
+<pre> SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE, 5);
+
+</pre>
</div>
-<h2 id="load_BMP_filename">load_BMP(filename)</h2>
-<div id="load_BMP_filename_CONTENT">
-<p>Loads a SDL::surface from a named Windows BMP file.
-SDL::load_BMP returns a SDL::surface on succés or undef on error.</p>
-<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>
+<h2 id="GL_swap_buffers">GL_swap_buffers</h2>
+<div id="GL_swap_buffers_CONTENT">
+<pre> SDL::Video::GL_swap_buffers();
+</pre>
+<p>Swap the OpenGL buffers, if double-buffering is supported.
+<code>SDL::Video::GL_swap_buffers</code> doesn't returns any value.</p>
+</div>
+<h1 id="Video_Overlay_Functions">Video Overlay Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Video_Overlay_Functions_CONTENT">
+<p>see <a href="SDL-Overlay.html">SDL::Overlay</a> </p>
+</div>
+<h2 id="lock_YUV_overlay">lock_YUV_overlay</h2>
+<div id="lock_YUV_overlay_CONTENT">
+<pre> $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );
+</pre>
+<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.
+It returns <code>0</code> on success or <code>-1</code> on error.</p>
+</div>
+<h2 id="unlock_YUV_overlay">unlock_YUV_overlay</h2>
+<div id="unlock_YUV_overlay_CONTENT">
+<pre> SDL::Video::unlock_YUV_overlay( $overlay );
+</pre>
+<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
+can be displayed. <code>unlock_YUV_overlay</code> does not return anything.</p>
+</div>
+<h2 id="display_YUV_overlay">display_YUV_overlay</h2>
+<div id="display_YUV_overlay_CONTENT">
+<pre> $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );
+
+</pre>
+<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
+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.
+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>
+<p>It returns <code>0</code> on success or <code>-1</code> on error.</p>
</div>
-<h2 id="save_BMP_surface_filename">save_BMP(surface,filename)</h2>
-<div id="save_BMP_surface_filename_CONTENT">
-<p>Saves the given SDL::Surface surface as a Windows BMP file named filename.
-it returns 0 on succés or -1 on error.</p>
+<h1 id="Window_Management_Functions">Window Management Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="Window_Management_Functions_CONTENT">
</div>
-<h2 id="set_color_key_surface_flag_key">set_color_key(surface,flag,key)</h2>
-<div id="set_color_key_surface_flag_key_CONTE">
-<p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
-<p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value).
-The key must be of the same pixel format as the surface, SDL::map_RGB is often useful for obtaining an acceptable value.
-If flag is SDL_SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.</p>
-<p>If flag is OR'd with SDL_RLEACCEL then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface.
-The surface will actually be encoded for RLE acceleration the first time SDL::blit_surface or SDL::display_format is called on the surface.
-If flag is 0, this function clears any current color key. </p>
-<p>SDL::set_color_key returns 0 on succés or -1 on error.</p>
+<h2 id="wm_set_caption">wm_set_caption</h2>
+<div id="wm_set_caption_CONTENT">
+<pre> SDL::Video::wm_set_caption( $title, $icon );
+</pre>
+<p>Sets the title-bar and icon name of the display window.</p>
+<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
+does not change the string. You may free the string after the function returns.</p>
+<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
+bar or desktop when the window is minimized). As with title this string may be freed after the function returns. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ SDL::init(SDL_INIT_VIDEO);
+ my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
-</div>
-<h2 id="set_alpha_surface_flag_key">set_alpha(surface,flag,key)</h2>
-<div id="set_alpha_surface_flag_key_CONTENT">
-<p>SDL::set_alpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
-<p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
-flags is used to specify whether alpha blending should be used (SDL_SRCALPHA) and whether the surface should use RLE acceleration for blitting (SDL_RLEACCEL).
-flags can be an OR'd combination of these two options, one of these options or 0.
-If SDL_SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface.
-The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with SDL_RLEACCEL.</p>
-<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>
-<p>Alpha affects surface blitting in the following ways: </p>
-<dl>
- <dt>RGBA->RGB with SDL_SRCALPHA</dt>
- <dd>
- <p>The source is alpha-blended with the destination, using the alpha channel.
-SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
- </dd>
- <dt>RGBA->RGB without SDL_SRCALPHA</dt>
- <dd>
- <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
- </dd>
- <dt>RGB->RGBA with SDL_SRCALPHA</dt>
- <dd>
- <p>The source is alpha-blended with the destination using the per-surface alpha value.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
-The alpha channel of the copied pixels is set to opaque.</p>
- </dd>
- <dt>RGB->RGBA without SDL_SRCALPHA</dt>
- <dd>
- <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
- </dd>
- <dt>RGBA->RGBA with SDL_SRCALPHA</dt>
- <dd>
- <p>The source is alpha-blended with the destination using the source alpha channel.
-The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
- </dd>
- <dt>RGBA->RGBA without SDL_SRCALPHA</dt>
- <dd>
- <p>The RGBA data is copied to the destination surface.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
- </dd>
- <dt>RGB->RGB with SDL_SRCALPHA</dt>
- <dd>
- <p>The source is alpha-blended with the destination using the per-surface alpha value.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
- </dd>
- <dt>RGB->RGB without SDL_SRCALPHA</dt>
- <dd>
- <p>The RGB data is copied from the source.
-If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
- </dd>
-</dl>
-<p>Note: When blitting, the presence or absence of SDL_SRCALPHA is relevant only on the source surface, not the destination.
-Note: Note that RGBA->RGBA blits (with SDL_SRCALPHA set) keep the alpha of the destination surface. This means that you cannot compose two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask.</p>
-<p>Note: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available. </p>
-<p>SDL::set_alpha returns 0 on succés or -1 on error.</p>
+ sleep(2);
-</div>
-<h2 id="set_clip_rect_surface_rect">set_clip_rect(surface,rect)</h2>
-<div id="set_clip_rect_surface_rect_CONTENT">
-<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 rectangle will be drawn into.
-The rectangle pointed to by rect will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall outside the edges of the surface.
-If rect is NULL the clipping rectangle will be set to the full size of the surface.
-SDL::set_clip_rect doesn't returns anything.</p>
+ SDL::quit;
+
+</pre>
</div>
-<h2 id="get_clip_rect_surface_rect">get_clip_rect(surface,rect)</h2>
-<div id="get_clip_rect_surface_rect_CONTENT">
-<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 rectangle is drawn into.
-The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
-SDL::get_clip_rect doesn't returns anything;</p>
+<h2 id="wm_get_caption">wm_get_caption</h2>
+<div id="wm_get_caption_CONTENT">
+<pre> SDL::Video::wm_get_caption( $title, $icon );
+</pre>
+<p>Retrieves the title-bar and icon name of the display window.</p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ SDL::init(SDL_INIT_VIDEO);
+ my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
-</div>
-<h2 id="blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</h2>
-<div id="blit_surface_src_src_rect_dest_dest_-2">
-<p>This performs a fast blit from the given source SDL::surface to the given destination SDL::surface.
-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 are ignored). Blits with negative dstrect coordinates will be clipped properly.
-If srcrect is NULL, the entire surface is copied. If dstrect is NULL, then the destination position (upper left corner) is (0, 0).
-The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).
-The blit function should not be called on a locked surface. I.e. when you use your own drawing functions you may need to lock a surface, but this is not the case with SDL::blit_surface. Like most surface manipulation functions in SDL, it should not be used together with OpenGL.</p>
-<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 how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
-SDL::blit_surface doesn't returns anything.</p>
+ my ($title, $icon) = @{ SDL::Video::wm_get_caption() };
-</div>
-<h2 id="fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</h2>
-<div id="fill_rect_dest_dest_rect_pixel_CONTE">
-<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 will be filled with color.</p>
-<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.
-If the color value contains an alpha value then the destination is simply "filled" with that alpha information, no blending takes place.</p>
-<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 of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually filled.</p>
-<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 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>
-<p>SDL::fill_rect returns 0 on succés or -1 on error.</p>
+ printf( "title is '%s' and icon is '%s'\n", $title, $icon );
-</div>
-<h2 id="GL_load_library_path">GL_load_library(path)</h2>
-<div id="GL_load_library_path_CONTENT">
-<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.
-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 SDL::GL_get_proc_address to retrieve function pointers to GL functions. </p>
-<p>SDL::GL_load_library returns 0 on succés or -1 or error.</p>
+ SDL::quit;
-</div>
-<h2 id="GL_get_proc_address_proc">GL_get_proc_address(proc)</h2>
-<div id="GL_get_proc_address_proc_CONTENT">
-<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 SDL::GL_load_library, then all GL functions must be retrieved this way. Usually this is used to retrieve function pointers to OpenGL extensions. Note that this function needs an OpenGL context to function properly, so it should be called after SDL::set_video_mode has been called (with the SDL_OPENGL flag).</p>
-<p>OpenGL function pointers must be declared APIENTRY . This will ensure the proper calling convention is followed on platforms where this matters (Win32) thereby avoiding stack corruption. In a Win32 build environment, APIENTRY should be defined as __stdcall. </p>
-<p>it returns undef if the function is not found.</p>
+</pre>
</div>
-<h2 id="GL_get_attribute_attr">GL_get_attribute(attr)</h2>
-<div id="GL_get_attribute_attr_CONTENT">
-<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 as you expected.
-SDL::GL_get_attribute returns undef if the attribute is not found.</p>
+<h2 id="wm_set_icon">wm_set_icon</h2>
+<div id="wm_set_icon_CONTENT">
+<pre> SDL::Video::wm_set_icon( $icon );
-</div>
-<h2 id="GL_set_attribute_attr_value">GL_set_attribute(attr,value)</h2>
-<div id="GL_set_attribute_attr_value_CONTENT">
-<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.
-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 requested ones.
-See SDL_GLattr for the full list of available attributes.
-SDL::GL_set_attribute returns 0 on succés or -1 on error.</p>
-<p>Note : The SDL_DOUBLEBUF flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled or disabled using the SDL_GL_DOUBLEBUFFER attribute. </p>
+</pre>
+<p>Sets the icon for the display window. Win32 icons must be 32x32.</p>
+<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>
+cannot be used.</p>
+<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
+(no transparency).</p>
+<p>Example:</p>
+<pre> SDL::Video::wm_set_icon(SDL::Video::load_BMP("icon.bmp"));
+
+</pre>
+<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>
+<p>Example:</p>
+<pre> my $image = SDL::Video::load_BMP("icon.bmp");
+
+ my colorkey = SDL::Video::map_RGB($image->format, 255, 0, 255); # specify the color that will be transparent
+
+ SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);
+
+ SDL::Video::wm_set_icon($image);
+
+</pre>
</div>
-<h2 id="GL_swap_buffers">GL_swap_buffers</h2>
-<div id="GL_swap_buffers_CONTENT">
-<p>Swap the OpenGL buffers, if double-buffering is supported.
-SDL::GL_swap_buffers doesn't returns any value.</p>
+<h2 id="wm_grab_input">wm_grab_input</h2>
+<div id="wm_grab_input_CONTENT">
+<pre> $grab_mode = SDL::Video::wm_grab_input($mode);
+
+</pre>
+<p>Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application,
+and not interpreted by a window manager, if any.</p>
+<p>When mode is <code>SDL_GRAB_QUERY</code> the grab mode is not changed, but the current grab mode is returned.</p>
+<p><code>mode</code> and the return value of <code>wm_grab_input</code> can be one of the following:</p>
+<ul>
+ <li><code>SDL_GRAB_QUERY</code> </li>
+ <li><code>SDL_GRAB_OFF</code> </li>
+ <li><code>SDL_GRAB_ON</code></li>
+</ul>
+
</div>
-<h2 id="GL_attr_to_be_coded">GL_attr *** to be coded</h2>
-<div id="GL_attr_to_be_coded_CONTENT">
+<h2 id="wm_iconify_window">wm_iconify_window</h2>
+<div id="wm_iconify_window_CONTENT">
+<pre> $iconify_window = SDL::Video::wm_iconify_window();
+</pre>
+<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,
+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>
+<p>Returns non-zero on success or 0 if iconification is not supported or was refused by the window manager. </p>
+<p>Example:</p>
+<pre> use SDL;
+ use SDL::Video;
+ use SDL::Surface;
+ SDL::init(SDL_INIT_VIDEO);
+ my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
+ sleep(2);
-</div>
-<h2 id="lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</h2>
-<div id="lock_YUV_overlay_overlay_CONTENT">
-<p>Much the same as <code>SDL::lock_surface</code>, SDL::lock_YUV_overlay locks the overlay for direct access to pixel data.
-It returns 0 on succés or -1 on error.</p>
+ SDL::Video::wm_iconify_window();
-</div>
-<h2 id="unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</h2>
-<div id="unlock_YUV_overlay_overlay_CONTENT">
-<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.
-It returns 0 on succés or -1 on error.</p>
+ sleep(2);
-</div>
-<h2 id="display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</h2>
-<div id="display_YUV_overlay_overlay_dstrect_">
-<p>Blit the overlay to the display surface specified when the overlay was created. The SDL::rect structure, dstrect, specifies a rectangle on the display where the overlay is drawn. The .x and .y fields of dstrect specify the upper left location in display coordinates. The overlay is scaled (independently in x and y dimensions) to the size specified by dstrect, and is optimized for 2x scaling</p>
-<p>It returns 0 on succés or -1 on error.</p>
+ SDL::quit;
+</pre>
+</div>
+<h2 id="wm_toggle_fullscreen">wm_toggle_fullscreen</h2>
+<div id="wm_toggle_fullscreen_CONTENT">
+<pre> $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
+</pre>
+<p>Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support
+is experimental).</p>
+</div>
+<h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="AUTHORS_CONTENT">
+<p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
</div>
<h2 id="Category_Objects">Category Objects</h2>
<div id="Category_Objects_CONTENT">
-<p><cite>SDL::Surface</cite>, <cite>SDL::Overlay</cite>, <cite>SDL::Color</cite>,
-<cite>SDL::Rect</cite>, <cite>SDL::Palette</cite>, <cite>SDL::PixelFormat</cite>,
-<cite>SDL::VideoInfo</cite></p>
+<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>,
+<a href="SDL-Rect.html">SDL::Rect</a>, <a href="SDL-Palette.html">SDL::Palette</a>, <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>,
+<a href="SDL-VideoInfo.html">SDL::VideoInfo</a></p>
</div>
</div>
\ No newline at end of file
projects / sdlgit/SDL-Site.git / blobdiff