view release on metacpan or  search on metacpan

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

=head1 Palette, Color and Pixel Functions

=head2	set_colors

 $set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... )

Sets a portion of the colormap for the given 8-bit surface. 

When surface is the surface associated with the current display, the display colormap will be updated with the requested colors. 
If C<SDL_HWPALETTE> was set in L<SDL::Video::set_video_mode|/set_video_mode> flags, C<SDL::Video::set_colors> will always return 1, and the 
palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
The color components of a L<SDL::Color> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors.
Palettized (8-bit) screen surfaces with the C<SDL_HWPALETTE> flag have two palettes, a logical palette that is used for mapping blits to/from 
the surface and a physical palette (that determines how the hardware will map the colors to the display). 
C<SDL::Video::set_colors> modifies both palettes (if present), and is equivalent to calling L<SDL::Video::set_palette|/set_palette> with the 
flags set to ( C<SDL_LOGPAL | SDL_PHYSPAL> ). 

If C<surface> is not a palettized surface, this function does nothing, returning 0. 
If all of the colors were set as passed to C<SDL::Video::set_colors>, it will return 1.
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 
actual color palette.

=head2	set_palette

 $set_palette = set_palette( $surface, $flags, $start, $color1, $color2, ... );

Sets a portion of the palette for the given 8-bit surface.

Palettized (8-bit) screen surfaces with the C<SDL_HWPALETTE> flag have two palettes, a logical palette that is used for mapping blits to/from 
the surface and a physical palette (that determines how the hardware will map the colors to the display). 
Non screen surfaces have a logical palette only. L<SDL::Video::blit|/blit> always uses the logical palette when blitting surfaces (if it has to 
convert between surface pixel formats). Because of this, it is often useful to modify only one or the other palette to achieve various 
special color effects (e.g., screen fading, color flashes, screen dimming).

This function can modify either the logical or physical palette by specifying C<SDL_LOGPAL> or C<SDL_PHYSPAL> the in the flags parameter.

When surface is the surface associated with the current display, the display colormap will be updated with the requested colors.
If C<SDL_HWPALETTE> was set in L<SDL::Video::set_video_mode|/set_video_mode> flags, C<SDL::Video::set_palette> will always return 1, and the 
palette is guaranteed to be set the way you desire, even if the window colormap has to be warped or run under emulation.
The color components of a C<SDL::Color> structure are 8-bits in size, giving you a total of 2563 = 16777216 colors. 

If C<surface> is not a palettized surface, this function does nothing, returning C<0>. If all of the colors were set as passed to C<set_palette>,
it will return C<1>. If not all the color entries were set exactly as given, it will return C<0>, and you should look at the surface palette 
to determine the actual color palette.

=head2	set_gamma

 $set_gamma = SDL::Video::set_gamma( $red_gamma, $green_gamma, $blue_gamma );

Sets the "gamma function" for the display of each color component. Gamma controls the brightness/contrast of colors displayed on the screen. 
A gamma value of 1.0 is identity (i.e., no adjustment is made).

This function adjusts the gamma based on the "gamma function" parameter, you can directly specify lookup tables for gamma adjustment 
with SDL::set_gamma_ramp.

B<Note>: Not all display hardware is able to change gamma.

C<SDL::Video::set_gamma> returns C<-1> on error.

B<Warning>: Under Linux (X.org Gnome and Xfce), gamma settings affects the entire display (including the desktop)! 

Example:

 use SDL;
 use SDL::Video;
 use SDL::Surface;
 use SDL::Rect;
 use Time::HiRes qw( usleep );

 # 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_SWSURFACE);
 
 # drawing something somewhere
 my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 128, 128, 128); # gray
 SDL::Video::fill_rect($screen_surface, 
                       SDL::Rect->new($screen_width / 4, $screen_height / 4, $screen_width / 2, $screen_height / 2), 
                       $mapped_color);
 
 # update the whole screen
 SDL::Video::update_rect($screen_surface, 0, 0, $screen_width, $screen_height);

 usleep(500000);
 
 for(1..20)
 {
    SDL::Video::set_gamma( 1 - $_ / 20, 1, 1 );
	usleep(40000);
 }
 
 for(1..20)
 {
    SDL::Video::set_gamma( $_ / 20, 1, 1 );
	usleep(40000);
 }

 SDL::Video::set_gamma( 1, 1, 1 );
 
 usleep(500000);

=head2	get_gamma_ramp

 $get_gamma_ramp = SDL::Video::get_gamma_ramp( \@red_table, \@green_table, \@blue_table );

Gets the gamma translation lookup tables currently used by the display. Each table is an array of 256 Uint16 values.
C<SDL::Video::get_gamma_ramp> returns -1 on error.

 use SDL;
 use SDL::Video;

 SDL::init(SDL_INIT_VIDEO);

 my (@red, @green, @blue);
 
 my $ret = SDL::Video::get_gamma_ramp( \@red, \@green, \@blue );

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

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> 
cannot be used.

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 
(no transparency).

Example:

 SDL::Video::wm_set_icon(SDL::Video::load_BMP("icon.bmp"));

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.

Example:

 my $image = SDL::Video::load_BMP("icon.bmp");

 my colorkey = SDL::Video::map_RGB($image->format, 255, 0, 255); # specify the color that will be transparent