From: Tobias Leich Date: Sun, 29 Nov 2009 16:10:02 +0000 (+0100) Subject: docs for video X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=878ae663f3db935e9f59640f357156c4bdf21c75;p=sdlgit%2FSDL-Site.git docs for video --- diff --git a/htdocs/assets/Video_lock_surface.png b/htdocs/assets/Video_lock_surface.png new file mode 100644 index 0000000..3ed9317 Binary files /dev/null and b/htdocs/assets/Video_lock_surface.png differ diff --git a/pages/SDL-Mixer-MixMusic.html-inc b/pages/SDL-Mixer-MixMusic.html-inc index 636bad0..b511949 100644 --- a/pages/SDL-Mixer-MixMusic.html-inc +++ b/pages/SDL-Mixer-MixMusic.html-inc @@ -3,7 +3,8 @@

Index

@@ -15,7 +16,12 @@

CATEGORY

Top

-

TODO, Core, Mixer, Structure

+

Core, Mixer, Structure

+ +
+

SYNOPSIS

Top

+
+

This structure is not directly usable. SDL Perl bindings handle the construction and destruction for you.

\ No newline at end of file diff --git a/pages/SDL-Overlay.html-inc b/pages/SDL-Overlay.html-inc index b1cc65b..b341277 100644 --- a/pages/SDL-Overlay.html-inc +++ b/pages/SDL-Overlay.html-inc @@ -90,7 +90,7 @@ SDL_YUY2_OVERLAY 0x32595559 /* Packed mode: Y0+U0+Y1+V0 */ SDL_UYVY_OVERLAY 0x59565955 /* Packed mode: U0+Y0+V0+Y1 */
* SDL_YVYU_OVERLAY 0x55595659 /* Packed mode: Y0+V0+Y1+U0 */
-
+ @@ -99,36 +99,38 @@ SDL_YVYU_OVERLAY 0x55595659 /* Packed mode: Y0+V0+Y1+U0 */

format

-

Overlay format (see YUV_Flags)

+

Overlay format (see YUV_Flags)

w, h

-

Width and height of overlay

+

Width and height of overlay

planes

-

Number of planes in the overlay. Usually either 1 or 3

+

Number of planes in the overlay. Usually either 1 or 3

pitches

-

An array of pitches, one for each plane. Pitch is the length of a row in bytes.

+

An array of pitches, one for each plane. Pitch is the length of a row in bytes.

pixels

-

As of release 2.3 direct right to overlay is disable.

-

An array of pointers to the data of each plane. The overlay should be locked before these pointers are used.

-

see SDL::Video::lock_YUV_overlay, SDL::Video::unload_YUV_overlay

+

As of release 2.3 direct right to overlay is disable.

+

An array of pointers to the data of each plane. The overlay should be locked before these pointers are used.

+

see SDL::Video::lock_YUV_overlay, SDL::Video::unload_YUV_overlay

hw_overlay

-

This will be set to 1 if the overlay is hardware accelerated.

-
- +

This will be set to 1 if the overlay is hardware accelerated.

+ + + + \ No newline at end of file diff --git a/pages/SDL-Video.html-inc b/pages/SDL-Video.html-inc index 6d6a9b4..ced5163 100644 --- a/pages/SDL-Video.html-inc +++ b/pages/SDL-Video.html-inc @@ -82,7 +82,7 @@
-Video.png
+Video.pngVideo_lock_surface.png

NAME

Top

@@ -253,9 +253,6 @@ It returns 0 if the mode is not supported at all, otherwise the sug SDL::quit(); - - -
@@ -349,69 +346,123 @@ each call to SDL::Video::set_vid

convert_surface(surface,format,flags)

-

Creates a new SDL::surface of the specified SDL::pixel_format, and then copies and maps the given surface to it. +

 $converted_surface = SDL::Video::convert_surface( $surface, $format, $flags );
+
+
+

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::create_RGB_surface and has those semantics. -This function is used internally by SDL::display_format. -This function can only be called after SDL::init.

-

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

+

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.

display_format

-

Converts a surface to the display format

+
 $new_surface = SDL::Video::display_format( $surface );
+
+
+

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer, suitable for fast +blitting onto the display surface. It calls SDL::Video::convert_surface.

+

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling +this function.

+

If you want an alpha channel, see SDL::Video::display_format_alpha. +Return Value

