From: Tobias Leich Date: Sun, 29 Nov 2009 20:24:04 +0000 (+0100) Subject: docs for video X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8edb6a07c21ec2f6097cc78c57d039a3513785de;p=sdlgit%2FSDL-Site.git docs for video --- diff --git a/pages/SDL-Video.html-inc b/pages/SDL-Video.html-inc index ced5163..8a91c05 100644 --- a/pages/SDL-Video.html-inc +++ b/pages/SDL-Video.html-inc @@ -248,7 +248,7 @@ It returns 0 if the mode is not supported at all, otherwise the sug unless($video_mode_ok) { - printf("this video mode ist not supported\n" ); + printf( "this video mode is not supported\n" ); } SDL::quit(); @@ -351,7 +351,7 @@ each call to SDL::Video::set_vid

Creates a new SDL::surface of the specified SDL::PixelFormat, and then copies and maps the given surface to it. It is also useful for making a copy of a surface.

-

The flags parameter is passed to SDL::Surface-new()> and has those semantics. +

The flags parameter is passed to SDL::Surface->new() and has those semantics. This function is used internally by SDL::Video::display_format. This function can only be called after SDL::init.

it returns a SDL::Surface on success or undef on error.

@@ -655,38 +655,66 @@ be unlocked as soon as possible.

set_clip_rect(surface,rect)

-

Sets the clipping rectangle for the given SDL::surface. When this surface is the destination of a blit, only the area within the clip +

 SDL::Video::set_clip_rect( $surface, $rect );
+
+
+

Sets the clipping rectangle for the given SDL::Surface. When this surface is the destination of a blit, only the area within the clip rectangle will be drawn into. 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 outside the edges of the surface. If rect is NULL the clipping rectangle will be set to the full size of the surface. -SDL::set_clip_rect doesn't returns anything.

+SDL::Video::set_clip_rect doesn't returns anything.

get_clip_rect(surface,rect)

-

Gets the clipping rectangle for the given SDL::surface. When this surface is the destination of a blit, only the area within the clip +

 SDL::Video::get_clip_rect( $surface, $rect );
+
+
+

Gets the clipping rectangle for the given SDL::Surface. When this surface is the destination of a blit, only the area within the clip rectangle is drawn into. The rectangle pointed to by rect will be filled with the clipping rectangle of the surface. -SDL::get_clip_rect doesn't returns anything;

+SDL::Video::get_clip_rect doesn't returns anything;

+
 use SDL;
+ use SDL::Video;
+ use SDL::Rect;
+ use SDL::Surface;
+
+ my $screen_width  = 640;
+ my $screen_height = 480;
 
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen  = SDL::Video::set_video_mode($screen_width, $screen_height, 32, SDL_SWSURFACE);
 
+ my $rect = SDL::Rect->new(0, 0, 0, 0);
 
+ SDL::Video::get_clip_rect($screen, $rect);
 
+ printf( "rect is %d, %d, %d, %d\n", $rect->x, $rect->y, $rect->w, $rect->h);
+
+ SDL::quit;
+
+

blit_surface(src,src_rect,dest,dest_rect)

-

This performs a fast blit from the given source SDL::surface to the given destination SDL::surface. -The width and height in srcrect determine the size of the copied rectangle. Only the position is used in the dstrect (the width and height -are ignored). Blits with negative dstrect coordinates will be clipped properly. -If srcrect is NULL, the entire surface is copied. If dstrect is NULL, then the destination position (upper left corner) is (0, 0). -The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified). +

 SDL::Video::blit_surface( $src_surface, $src_rect, $dest_surface, $dest_rect );
+
+
+

This performs a fast blit from the given source SDL::Surface to the given destination SDL::Surface. +The width and height in src_surface determine the size of the copied rectangle. Only the position is used in the dst_rect +(the width and height are ignored). Blits with negative dst_rect coordinates will be clipped properly. +If src_rect is NULL, the entire surface is copied. If dst_rect is NULL, then the destination position (upper left corner) is (0, 0). +The final blit rectangle is saved in dst_rect after all clipping is performed (src_rect is not modified). 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, -but this is not the case with SDL::blit_surface. Like most surface manipulation functions in SDL, it should not be used together with OpenGL.

-

The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL::set_alpha for an explanation of -how this affects your results. Colorkeying and alpha attributes also interact with surface blitting. -SDL::blit_surface doesn't returns anything.

+but this is not the case with SDL::Video::blit_surface. Like most surface manipulation functions in SDL, it should not be used together +with OpenGL.

+

The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL::Video::set_alpha for an +explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting. +SDL::Video::blit_surface doesn't returns anything.

