overlay results from the CPAN

SDL

 use SDL::Video;
 use SDL::Surface;
 use SDL::Rect;

 # the size of the window box or the screen resolution if fullscreen
 my $screen_width   = 800;
 my $screen_height  = 600;

 SDL::init(SDL_INIT_VIDEO);

 # setting video mode
 my $screen_surface = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_ANYFORMAT);
 
 # drawing something somewhere
 my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
 SDL::Video::fill_rect($screen_surface, 
                       SDL::Rect->new($screen_width / 4, $screen_height / 4, 
                                      $screen_width / 2, $screen_height / 2), $mapped_color);
 
 # update an area on the screen so its visible
 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);

 sleep(5); # just to have time to see it

=head1 CONSTANTS

The constants are exported by default. You can avoid this by doing:

 use SDL::Video ();

and access them directly:

 SDL::Video::SDL_SWSURFACE;

or by choosing the export tags below:

Export tag: ':surface'

 SDL_ASYNCBLIT       Use asynchronous blit if possible
 SDL_SWSURFACE       Stored in the system memory.
 SDL_HWSURFACE       Stored in video memory

Export tag: ':video'

 SDL_ANYFORMAT       Allow any pixel-format
 SDL_HWPALETTE       Have an exclusive palette
 SDL_DOUBLEBUF       Double buffered
 SDL_FULLSCREEN      Full screen surface
 SDL_OPENGL          Have an OpenGL context
 SDL_OPENGLBLIT      Support OpenGL blitting. 
                     NOTE: This option is kept for compatibility only, and is not recommended for new code.
 SDL_RESIZABLE       Resizable surface
 SDL_NOFRAME         No window caption or edge frame
 SDL_HWACCEL         Use hardware acceleration blit
 SDL_SRCCOLORKEY     Use colorkey blitting
 SDL_RLEACCELOK      Private flag
 SDL_RLEACCEL        Accelerated colorkey blitting with RLE
 SDL_SRCALPHA        Use alpha blending blit
 SDL_PREALLOC        Use preallocated memory

Export tag ':overlay'

 SDL_YV12_OVERLAY    Planar mode: Y + V + U  (3 planes)
 SDL_IYUV_OVERLAY    Planar mode: Y + U + V  (3 planes)
 SDL_YUY2_OVERLAY    Packed mode: Y0+U0+Y1+V0 (1 plane)
 SDL_UYVY_OVERLAY    Packed mode: U0+Y0+V0+Y1 (1 plane)
 SDL_YVYU_OVERLAY    Packed mode: Y0+V0+Y1+U0 (1 plane)

Export tag ':palette'

 SDL_LOGPAL          Logical palette, which controls how blits are mapped to/from the surface
 SDL_PHYSPAL         Physical palette, which controls how pixels look on the screen
 
Export tag ':grab'

 SDL_GRAB_QUERY
 SDL_GRAB_OFF
 SDL_GRAB_ON
 SDL_GRAB_FULLSCREEN Used internally

Export tag ':gl'

 SDL_GL_RED_SIZE
 SDL_GL_GREEN_SIZE
 SDL_GL_BLUE_SIZE
 SDL_GL_ALPHA_SIZE
 SDL_GL_BUFFER_SIZE
 SDL_GL_DOUBLEBUFFER
 SDL_GL_DEPTH_SIZE
 SDL_GL_STENCIL_SIZE
 SDL_GL_ACCUM_RED_SIZE
 SDL_GL_ACCUM_GREEN_SIZE
 SDL_GL_ACCUM_BLUE_SIZE
 SDL_GL_ACCUM_ALPHA_SIZE
 SDL_GL_STEREO
 SDL_GL_MULTISAMPLEBUFFERS
 SDL_GL_MULTISAMPLESAMPLES
 SDL_GL_ACCELERATED_VISUAL
 SDL_GL_SWAP_CONTROL

=head1 Core Functions

=head2	get_video_surface

 my $surface = SDL::Video::get_video_surface();

This function returns the current display L<SDL::Surface>. If SDL is doing format conversion on the display surface, this 
function returns the publicly visible surface, not the real video surface.

Example:

 # somewhere after you set the video mode
 my $surface = SDL::Video::get_video_surface();
 
 printf( "our screen is %d pixels wide and %d pixels high\n", $surface->w, $surface->h );

=head2	get_video_info

 my $video_info = SDL::Video::get_video_info();

