SDL::Video(3pm)

1SDL::Video(3)         User Contributed Perl Documentation        SDL::Video(3)
2
3
4

NAME

6       SDL::Video - Bindings to the video category in SDL API
7

SYNOPSIS

12        use SDL;
13        use SDL::Video;
14        use SDL::Surface;
15        use SDL::Rect;
16
17        # the size of the window box or the screen resolution if fullscreen
18        my $screen_width   = 800;
19        my $screen_height  = 600;
20
21        SDL::init(SDL_INIT_VIDEO);
22
23        # setting video mode
24        my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_ANYFORMAT);
25
26        # drawing something somewhere
27        my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
28        SDL::Video::fill_rect($screen_surface,
29                              SDL::Rect->new($screen_width / 4, $screen_height / 4,
30                                             $screen_width / 2, $screen_height / 2), $mapped_color);
31
32        # update an area on the screen so its visible
33        SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
34
35        sleep(5); # just to have time to see it
36

CONSTANTS

38       The constants are exported by default. You can avoid this by doing:
39
40        use SDL::Video ();
41
42       and access them directly:
43
44        SDL::Video::SDL_SWSURFACE;
45
46       or by choosing the export tags below:
47
48       Export tag: ':surface'
49
50        SDL_ASYNCBLIT       Use asynchronous blit if possible
51        SDL_SWSURFACE       Stored in the system memory.
52        SDL_HWSURFACE       Stored in video memory
53
54       Export tag: ':video'
55
56        SDL_ANYFORMAT       Allow any pixel-format
57        SDL_HWPALETTE       Have an exclusive palette
58        SDL_DOUBLEBUF       Double buffered
59        SDL_FULLSCREEN      Full screen surface
60        SDL_OPENGL          Have an OpenGL context
61        SDL_OPENGLBLIT      Support OpenGL blitting.
62                            NOTE: This option is kept for compatibility only, and is not recommended for new code.
63        SDL_RESIZABLE       Resizable surface
64        SDL_NOFRAME         No window caption or edge frame
65        SDL_HWACCEL         Use hardware acceleration blit
66        SDL_SRCCOLORKEY     Use colorkey blitting
67        SDL_RLEACCELOK      Private flag
68        SDL_RLEACCEL        Accelerated colorkey blitting with RLE
69        SDL_SRCALPHA        Use alpha blending blit
70        SDL_PREALLOC        Use preallocated memory
71
72       Export tag ':overlay'
73
74        SDL_YV12_OVERLAY    Planar mode: Y + V + U  (3 planes)
75        SDL_IYUV_OVERLAY    Planar mode: Y + U + V  (3 planes)
76        SDL_YUY2_OVERLAY    Packed mode: Y0+U0+Y1+V0 (1 plane)
77        SDL_UYVY_OVERLAY    Packed mode: U0+Y0+V0+Y1 (1 plane)
78        SDL_YVYU_OVERLAY    Packed mode: Y0+V0+Y1+U0 (1 plane)
79
80       Export tag ':palette'
81
82        SDL_LOGPAL          Logical palette, which controls how blits are mapped to/from the surface
83        SDL_PHYSPAL         Physical palette, which controls how pixels look on the screen
84
85       Export tag ':grab'
86
87        SDL_GRAB_QUERY
88        SDL_GRAB_OFF
89        SDL_GRAB_ON
90        SDL_GRAB_FULLSCREEN Used internally
91
92       Export tag ':gl'
93
94        SDL_GL_RED_SIZE
95        SDL_GL_GREEN_SIZE
96        SDL_GL_BLUE_SIZE
97        SDL_GL_ALPHA_SIZE
98        SDL_GL_BUFFER_SIZE
99        SDL_GL_DOUBLEBUFFER
100        SDL_GL_DEPTH_SIZE
101        SDL_GL_STENCIL_SIZE
102        SDL_GL_ACCUM_RED_SIZE
103        SDL_GL_ACCUM_GREEN_SIZE
104        SDL_GL_ACCUM_BLUE_SIZE
105        SDL_GL_ACCUM_ALPHA_SIZE
106        SDL_GL_STEREO
107        SDL_GL_MULTISAMPLEBUFFERS
108        SDL_GL_MULTISAMPLESAMPLES
109        SDL_GL_ACCELERATED_VISUAL
110        SDL_GL_SWAP_CONTROL
111

Core Functions