+

For an example see load_BMP.

update_rect(surface,x,y,width,height)

@@ -900,7 +928,7 @@ with SDL::set_gamma_ramp.

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

+SDL::Video::get_gamma_ramp returns -1 on error.

 use SDL;
  use SDL::Video;
 
@@ -1054,9 +1082,8 @@ component (e.g., a completely white pixel in 16-bit RGB565 format would return [
 
 
GL_load_library(path)

 

-
If you wish, you may load the OpenGL library from the given path at runtime, this must be done before SDL::set_video_mode is called.
-The path of the GL library is passed to SDL::GL_load_library and it returns 0 on success, or -1 on an error. You must then use 
-SDL::GL_get_proc_address to retrieve function pointers to GL functions. 

+
If you wish, you may load the OpenGL library from the given path at runtime, this must be done before SDL::Video::set_video_mode is called.
+You must then use SDL::Video::GL_get_proc_address to retrieve function pointers to GL functions. 

 
SDL::GL_load_library returns 0 on success or -1 or error.

 
 

@@ -1134,26 +1161,136 @@ The overlay is scaled (independently in x and y dimensions) to the size specifie
 
 
wm_set_caption(title,icon)

 

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

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

+
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.

+
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);
+
+ SDL::quit;
+
+

 
 

 
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 );
+
+ SDL::quit;
+
+

 
 

 
wm_set_icon(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 SDL::Video::set_video_mode. Note that this means 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
+
+ SDL::Video::set_color_key($image, SDL_SRCCOLORKEY, $colorkey);              
+
+ SDL::Video::wm_set_icon($image);
+
+

 
 

 
wm_grab_input(mode)

 

+
 $grab_mode = SDL::Video::wm_grab_input($mode);
+
+

+
Grabbing means that the mouse is confined to the application window, and nearly all keyboard input is passed directly to the application, 
+and not interpreted by a window manager, if any.

+
When mode is SDL_GRAB_QUERY the grab mode is not changed, but the current grab mode is returned.

+
mode and the return value of wm_grab_input can be one of the following:

+
    
+		
  • SDL_GRAB_QUERY	
    • 
+		
  • SDL_GRAB_OFF	
    • 
+		
  • SDL_GRAB_ON
    • 
+

+
 
 

 
wm_iconify_window()

 

+
 $iconify_window = SDL::Video::wm_iconify_window();
+
+

+
If the application is running in a window managed environment SDL attempts to iconify/minimise it. If wm_iconify_window is successful, 
+the application will receive a SDL_APPACTIVE loss event (see Application visibility events at SDL::Event).

+
Returns non-zero on success or 0 if iconification is not supported or was refused by the window manager. 

+
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);
+
+ sleep(2);
+
+ SDL::Video::wm_iconify_window();
+
+ sleep(2); 
+
+ SDL::quit;
+
+

 
 

 
wm_toggle_fullscreen(surface)

 

+
 $toggle = SDL::Video::wm_toggle_fullscreen( $surface );
+
+

+
Toggles the application between windowed and fullscreen mode, if supported. (X11 is the only target currently supported, BeOS support 
+is experimental).

 
 

 
SEE ALSO
Top

diff --git a/pages/documentation.html-inc b/pages/documentation.html-inc
index 7a1eebc..6f33d40 100644
--- a/pages/documentation.html-inc
+++ b/pages/documentation.html-inc
@@ -1,2 +1,2 @@
 

-
Documentation (latest development branch)
Core
thumbSDL- Simple DirectMedia Layer for Perl
Structure
thumbSDL::AudioCVT- Audio Conversion Structure
thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
CDROM
thumbSDL::CDROM- SDL Bindings for the CDROM device
Structure
thumbSDL::CD- SDL Bindings for structure SDL_CD
thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
Events
thumbSDL::Events- Bindings to the Events Category in SDL API
Structure
thumbSDL::Event- General event structure
Joystick
thumbSDL::Joystick- SDL Bindings for the Joystick device
Structure
thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
Mouse
thumbSDL::Mouse- SDL Bindings for the Mouse device
Structure
thumbSDL::Cursor- Mouse cursor structure
MultiThread
thumbSDL::MultiThread- Bindings to the MultiThread category in SDL API
Structure
thumbSDL::Version- SDL Bindings for structure SDL_Version
Video
thumbSDL::Video- Bindings to the video category in SDL API
Structure
thumbSDL::Color- Format independent color description
thumbSDL::Overlay- YUV Video overlay
thumbSDL::Palette- Color palette for 8-bit pixel formats 
thumbSDL::PixelFormat- Stores surface format information
thumbSDL::Rect- Defines a rectangular area
thumbSDL::Surface- Graphic surface structure.
thumbSDL::VideoInfo- Video Target Information 