+

Note: Remember to use a different variable for the returned surface, otherwise you have a memory leak, since the original surface isn't freed.

display_format_alpha

-

Converts a surface to the display format

+
 $new_surface = SDL::Video::display_format_alpha( $surface );
+
+
+

This function takes a surface and copies it to a new surface of the pixel format and colors of the video framebuffer plus an alpha channel, +suitable for fast blitting onto the display surface. It calls SDL::Video::convert_surface.

+

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling +this function.

+

This function can be used to convert a colorkey to an alpha channel, if the SDL_SRCCOLORKEY flag is set on the surface. The generated +surface will then be transparent (alpha=0) where the pixels match the colorkey, and opaque (alpha=255) elsewhere.

+

Note: The video surface must be initialised using SDL::Video::set_video_mode before this function is called, or it will segfault.

load_BMP(filename)

-

Loads a SDL::surface from a named Windows BMP file. -SDL::load_BMP returns a SDL::surface on success or undef on error.

-

Note: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect).

+
 $surface = SDL::Video::load_BMP( $filename );
 
+
+

Loads a SDL::Surface from a named Windows BMP file. +SDL::Video::load_BMP returns a SDL::Surface on success or undef on error.

+

Note: When loading a 24-bit Windows BMP file, pixel data points are loaded as blue, green, red, and NOT red, green, blue (as one might expect).

+
 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 $picture = SDL::Video::load_BMP('test.bmp');
+
+ die(SDL::get_error) unless $picture;
+
+ my $rect    = SDL::Rect->new(0, 0, $screen_width, $screen_height);
+
+ SDL::Video::blit_surface( $picture, SDL::Rect->new(0, 0, $picture->w, $picture->h), 
+                           $screen,  SDL::Rect->new(0, 0, $screen->w,  $screen->h) );
+
+ SDL::Video::update_rect( $screen, 0, 0, $screen_width, $screen_height );
+
+ sleep(2);
+
+ SDL::quit;
+
+

save_BMP(surface,filename)

-

Saves the given SDL::Surface surface as a Windows BMP file named filename. +

 $saved_BMP = SDL::Video::save_BMP( $surface, $filename );
+
+
+

Saves the given SDL::Surface as a Windows BMP file named filename. it returns 0 on success or -1 on error.

set_color_key(surface,flag,key)

+
 $set_color_key = SDL::Video::set_color_key( $surface, $flag, $key );
+
+

Sets the color key (transparent pixel) in a blittable surface and enables or disables RLE blit acceleration.

RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value). -The key must be of the same pixel format as the surface, SDL::map_RGB is often useful for obtaining an acceptable value. -If flag is SDL_SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.

-

If flag is OR'd with SDL_RLEACCEL then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface. -The surface will actually be encoded for RLE acceleration the first time SDL::blit_surface or SDL::display_format is called on the surface. -If flag is 0, this function clears any current color key.

-

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

- - - - +The key must be of the same pixel format as the surface, SDL::Video::map_RGB is often useful for obtaining an acceptable value. +If flag is SDL_SRCCOLORKEY then key is the transparent pixel value in the source image of a blit.

+

If flag is OR'd with SDL_RLEACCEL then the surface will be drawn using RLE acceleration when drawn with SDL::Blit_surface. +The surface will actually be encoded for RLE acceleration the first time SDL::Video::blit_surface or SDL::Video::display_format +is called on the surface. +If flag is 0, this function clears any current color key.

+

SDL::Video::set_color_key returns 0 on success or -1 on error.

set_alpha(surface,flag,key)

-

SDL::set_alpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.

+
 $set_alpha = SDL::Video::set_alpha( $surface, $flag, $key );
+
+
+

set_alpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.

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 (SDL_SRCALPHA) and whether the surface should use RLE acceleration for -blitting (SDL_RLEACCEL). -flags can be an OR'd combination of these two options, one of these options or 0. -If SDL_SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface. +flags is used to specify whether alpha blending should be used ( SDL_SRCALPHA ) and whether the surface should use RLE acceleration for +blitting ( SDL_RLEACCEL ). +flags can be an OR'd combination of these two options, one of these options or 0. +If 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 SDL_RLEACCEL.

-

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.

+still be accelerated with SDL_RLEACCEL.

+

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:

