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