From: Tobias Leich Date: Thu, 26 Nov 2009 23:43:03 +0000 (+0100) Subject: updated docs for video X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=096d8dc83e9fce28b4ee221fcbe30eb9ead13da5;p=sdlgit%2FSDL-Site.git updated docs for video --- diff --git a/pages/SDL-Video.html-inc b/pages/SDL-Video.html-inc index a805401..aef1190 100644 --- a/pages/SDL-Video.html-inc +++ b/pages/SDL-Video.html-inc @@ -170,11 +170,11 @@ word identifier like "x11", "windib"

list_modes(formats,flags)

-
 my @modes = @{ SDL::Video::list_modes($video_info->vfmt, SDL_NOFRAME) };
+
 my @modes = @{ SDL::Video::list_modes( $pixel_format, $flags ) };
 
 

-
Returns a pointer to an array of available screen dimensions for the given format and video flags,
-or it return undef if no modes are avalaibles.

+
Returns a ref to an array of available screen dimensions for the given format and video flags,
+or it return undef if no modes are available.

 
Example:

 
 use SDL;
  use SDL::Video;
@@ -208,8 +208,31 @@ or it return undef if no modes are avalaibles.

video_mode_ok(width,height,bpp,flags)

-

Checks to see if a particular video mode of the given width,height,bpp and flags is supported. -It returns 0 if the mode is not supported at all, or the suggested bpp.

+
 my $bpp_ok = SDL::Video::video_mode_ok( $width, $height, $bpp, $flags );
+
+
+

This function is used to check whether the requested mode is supported by the current video device. The arguments passed to this function +are the same as those you would pass to SDL::Video::set_video_mode. +It returns 0 if the mode is not supported at all, otherwise the suggested bpp.

+

Example:

+
 use SDL;
+ use SDL::Video;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $video_mode_ok = SDL::Video::video_mode_ok( 800, 600, 32, SDL_SWSURFACE );
+
+ unless($video_mode_ok)
+ {
+     printf("this video mode ist not supported\n" );
+ }
+
+ SDL::quit();
+
+
+
+
+

set_video_mode(width,height,bpp,flags)

@@ -217,8 +240,9 @@ It returns 0 if the mode is not supported at all, or the suggested bpp.

 my $surface = SDL::Video::set_video_mode( 800, 600, 32, SDL_SWSURFACE|SDL_DOUBLEBUF|SDL_FULLSCREEN);
-

Sets up a video mode with the specified width, height, bits-per-pixel and flags. -set_video_mode returns a SDL::Surface on success or it returns undef on error, the error message is retrieved using SDL::get_error.

+

Sets up a video mode with the specified width, height, bits-per-pixel and flags. +set_video_mode returns a SDL::Surface on success otherwise it returns undef on error, the error message is retrieved +using SDL::get_error.

List of avalaibles flags

@@ -282,47 +306,78 @@ When the window is resized by the user a SDL_VIDEORESIZE event is g Fullscreen modes automatically have this flag set.

-

Note 1: Use SDL_SWSURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. -When you use hardware surfaces (by passing the flag SDL_HWSURFACE as parameter), SDL copies the surfaces from video memory to system memory +

Note 1: Use SDL_SWSURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. +When you use hardware surfaces (by passing the flag SDL_HWSURFACE as parameter), SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them. This can cause a major performance hit. Be aware that you may request a hardware surface, but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface -when using SDL_FULLSCREEN. The SDL_HWSURFACE flag is best used when the surfaces you'll be blitting can also be stored in video memory.

-

Note 2: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment -variables SDL_VIDEO_CENTERED=center or SDL_VIDEO_WINDOW_POS=x,y. You can also set them via SDL::putenv.

-

Note 3: This function should be called in the main thread of your application.

-

User note 1: Some have found that enabling OpenGL attributes like SDL_GL_STENCIL_SIZE (the stencil buffer size) before the video mode has +when using SDL_FULLSCREEN. The SDL_HWSURFACE flag is best used when the surfaces you'll be blitting can also be stored in video memory.

+

Note 2: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment +variables SDL_VIDEO_CENTERED=center or SDL_VIDEO_WINDOW_POS=x,y. You can also set them via SDL::putenv.

+

Note 3: This function should be called in the main thread of your application.

+

User note 1: Some have found that enabling OpenGL attributes like SDL_GL_STENCIL_SIZE (the stencil buffer size) before the video mode has been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.

-

User note 2: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL +

User note 2: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL::set_video_mode. In Linux, -however, it works fine, and the initialization code only needs to be executed after the first call to SDL::set_video_mode (although there -is no harm in executing the initialization code after each call to SDL::set_video_mode, for example for a multiplatform application).