This function returns a read-only L<structure|SDL::VideoInfo> containing information about the video hardware. If it is called before

lib/pods/SDL/Video.pod view on Meta::CPAN


The surface parameter specifies which SDL::surface whose alpha attributes you wish to adjust. 
flags is used to specify whether alpha blending should be used ( C<SDL_SRCALPHA> ) and whether the surface should use RLE acceleration for 
blitting ( C<SDL_RLEACCEL> ). 
flags can be an OR'd combination of these two options, one of these options or C<0>. 
If C<SDL_SRCALPHA> is not passed as a flag then all alpha information is ignored when blitting the surface. 
The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can 
still be accelerated with C<SDL_RLEACCEL>.

B<Note>: The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.

Alpha affects surface blitting in the following ways: 

=over 4

=item RGBA->RGB with C<SDL_SRCALPHA>

The source is alpha-blended with the destination, using the alpha channel. 
SDL_SRCCOLORKEY and the per-surface alpha are ignored.

=item RGBA->RGB without C<SDL_SRCALPHA>

The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored. 
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

=item RGB->RGBA with C<SDL_SRCALPHA>

The source is alpha-blended with the destination using the per-surface alpha value. 
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied. 
The alpha channel of the copied pixels is set to opaque.

=item RGB->RGBA without C<SDL_SRCALPHA>

The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque. 
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

=item RGBA->RGBA with C<SDL_SRCALPHA>

The source is alpha-blended with the destination using the source alpha channel. 
The alpha channel in the destination surface is left untouched. SDL_SRCCOLORKEY is ignored.

=item RGBA->RGBA without C<SDL_SRCALPHA>

The RGBA data is copied to the destination surface.
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

=item RGB->RGB with C<SDL_SRCALPHA>

The source is alpha-blended with the destination using the per-surface alpha value. 
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

=item RGB->RGB without C<SDL_SRCALPHA>

The RGB data is copied from the source. 
If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

=back

B<Note>: When blitting, the presence or absence of C<SDL_SRCALPHA> is relevant only on the source surface, not the destination.
B<Note>: Note that RGBA->RGBA blits (with C<SDL_SRCALPHA> set) keep the alpha of the destination surface. This means that you cannot compose 
two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask.

B<Note>: Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available. 

C<SDL::Video::set_alpha> returns C<0> on success or C<-1> on error.

=head2	fill_rect

 $fill_rect = SDL::Video::fill_rect( $dest, $dest_rect, $pixel );

This function performs a fast fill of the given L<SDL::Rect> with the given L<SDL::PixelFormat>. If dest_rect is NULL, the whole surface 
will be filled with color.

The color should be a pixel of the format used by the surface, and can be generated by the L<SDL::Video::map_RGB|/map_RGB> or 
C<SDL::Video::map_RGBA|/map_RGBA> functions. If the color value contains an alpha value then the destination is simply "filled" with that 
alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via L<SDL::Video::set_clip_rect|/set_clip_rect>), then this function will clip based 
on the intersection of the clip rectangle and the dstrect rectangle, and the dstrect rectangle will be modified to represent the area actually 
filled.

If you call this on the video surface (ie: the value of L<SDL::Video::get_video_surface|/get_video_surface>) you may have to update the video 
surface to see the result. This can happen if you are using a shadowed surface that is not double buffered in Windows XP using build 1.2.9. 

C<SDL::Video::fill_rect> returns C<0> on success or C<-1> on error.

for an example see L</SYNOPSIS>.

=head1 Surface Locking and Unlocking

=head2	lock_surface

 int SDL::Video::lock_surface( $surface );

C<SDL::Video::lock_surface> sets up the given L<SDL::Surface> for directly accessing the pixels.
Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to ( C<surface->set_pixels>) and read from ( C<surface->get_pixels> ), 
using the pixel format stored in C<surface->format>. 
Once you are done accessing the surface, you should use L<SDL::Video::unlock_surface|/unlock_surface> to release the lock.

Not all surfaces require locking. If L<SDL::Video::MUSTLOCK|/MUSTLOCK> evaluates to C<0>, then reading and writing pixels to the surface can 
be performed at any time, and the pixel format of the surface will not change.
No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.
C<SDL::Video::lock_surface> returns C<0> on success or C<-1> on error.

