=pod

=head1 NAME

SDL::Surface - Graphic surface structure.

=head1 CATEGORY

Core, Video, Structure

=head1 SYNOPSIS

The main surface (display) is provided by L<SDL::Video::set_video_mode>.
  use SDL; #provides flags & constants
  use SDL::Video; #provides access to set_video_mode
  use SDL::Surface; #provides access to SDL_Surface struct internals
  
  SDL::init(SDL_INIT_VIDEO); 
  my $display = SDL::Video::set_video_mode(); 
 
All surfaces constructed from now on are attached to the $display. There are two constructors available to do this.

  my $surface  = SDL::Surface->new ( ... ); 
  my $surface2 = SDL::Surface->new_from ( surface, ... ); 
  
=head1 DESCRIPTION

An C<SDL_Surface> defines a surfaceangular area of pixels.

=head1 CONSTANTS

The constants are exported by default. You can avoid this by doing:

 use SDL::Video ();

and access them directly:

 SDL::Video::SDL_SWSURFACE;

Available constants: see L</flags>

=head1 METHODS

=head2 new ( flags, width, height, depth, Rmask, Gmask, Bmask, Amask )

The constructor creates a new surface with the specified parameter values.

    my $surface = SDL::Surface->new( ... );

=head2 new_from ( surface, width, height, depth, Rmask, Gmask, Bmask, Amask )

The constructor creates a new surface with the specified parameter values. 

    my $surface = SDL::Surface->new_from( $old_surface, ... );


=head3 Construtor Parameters

=head4 flags

Available flags for new() are exported by SDL::Video

=over 4

=item SDL_ASYNCBLIT

Use asynchronous blit if possible

=item SDL_SWSURFACE

Stored in the system memory.

=item SDL_HWSURFACE

Stored in video memory

=back

=head2 w

SDL::Surface width are defined at construction. Thus the following is read only. 

  my $w = $surface->w; 
  
=head2 h

SDL::Surface height are defined at construction. Thus the following is read only. 

  my $h = $surface->h; 

=head2 format

The format of the pixels stored in the surface. See L<SDL::PixelFormat>

 my $format = $surface->format;

=head2 pitch

 my $pitch = $surface->pitch;

SDL::Surface's scanline length in bytes

=head2 clip_rect

To get the surface's clip_rect we the following

 my $clip_rect = SDL::Rect->new(0,0,0,0);
 SDL::Video::get_clip_rect($surface, $clip_rect);

To set the surface's clip_rect use the following

 my $clip_rect = SDL::Rect->new(2,23,23,542);
 SDL::Video::set_clip_rect($surface, $clip_rect);

=head1 Direct Write to Surface Pixel

Disclaimer: This can be very slow, it is suitable for creating surfaces one time and not for animations

=head2 get_pixels

 $surface->get_pixels( $offset )  

Returns the current integer value at (surface->pixels)[offset] 

=head2 set_pixels

 $surface->set_pixels( $offset, $value );

Sets the current integer to $value at (surface->pixels)[offset]

=head3 Usage

  sub putpixel
  {
	my($x, $y, $color) = @_;
	my $lineoffset = $y * ($screen->pitch / $depth_in_bytes); 
	$screen->set_pixels( $lineoffset+ $x, $color);
  }

Note: $depth_in_bytes for 32 is 4, 16 is 2, 8 is 1;

See also examples/sols/ch02.pl

=head2 get_pixels_ptr

 $surface->get_pixels_ptr();

Returns the C ptr to this surfaces's pixels



=head1 SEE ALSO

L<SDL>, L<SDL::PixelFormat>, L<SDL::Video>, L<SDL::Rect>

=cut
