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