RGBA->RGB with SDL_SRCALPHA
@@ -456,24 +507,29 @@ If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are c If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.

-

Note: When blitting, the presence or absence of SDL_SRCALPHA is relevant only on the source surface, not the destination. -Note: Note that RGBA->RGBA blits (with SDL_SRCALPHA set) keep the alpha of the destination surface. This means that you cannot compose +

Note: When blitting, the presence or absence of SDL_SRCALPHA is relevant only on the source surface, not the destination. +Note: Note that RGBA->RGBA blits (with 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.

-

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

-

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

+

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

+

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

fill_rect(dest,dest_rect,pixel)

-

This function performs a fast fill of the given SDL::rectangle with the given SDL::pixel_format. If dstrect is NULL, the whole surface +

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

This function performs a fast fill of the given SDL::Rect with the given 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 SDL::MapRGB or SDL::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 SDL::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 SDL::get_video_surface()) you may have to update the video surface to see the +

The color should be a pixel of the format used by the surface, and can be generated by the SDL::Video::map_RGB or SDL::Video::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 SDL::Video::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 SDL::Video::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.

-

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

+

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

+

for an example see SYNOPSIS.

Surface locking and unlocking

Top

@@ -495,37 +551,81 @@ No operating system or library calls should be made between the lock/unlock pair SDL::Video::lock_surface returns 0 on success or -1 on error.

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 SDL;
+
 use strict;
+ use warnings;
+ use Carp;
+
+ use SDL v2.3;
  use SDL::Video;
+ use SDL::Event;
+ use SDL::Events;
  use SDL::Surface;
 
- SDL::init(SDL_INIT_VIDEO);
+ my $screen;
 
- my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_HWSURFACE);
+ sub putpixel
+ {
+     my($x, $y, $color) = @_;
+     my $lineoffset     = $y * ($screen->pitch / 4);
+     $screen->set_pixels( $lineoffset+ $x, $color);
+ }
 
- if(SDL::Video::MUSTLOCK($screen_surface))
+ sub render
  {
-     print( "the surface must be locked\n" );
+     if( SDL::Video::MUSTLOCK( $screen) )
+     {
+         return if (SDL::Video::lock_surface( $screen ) < 0)
+     }
 
-     if(0 == SDL::Video::lock_surface($screen_surface))
+     my $ticks                = SDL::get_ticks();
+     my ($i, $y, $yofs, $ofs) = (0,0,0,0);
+     for ($i = 0; $i < 480; $i++)
      {
-         print( "lock succesful\n" );
+         for (my $j = 0, $ofs = $yofs; $j < 640; $j++, $ofs++)
+         {
+             $screen->set_pixels( $ofs, (  $i * $i + $j * $j + $ticks ) );
+         }
+         $yofs += $screen->pitch / 4;
      }
-	 else
-	 {
-	     print( "error while locking surface" );
-	 }
 
-	 # pixel manipulation goes here
+     putpixel(10, 10, 0xff0000);
+     putpixel(11, 10, 0xff0000);
+     putpixel(10, 11, 0xff0000);
+     putpixel(11, 11, 0xff0000);
+
+     SDL::Video::unlock_surface($screen) if (SDL::Video::MUSTLOCK($screen));
 
-     SDL::Video::unlock_surface($screen_surface); # unlock_surface returns nothing
+     SDL::Video::update_rect($screen, 0, 0, 640, 480);    
+
+     return 0;
  }
- else
+
+ sub main
  {
-     print( "the surface need not to be locked" );
+     carp 'Unable to init SDL: '.SDL::get_error() if( SDL::init(SDL_INIT_VIDEO) < 0);
+
+     $screen = SDL::Video::set_video_mode( 640, 480, 32, SDL_SWSURFACE);
+
+     carp 'Unable to set 640x480x32 video' . SDL::get_error() if(!$screen);
+
+     while(1)
+     {
+         render();
+
+         my $event = SDL::Event->new();
+
+         while( SDL::Events::poll_event($event) )
+         {
+             my $type = $event->type;
+             return 0 if( $type == SDL_KEYDOWN || $type == SDL_QUIT);
+         }
+         SDL::Events::pump_events();
+     }
  }
 
- SDL::quit();
+ main();
+
+ SDL::quit;
 
 

 
diff --git a/pages/documentation.html-inc b/pages/documentation.html-inc
index 45f7a63..7a1eebc 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
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