113   get_video_surface
114        my $surface = SDL::Video::get_video_surface();
115
116       This function returns the current display SDL::Surface. If SDL is doing
117       format conversion on the display surface, this function returns the
118       publicly visible surface, not the real video surface.
119
120       Example:
121
122        # somewhere after you set the video mode
123        my $surface = SDL::Video::get_video_surface();
124
125        printf( "our screen is %d pixels wide and %d pixels high\n", $surface->w, $surface->h );
126
127   get_video_info
128        my $video_info = SDL::Video::get_video_info();
129
130       This function returns a read-only structure containing information
131       about the video hardware. If it is called before
132       SDL::Video::set_video_mode, the "vfmt" member of the returned structure
133       will contain the pixel format of the best video mode.
134
135       Example:
136
137        use SDL;
138        use SDL::Video;
139        use SDL::VideoInfo;
140        use SDL::PixelFormat;
141
142        SDL::init(SDL_INIT_VIDEO);
143
144        my $video_info = SDL::Video::get_video_info();
145
146        printf( "we can have %dbits per pixel\n", $video_info->vfmt->BitsPerPixel );
147
148   video_driver_name
149        my $driver_name = SDL::Video::video_driver_name();
150
151       This function will return the name of the initialized video driver up
152       to a maximum of 1024 characters. The driver name is a simple one word
153       identifier like "x11", "windib" or "directx".
154
155       Note: Some platforms allow selection of the video driver through the
156       "SDL_VIDEODRIVER" environment variable.
157
158       Example:
159
160        use SDL;
161        use SDL::Video;
162
163        SDL::init(SDL_INIT_VIDEO);
164
165        print SDL::Video::video_driver_name() . "\n";
166
167   list_modes
168        my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
169
170       Returns a reference to an array:
171
172       ·   of available screen dimensions (as "SDL::Rect"'s) for the given
173           format and video flags.
174
175       ·   with first array element 'all'. In this case you can set all modes.
176
177       ·   with first array element 'none' if no mode is available.
178
179       Note: <list_modes> should be called before the video_mode ist set.
180       Otherwise you will always get 'all'.
181
182       Example:
183
184        use SDL;
185        use SDL::Video;
186        use SDL::VideoInfo;
187        use SDL::PixelFormat;
188        use SDL::Rect;
189
190        SDL::init(SDL_INIT_VIDEO);
191
192        my $video_info = SDL::Video::get_video_info();
193
194        my @modes = @{ SDL::Video::list_modes($video_info->vfmt, SDL_NOFRAME) };
195
196        if($#modes > 0)
197        {
198            print("available modes:\n");
199            foreach my $mode ( @modes )
200            {
201                printf("%d x %d\n", $mode->w, $mode->h );
202            }
203        }
204        elsif($#modes == 0)
205        {
206            printf("%s video modes available\n", $modes[0]);
207        }
208
209   video_mode_ok
210        my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
211
212       This function is used to check whether the requested mode is supported
213       by the current video device. The arguments passed to this function are
214       the same as those you would pass to SDL::Video::set_video_mode.  It
215       returns 0 if the mode is not supported at all, otherwise the suggested
216       "bpp".
217
218       Example:
219
220        use SDL;
221        use SDL::Video;
222
223        SDL::init(SDL_INIT_VIDEO);
224
225        my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
226
227        unless($video_mode_ok)
228        {
229            printf( "this video mode is not supported\n" );
230        }
231
232   set_video_mode
233        my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
234
235       Sets up a video mode with the specified width, height, bits-per-pixel
236       and flags.  "set_video_mode" returns a SDL::Surface on success
237       otherwise it returns undef on error, the error message is retrieved
238       using "SDL::get_error".
239
240       List of available flags
241
242       "SDL_SWSURFACE"
243           Create the video surface in system memory
244
245       "SDL_HWSURFACE"
246           Create the video surface in video memory
247
248       "SDL_ASYNCBLIT"
249           Enables the use of asynchronous updates of the display surface.
250           This will usually slow down blitting on single CPU machines, but
251           may provide a speed increase on SMP systems.
252
253       "SDL_ANYFORMAT"
254           Normally, if a video surface of the requested bits-per-pixel (bpp)
255           is not available, SDL will emulate one with a shadow surface.
256           Passing "SDL_ANYFORMAT" prevents this and causes SDL to use the
257           video surface, regardless of its pixel depth.
258
259       "SDL_HWPALETTE"
260           Give SDL exclusive palette access. Without this flag you may not
261           always get the colors you request with SDL::set_colors or
262           SDL::set_palette.
263
264       "SDL_DOUBLEBUF"
265           Enable hardware double buffering; only valid with "SDL_HWSURFACE".
266           Calling SDL::Video::flip will flip the buffers and update the
267           screen.  All drawing will take place on the surface that is not
268           displayed at the moment.  If double buffering could not be enabled
269           then SDL::Video::flip will just perform a SDL::Video::update_rect
270           on the entire screen.
271
272       "SDL_FULLSCREEN"
273           SDL will attempt to use a fullscreen mode. If a hardware resolution
274           change is not possible (for whatever reason), the next higher
275           resolution will be used and the display window centered on a black
276           background.
277
278       "SDL_OPENGL"
279           Create an OpenGL rendering context. You should have previously set
280           OpenGL video attributes with SDL::Video::GL_set_attribute.
281
282       "SDL_OPENGLBLIT"
283           Create an OpenGL rendering context, like above, but allow normal
284           blitting operations.  The screen (2D) surface may have an alpha
285           channel, and SDL::update_rects must be used for updating changes to
286           the screen surface.  NOTE: This option is kept for compatibility
287           only, and will be removed in next versions. Is not recommended for
288           new code.
289
290       "SDL_RESIZABLE"
291           Create a resizable window.  When the window is resized by the user
292           a "SDL_VIDEORESIZE" event is generated and
293           SDL::Video::set_video_mode can be called again with the new size.
294
295       "SDL_NOFRAME"
296           If possible, SDL_NOFRAME causes SDL to create a window with no
297           title bar or frame decoration.  Fullscreen modes automatically have
298           this flag set.
299
300       Note 1: Use "SDL_SWSURFACE" if you plan on doing per-pixel
301       manipulations, or blit surfaces with alpha channels, and require a high
302       framerate.  When you use hardware surfaces (by passing the flag
303       "SDL_HWSURFACE" as parameter), SDL copies the surfaces from video
304       memory to system memory when you lock them, and back when you unlock
305       them. This can cause a major performance hit. Be aware that you may
306       request a hardware surface, but receive a software surface because the
307       video driver doesn't support hardware surface. Many platforms can only
308       provide a hardware surface when using "SDL_FULLSCREEN". The
309       "SDL_HWSURFACE" flag is best used when the surfaces you'll be blitting
310       can also be stored in video memory.
311
312       Note 2: If you want to control the position on the screen when creating
313       a windowed surface, you may do so by setting the environment variables
314       "SDL_VIDEO_CENTERED=center" or "SDL_VIDEO_WINDOW_POS=x,y". You can also
315       set them via "SDL::putenv".
316
317       Note 3: This function should be called in the main thread of your
318       application.
319
320       User note 1: Some have found that enabling OpenGL attributes like
321       "SDL_GL_STENCIL_SIZE" (the stencil buffer size) before the video mode
322       has been set causes the application to simply ignore those attributes,
323       while enabling attributes after the video mode has been set works fine.
324
325       User note 2: Also note that, in Windows, setting the video mode resets
326       the current OpenGL context. You must execute again the OpenGL
327       initialization code (set the clear color or the shade model, or reload
328       textures, for example) after calling SDL::set_video_mode. In Linux,
329       however, it works fine, and the initialization code only needs to be
330       executed after the first call to SDL::Video::set_video_mode (although
331       there is no harm in executing the initialization code after each call
332       to SDL::Video::set_video_mode, for example for a multiplatform
333       application).
334
335   convert_surface
336        $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
337
338       Creates a new SDL::surface of the specified SDL::PixelFormat, and then
339       copies and maps the given surface to it.  It is also useful for making
340       a copy of a surface.
341
342       The flags parameter is passed to SDL::Surface"->new" and has those
343       semantics.  This function is used internally by
344       SDL::Video::display_format.  This function can only be called after
345       "SDL::init".
346
347       it returns a SDL::Surface on success or "undef" on error.
348
349   display_format
350        $new_surface = SDL::Video::display_format( $surface );
351
352       This function takes a surface and copies it to a new surface of the
353       pixel format and colors of the video framebuffer, suitable for fast
354       blitting onto the display surface. It calls
355       SDL::Video::convert_surface.
356
357       If you want to take advantage of hardware colorkey or alpha blit
358       acceleration, you should set the colorkey and alpha value before
359       calling this function.
360
361       If you want an alpha channel, see "SDL::Video::display_format_alpha".
362       Return Value
363
364       Note: Remember to use a different variable for the returned surface,
365       otherwise you have a memory leak, since the original surface isn't
366       freed.
367
368   display_format_alpha
369        $new_surface = SDL::Video::display_format_alpha( $surface );
370
371       This function takes a surface and copies it to a new surface of the
372       pixel format and colors of the video framebuffer plus an alpha channel,
373       suitable for fast blitting onto the display surface. It calls
374       SDL::Video::convert_surface.
375
376       If you want to take advantage of hardware colorkey or alpha blit
377       acceleration, you should set the colorkey and alpha value before
378       calling this function.
379
380       This function can be used to convert a colorkey to an alpha channel, if
381       the "SDL_SRCCOLORKEY" flag is set on the surface. The generated surface
382       will then be transparent (alpha=0) where the pixels match the colorkey,
383       and opaque (alpha=255) elsewhere.
384
385       Note: The video surface must be initialised using
386       SDL::Video::set_video_mode before this function is called, or it will
387       segfault.
388
389   load_BMP
390        $surface = SDL::Video::load_BMP( $filename );
391
392       Loads a SDL::Surface from a named Windows BMP file.
393       "SDL::Video::load_BMP" returns a SDL::Surface on success or "undef" on
394       error.
395
396       Note: When loading a 24-bit Windows BMP file, pixel data points are
397       loaded as blue, green, red, and NOT red, green, blue (as one might
398       expect).
399
400        use SDL;
401        use SDL::Video;
402        use SDL::Rect;
403        use SDL::Surface;
404
405        my $screen_width  = 640;
406        my $screen_height = 480;
407
408        SDL::init(SDL_INIT_VIDEO);
409
410        my $screen  = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
411
412        my $picture = SDL::Video::load_BMP('test.bmp');
413
414        die(SDL::get_error) unless $picture;
415
416        my $rect    = SDL::Rect->new(0, 0, $screen_width, $screen_height);
417
418        SDL::Video::blit_surface( $picture, SDL::Rect->new(0, 0, $picture->w, $picture->h),
419                                  $screen,  SDL::Rect->new(0, 0, $screen->w,  $screen->h) );
420
421        SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
422
423        sleep(2);
424
425   save_BMP
426        $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
427
428       Saves the given SDL::Surface as a Windows BMP file named filename.  it
429       returns 0 on success or -1 on error.
430
431   set_color_key
432        $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
433
434       Sets the color key (transparent pixel) in a blittable surface and
435       enables or disables RLE blit acceleration.  $key can be an integer or
436       an SDL::Color object. If you pass an SDL::Color object
437       SDL::Video::map_RGB will be called on it before setting the color key.
438
439       RLE acceleration can substantially speed up blitting of images with
440       large horizontal runs of transparent pixels (i.e., pixels that match
441       the key value).  The key must be of the same pixel format as the
442       surface, SDL::Video::map_RGB is often useful for obtaining an
443       acceptable value.  If flag is "SDL_SRCCOLORKEY" then key is the
444       transparent pixel value in the source image of a blit.
445
446       If "flag" is OR'd with "SDL_RLEACCEL" then the surface will be drawn
447       using RLE acceleration when drawn with SDL::Video::blit_surface.  The
448       surface will actually be encoded for RLE acceleration the first time
449       SDL::Video::blit_surface or
450       "SDL::Video::display_format|/display_format" is called on the surface.
451       If "flag" is 0, this function clears any current color key.
452
453       "SDL::Video::set_color_key" returns 0 on success or "-1" on error.
454
455   set_alpha
456        $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
457
458       "set_alpha" is used for setting the per-surface alpha value and/or
459       enabling and disabling alpha blending.
460
461       The surface parameter specifies which SDL::surface whose alpha
462       attributes you wish to adjust.  flags is used to specify whether alpha
463       blending should be used ( "SDL_SRCALPHA" ) and whether the surface
464       should use RLE acceleration for blitting ( "SDL_RLEACCEL" ).  flags can
465       be an OR'd combination of these two options, one of these options or 0.
466       If "SDL_SRCALPHA" is not passed as a flag then all alpha information is
467       ignored when blitting the surface.  The alpha parameter is the per-
468       surface alpha value; a surface need not have an alpha channel to use
469       per-surface alpha and blitting can still be accelerated with
470       "SDL_RLEACCEL".
471
472       Note: The per-surface alpha value of 128 is considered a special case
473       and is optimised, so it's much faster than other per-surface values.
474
475       Alpha affects surface blitting in the following ways:
476
477       RGBA->RGB with "SDL_SRCALPHA"
478           The source is alpha-blended with the destination, using the alpha
479           channel.  SDL_SRCCOLORKEY and the per-surface alpha are ignored.
480
481       RGBA->RGB without "SDL_SRCALPHA"
482           The RGB data is copied from the source. The source alpha channel
483           and the per-surface alpha value are ignored.  If SDL_SRCCOLORKEY is
484           set, only the pixels not matching the colorkey value are copied.
485
486       RGB->RGBA with "SDL_SRCALPHA"
487           The source is alpha-blended with the destination using the per-
488           surface alpha value.  If SDL_SRCCOLORKEY is set, only the pixels
489           not matching the colorkey value are copied.  The alpha channel of
490           the copied pixels is set to opaque.
491
492       RGB->RGBA without "SDL_SRCALPHA"
493           The RGB data is copied from the source and the alpha value of the
494           copied pixels is set to opaque.  If SDL_SRCCOLORKEY is set, only
495           the pixels not matching the colorkey value are copied.
496
497       RGBA->RGBA with "SDL_SRCALPHA"
498           The source is alpha-blended with the destination using the source
499           alpha channel.  The alpha channel in the destination surface is
500           left untouched. SDL_SRCCOLORKEY is ignored.
501
502       RGBA->RGBA without "SDL_SRCALPHA"
503           The RGBA data is copied to the destination surface.  If
504           SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey
505           value are copied.
506
507       RGB->RGB with "SDL_SRCALPHA"
508           The source is alpha-blended with the destination using the per-
509           surface alpha value.  If SDL_SRCCOLORKEY is set, only the pixels
510           not matching the colorkey value are copied.
511
512       RGB->RGB without "SDL_SRCALPHA"
513           The RGB data is copied from the source.  If SDL_SRCCOLORKEY is set,
514           only the pixels not matching the colorkey value are copied.
515
516       Note: When blitting, the presence or absence of "SDL_SRCALPHA" is
517       relevant only on the source surface, not the destination.  Note: Note
518       that RGBA->RGBA blits (with "SDL_SRCALPHA" set) keep the alpha of the
519       destination surface. This means that you cannot compose two arbitrary
520       RGBA surfaces this way and get the result you would expect from
521       "overlaying" them; the destination alpha will work as a mask.
522
523       Note: Also note that per-pixel and per-surface alpha cannot be
524       combined; the per-pixel alpha is always used if available.
525
526       "SDL::Video::set_alpha" returns 0 on success or "-1" on error.
527
528   fill_rect
529        $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );
530
531       This function performs a fast fill of the given SDL::Rect with the
532       given SDL::PixelFormat. If dest_rect is NULL, the whole surface will be
533       filled with color.
534
535       The color should be a pixel of the format used by the surface, and can
536       be generated by the SDL::Video::map_RGB or
537       "SDL::Video::map_RGBA|/map_RGBA" functions. If the color value contains
538       an alpha value then the destination is simply "filled" with that alpha
539       information, no blending takes place.
540
541       If there is a clip rectangle set on the destination (set via
542       SDL::Video::set_clip_rect), then this function will clip based on the
543       intersection of the clip rectangle and the dstrect rectangle, and the
544       dstrect rectangle will be modified to represent the area actually
545       filled.
546
547       If you call this on the video surface (ie: the value of
548       SDL::Video::get_video_surface) you may have to update the video surface
549       to see the result. This can happen if you are using a shadowed surface
550       that is not double buffered in Windows XP using build 1.2.9.
551
552       "SDL::Video::fill_rect" returns 0 on success or "-1" on error.
553
554       for an example see "SYNOPSIS".
555

Surface Locking and Unlocking

557   lock_surface
558        int SDL::Video::lock_surface( $surface );
559
560       "SDL::Video::lock_surface" sets up the given SDL::Surface for directly
561       accessing the pixels.  Between calls to SDL::lock_surface and
562       SDL::unlock_surface, you can write to ( "surface-"set_pixels>) and read
563       from ( "surface-"get_pixels> ), using the pixel format stored in
564       "surface-"format>.  Once you are done accessing the surface, you should
565       use SDL::Video::unlock_surface to release the lock.
566
567       Not all surfaces require locking. If SDL::Video::MUSTLOCK evaluates to
568       0, then reading and writing pixels to the surface can be performed at
569       any time, and the pixel format of the surface will not change.  No
570       operating system or library calls should be made between the
571       lock/unlock pairs, as critical system locks may be held during this
572       time.  "SDL::Video::lock_surface" returns 0 on success or "-1" on
573       error.
574
575       Note: Since SDL 1.1.8, the surface locks are recursive. This means that
576       you can lock a surface multiple times, but each lock must have a
577       matching unlock.
578
579        use strict;
580        use warnings;
581        use Carp;
582
583        use SDL v2.3;
584        use SDL::Video;
585        use SDL::Event;
586        use SDL::Events;
587        use SDL::Surface;
588
589        my $screen;
590
591        sub putpixel
592        {
593            my($x, $y, $color) = @_;
594            my $lineoffset     = $y * ($screen->pitch / 4);
595            $screen->set_pixels( $lineoffset+ $x, $color);
596        }
597
598        sub render
599        {
600            if( SDL::Video::MUSTLOCK( $screen) )
601            {
602                return if (SDL::Video::lock_surface( $screen ) < 0)
603            }
604
605            my $ticks                = SDL::get_ticks();
606            my ($i, $y, $yofs, $ofs) = (0,0,0,0);
607            for ($i = 0; $i < 480; $i++)
608            {
609                for (my $j = 0, $ofs = $yofs; $j < 640; $j++, $ofs++)
610                {
611                    $screen->set_pixels( $ofs, (  $i * $i + $j * $j + $ticks ) );
612                }
613                $yofs += $screen->pitch / 4;
614            }
615
616            putpixel(10, 10, 0xff0000);
617            putpixel(11, 10, 0xff0000);
618            putpixel(10, 11, 0xff0000);
619            putpixel(11, 11, 0xff0000);
620
621            SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
622
623            SDL::Video::update_rect($screen, 0, 0, 640, 480);
624
625            return 0;
626        }
627
628        sub main
629        {
630            Carp::cluck 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) < 0);
631
632            $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
633
634            Carp::cluck 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
635
636            while(1)
637            {
638                render();
639
640                my $event = SDL::Event->new();
641
642                while( SDL::Events::poll_event($event) )
643                {
644                    my $type = $event->type;
645                    return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
646                }
647                SDL::Events::pump_events();
648            }
649        }
650
651        main();
652
653   unlock_surface
654        SDL::Video::unlock_surface( $surface );
655
656       Surfaces that were previously locked using SDL::Video::lock_surface
657       must be unlocked with "SDL::Video::unlock_surface".  Surfaces should be
658       unlocked as soon as possible.  "SDL::Video::unlock_surface" doesn't
659       return anything.
660
661       Note: Since 1.1.8, the surface locks are recursive. See
662       SDL::Video::lock_surface for more information.
663
664   MUSTLOCK
665        int SDL::Video::MUSTLOCK( $surface );
666
667       "MUSTLOCK" returns 0 if the surface does not have to be locked during
668       pixel operations, otherwise 1.
669