Cookbook
thumbSDL::Cookbook
thumbSDL::Cookbook::PDL

Extension
thumbSDL::App- a SDL perl extension

Mixer
thumbSDL::Mixer- a SDL perl extension
TODO
Core
Audio
thumbSDL::Audio- SDL Bindings for Audio
Structure
thumbSDL::RWOps- SDL Bindings to SDL_RWOPs

Tutorials
thumbSDL::Tutorial- introduction to Perl SDL
thumbSDL::Tutorial::Animation
thumbSDL::Tutorial::Images
thumbSDL::Tutorial::LunarLander- a small tutorial on Perl SDL
thumbSDL::Tutorial::Pong
thumbSDL::Tutorial::Tetris

UNCATEGORIZED
thumbSDL::Font- a SDL perl extension
thumbSDL::Game::Palette- a perl extension
thumbSDL::MPEG- a SDL perl extension
thumbSDL::Music- a perl extension
thumbSDL::OpenGL- a perl extension
thumbSDL::SFont- a perl extension
thumbSDL::SMPEG- a SDL perl extension
thumbSDL::Sound- a perl extension
thumbSDL::TTFont- a SDL perl extension
thumbSDL::Timer- a SDL perl extension for managing timers.
thumbSDL::Tool::Font- a perl extension
thumbSDL::Tool::Graphic
thumbSDL::old-cdrom- a SDL perl extension for managing CD-ROM drives

+
Documentation (latest development branch)
Core
thumbSDL- Simple DirectMedia Layer for Perl
Structure
thumbSDL::AudioCVT- Audio Conversion Structure
thumbSDL::AudioSpec- SDL Bindings for structure SDL::AudioSpec
CDROM
thumbSDL::CDROM- SDL Bindings for the CDROM device
Structure
thumbSDL::CD- SDL Bindings for structure SDL_CD
thumbSDL::CDTrack- SDL Bindings for structure SDL_CDTrack
Events
thumbSDL::Events- Bindings to the Events Category in SDL API
Structure
thumbSDL::Event- General event structure
Joystick
thumbSDL::Joystick- SDL Bindings for the Joystick device
Structure
thumbSDL::Mixer::MixChunk- SDL Bindings for structure SDL_MixChunk
thumbSDL::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
Mouse
thumbSDL::Mouse- SDL Bindings for the Mouse device
Structure
thumbSDL::Cursor- Mouse cursor structure
MultiThread
thumbSDL::MultiThread- Bindings to the MultiThread category in SDL API
Structure
thumbSDL::Version- SDL Bindings for structure SDL_Version
Video
thumbSDL::Video- Bindings to the video category in SDL API
Structure
thumbSDL::Color- Format independent color description
thumbSDL::Overlay- YUV Video overlay
thumbSDL::Palette- Color palette for 8-bit pixel formats 
thumbSDL::PixelFormat- Stores surface format information
thumbSDL::Rect- Defines a rectangular area
thumbSDL::Surface- Graphic surface structure.
thumbSDL::VideoInfo- Video Target Information 

Cookbook
thumbSDL::Cookbook
thumbSDL::Cookbook::PDL

Extension
thumbSDL::App- a SDL perl extension

Mixer
thumbSDL::Mixer- a SDL perl extension
TODO
Core
Audio
thumbSDL::Audio- SDL Bindings for Audio
Structure
thumbSDL::RWOps- SDL Bindings to SDL_RWOPs

Tutorials
thumbSDL::Tutorial- introduction to Perl SDL
thumbSDL::Tutorial::Animation
thumbSDL::Tutorial::Images
thumbSDL::Tutorial::LunarLander- a small tutorial on Perl SDL
thumbSDL::Tutorial::Pong
thumbSDL::Tutorial::Tetris

UNCATEGORIZED
thumbSDL::Font- a SDL perl extension
thumbSDL::Game::Palette- a perl extension
thumbSDL::MPEG- a SDL perl extension
thumbSDL::Music- a perl extension
thumbSDL::OpenGL- a perl extension
thumbSDL::SFont- a perl extension
thumbSDL::SMPEG- a SDL perl extension
thumbSDL::Sound- a perl extension
thumbSDL::TTFont- a SDL perl extension
thumbSDL::Timer- a SDL perl extension for managing timers.
thumbSDL::Tool::Font- a perl extension
thumbSDL::Tool::Graphic
thumbSDL::old-cdrom- a SDL perl extension for managing CD-ROM drives