Creates a new SDL::surface of the specified SDL::pixel_format, 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.
+ +Converts a surface to the display format
+ +Converts a surface to the display format
+ +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).
+ + + + + +Saves the given SDL::Surface surface as a Windows BMP file named filename. +it returns 0 on success or -1 on error.
+ +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.
+ + + + + +SDL::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. +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.
+Alpha affects surface blitting in the following ways:
+The source is alpha-blended with the destination, using the alpha channel. +SDL_SRCCOLORKEY and the per-surface alpha are ignored.
+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.
+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.
+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.
+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.
+The RGBA data is copied to the destination surface. +If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
+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 RGB data is copied from the source. +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 +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.
+ +This function performs a fast fill of the given SDL::rectangle with the given SDL::pixel_format. If dstrect 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 +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.
+ +int SDL::Video::lock_surface( $surface ); + ++
SDL::Video::lock_surface sets up the given SDL::Surface for directly accessing the pixels.
+Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to ( surface-set_pixels>) and read from ( surface-get_pixels> ),
+using the pixel format stored in surface-format>.
+Once you are done accessing the surface, you should use SDL::Video::unlock_surface to release the lock.
Not all surfaces require locking. If SDL::Video::MUSTLOCK(surface) evaluates to 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.
+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 SDL::Video;
+ use SDL::Surface;
+
+ SDL::init(SDL_INIT_VIDEO);
+
+ my $screen_surface = SDL::Video::set_video_mode(640, 480, 16, SDL_HWSURFACE);
+
+ if(SDL::Video::MUSTLOCK($screen_surface))
+ {
+ print( "the surface must be locked\n" );
+
+ if(0 == SDL::Video::lock_surface($screen_surface))
+ {
+ print( "lock succesful\n" );
+ }
+ else
+ {
+ print( "error while locking surface" );
+ }
+
+ # pixel manipulation goes here
+
+ SDL::Video::unlock_surface($screen_surface); # unlock_surface returns nothing
+ }
+ else
+ {
+ print( "the surface need not to be locked" );
+ }
+
+ SDL::quit();
+
+
+
+void SDL::Video::unlock_surface( $surface ); + ++
Surfaces that were previously locked using SDL::Video::lock_surface must be unlocked with SDL::Video::unlock_surface. Surfaces should
+be unlocked as soon as possible.
+SDL::Video::unlock_surface doesn't return anything.
Note: Since 1.1.8, the surface locks are recursive. See SDL::Video::lock_surface for more information.
int SDL::Video::MUSTLOCK( $surface ); + ++
MUSTLOCK returns 0 if the surface does not have to be locked during pixel operations, otherwise 1.
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.
+ +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;
+ + + + + +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). +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.
+ +update_rect( $surface, $left, $top, $width, $height ); @@ -428,6 +689,10 @@ perform hardware flipping.
$set_colors = SDL::Video::set_colors( $surface, $start, $color1, $color2, ... ) @@ -636,14 +901,12 @@ If the SDL::PixelFormat's bpp (color depth) my $_16bit = SDL::Video::map_RGB( $screen_surface->format, $r, $g, $b ); # 16bpp is 5 bits red, 6 bits green and 5 bits blue - # we will obtain the values for each color and calculating them back to 24bit color system - $r = (($_16bit & 0b1111100000000000) >> 11) / 0b11111 * 0b11111111; - $g = (($_16bit & 0b0000011111100000) >> 5) / 0b111111 * 0b11111111; - $b = ($_16bit & 0b0000000000011111) / 0b11111 * 0b11111111; + # we will obtain the values for each color and calculating them back to 24/32bit color system + ($r, $g, $b) = @{ SDL::Video::get_RGB( $screen_surface->format, $_16bit ) }; printf( "for 16bpp it is: 0x%02X 0x%02X 0x%02X\n", $r, $g, $b ); - # so color #9CDC67 becomes #9CDE62 + # so color #9CDC67 becomes #9CDF63 SDL::quit(); @@ -652,7 +915,10 @@ If the SDL::PixelFormat's bpp (color depth)
Maps the RGBA color value to the specified SDL::pixel_format and returns the pixel value as a 32-bit int. +
$pixel = SDL::Video::map_RGB( $pixel_format, $r, $g, $b, $a ); + ++
Maps the RGBA color value to the specified SDL::PixelFormat and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of the closest matching color in the palette will be returned. If the specified pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette).
A pixel value best approximating the given RGBA color value for a given pixel format. @@ -662,206 +928,26 @@ with a 16-bpp format the return value can be assigned to a Uint16, and similarly
Returns RGB values from a pixel in the specified pixel format. +
$rgb_array_ref = SDL::Video::get_RGB( $pixel_format, $pixel ); + ++
Returns RGB values from a pixel in the specified pixel format. The pixel is an integer (e.g. 16bit RGB565, 24/32bit RGB888). This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
+For an example see SDL::Video::map_RGB.
$rgba_array_ref = SDL::Video::get_RGBA( $pixel_format, $pixel ); + +
Gets RGBA values from a pixel in the specified pixel format. This function uses the entire 8-bit [0..255] range when converting color components from pixel formats with less than 8-bits per RGB component (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff, 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
If the surface has no alpha component, the alpha will be returned as 0xff (100% opaque).
SDL::lock_surface sets up the given SDL::surface for directly accessing the pixels. -Between calls to SDL::lock_surface and SDL::unlock_surface, you can write to and read from surface->pixels, using the pixel format stored -in surface->format. -Once you are done accessing the surface, you should use SDL::unlock_surface to release the lock.
-Not all surfaces require locking. If SDL::MUSTLOCK(surface) evaluates to 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. -SDL::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.
- -Surfaces that were previously locked using SDL::lock_surface must be unlocked with SDL::unlock_surface. Surfaces should be unlocked as -soon as possible. -SDL::unlock_surface doesn't return anything.
-Note : Since 1.1.8, the surface locks are recursive. See SDL::lock_surface for more information.
Creates a new SDL::surface of the specified SDL::pixel_format, 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.
- -Converts a surface to the display format
- -Converts a surface to the display format
- -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).
- - - - - -Saves the given SDL::Surface surface as a Windows BMP file named filename. -it returns 0 on success or -1 on error.
- -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.
- - - - - -SDL::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. -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.
-Alpha affects surface blitting in the following ways:
-The source is alpha-blended with the destination, using the alpha channel. -SDL_SRCCOLORKEY and the per-surface alpha are ignored.
-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.
-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.
-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.
-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.
-The RGBA data is copied to the destination surface. -If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied.
-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 RGB data is copied from the source. -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 -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.
- -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.
- -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;
- - - - - -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). -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.
- -This function performs a fast fill of the given SDL::rectangle with the given SDL::pixel_format. If dstrect 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 -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.
- -It returns 0 on success or -1 on error.
+