=pod

=head1 NAME

SDLx::Surface - Graphic surface matrix extension

=head1 CATEGORY

Extension

=head1 SYNOPSIS

 use SDL;
 use SDL::Video;
 use SDLx::Surface;

 # Create the main surface (display)
 SDL::init(SDL_INIT_VIDEO);
 my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);

 my $surf_matrix = SDLx::Surface->new( surface => $display);
 
 $surf__matrix->[10][10] = 0xFFFF; #for 16bpp write white at x = 10 and y=10

 $surf_matrix->surface( $new_surface );

 my $orig_surface = $surf_matrix->surface();

=head1 DESCRIPTION

An C<SDLx::Surface> allows matrix read and write to a surface, safely. 

=head1 METHODS

=head2 new

Takes a SDL::Surface in hash format.

If a surface is passed to 'surface =>' that is loaded. Otherwise you can define at least a width and a height. 

	SDLx::Surface->new(  surface => $surface) # The $surface is loaded

	SDLx::Surface->new( width=> 400, height=>200) 
		# A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32) is loaded

	SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>24 ) 
	  	# A SDL::Surface->new( SDL_SWSURFACE, 400, 200, 24) is loaded 

	SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>32, greenmask=>0xFF000000 )
		# A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32, 0, 0xFF000000,0, 0, 0 ) is loaded

=head2 surface

If a SDL::Surface is passed it is attached to the matrix. Returns the SDL::Surface that is currently attached to this SDLx::Surface

=head2 get_display

If L<SDLx::App::new> or L<SDL::Video::get_video_mode> called before then:

 my $appx = SDLx::Surface::get_display(); 

gets the display if it is already made. Passed options are ignored. Otherwise you can quickly make the display with :

 SDLx::Surface::get_display( width => 20, height => 20) #depth => 32 and SDL_ANYFORMAT used

or you can also pass flags and depth. 

 SDLx::Surface::get_display( width => 20, height => 20, flags=> SDL_HWSURFACE, depth=>24) 

Get or create the main display surface and attach to a SDLx::Surface.

=head1 EXTENSIONS

=head2 blit 

 $sdlx_surface->blit( $dest, $src_rect, $dest_rect );

Blits SDLx::Surface onto $dest surface. 
$src_rect or $dest_rect are optional. $src_rect or $dest_rect can be array refs or SDL::Rect. $dest can be SDLx::Surface or SDL::Surface. 

Returns $self

=head2 flip

Applies L<SDL::Video::flip> to the Surface, with error checking.

Returns $self

=head2 update

 $sdlx_surface->update(); # whole surface is updated
 $sdlx_surface->update([0,0,1,1]); # only that area (0,0,1,1) is updated
 
 $sdlx_surface->update( [ SDL::Rect->new(0,0,1,2) ... ]); # defined rects are updated

Applies L<SDL::Video::update_rect> for no rect or 1 array ref. Applies L<SDL::Video::update_rects> for array of L<SDL::Rect>s. 

Returns $self

=head1 AUTHOR

 kthakore 