B<Note>: Since SDL 1.1.8, the surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have 
a matching unlock.

 use strict;
 use warnings;
 use Carp;
 
 use SDL v2.3;
 use SDL::Video;
 use SDL::Event;
 use SDL::Events;
 use SDL::Surface;
 
 my $screen;
 
 sub putpixel
 {

lib/pods/SDL/Video.pod view on Meta::CPAN

C<SDL_GL_STENCIL_SIZE>

=item *

C<SDL_GL_ACCUM_RED_SIZE>

=item *

C<SDL_GL_ACCUM_GREEN_SIZE>

=item *

C<SDL_GL_ACCUM_BLUE_SIZE>

=item *

C<SDL_GL_ACCUM_ALPHA_SIZE>

=item *

C<SDL_GL_STEREO>

=item *

C<SDL_GL_MULTISAMPLEBUFFERS>

=item *

C<SDL_GL_MULTISAMPLESAMPLES>

=item *

C<SDL_GL_ACCELERATED_VISUAL>

=item *

C<SDL_GL_SWAP_CONTROL>

=back

C<GL_set_attribute> returns C<0> on success or C<-1> on error.

B<Note>: The C<SDL_DOUBLEBUF> flag is not required to enable double buffering when setting an OpenGL video mode. Double buffering is enabled 
or disabled using the C<SDL_GL_DOUBLEBUFFER> attribute. 

Example:

 SDL::Video::GL_set_attribute(SDL_GL_RED_SIZE, 5);

=head2	GL_swap_buffers

 SDL::Video::GL_swap_buffers();

Swap the OpenGL buffers, if double-buffering is supported.
C<SDL::Video::GL_swap_buffers> doesn't returns any value.

=head1 Video Overlay Functions

see L<SDL::Overlay> 

=head2	lock_YUV_overlay

 $lock_overlay = SDL::Video::lock_YUV_overlay( $overlay );

Much the same as L<SDL::Video::lock_surface|/lock_surface>, C<lock_YUV_overlay> locks the overlay for direct access to pixel data.
It returns C<0> on success or C<-1> on error.

=head2	unlock_YUV_overlay

 SDL::Video::unlock_YUV_overlay( $overlay );

The opposite to L<SDL::Video::lock_YUV_overlay|/sock_YUV_overlay>. Unlocks a previously locked overlay. An overlay must be unlocked before it 
can be displayed. C<unlock_YUV_overlay> does not return anything.

=head2	display_YUV_overlay

 $display_overlay = SDL::Video::display_YUV_overlay( $overlay, $dstrect );

Blit the overlay to the display surface specified when the overlay was created. The L<SDL::Rect> structure, C<dstrect>, specifies a rectangle 
on the display where the overlay is drawn. The C<x> and C<y> fields of C<dstrect> specify the upper left location in display coordinates. 
The overlay is scaled (independently in x and y dimensions) to the size specified by dstrect, and is C<optimized> for 2x scaling

It returns C<0> on success or C<-1> on error.

=head1 Window Management Functions

=head2	wm_set_caption

 SDL::Video::wm_set_caption( $title, $icon );

Sets the title-bar and icon name of the display window.

C<title> is a UTF-8 encoded null-terminated string which will serve as the window title (the text at the top of the window). The function 
does not change the string. You may free the string after the function returns.

C<icon> is a UTF-8 encoded null-terminated string which will serve as the iconified window title (the text which is displayed in the menu 
bar or desktop when the window is minimized). As with title this string may be freed after the function returns. 

Example:

 use SDL;
 use SDL::Video;
 use SDL::Surface;
 
 SDL::init(SDL_INIT_VIDEO);
 
 my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
 
 SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
 
 sleep(2);

=head2	wm_get_caption

 SDL::Video::wm_get_caption( $title, $icon );

Retrieves the title-bar and icon name of the display window.

Example:

 use SDL;
 use SDL::Video;
 use SDL::Surface;
 
 SDL::init(SDL_INIT_VIDEO);
 
 my $screen  = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
 
 SDL::Video::wm_set_caption( 'maximized title', 'minimized title' );
 
 my ($title, $icon) = @{ SDL::Video::wm_get_caption() };
 
 printf( "title is '%s' and icon is '%s'\n", $title, $icon );

=head2	wm_set_icon

 SDL::Video::wm_set_icon( $icon );

Sets the icon for the display window. Win32 icons must be 32x32.

This function must be called before the first call to L<SDL::Video::set_video_mode|/set_video_mode>. Note that this means L<SDL::Image>

( run in 1.858 second using v1.01-cache-2.11-cpan-39bf76dae61 )