Screen Updating Functions

671   set_clip_rect
672        SDL::Video::set_clip_rect( $surface, $rect );
673
674       Sets the clipping rectangle for the given SDL::Surface. When this
675       surface is the destination of a blit, only the area within the clip
676       rectangle will be drawn into.  The rectangle pointed to by rect will be
677       clipped to the edges of the surface so that the clip rectangle for a
678       surface can never fall outside the edges of the surface.  If rect is
679       NULL the clipping rectangle will be set to the full size of the
680       surface.  "SDL::Video::set_clip_rect" doesn't returns anything.
681
682   get_clip_rect
683        SDL::Video::get_clip_rect( $surface, $rect );
684
685       Gets the clipping rectangle for the given SDL::Surface. When this
686       surface is the destination of a blit, only the area within the clip
687       rectangle is drawn into.  The rectangle pointed to by rect will be
688       filled with the clipping rectangle of the surface.
689       "SDL::Video::get_clip_rect" doesn't returns anything;
690
691        use SDL;
692        use SDL::Video;
693        use SDL::Rect;
694        use SDL::Surface;
695
696        my $screen_width  = 640;
697        my $screen_height = 480;
698
699        SDL::init(SDL_INIT_VIDEO);
700
701        my $screen  = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
702
703        my $rect = SDL::Rect->new(0, 0, 0, 0);
704
705        SDL::Video::get_clip_rect($screen, $rect);
706
707        printf( "rect is %d, %d, %d, %d\n", $rect->x, $rect->y, $rect->w, $rect->h);
708
709   blit_surface
710        SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
711
712       This performs a fast blit from the given source SDL::Surface to the
713       given destination SDL::Surface.  The width and height in $src_rect
714       determine the size of the copied rectangle. Only the position is used
715       in the $dest_rect (the width and height are ignored). Blits with
716       negative "dest_rect" coordinates will be clipped properly.  If
717       $src_rect is "undef", the entire surface is copied. If $dest_rect is
718       "undef", then the destination position (upper left corner) is (0, 0).
719       The final blit rectangle is saved in $dest_rect after all clipping is
720       performed ($src_rect is not modified).  The blit function should not be
721       called on a locked surface. I.e. when you use your own drawing
722       functions you may need to lock a surface, but this is not the case with
723       "SDL::Video::blit_surface". Like most surface manipulation functions in
724       SDL, it should not be used together with OpenGL.
725
726       The results of blitting operations vary greatly depending on whether
727       "SDL_SRCALPHA" is set or not. See SDL::Video::set_alpha for an
728       explanation of how this affects your results. Colorkeying and alpha
729       attributes also interact with surface blitting.
730       "SDL::Video::blit_surface" doesn't returns anything.
731
732       For an example see SDL::Video::load_BMP.
733
734   update_rect
735        update_rect( $surface, $left, $top, $width, $height );
736
737       Makes sure the given area is updated on the given screen.  The
738       rectangle must be confined within the screen boundaries because there's
739       no clipping.  update_rect doesn't returns any value.
740
741       Note: This function should not be called while screen is locked by
742       SDL::Video::lock_surface
743
744       Note2: If "x", "y", "width" and "height" are all equal to 0,
745       "update_rect" will update the entire screen.
746
747       For an example see SYNOPSIS
748
749   update_rects
750        update_rects( $surface, @rects );
751
752       Makes sure the given list of rectangles is updated on the given screen.
753       The rectangle must be confined within the screen boundaries because
754       there's no clipping.  "update_rects" doesn't returns any value.
755
756       Note: This function should not be called while screen is locked by
757       SDL::Video::lock_surface.
758
759       Example:
760
761        use SDL;
762        use SDL::Video;
763        use SDL::Surface;
764        use SDL::Rect;
765
766        # the size of the window box or the screen resolution if fullscreen
767        my $screen_width   = 800;
768        my $screen_height  = 600;
769
770        SDL::init(SDL_INIT_VIDEO);
771
772        # setting video mode
773        my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
774
775        # drawing the whole screen blue
776        my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
777        SDL::Video::fill_rect($screen_surface,
778                              SDL::Rect->new(0, 0, $screen_width, $screen_height),
779                              $mapped_color);
780
781        my @rects = ();
782        push(@rects, SDL::Rect->new(200,   0, 400, 600));
783        push(@rects, SDL::Rect->new(  0, 150, 800, 300));
784
785        # updating parts of the screen (should look like a cross)
786        SDL::Video::update_rects($screen_surface, @rects);
787
788        sleep(2);
789
790   flip
791        $flip = SDL::Video::flip( $screen_surface );
792
793       On hardware that supports double-buffering, this function sets up a
794       flip and returns.  The hardware will wait for vertical retrace, and
795       then swap video buffers before the next video surface blit or lock will
796       return.  On hardware that doesn't support double-buffering or if
797       "SDL_SWSURFACE" was set, this is equivalent to calling
798       "SDL::Video::update_rect( $screen, 0, 0, 0, 0 )".
799
800       A software screen surface is also updated automatically when parts of a
801       SDL window are redrawn, caused by overlapping windows or by restoring
802       from an iconified state. As a result there is no proper double buffer
803       behavior in windowed mode for a software screen, in contrast to a full
804       screen software mode.
805
806       The "SDL_DOUBLEBUF" flag must have been passed to
807       SDL::Video::set_video_mode, when setting the video mode for this
808       function to perform hardware flipping.
809
810       "flip" returns 0 on success or "-1" on error.
811
812       Note: If you want to swap the buffers of an initialized OpenGL context,
813       use the function SDL::Video::GL_swap_buffers instead.
814
815       Example:
816
817        use SDL;
818        use SDL::Video;
819        use SDL::Surface;
820
821        # the size of the window box or the screen resolution if fullscreen
822        my $screen_width   = 800;
823        my $screen_height  = 600;
824
825        SDL::init(SDL_INIT_VIDEO);
826
827        # setting video mode
828        my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_DOUBLEBUF|SDL_FULLSCREEN);
829
830        # do some video operations here
831
832        # doing page flipping
833        unless( SDL::Video::flip($screen_surface) == 0 )
834        {
835            printf( STDERR "failed to swap buffers: %s\n", SDL::get_error() );
836        }
837