- - - - - - - - - - +however, it works fine, and the initialization code only needs to be executed after the first call to +SDL::Video::set_video_mode (although there is no harm in executing the initialization code after +each call to SDL::Video::set_video_mode, for example for a multiplatform application).

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

+
 update_rect( $surface, $left, $top, $width, $height );
+
+

Makes sure the given area is updated on the given screen. The rectangle must be confined within the screen boundaries because there's no clipping. update_rect doesn't returns any value.

-

Note : This function should not be called while screen is locked by SDL::lock_surface -Note2 : If x, y, width and height are all equal to 0, SDL_UpdateRect will update the entire screen.

+

Note: This function should not be called while screen is locked by SDL::Video::lock_surface

+

Note2: If x, y, width and height are all equal to 0, update_rect will update the entire screen.

+

For an example see SYNOPSIS

update_rects(surface,rects)

+
 update_rects( $surface, @rects );
+
+

Makes sure the given list of rectangles is updated on the given screen. The rectangle must be confined within the screen boundaries because there's no clipping. -update_rects doesn't returns any value.

-

Note : This function should not be called while screen is locked by SDL::lock_surface

+update_rects doesn't returns any value.

+

Note: This function should not be called while screen is locked by SDL::Video::lock_surface.

+

Example:

+
 use 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_SWSURFACE);
+
+ # drawing the whole screen blue
+ my $mapped_color   = SDL::Video::map_RGB($screen_surface->format(), 0, 0, 255); # blue
+ SDL::Video::fill_rect($screen_surface, 
+                       SDL::Rect->new(0, 0, $screen_width, $screen_height),
+                       $mapped_color);
+
+ my @rects = ();
+ push(@rects, SDL::Rect->new(200,   0, 400, 600));
+ push(@rects, SDL::Rect->new(  0, 150, 800, 300));
+
+ # updating parts of the screen (should look like a cross)
+ SDL::Video::update_rects($screen_surface, @rects);
+
+ sleep(2);
+
+ SDL::quit();
+
+

flip(surface)

diff --git a/pages/SDL.html-inc b/pages/SDL.html-inc index 533dad4..b74b8be 100644 --- a/pages/SDL.html-inc +++ b/pages/SDL.html-inc @@ -25,9 +25,9 @@
  • quit
  • was_init(flags)
  • get_error()
    • -
  • set_error(error) *need to be coded
    • +
  • set_error_real(error, @values)
  • error(code) * need to be coded
    • -
  • clear_error() * need to be coded
    • +
  • clear_error()
  • load_object()
  • load_function()
  • unload_object()
    • @@ -38,7 +38,7 @@
  • delay(ms)
    • -
  • STUFF TO BE DONE for the documentation +
  • AUTHORS
    • @@ -197,8 +197,8 @@ If 'flags' is 0 or SDL_INIT_EVERYTHING, it returns a mask of all initialized sub SDL::get_error, which returns a scalar containing the text of the message if any.

    -

    set_error(error) *need to be coded

    -
    +

    set_error_real(error, @values)

    +

    SDL::get_error sets the SDL error to a printf style formatted string. it doesn't returns any values.

    @@ -255,8 +255,8 @@ which are equivalent to SDL_Error(SDL_ENOMEM) and SDL_Error(SDL_UNSUPPORTED) res
    -

    clear_error() * need to be coded

    -
    +

    clear_error()

    +

    SDL::clear_error deletes all information about the last internal SDL error. Useful if the error has been handled by the program. it doesn't returns any value.

    @@ -308,24 +308,13 @@ than the specified depending on the underlying OS.

    -

    STUFF TO BE DONE for the documentation

    Top

    -
    -
    -
-
-	SDL:: to improve
-	SDL::Video add examples, need general improvement.
-	Event.pod need to be checked against Events.pod
-	SDL::Events need to be completed
-	SDL::Cdrom need some examples. 
-	SDL::MultiThread to be created( once implemented  ). 
-	SDL::Timer need examples. 
-	SDL::RW to be created.
-	SDL::Mouse need to be created.
-	SDL::Joystick need to be created.
-	SDL::Audio need to be created.
+
    AUTHORS
    Top
    
+
    
+
    magnet, kthakore
    
+
+
+
 
-
    \ No newline at end of file diff --git a/pages/documentation.html-inc b/pages/documentation.html-inc index 0e3d917..03baec6 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
    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::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
    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
    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::Mixer::MixMusic- SDL Bindings for structure SDL_MixMusic
    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