projects / sdlgit/SDL-Site.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | history | HEAD
docs for video done
[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>
12<li><a href="#list_modes_formats_flags">list_modes(formats,flags)</a></li>
13<li><a href="#video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</a></li>
14<li><a href="#set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</a>
162a0989 15<ul><li><a href="#List_of_avalaibles_flags">List of avalaibles flags</a></li>
16</ul>
17</li>
b968d0e8 18<li><a href="#convert_surface_surface_format_flags">convert_surface(surface,format,flags)</a></li>
19<li><a href="#display_format">display_format</a></li>
20<li><a href="#display_format_alpha">display_format_alpha</a></li>
21<li><a href="#load_BMP_filename">load_BMP(filename)</a></li>
22<li><a href="#save_BMP_surface_filename">save_BMP(surface,filename)</a></li>
23<li><a href="#set_color_key_surface_flag_key">set_color_key(surface,flag,key)</a></li>
24<li><a href="#set_alpha_surface_flag_key">set_alpha(surface,flag,key)</a></li>
25<li><a href="#fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</a></li>
26</ul>
27</li>
28<li><a href="#Surface_locking_and_unlocking">Surface locking and unlocking</a>
29<ul><li><a href="#lock_surface_surface">lock_surface(surface)</a></li>
30<li><a href="#unlock_surface_surface">unlock_surface(surface)</a></li>
31<li><a href="#MUSTLOCK_surface">MUSTLOCK(surface)</a></li>
32</ul>
33</li>
34<li><a href="#Screen_Updating_Functions">Screen Updating Functions</a>
35<ul><li><a href="#set_clip_rect_surface_rect">set_clip_rect(surface,rect)</a></li>
36<li><a href="#get_clip_rect_surface_rect">get_clip_rect(surface,rect)</a></li>
37<li><a href="#blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</a></li>
162a0989 38<li><a href="#update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</a></li>
39<li><a href="#update_rects_surface_rects">update_rects(surface,rects) </a></li>
40<li><a href="#flip_surface">flip(surface)</a></li>
b968d0e8 41</ul>
42</li>
43<li><a href="#Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</a>
44<ul><li><a href="#set_colors_surface_start_colors">set_colors(surface,start,colors)</a></li>
162a0989 45<li><a href="#set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</a></li>
46<li><a href="#set_gamma_r_g_b">set_gamma(r,g,b)</a></li>
904171e2 47<li><a href="#get_gamma_ramp_rt_gt_bt">get_gamma_ramp(rt,gt,bt)</a></li>
162a0989 48<li><a href="#set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</a></li>
49<li><a href="#map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</a></li>
50<li><a href="#map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</a></li>
51<li><a href="#get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</a></li>
52<li><a href="#get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</a></li>
3540cbee 53</ul>
54</li>
55<li><a href="#GL_Methods">GL Methods</a>
56<ul><li><a href="#GL_load_library_path">GL_load_library(path)</a></li>
162a0989 57<li><a href="#GL_get_proc_address_proc">GL_get_proc_address(proc)</a></li>
58<li><a href="#GL_get_attribute_attr">GL_get_attribute(attr)</a></li>
59<li><a href="#GL_set_attribute_attr_value">GL_set_attribute(attr,value)</a></li>
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>
3540cbee 64<ul><li><a href="#lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</a></li>
162a0989 65<li><a href="#unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</a></li>
66<li><a href="#display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</a></li>
67</ul>
68</li>
b968d0e8 69<li><a href="#Window_Management_Functions">Window Management Functions</a>
70<ul><li><a href="#wm_set_caption_title_icon">wm_set_caption(title,icon)</a></li>
71<li><a href="#wm_get_caption">wm_get_caption()</a></li>
72<li><a href="#wm_set_icon_icon">wm_set_icon(icon)</a></li>
73<li><a href="#wm_grab_input_mode">wm_grab_input(mode)</a></li>
74<li><a href="#wm_iconify_window">wm_iconify_window()</a></li>
75<li><a href="#wm_toggle_fullscreen_surface">wm_toggle_fullscreen(surface)</a></li>
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>
52432657 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>
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
155<a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>, the <code>vfmt</code> member of the returned structure will contain the pixel
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>
195<h2 id="list_modes_formats_flags">list_modes(formats,flags)</h2>
196<div id="list_modes_formats_flags_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>
233<h2 id="video_mode_ok_width_height_bpp_flags">video_mode_ok(width,height,bpp,flags)</h2>
234<div id="video_mode_ok_width_height_bpp_flags-2">
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
239are the same as those you would pass to <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>.
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>
259<h2 id="set_video_mode_width_height_bpp_flag">set_video_mode(width,height,bpp,flags)</h2>
260<div id="set_video_mode_width_height_bpp_flag-2">
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.
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
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>
7067312b 296 <p>Enable hardware double buffering; only valid with <code>SDL_HWSURFACE</code>. Calling <a href="#flip_surface">SDL::Video::flip</a> will flip the buffers and update
297the screen.
449a007b 298All drawing will take place on the surface that is not displayed at the moment.
7067312b 299If double buffering could not be enabled then <a href="#flip_surface">SDL::Video::flip</a> will just perform a
300<a href="#update_rect_surface_x_y_width_height">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
310<a href="#GL_set_attribute_attr_value">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
322<a href="#set_video_mode_width_height_bpp_flag">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
343<a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a> (although there is no harm in executing the initialization code after
344each call to <a href="#set_video_mode_width_height_bpp_flag">SDL::Video::set_video_mode</a>, for example for a multiplatform application). </p>
162a0989 345
346</div>
b968d0e8 347<h2 id="convert_surface_surface_format_flags">convert_surface(surface,format,flags)</h2>
348<div id="convert_surface_surface_format_flags-2">
878ae663 349<pre> $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
350
351</pre>
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>
8edb6a07 354<p>The flags parameter is passed to <code>SDL::Surface-&gt;new()</code> and has those semantics.
878ae663 355This function is used internally by <code>SDL::Video::display_format</code>.
356This function can only be called after <code>SDL::init</code>. </p>
357<p>it returns a <code>SDL::Surface</code> 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
366blitting onto the display surface. It calls <code>SDL::Video::convert_surface</code>.</p>
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,
380suitable for fast blitting onto the display surface. It calls <code>SDL::Video::convert_surface</code>.</p>
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>
385<p><strong>Note</strong>: The video surface must be initialised using <code>SDL::Video::set_video_mode</code> before this function is called, or it will segfault.</p>
b968d0e8 386
387</div>
388<h2 id="load_BMP_filename">load_BMP(filename)</h2>
389<div id="load_BMP_filename_CONTENT">
878ae663 390<pre> $surface = SDL::Video::load_BMP( $filename );
391
392</pre>
393<p>Loads a <code>SDL::Surface</code> from a named Windows BMP file.
394<code>SDL::Video::load_BMP</code> returns a <code>SDL::Surface</code> on success or <code>undef</code> on error.</p>
395<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>
396<pre> use SDL;
397 use SDL::Video;
398 use SDL::Rect;
399 use SDL::Surface;
400
401 my $screen_width = 640;
402 my $screen_height = 480;
403
404 SDL::init(SDL_INIT_VIDEO);
405
406 my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
407
408 my $picture = SDL::Video::load_BMP('test.bmp');
409
410 die(SDL::get_error) unless $picture;
b968d0e8 411
878ae663 412 my $rect = SDL::Rect-&gt;new(0, 0, $screen_width, $screen_height);
b968d0e8 413
878ae663 414 SDL::Video::blit_surface( $picture, SDL::Rect-&gt;new(0, 0, $picture-&gt;w, $picture-&gt;h),
415 $screen, SDL::Rect-&gt;new(0, 0, $screen-&gt;w, $screen-&gt;h) );
b968d0e8 416
878ae663 417 SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
b968d0e8 418
878ae663 419 sleep(2);
420
421 SDL::quit;
422
423</pre>
b968d0e8 424
425</div>
426<h2 id="save_BMP_surface_filename">save_BMP(surface,filename)</h2>
427<div id="save_BMP_surface_filename_CONTENT">
878ae663 428<pre> $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
429
430</pre>
431<p>Saves the given <code>SDL::Surface</code> as a Windows BMP file named filename.
b968d0e8 432it returns 0 on success or -1 on error.</p>
433
434</div>
435<h2 id="set_color_key_surface_flag_key">set_color_key(surface,flag,key)</h2>
436<div id="set_color_key_surface_flag_key_CONTE">
878ae663 437<pre> $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
438
439</pre>
b968d0e8 440<p>Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.</p>
441<p>RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match
442the key value).
878ae663 443The key must be of the same pixel format as the surface, <code>SDL::Video::map_RGB</code> is often useful for obtaining an acceptable value.
444If flag is <code>SDL_SRCCOLORKEY</code> then key is the transparent pixel value in the source image of a blit.</p>
445<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.
446The surface will actually be encoded for RLE acceleration the first time <code>SDL::Video::blit_surface</code> or <code>SDL::Video::display_format</code>
447is called on the surface.
448If <code>flag</code> is <code>0</code>, this function clears any current color key. </p>
449<p><code>SDL::Video::set_color_key</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
b968d0e8 450
451</div>
452<h2 id="set_alpha_surface_flag_key">set_alpha(surface,flag,key)</h2>
453<div id="set_alpha_surface_flag_key_CONTENT">
878ae663 454<pre> $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
455
456</pre>
457<p><code>set_alpha</code> is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.</p>
b968d0e8 458<p>The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust.
878ae663 459flags is used to specify whether alpha blending should be used ( <code>SDL_SRCALPHA</code> ) and whether the surface should use RLE acceleration for
460blitting ( <code>SDL_RLEACCEL</code> ).
461flags can be an OR'd combination of these two options, one of these options or <code>0</code>.
462If <code>SDL_SRCALPHA</code> is not passed as a flag then all alpha information is ignored when blitting the surface.
b968d0e8 463The 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 464still be accelerated with <code>SDL_RLEACCEL</code>.</p>
465<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 466<p>Alpha affects surface blitting in the following ways: </p>
467<dl>
468 <dt>RGBA-&gt;RGB with SDL_SRCALPHA</dt>
469 <dd>
470 <p>The source is alpha-blended with the destination, using the alpha channel.
471SDL_SRCCOLORKEY and the per-surface alpha are ignored.</p>
472 </dd>
473 <dt>RGBA-&gt;RGB without SDL_SRCALPHA</dt>
474 <dd>
475 <p>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.
476If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
477 </dd>
478 <dt>RGB-&gt;RGBA with SDL_SRCALPHA</dt>
479 <dd>
480 <p>The source is alpha-blended with the destination using the per-surface alpha value.
481If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
482The alpha channel of the copied pixels is set to opaque.</p>
483 </dd>
484 <dt>RGB-&gt;RGBA without SDL_SRCALPHA</dt>
485 <dd>
486 <p>The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque.
487If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
488 </dd>
489 <dt>RGBA-&gt;RGBA with SDL_SRCALPHA</dt>
490 <dd>
491 <p>The source is alpha-blended with the destination using the source alpha channel.
492The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.</p>
493 </dd>
494 <dt>RGBA-&gt;RGBA without SDL_SRCALPHA</dt>
495 <dd>
496 <p>The RGBA data is copied to the destination surface.
497If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
498 </dd>
499 <dt>RGB-&gt;RGB with SDL_SRCALPHA</dt>
500 <dd>
501 <p>The source is alpha-blended with the destination using the per-surface alpha value.
502If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
503 </dd>
504 <dt>RGB-&gt;RGB without SDL_SRCALPHA</dt>
505 <dd>
506 <p>The RGB data is copied from the source.
507If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.</p>
508 </dd>
509</dl>
878ae663 510<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.
511<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 512two 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 513<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>
514<p><code>SDL::Video::set_alpha</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
b968d0e8 515
516</div>
517<h2 id="fill_rect_dest_dest_rect_pixel">fill_rect(dest,dest_rect,pixel)</h2>
518<div id="fill_rect_dest_dest_rect_pixel_CONTE">
878ae663 519<pre> $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );
520
521</pre>
522<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 523will be filled with color.</p>
878ae663 524<p>The color should be a pixel of the format used by the surface, and can be generated by the <code>SDL::Video::map_RGB</code> or <code>SDL::Video::map_RGBA</code>
525functions. If the color value contains an alpha value then the destination is simply &quot;filled&quot; with that alpha information, no blending takes
526place.</p>
527<p>If there is a clip rectangle set on the destination (set via <code>SDL::Video::set_clip_rect</code>), then this function will clip based on the
528intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually filled.</p>
529<p>If you call this on the video surface (ie: the value of <code>SDL::Video::get_video_surface</code>) you may have to update the video surface to see the
b968d0e8 530result. 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 531<p><code>SDL::Video::fill_rect</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
532<p>for an example see <a href="#SYNOPSIS">SYNOPSIS</a>.</p>
b968d0e8 533
534</div>
535<h1 id="Surface_locking_and_unlocking">Surface locking and unlocking</h1><p><a href="#TOP" class="toplink">Top</a></p>
536<div id="Surface_locking_and_unlocking_CONTEN">
537
538</div>
539<h2 id="lock_surface_surface">lock_surface(surface)</h2>
540<div id="lock_surface_surface_CONTENT">
541<pre> int SDL::Video::lock_surface( $surface );
542
543</pre>
544<p><code>SDL::Video::lock_surface</code> sets up the given <a href="/SDL-Surface.html">SDL::Surface</a> for directly accessing the pixels.
545Between 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; ),
546using the pixel format stored in <code>surface-</code>format&gt;.
547Once you are done accessing the surface, you should use <code>SDL::Video::unlock_surface</code> to release the lock.</p>
548<p>Not all surfaces require locking. If <code>SDL::Video::MUSTLOCK(surface)</code> evaluates to <code>0</code>, then reading and writing pixels to the surface can
549be performed at any time, and the pixel format of the surface will not change.
550No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
551<code>SDL::Video::lock_surface</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
552<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
553a matching unlock.</p>
878ae663 554<pre> use strict;
555 use warnings;
556 use Carp;
557
558 use SDL v2.3;
b968d0e8 559 use SDL::Video;
878ae663 560 use SDL::Event;
561 use SDL::Events;
b968d0e8 562 use SDL::Surface;
563
878ae663 564 my $screen;
b968d0e8 565
878ae663 566 sub putpixel
567 {
568 my($x, $y, $color) = @_;
569 my $lineoffset = $y * ($screen-&gt;pitch / 4);
570 $screen-&gt;set_pixels( $lineoffset+ $x, $color);
571 }
b968d0e8 572
878ae663 573 sub render
b968d0e8 574 {
878ae663 575 if( SDL::Video::MUSTLOCK( $screen) )
576 {
577 return if (SDL::Video::lock_surface( $screen ) &lt; 0)
578 }
b968d0e8 579
878ae663 580 my $ticks = SDL::get_ticks();
581 my ($i, $y, $yofs, $ofs) = (0,0,0,0);
582 for ($i = 0; $i &lt; 480; $i++)
b968d0e8 583 {
878ae663 584 for (my $j = 0, $ofs = $yofs; $j &lt; 640; $j++, $ofs++)
585 {
586 $screen-&gt;set_pixels( $ofs, ( $i * $i + $j * $j + $ticks ) );
587 }
588 $yofs += $screen-&gt;pitch / 4;
b968d0e8 589 }
b968d0e8 590
878ae663 591 putpixel(10, 10, 0xff0000);
592 putpixel(11, 10, 0xff0000);
593 putpixel(10, 11, 0xff0000);
594 putpixel(11, 11, 0xff0000);
595
596 SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
b968d0e8 597
878ae663 598 SDL::Video::update_rect($screen, 0, 0, 640, 480);
599
600 return 0;
b968d0e8 601 }
878ae663 602
603 sub main
b968d0e8 604 {
878ae663 605 carp 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) &lt; 0);
606
607 $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
608
609 carp 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
610
611 while(1)
612 {
613 render();
614
615 my $event = SDL::Event-&gt;new();
616
617 while( SDL::Events::poll_event($event) )
618 {
619 my $type = $event-&gt;type;
620 return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
621 }
622 SDL::Events::pump_events();
623 }
b968d0e8 624 }
625
878ae663 626 main();
627
628 SDL::quit;
b968d0e8 629
630</pre>
631
632</div>
633<h2 id="unlock_surface_surface">unlock_surface(surface)</h2>
634<div id="unlock_surface_surface_CONTENT">
635<pre> void SDL::Video::unlock_surface( $surface );
636
637</pre>
638<p>Surfaces that were previously locked using <code>SDL::Video::lock_surface</code> must be unlocked with <code>SDL::Video::unlock_surface</code>. Surfaces should
639be unlocked as soon as possible.
640<code>SDL::Video::unlock_surface</code> doesn't return anything.</p>
641<p><strong>Note</strong>: Since 1.1.8, the surface locks are recursive. See <code>SDL::Video::lock_surface</code> for more information. </p>
642
643</div>
644<h2 id="MUSTLOCK_surface">MUSTLOCK(surface)</h2>
645<div id="MUSTLOCK_surface_CONTENT">
646<pre> int SDL::Video::MUSTLOCK( $surface );
647
648</pre>
649<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>
650
651</div>
652<h1 id="Screen_Updating_Functions">Screen Updating Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
653<div id="Screen_Updating_Functions_CONTENT">
654
655</div>
656<h2 id="set_clip_rect_surface_rect">set_clip_rect(surface,rect)</h2>
657<div id="set_clip_rect_surface_rect_CONTENT">
8edb6a07 658<pre> SDL::Video::set_clip_rect( $surface, $rect );
659
660</pre>
661<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 662rectangle will be drawn into.
663The 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
664outside the edges of the surface.
665If rect is NULL the clipping rectangle will be set to the full size of the surface.
8edb6a07 666<code>SDL::Video::set_clip_rect</code> doesn't returns anything.</p>
b968d0e8 667
668</div>
669<h2 id="get_clip_rect_surface_rect">get_clip_rect(surface,rect)</h2>
670<div id="get_clip_rect_surface_rect_CONTENT">
8edb6a07 671<pre> SDL::Video::get_clip_rect( $surface, $rect );
672
673</pre>
674<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 675rectangle is drawn into.
676The rectangle pointed to by rect will be filled with the clipping rectangle of the surface.
8edb6a07 677<code>SDL::Video::get_clip_rect</code> doesn't returns anything;</p>
678<pre> use SDL;
679 use SDL::Video;
680 use SDL::Rect;
681 use SDL::Surface;
682
683 my $screen_width = 640;
684 my $screen_height = 480;
b968d0e8 685
8edb6a07 686 SDL::init(SDL_INIT_VIDEO);
687
688 my $screen = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
b968d0e8 689
8edb6a07 690 my $rect = SDL::Rect-&gt;new(0, 0, 0, 0);
b968d0e8 691
8edb6a07 692 SDL::Video::get_clip_rect($screen, $rect);
b968d0e8 693
8edb6a07 694 printf( &quot;rect is %d, %d, %d, %d\n&quot;, $rect-&gt;x, $rect-&gt;y, $rect-&gt;w, $rect-&gt;h);
695
696 SDL::quit;
697
698</pre>
b968d0e8 699
700</div>
701<h2 id="blit_surface_src_src_rect_dest_dest_">blit_surface(src,src_rect,dest,dest_rect)</h2>
702<div id="blit_surface_src_src_rect_dest_dest_-2">
8edb6a07 703<pre> SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
704
705</pre>
706<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>.
707The 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>
708(the width and height are ignored). Blits with negative <code>dst_rect</code> coordinates will be clipped properly.
709If <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).
710The final blit rectangle is saved in <code>dst_rect</code> after all clipping is performed (<code>src_rect</code> is not modified).
b968d0e8 711The 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 712but 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
713with OpenGL.</p>
714<p>The results of blitting operations vary greatly depending on whether <code>SDL_SRCALPHA</code> is set or not. See <code>SDL::Video::set_alpha</code> for an
715explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting.
716<code>SDL::Video::blit_surface</code> doesn't returns anything.</p>
717<p>For an example see <a href="#load_BMP_filename">load_BMP</a>.</p>
b968d0e8 718
719</div>
162a0989 720<h2 id="update_rect_surface_x_y_width_height">update_rect(surface,x,y,width,height)</h2>
721<div id="update_rect_surface_x_y_width_height-2">
096d8dc8 722<pre> update_rect( $surface, $left, $top, $width, $height );
723
724</pre>
162a0989 725<p>Makes sure the given area is updated on the given screen.
726The rectangle must be confined within the screen boundaries because there's no clipping.
727update_rect doesn't returns any value.</p>
096d8dc8 728<p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface_surface">SDL::Video::lock_surface</a></p>
729<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>
730<p>For an example see <a href="#SYNOPSIS">SYNOPSIS</a></p>
162a0989 731
732</div>
733<h2 id="update_rects_surface_rects">update_rects(surface,rects) </h2>
734<div id="update_rects_surface_rects_CONTENT">
096d8dc8 735<pre> update_rects( $surface, @rects );
736
737</pre>
162a0989 738<p>Makes sure the given list of rectangles is updated on the given screen.
739The rectangle must be confined within the screen boundaries because there's no clipping.
096d8dc8 740<code>update_rects</code> doesn't returns any value.</p>
741<p><strong>Note</strong>: This function should not be called while screen is locked by <a href="#lock_surface_surface">SDL::Video::lock_surface</a>.</p>
742<p>Example:</p>
743<pre> use SDL;
744 use SDL::Video;
745 use SDL::Surface;
746 use SDL::Rect;
747
748 # the size of the window box or the screen resolution if fullscreen
749 my $screen_width = 800;
750 my $screen_height = 600;
751
752 SDL::init(SDL_INIT_VIDEO);
753
754 # setting video mode
755 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
756
757 # drawing the whole screen blue
758 my $mapped_color = SDL::Video::map_RGB($screen_surface-&gt;format(), 0, 0, 255); # blue
759 SDL::Video::fill_rect($screen_surface,
760 SDL::Rect-&gt;new(0, 0, $screen_width, $screen_height),
761 $mapped_color);
762
763 my @rects = ();
764 push(@rects, SDL::Rect-&gt;new(200, 0, 400, 600));
765 push(@rects, SDL::Rect-&gt;new( 0, 150, 800, 300));
766
767 # updating parts of the screen (should look like a cross)
768 SDL::Video::update_rects($screen_surface, @rects);
769
770 sleep(2);
771
772 SDL::quit();
773
774</pre>
162a0989 775
776</div>
777<h2 id="flip_surface">flip(surface)</h2>
778<div id="flip_surface_CONTENT">
904171e2 779<pre> $flip = SDL::Video::flip( $screen_surface );
780
781</pre>
162a0989 782<p>On hardware that supports double-buffering, this function sets up a flip and returns.
783The hardware will wait for vertical retrace, and then swap video buffers before the next video surface blit or lock will return.
904171e2 784On hardware that doesn't support double-buffering or if <code>SDL_SWSURFACE</code> was set, this is equivalent to calling
785<code>SDL::Video::update_rect( $screen, 0, 0, 0, 0 )</code>.</p>
7067312b 786<p>A software screen surface is also updated automatically when parts of a SDL window are redrawn, caused by overlapping windows or by
787restoring from an iconified state. As a result there is no proper double buffer behavior in windowed mode for a software screen, in
788contrast to a full screen software mode.</p>
904171e2 789<p>The <code>SDL_DOUBLEBUF</code> flag must have been passed to <code>SDL::Video::set_video_mode</code>, when setting the video mode for this function to
790perform hardware flipping.</p>
791<p><code>flip</code> returns <code>0</code> on success or <code>-1</code> on error.</p>
792<p><strong>Note</strong>: If you want to swap the buffers of an initialized OpenGL context, use the function <code>SDL::Video::GL_swap_buffers</code> instead. </p>
793<p>Example:</p>
794<pre> use SDL;
795 use SDL::Video;
796 use SDL::Surface;
797
798 # the size of the window box or the screen resolution if fullscreen
799 my $screen_width = 800;
800 my $screen_height = 600;
801
802 SDL::init(SDL_INIT_VIDEO);
803
804 # setting video mode
805 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
806
807 # do some video operations here
808
809 # doing page flipping
810 unless( SDL::Video::flip($screen_surface) == 0 )
811 {
812 printf( STDERR &quot;failed to swap buffers: %s\n&quot;, SDL::get_error() );
813 }
814
815 SDL::quit();
816
817</pre>
162a0989 818
819</div>
b968d0e8 820<h1 id="Palette_Color_and_Pixel_Functions">Palette, Color and Pixel Functions</h1><p><a href="#TOP" class="toplink">Top</a></p>
821<div id="Palette_Color_and_Pixel_Functions_CO">
822
823</div>
162a0989 824<h2 id="set_colors_surface_start_colors">set_colors(surface,start,colors)</h2>
825<div id="set_colors_surface_start_colors_CONT">
904171e2 826<pre> $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
827
828</pre>
162a0989 829<p>Sets a portion of the colormap for the given 8-bit surface. </p>
830<p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
904171e2 831If <code>SDL_HWPALETTE</code> was set in <code>SDL::Video::set_video_mode</code> flags, <code>SDL::Video::set_colors</code> will always return 1, and the palette is
832guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
833The 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.
834Palettized (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 835the surface and a physical palette (that determines how the hardware will map the colors to the display).
904171e2 836<code>SDL::Video::set_colors</code> modifies both palettes (if present), and is equivalent to calling <code>SDL::Video::set_palette</code> with the flags set to
837( <code>SDL_LOGPAL | SDL_PHYSPAL</code> ). </p>
838<p>If <code>surface</code> is not a palettized surface, this function does nothing, returning 0.
839If all of the colors were set as passed to <code>SDL::Video::set_colors</code>, it will return 1.
7067312b 840If 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
841actual color palette.</p>
162a0989 842
843</div>
844<h2 id="set_palette_surface_flags_start_colo">set_palette(surface,flags,start,colors)</h2>
845<div id="set_palette_surface_flags_start_colo-2">
904171e2 846<pre> $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
847
848</pre>
162a0989 849<p>Sets a portion of the palette for the given 8-bit surface.</p>
904171e2 850<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 851the surface and a physical palette (that determines how the hardware will map the colors to the display).
904171e2 852Non screen surfaces have a logical palette only. <code>SDL::Video::blit</code> always uses the logical palette when blitting surfaces (if it has to
7067312b 853convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various
854special color effects (e.g., screen fading, color flashes, screen dimming).</p>
904171e2 855<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 856<p>When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
904171e2 857If <code>SDL_HWPALETTE</code> was set in <code>SDL::Video::set_video_mode</code> flags, <code>SDL::Video::set_palette</code> will always return 1, and the palette is
858guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
859The color components of a <code>SDL::Color</code> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. </p>
860<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>,
861it 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 862to determine the actual color palette.</p>
162a0989 863
864</div>
865<h2 id="set_gamma_r_g_b">set_gamma(r,g,b)</h2>
866<div id="set_gamma_r_g_b_CONTENT">
904171e2 867<pre> $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
868
869</pre>
162a0989 870<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.
871A gamma value of 1.0 is identity (i.e., no adjustment is made).</p>
7067312b 872<p>This function adjusts the gamma based on the &quot;gamma function&quot; parameter, you can directly specify lookup tables for gamma adjustment
873with SDL::set_gamma_ramp.</p>
904171e2 874<p><strong>Note</strong>: Not all display hardware is able to change gamma.</p>
875<p><code>SDL::Video::set_gamma</code> returns <code>-1</code> on error.</p>
876<p><strong>Warning</strong>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! </p>
877<p>Example:</p>
878<pre> use SDL;
879 use SDL::Video;
880 use SDL::Surface;
881 use SDL::Rect;
882 use Time::HiRes qw( usleep );
883
884 # the size of the window box or the screen resolution if fullscreen
885 my $screen_width = 800;
886 my $screen_height = 600;
887
888 SDL::init(SDL_INIT_VIDEO);
889
890 # setting video mode
891 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
892
893 # drawing something somewhere
894 my $mapped_color = SDL::Video::map_RGB($screen_surface-&gt;format(), 128, 128, 128); # gray
895 SDL::Video::fill_rect($screen_surface,
896 SDL::Rect-&gt;new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
897 $mapped_color);
898
899 # update the whole screen
900 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
901
902 usleep(500000);
903
904 for(1..20)
905 {
906 SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
907 usleep(40000);
908 }
909
910 for(1..20)
911 {
912 SDL::Video::set_gamma( $_ / 20, 1, 1 );
913 usleep(40000);
914 }
915
916 SDL::Video::set_gamma( 1, 1, 1 );
917
918 usleep(500000);
919
920 SDL::quit();
921
922</pre>
162a0989 923
924</div>
904171e2 925<h2 id="get_gamma_ramp_rt_gt_bt">get_gamma_ramp(rt,gt,bt)</h2>
926<div id="get_gamma_ramp_rt_gt_bt_CONTENT">
927<pre> $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
928
929</pre>
162a0989 930<p>Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
8edb6a07 931<code>SDL::Video::get_gamma_ramp</code> returns -1 on error.</p>
904171e2 932<pre> use SDL;
933 use SDL::Video;
934
935 SDL::init(SDL_INIT_VIDEO);
936
937 my (@red, @green, @blue);
938
939 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
940
941 if( -1 == $ret )
942 {
943 print( &quot;an error occoured&quot; );
944 }
945 else
946 {
947 printf( &quot;for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[255], $green[255], $blue[255] );
948 printf( &quot;for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[127], $green[127], $blue[127] );
949 printf( &quot;for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[0], $green[0], $blue[0] );
950 }
951
952 SDL::quit();
953
954</pre>
162a0989 955
956</div>
957<h2 id="set_gamma_ramp_rt_gt_bt">set_gamma_ramp(rt,gt,bt)</h2>
958<div id="set_gamma_ramp_rt_gt_bt_CONTENT">
3774ca11 959<pre> $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
960
961</pre>
962<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 963mapping between the input and output for that channel.
162a0989 964The 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.
965You may pass NULL to any of the channels to leave them unchanged.</p>
7067312b 966<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
3774ca11 967with <code>SDL::Video::set_gamma</code>.</p>
162a0989 968<p>Not all display hardware is able to change gamma.
3774ca11 969<code>SDL::Video::set_gamma_ramp</code> returns <code>-1</code> on error (or if gamma adjustment is not supported).</p>
970<p>Example:</p>
971<pre> use SDL;
972 use SDL::Video;
973
974 SDL::init(SDL_INIT_VIDEO);
975
976 my (@red, @green, @blue);
977
978 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
979
980 $red[127] = 0xFF00;
981
982 $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
983
984 $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
985
986 if( -1 == $ret )
987 {
988 print( &quot;an error occoured&quot; );
989 }
990 else
991 {
992 printf( &quot;for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[255], $green[255], $blue[255] );
993 printf( &quot;for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[127], $green[127], $blue[127] );
994 printf( &quot;for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n&quot;, $red[0], $green[0], $blue[0] );
995 }
996
997 SDL::quit();
998
999</pre>
162a0989 1000
1001</div>
1002<h2 id="map_RGB_pixel_format_r_g_b">map_RGB(pixel_format,r,g,b)</h2>
1003<div id="map_RGB_pixel_format_r_g_b_CONTENT">
3774ca11 1004<pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
1005
1006</pre>
1007<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 1008If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1009If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque). </p>
3774ca11 1010<p><code>SDL::Video::map_RGB</code> returns a pixel value best approximating the given RGB color value for a given pixel format.
1011If 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 1012(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 1013<pre> use SDL;
1014 use SDL::Video;
1015 use SDL::PixelFormat;
1016 use SDL::Surface;
1017
1018 SDL::init(SDL_INIT_VIDEO);
1019
1020 my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
1021 # ^-- 16 bits per pixel
1022
1023 $r = 0x9C;
1024 $g = 0xDC;
1025 $b = 0x67;
1026
1027 printf( &quot;for 24bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b);
1028
1029 my $_16bit = SDL::Video::map_RGB( $screen_surface-&gt;format, $r, $g, $b );
1030
1031 # 16bpp is 5 bits red, 6 bits green and 5 bits blue
b968d0e8 1032 # we will obtain the values for each color and calculating them back to 24/32bit color system
1033 ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface-&gt;format, $_16bit ) };
3774ca11 1034
1035 printf( &quot;for 16bpp it is: 0x%02X 0x%02X 0x%02X\n&quot;, $r, $g, $b );
1036
b968d0e8 1037 # so color #9CDC67 becomes #9CDF63
3774ca11 1038
1039 SDL::quit();
1040
1041</pre>
162a0989 1042
1043</div>
1044<h2 id="map_RGBA_pixel_format_r_g_b_a">map_RGBA(pixel_format,r,g,b,a)</h2>
1045<div id="map_RGBA_pixel_format_r_g_b_a_CONTEN">
b968d0e8 1046<pre> $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b, $a );
1047
1048</pre>
1049<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 1050If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned.
1051If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette). </p>
1052<p>A pixel value best approximating the given RGBA color value for a given pixel format.
7067312b 1053If 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.,
1054with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).</p>
162a0989 1055
1056</div>
1057<h2 id="get_RGB_pixel_format_pixel">get_RGB(pixel_format,pixel)</h2>
1058<div id="get_RGB_pixel_format_pixel_CONTENT">
b968d0e8 1059<pre> $rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel );
1060
1061</pre>
1062<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 1063This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1064component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
b968d0e8 1065<p>For an example see <code>SDL::Video::map_RGB</code>.</p>
162a0989 1066
1067</div>
1068<h2 id="get_RGBA_pixel_format_pixel">get_RGBA(pixel_format,pixel)</h2>
1069<div id="get_RGBA_pixel_format_pixel_CONTENT">
b968d0e8 1070<pre> $rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel );
1071
1072</pre>
162a0989 1073<p>Gets RGBA values from a pixel in the specified pixel format.
7067312b 1074This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB
1075component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).</p>
162a0989 1076<p>If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque). </p>
1077
1078</div>
3540cbee 1079<h1 id="GL_Methods">GL Methods</h1><p><a href="#TOP" class="toplink">Top</a></p>
1080<div id="GL_Methods_CONTENT">
1081
1082</div>
162a0989 1083<h2 id="GL_load_library_path">GL_load_library(path)</h2>
1084<div id="GL_load_library_path_CONTENT">
8d3da0de 1085<pre> $gl_load_lib = SDL::Video::GL_load_library( 'path/to/static/glfunctions.dll' );
1086
1087</pre>
8edb6a07 1088<p>If you wish, you may load the OpenGL library from the given path at runtime, this must be done before <code>SDL::Video::set_video_mode</code> is called.
1089You must then use <code>SDL::Video::GL_get_proc_address</code> to retrieve function pointers to GL functions. </p>
8d3da0de 1090<p><code>GL_load_library</code> returns <code>0</code> on success or <code>-1</code> or error.</p>
162a0989 1091
1092</div>
1093<h2 id="GL_get_proc_address_proc">GL_get_proc_address(proc)</h2>
1094<div id="GL_get_proc_address_proc_CONTENT">
8d3da0de 1095
1096
1097
1098
1099
1100
1101
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
8d3da0de 1103<code>SDL::Video::GL_load_library</code>, then all GL functions must be retrieved this way. Usually this is used to retrieve function pointers to OpenGL
1104extensions. Note that this function needs an OpenGL context to function properly, so it should be called after <code>SDL::Video::set_video_mode</code>
1105has been called (with the <code>SDL_OPENGL</code> flag).</p>
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>
1125<h2 id="GL_get_attribute_attr">GL_get_attribute(attr)</h2>
1126<div id="GL_get_attribute_attr_CONTENT">
8d3da0de 1127<pre> $value = SDL::Video::GL_get_attribute( $attr );
1128
1129</pre>
1130<p>It returns SDL/OpenGL attribute <code>attr</code>. This is useful after a call to <code>SDL::Video::set_video_mode</code> to check whether your attributes have
1131been set as you expected.
1132<code>SDL::Video::GL_get_attribute</code> returns undef if the attribute is not found.</p>
1133<p>Example:</p>
1134<pre> print( SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE) );
1135
1136</pre>
162a0989 1137
1138</div>
1139<h2 id="GL_set_attribute_attr_value">GL_set_attribute(attr,value)</h2>
1140<div id="GL_set_attribute_attr_value_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
1145<code>SDL::Video::set_video_mode</code>.
1146You should use <code>GL_get_attribute</code> to check the values after a <code>set_video_mode</code> call, since the values obtained can differ from the
1147requested ones.</p>
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">
1189<p>see <a href="/SDL-Overlay.html">SDL::Overlay</a> </p>
3540cbee 1190
1191</div>
162a0989 1192<h2 id="lock_YUV_overlay_overlay">lock_YUV_overlay(overlay)</h2>
1193<div id="lock_YUV_overlay_overlay_CONTENT">
8d3da0de 1194<pre> $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );
1195
1196</pre>
1197<p>Much the same as <code>SDL::Video::lock_surface</code>, <code>lock_YUV_overlay</code> locks the overlay for direct access to pixel data.
1198It returns <code>0</code> on success or <code>-1</code> on error.</p>
162a0989 1199
1200</div>
1201<h2 id="unlock_YUV_overlay_overlay">unlock_YUV_overlay(overlay)</h2>
1202<div id="unlock_YUV_overlay_overlay_CONTENT">
8d3da0de 1203<pre> SDL::Video::unlock_YUV_overlay( $overlay );
1204
1205</pre>
1206<p>The opposite to <code>SDL::Video::lock_YUV_overlay</code>. Unlocks a previously locked overlay. An overlay must be unlocked before it can be displayed.
1207<code>unlock_YUV_overlay</code> does not return anything.</p>
162a0989 1208
1209</div>
1210<h2 id="display_YUV_overlay_overlay_dstrect">display_YUV_overlay(overlay,dstrect)</h2>
1211<div id="display_YUV_overlay_overlay_dstrect_">
8d3da0de 1212<pre> $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );
1213
1214</pre>
1215<p>Blit the overlay to the display surface specified when the overlay was created. The <code>SDL::Rect</code> structure, <code>dstrect</code>, specifies a rectangle
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>
1225<h2 id="wm_set_caption_title_icon">wm_set_caption(title,icon)</h2>
1226<div id="wm_set_caption_title_icon_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>
1253<h2 id="wm_get_caption">wm_get_caption()</h2>
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>
1279<h2 id="wm_set_icon_icon">wm_set_icon(icon)</h2>
1280<div id="wm_set_icon_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>
1285<p>This function must be called before the first call to <code>SDL::Video::set_video_mode</code>. Note that this means <code>SDL::Image</code> cannot be used.</p>
1286<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
1287(no transparency).</p>
1288<p>Example:</p>
1289<pre> SDL::Video::wm_set_icon(SDL::Video::load_BMP(&quot;icon.bmp&quot;));
1290
1291</pre>
1292<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>
1293<p>Example:</p>
1294<pre> my $image = SDL::Video::load_BMP(&quot;icon.bmp&quot;);
1295
1296 my colorkey = SDL::Video::map_RGB($image-&gt;format, 255, 0, 255); # specify the color that will be transparent
1297
1298 SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);
1299
1300 SDL::Video::wm_set_icon($image);
1301
1302</pre>
b968d0e8 1303
1304</div>
1305<h2 id="wm_grab_input_mode">wm_grab_input(mode)</h2>
1306<div id="wm_grab_input_mode_CONTENT">
8edb6a07 1307<pre> $grab_mode = SDL::Video::wm_grab_input($mode);
1308
1309</pre>
1310<p>Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application,
1311and not interpreted by a window manager, if any.</p>
1312<p>When mode is <code>SDL_GRAB_QUERY</code> the grab mode is not changed, but the current grab mode is returned.</p>
1313<p><code>mode</code> and the return value of <code>wm_grab_input</code> can be one of the following:</p>
1314<ul>
1315 <li><code>SDL_GRAB_QUERY</code> </li>
1316 <li><code>SDL_GRAB_OFF</code> </li>
1317 <li><code>SDL_GRAB_ON</code></li>
1318</ul>
1319
b968d0e8 1320
1321</div>
1322<h2 id="wm_iconify_window">wm_iconify_window()</h2>
1323<div id="wm_iconify_window_CONTENT">
8edb6a07 1324<pre> $iconify_window = SDL::Video::wm_iconify_window();
1325
1326</pre>
1327<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,
1328the application will receive a <code>SDL_APPACTIVE</code> loss event (see Application visibility events at <a href="/SDL-Event.html">SDL::Event</a>).</p>
1329<p>Returns non-zero on success or 0 if iconification is not supported or was refused by the window manager. </p>
1330<p>Example:</p>
1331<pre> use SDL;
1332 use SDL::Video;
1333 use SDL::Surface;
1334
1335 SDL::init(SDL_INIT_VIDEO);
1336
1337 my $screen = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1338
1339 sleep(2);
1340
1341 SDL::Video::wm_iconify_window();
1342
1343 sleep(2);
1344
1345 SDL::quit;
1346
1347</pre>
b968d0e8 1348
1349</div>
1350<h2 id="wm_toggle_fullscreen_surface">wm_toggle_fullscreen(surface)</h2>
1351<div id="wm_toggle_fullscreen_surface_CONTENT">
8edb6a07 1352<pre> $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
1353
1354</pre>
1355<p>Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support
1356is experimental).</p>
162a0989 1357
1358</div>
8d3da0de 1359<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
1360<div id="AUTHOR_CONTENT">
1361<p>magnet, Tobias Leich (FROGGS)</p>
1362
1363</div>
162a0989 1364<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
1365<div id="SEE_ALSO_CONTENT">
1366
1367</div>
1368<h2 id="Category_Objects">Category Objects</h2>
1369<div id="Category_Objects_CONTENT">
46beffd8 1370<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>,
1371<a href="/SDL-Rect.html">SDL::Rect</a>, <a href="/SDL-Palette.html">SDL::Palette</a>, <a href="/SDL-PixelFormat.html">SDL::PixelFormat</a>,
1372<a href="/SDL-VideoInfo.html">SDL::VideoInfo</a></p>
162a0989 1373
1374</div>
1375</div>
Unnamed repository; edit this file to name it for gitweb.