Palette, Color and Pixel Functions

839   set_colors
840        $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )
841
842       Sets a portion of the colormap for the given 8-bit surface.
843
844       When surface is the surface associated with the current display, the
845       display colormap will be updated with the requested colors.  If
846       "SDL_HWPALETTE" was set in SDL::Video::set_video_mode flags,
847       "SDL::Video::set_colors" will always return 1, and the palette is
848       guaranteed to be set the way you desire, even if the window colormap
849       has to be warped or run under emulation.  The color components of a
850       SDL::Color structure are 8-bits in size, giving you a total of 2563 =
851       16777216 colors.  Palettized (8-bit) screen surfaces with the
852       "SDL_HWPALETTE" flag have two palettes, a logical palette that is used
853       for mapping blits to/from the surface and a physical palette (that
854       determines how the hardware will map the colors to the display).
855       "SDL::Video::set_colors" modifies both palettes (if present), and is
856       equivalent to calling SDL::Video::set_palette with the flags set to (
857       "SDL_LOGPAL | SDL_PHYSPAL" ).
858
859       If "surface" is not a palettized surface, this function does nothing,
860       returning 0.  If all of the colors were set as passed to
861       "SDL::Video::set_colors", it will return 1.  If not all the color
862       entries were set exactly as given, it will return 0, and you should
863       look at the surface palette to determine the actual color palette.
864
865   set_palette
866        $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );
867
868       Sets a portion of the palette for the given 8-bit surface.
869
870       Palettized (8-bit) screen surfaces with the "SDL_HWPALETTE" flag have
871       two palettes, a logical palette that is used for mapping blits to/from
872       the surface and a physical palette (that determines how the hardware
873       will map the colors to the display).  Non screen surfaces have a
874       logical palette only. SDL::Video::blit always uses the logical palette
875       when blitting surfaces (if it has to convert between surface pixel
876       formats). Because of this, it is often useful to modify only one or the
877       other palette to achieve various special color effects (e.g., screen
878       fading, color flashes, screen dimming).
879
880       This function can modify either the logical or physical palette by
881       specifying "SDL_LOGPAL" or "SDL_PHYSPAL" the in the flags parameter.
882
883       When surface is the surface associated with the current display, the
884       display colormap will be updated with the requested colors.  If
885       "SDL_HWPALETTE" was set in SDL::Video::set_video_mode flags,
886       "SDL::Video::set_palette" will always return 1, and the palette is
887       guaranteed to be set the way you desire, even if the window colormap
888       has to be warped or run under emulation.  The color components of a
889       "SDL::Color" structure are 8-bits in size, giving you a total of 2563 =
890       16777216 colors.
891
892       If "surface" is not a palettized surface, this function does nothing,
893       returning 0. If all of the colors were set as passed to "set_palette",
894       it will return 1. If not all the color entries were set exactly as
895       given, it will return 0, and you should look at the surface palette to
896       determine the actual color palette.
897
898   set_gamma
899        $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );
900
901       Sets the "gamma function" for the display of each color component.
902       Gamma controls the brightness/contrast of colors displayed on the
903       screen.  A gamma value of 1.0 is identity (i.e., no adjustment is
904       made).
905
906       This function adjusts the gamma based on the "gamma function"
907       parameter, you can directly specify lookup tables for gamma adjustment
908       with SDL::set_gamma_ramp.
909
910       Note: Not all display hardware is able to change gamma.
911
912       "SDL::Video::set_gamma" returns "-1" on error.
913
914       Warning: Under Linux (X.org Gnome and Xfce), gamma settings affects the
915       entire display (including the desktop)!
916
917       Example:
918
919        use SDL;
920        use SDL::Video;
921        use SDL::Surface;
922        use SDL::Rect;
923        use Time::HiRes qw( usleep );
924
925        # the size of the window box or the screen resolution if fullscreen
926        my $screen_width   = 800;
927        my $screen_height  = 600;
928
929        SDL::init(SDL_INIT_VIDEO);
930
931        # setting video mode
932        my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
933
934        # drawing something somewhere
935        my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 128, 128, 128); # gray
936        SDL::Video::fill_rect($screen_surface,
937                              SDL::Rect->new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2),
938                              $mapped_color);
939
940        # update the whole screen
941        SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);
942
943        usleep(500000);
944
945        for(1..20)
946        {
947           SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
948               usleep(40000);
949        }
950
951        for(1..20)
952        {
953           SDL::Video::set_gamma( $_ / 20, 1, 1 );
954               usleep(40000);
955        }
956
957        SDL::Video::set_gamma( 1, 1, 1 );
958
959        usleep(500000);
960
961   get_gamma_ramp
962        $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );
963
964       Gets the gamma translation lookup tables currently used by the display.
965       Each table is an array of 256 Uint16 values.
966       "SDL::Video::get_gamma_ramp" returns -1 on error.
967
968        use SDL;
969        use SDL::Video;
970
971        SDL::init(SDL_INIT_VIDEO);
972
973        my (@red, @green, @blue);
974
975        my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
976
977        if( -1 == $ret )
978        {
979            print( "an error occurred" );
980        }
981        else
982        {
983            printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
984            printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
985            printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0],   $green[0],   $blue[0]   );
986        }
987
988   set_gamma_ramp
989        $set_gamma_ramp = SDL::Video::set_gamma_ramp( \@red_table, \@green_table, \@blue_table );
990
991       Sets the gamma lookup tables for the display for each color component.
992       Each table is an array ref of 256 Uint16 values, representing a mapping
993       between the input and output for that channel.  The input is the index
994       into the array, and the output is the 16-bit gamma value at that index,
995       scaled to the output color precision.  You may pass NULL to any of the
996       channels to leave them unchanged.
997
998       This function adjusts the gamma based on lookup tables, you can also
999       have the gamma calculated based on a "gamma function" parameter with
1000       SDL::Video::set_gamma.
1001
1002       Not all display hardware is able to change gamma.
1003       "SDL::Video::set_gamma_ramp" returns "-1" on error (or if gamma
1004       adjustment is not supported).
1005
1006       Example:
1007
1008        use SDL;
1009        use SDL::Video;
1010
1011        SDL::init(SDL_INIT_VIDEO);
1012
1013        my (@red, @green, @blue);
1014
1015        my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1016
1017        $red[127] = 0xFF00;
1018
1019           $ret = SDL::Video::set_gamma_ramp( \@red, \@green, \@blue );
1020
1021           $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );
1022
1023        if( -1 == $ret )
1024        {
1025            print( "an error occurred" );
1026        }
1027        else
1028        {
1029            printf( "for gamma = 1.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[255], $green[255], $blue[255] );
1030            printf( "for gamma = 0.5: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[127], $green[127], $blue[127] );
1031            printf( "for gamma = 0.0: red=0x%04X, green=0x%04X, blue=0x%04X\n", $red[0],   $green[0],   $blue[0]   );
1032        }
1033
1034   map_RGB
1035        $pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b );
1036
1037       Maps the RGB color value to the specified SDL::PixelFormat and returns
1038       the pixel value as a 32-bit int.  If the format has a palette (8-bit)
1039       the index of the closest matching color in the palette will be
1040       returned.  If the specified pixel format has an alpha component it will
1041       be returned as all 1 bits (fully opaque).
1042
1043       "SDL::Video::map_RGB" returns a pixel value best approximating the
1044       given RGB color value for a given pixel format.  If the
1045       SDL::PixelFormat's  bpp (color depth) is less than 32-bpp then the
1046       unused upper bits of the return value can safely be ignored (e.g., with
1047       a 16-bpp format the return value can be assigned to a Uint16, and
1048       similarly a Uint8 for an 8-bpp format).
1049
1050        use SDL;
1051        use SDL::Video;
1052        use SDL::PixelFormat;
1053        use SDL::Surface;
1054
1055        SDL::init(SDL_INIT_VIDEO);
1056
1057        my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
1058        #                                                          ^-- 16 bits per pixel
1059
1060        $r = 0x9C;
1061        $g = 0xDC;
1062        $b = 0x67;
1063
1064        printf( "for 24bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b);
1065
1066        my $_16bit = SDL::Video::map_RGB( $screen_surface->format, $r, $g, $b );
1067
1068        # 16bpp is 5 bits red, 6 bits green and 5 bits blue
1069        # we will obtain the values for each color and calculating them back to 24/32bit color system
1070        ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface->format, $_16bit ) };
1071
1072        printf( "for 16bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b );
1073
1074        # so color #9CDC67 becomes #9CDF63
1075
1076   map_RGBA
1077        $pixel = SDL::Video::map_RGBA( $pixel_format, $r, $g, $b, $a );
1078
1079       Maps the RGBA color value to the specified SDL::PixelFormat and returns
1080       the pixel value as a 32-bit int.  If the format has a palette (8-bit)
1081       the index of the closest matching color in the palette will be
1082       returned.  If the specified pixel format has no alpha component the
1083       alpha value will be ignored (as it will be in formats with a palette).
1084
1085       A pixel value best approximating the given RGBA color value for a given
1086       pixel format.  If the pixel format bpp (color depth) is less than
1087       32-bpp then the unused upper bits of the return value can safely be
1088       ignored (e.g., with a 16-bpp format the return value can be assigned to
1089       a Uint16, and similarly a Uint8 for an 8-bpp format).
1090
1091   get_RGB
1092        $rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel );
1093
1094       Returns RGB values from a pixel in the specified pixel format. The
1095       pixel is an integer (e.g. 16bit RGB565, 24/32bit RGB888).  This
1096       function uses the entire 8-bit [0..255] range when converting color
1097       components from pixel formats with less than 8-bits per RGB component
1098       (e.g., a completely white pixel in 16-bit RGB565 format would return
1099       [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
1100
1101       For an example see SDL::Video::map_RGB.
1102
1103   get_RGBA
1104        $rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel );
1105
1106       Gets RGBA values from a pixel in the specified pixel format.  This
1107       function uses the entire 8-bit [0..255] range when converting color
1108       components from pixel formats with less than 8-bits per RGB component
1109       (e.g., a completely white pixel in 16-bit RGB565 format would return
1110       [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
1111
1112       If the surface has no alpha component, the alpha will be returned as
1113       0xff (100% opaque).
1114

GL Methods

1116   GL_load_library
1117        $gl_load_lib = SDL::Video::GL_load_library( 'path/to/static/glfunctions.dll' );
1118
1119       If you wish, you may load the OpenGL library from the given path at
1120       runtime, this must be done before SDL::Video::set_video_mode is called.
1121       You must then use SDL::Video::GL_get_proc_address to retrieve function
1122       pointers to GL functions.
1123
1124       "GL_load_library" returns 0 on success or "-1" or error.
1125
1126   GL_get_proc_address
1127        $proc_address = SDL::Video::GL_get_proc_address( $proc );
1128
1129       Returns the address of the GL function proc, or NULL if the function is
1130       not found. If the GL library is loaded at runtime, with
1131       SDL::Video::GL_load_library, then all GL functions must be retrieved
1132       this way. Usually this is used to retrieve function pointers to OpenGL
1133       extensions. Note that this function needs an OpenGL context to function
1134       properly, so it should be called after SDL::Video::set_video_mode has
1135       been called (with the "SDL_OPENGL" flag).
1136
1137       It returns undef if the function is not found.
1138
1139       Example:
1140
1141        my $has_multitexture = 1;
1142
1143        # Get function pointer
1144        $gl_active_texture_ARB_ptr = SDL::Video::GL_get_proc_address("glActiveTextureARB");
1145
1146        # Check for a valid function ptr
1147        unless($gl_active_texture_ARB_ptr)
1148        {
1149            printf( STDERR "Multitexture Extensions not present.\n" );
1150            $has_multitexture = 0;
1151        }
1152
1153        $gl_active_texture_ARB_ptr(GL_TEXTURE0_ARB) if $has_multitexture;
1154
1155   GL_get_attribute
1156        $value = SDL::Video::GL_get_attribute( $attr );
1157
1158       It returns SDL/OpenGL attribute "attr". This is useful after a call to
1159       SDL::Video::set_video_mode to check whether your attributes have been
1160       set as you expected.  "SDL::Video::GL_get_attribute" returns "undef" if
1161       the attribute is not found.
1162
1163       Example:
1164
1165        print( SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE) );
1166
1167   GL_set_attribute
1168        $set_attr = SDL::Video::GL_set_attribute( $attr, $value );
1169
1170       This function sets the given OpenGL attribute "attr" to "value". The
1171       requested attributes will take effect after a call to
1172       SDL::Video::set_video_mode.  You should use
1173       "SDL::Video::GL_get_attribute|/GL_get_attribute" to check the values
1174       after a SDL::Video::set_video_mode call, since the values obtained can
1175       differ from the requested ones.
1176
1177       Available attributes:
1178
1179       ·   "SDL_GL_RED_SIZE"
1180
1181       ·   "SDL_GL_GREEN_SIZE"
1182
1183       ·   "SDL_GL_BLUE_SIZE"
1184
1185       ·   "SDL_GL_ALPHA_SIZE"
1186
1187       ·   "SDL_GL_BUFFER_SIZE"
1188
1189       ·   "SDL_GL_DOUBLEBUFFER"
1190
1191       ·   "SDL_GL_DEPTH_SIZE"
1192
1193       ·   "SDL_GL_STENCIL_SIZE"
1194
1195       ·   "SDL_GL_ACCUM_RED_SIZE"
1196
1197       ·   "SDL_GL_ACCUM_GREEN_SIZE"
1198
1199       ·   "SDL_GL_ACCUM_BLUE_SIZE"
1200
1201       ·   "SDL_GL_ACCUM_ALPHA_SIZE"
1202
1203       ·   "SDL_GL_STEREO"
1204
1205       ·   "SDL_GL_MULTISAMPLEBUFFERS"
1206
1207       ·   "SDL_GL_MULTISAMPLESAMPLES"
1208
1209       ·   "SDL_GL_ACCELERATED_VISUAL"
1210
1211       ·   "SDL_GL_SWAP_CONTROL"
1212
1213       "GL_set_attribute" returns 0 on success or "-1" on error.
1214
1215       Note: The "SDL_DOUBLEBUF" flag is not required to enable double
1216       buffering when setting an OpenGL video mode. Double buffering is
1217       enabled or disabled using the "SDL_GL_DOUBLEBUFFER" attribute.
1218
1219       Example:
1220
1221        SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE, 5);
1222
1223   GL_swap_buffers
1224        SDL::Video::GL_swap_buffers();
1225
1226       Swap the OpenGL buffers, if double-buffering is supported.
1227       "SDL::Video::GL_swap_buffers" doesn't returns any value.
1228

Video Overlay Functions

1230       see SDL::Overlay
1231
1232   lock_YUV_overlay
1233        $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );
1234
1235       Much the same as SDL::Video::lock_surface, "lock_YUV_overlay" locks the
1236       overlay for direct access to pixel data.  It returns 0 on success or
1237       "-1" on error.
1238
1239   unlock_YUV_overlay
1240        SDL::Video::unlock_YUV_overlay( $overlay );
1241
1242       The opposite to SDL::Video::lock_YUV_overlay. Unlocks a previously
1243       locked overlay. An overlay must be unlocked before it can be displayed.
1244       "unlock_YUV_overlay" does not return anything.
1245
1246   display_YUV_overlay
1247        $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );
1248
1249       Blit the overlay to the display surface specified when the overlay was
1250       created. The SDL::Rect structure, "dstrect", specifies a rectangle on
1251       the display where the overlay is drawn. The "x" and "y" fields of
1252       "dstrect" specify the upper left location in display coordinates.  The
1253       overlay is scaled (independently in x and y dimensions) to the size
1254       specified by dstrect, and is "optimized" for 2x scaling
1255
1256       It returns 0 on success or "-1" on error.
1257

Window Management Functions

1259   wm_set_caption
1260        SDL::Video::wm_set_caption( $title, $icon );
1261
1262       Sets the title-bar and icon name of the display window.
1263
1264       "title" is a UTF-8 encoded null-terminated string which will serve as
1265       the window title (the text at the top of the window). The function does
1266       not change the string. You may free the string after the function
1267       returns.
1268
1269       "icon" is a UTF-8 encoded null-terminated string which will serve as
1270       the iconified window title (the text which is displayed in the menu bar
1271       or desktop when the window is minimized). As with title this string may
1272       be freed after the function returns.
1273
1274       Example:
1275
1276        use SDL;
1277        use SDL::Video;
1278        use SDL::Surface;
1279
1280        SDL::init(SDL_INIT_VIDEO);
1281
1282        my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1283
1284        SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1285
1286        sleep(2);
1287
1288   wm_get_caption
1289        SDL::Video::wm_get_caption( $title, $icon );
1290
1291       Retrieves the title-bar and icon name of the display window.
1292
1293       Example:
1294
1295        use SDL;
1296        use SDL::Video;
1297        use SDL::Surface;
1298
1299        SDL::init(SDL_INIT_VIDEO);
1300
1301        my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1302
1303        SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
1304
1305        my ($title, $icon) = @{ SDL::Video::wm_get_caption() };
1306
1307        printf( "title is '%s' and icon is '%s'\n", $title, $icon );
1308
1309   wm_set_icon
1310        SDL::Video::wm_set_icon( $icon );
1311
1312       Sets the icon for the display window. Win32 icons must be 32x32.
1313
1314       This function must be called before the first call to
1315       SDL::Video::set_video_mode. Note that this means SDL::Image cannot be
1316       used.
1317
1318       The shape is determined by the colorkey or alpha channel of the icon,
1319       if any. If neither of those are present, the icon is made opaque (no
1320       transparency).
1321
1322       Example:
1323
1324        SDL::Video::wm_set_icon(SDL::Video::load_BMP("icon.bmp"));
1325
1326       Another option, if your icon image does not have a colorkey set, is to
1327       use the SDL::Video::set_color_key to set the transparency.
1328
1329       Example:
1330
1331        my $image = SDL::Video::load_BMP("icon.bmp");
1332
1333        my colorkey = SDL::Video::map_RGB($image->format, 255, 0, 255); # specify the color that will be transparent
1334
1335        SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);
1336
1337        SDL::Video::wm_set_icon($image);
1338
1339   wm_grab_input
1340        $grab_mode = SDL::Video::wm_grab_input($mode);
1341
1342       Grabbing means that the mouse is confined to the application window,
1343       and nearly all keyboard input is passed directly to the application,
1344       and not interpreted by a window manager, if any.
1345
1346       When mode is "SDL_GRAB_QUERY" the grab mode is not changed, but the
1347       current grab mode is returned.
1348
1349       "mode" and the return value of "wm_grab_input" can be one of the
1350       following:
1351
1352       ·   "SDL_GRAB_QUERY"
1353
1354       ·   "SDL_GRAB_OFF"
1355
1356       ·   "SDL_GRAB_ON"
1357
1358   wm_iconify_window
1359        $iconify_window = SDL::Video::wm_iconify_window();
1360
1361       If the application is running in a window managed environment SDL
1362       attempts to iconify/minimise it. If "wm_iconify_window" is successful,
1363       the application will receive a "SDL_APPACTIVE" loss event (see
1364       Application visibility events at SDL::Event).
1365
1366       Returns non-zero on success or 0 if iconification is not supported or
1367       was refused by the window manager.
1368
1369       Example:
1370
1371        use SDL;
1372        use SDL::Video;
1373        use SDL::Surface;
1374
1375        SDL::init(SDL_INIT_VIDEO);
1376
1377        my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
1378
1379        sleep(2);
1380
1381        SDL::Video::wm_iconify_window();
1382
1383        sleep(2);
1384
1385   wm_toggle_fullscreen
1386        $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
1387
1388       Toggles the application between windowed and fullscreen mode, if
1389       supported. (X11 is the only target currently supported, BeOS support is
1390       experimental).
1391

AUTHORS

1393       See "AUTHORS" in SDL.
1394

NAME

CATEGORY

SYNOPSIS

CONSTANTS

Core Functions

Surface Locking and Unlocking

Screen Updating Functions

Palette, Color and Pixel Functions

GL Methods

Video Overlay Functions

Window Management Functions

AUTHORS

SEE ALSO