/lib/pods/SDLx/Surface.pod
http://github.com/PerlGameDev/SDL · Unknown · 286 lines · 169 code · 117 blank · 0 comment · 0 complexity · 0575fb5cec1ada09f6be2b9118e83fde MD5 · raw file
- =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 CONSTRUCTOR
- =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
- SDLx::Surface->new( w => 1, h => 1, color => 0xFF0000FF )
- # A SDL::Surface->new( SDL_ANYFORMAT, 1, 1, 32, 0, 0, 0, 0 ) is loaded
- all pixels are colored with color (red)
- =head2 display
- If L<SDLx::App::new|SDLx::App/"new"> or L<SDL::Video::get_video_mode|SDL::Video/"get_video_mode"> called before then:
- my $appx = SDLx::Surface::display();
- gets the display if it is already made. Passed options are ignored. Otherwise you can quickly make the display with :
- SDLx::Surface::display( width => 20, height => 20) #depth => 32 and SDL_ANYFORMAT used
- or you can also pass flags and depth.
- SDLx::Surface::display( width => 20, height => 20, flags=> SDL_HWSURFACE, depth=>24)
- You can also use the keys C<w> and C<h> in place of C<width> and C<height>, as with C<new>.
- Get or create the main display surface and attach to a C<SDLx::Surface>.
- =head2 duplicate
- Does a attributes only, no pixel, copy of another SDLx::Surface.
- =head1 ATTRIBUTES
- =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 w, h, format, pitch, flags
- Returns the inner SDL::Surface's respective attribute. See C<SDL::Surface>.
- =head2 clip_rect
- Sets the passed C<SDL::Rect> as the new clip_rect for the surface. Returns the SDL::Surface's clip_rect. See
- L<SDL::Video::get_clip_rect|SDL::Video/"get_clip_rect"> and L<SDL::Video::set_clip_rect|SDL::Video/"set_clip_rect">.
- =head1 EXTENSIONS
- =head2 load
- my $surface = SDLx::Surface->load( 'hero.png' );
- my $surface = SDLx::Surface->load( 'hero.dat', 'bmp' );
- Loads the given image file into a I<new> SDLx::Surface surface. A new
- surface is B<always> created, even if you call it from an already crafted
- object. Croaks on errors such as no support built for that image extension
- or a file reading error (the error message is SDL::get_error and should
- give more details).
- Note that load() will automatically figure out the extension based on the
- filename you provide. If you wish to force an extension for whatever reason
- (like having a filename with a different extension or none at all), you can
- optionally pass the file type as a second parameter. Case is not relevant.
- If you don't have SDL_image in your build, only bitmap images will be
- supported.
- Returns the new Surface.
- =head2 blit
- $sdlx_surface->blit( $dest, $src_rect, $dest_rect );
- Blits C<SDLx::Surface> onto $dest surface.
- $src_rect or $dest_rect are optional. If $src_rect is omitted, it will be the size of the entire surface. If $dest_rect is omitted,
- it will be blitted at C<(0, 0)>. $src_rect or $dest_rect can be array refs or C<SDL::Rect>. $dest can be C<SDLx::Surface> or C<SDL::Surface>.
- Note that the final blit rectangle is stored in $dest_rect after clipping is performed.
- Returns $self
- =head2 blit_by
- $sdlx_surface->blit_by( $src, $src_rect, $dest_rect );
- Does the same as C<blit> but the C<SDLx::Surface> is the one being blitted to.
- This is useful when the surface you have isn't an C<SDLx::Surface>, but the surface it is being blitted to is.
- Note that the final blit rectangle is stored in $dest_rect after clipping is performed.
- =head2 flip
- Applies L<SDL::Video::flip|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|SDL::Video/"update_rect"> for no rect or 1 array ref. Applies
- L<SDL::Video::update_rects|SDL::Video/"update_rects"> for array of L<SDL::Rect>s.
- Returns $self
- =head2 draw_rect
- $sdlx_surface->draw_rect( [$x,$y,$w,$h], 0xFFFF00FF );
- $sdlx_surface->draw_rect( SDL::Rect->new($x,$y,$w,$h), 0xFFFF00FF );
- Draws a rect on the surface with the given color. If the rect is omitted, the colored rect will be drawn to the entire surface.
- Returns $self
- =head2 draw_line
- $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], $color, $antialias); # $color is a number
- $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], \@color, $antialias); #
- Draws a line on the surface. Antialias is turned on if $antialias is true.
- Returns $self
- =head2 draw_circle
- $sdlx_surface->draw_circle( [$x1, $y1], $radius, \@color, $antialias );
- Draws an unfilled circle at C<($x1,$y1)> of size $radius and $color.
- Antialias is turned on if $antialias is true.
- Returns $self
- =head2 draw_circle_filled
- $sdlx_surface->draw_circle_filled( [$x1, $y1], $radius, \@color );
- Draws an B<filled> circle at C<($x1,$y1)> of size $radius and $color.
- Antialias is turned on automatically.
- Returns $self
- =head2 draw_trigon
- $sdlx_surface->draw_trigon( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color, $antialias );
- Draws an unfilled trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>,
- C<($x3,$y3)> and $color.
- Antialias is turned on if $antialias is true.
- Returns $self
- =head2 draw_trigon_filled
- $sdlx_surface->draw_trigon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color );
- Draws an B<filled> trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>,
- C<($x3,$y3)> and $color.
- Antialias is turned on automatically.
- Returns $self
- =head2 draw_polygon
- $sdlx_surface->draw_polygon( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color, $antialias );
- Draws an unfilled polygon with vertices C<($xN,$yN)> and $color.
- Antialias is turned on if $antialias is true.
- Returns $self
- =head2 draw_polygon_filled
- $sdlx_surface->draw_polygon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color );
- Draws an B<filled> polygon with vertices C<($xN,$yN)> and $color.
- Antialias is turned on automatically.
- Returns $self
- =head2 draw_arc
- $sdlx_surface->draw_arc( [ $x, $y ], $radius, $start, $end, $color );
- Draws an arc around C<($x,$y)> with $radius, $start radius, $end radius
- and $color.
- Returns $self
- =head2 draw_ellipse
- $sdlx_surface->draw_ellipse( [ $x, $y ], $rx, $ry, $color );
- Draws an unfilled ellipse centered at C<($x,$y)> with horizontal radius $rx,
- vertical radius $ry and $color.
- Antialias is turned on if $antialias is true.
- Returns $self
- =head2 draw_ellipse_filled
- $sdlx_surface->draw_ellipse_filled( [ $x, $y ], $rx, $ry, $color );
- Draws an B<filled> ellipse centered at C<($x,$y)> with horizontal radius $rx,
- vertical radius $ry and $color.
- Antialias is turned on automatically.
- Returns $self
- =head2 draw_bezier
- $sdlx_surface->draw_bezier( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], $s, $color );
- Draws a bezier curve of points C<($xN,$yN)> using $s steps for
- interpolation and $color.
- Antialias is turned on automatically.
- Returns $self
- =head2 draw_gfx_text
- Draw text using gfx (not pretty but fast) at give vector, color.
- $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo");
- $surf->draw_gfx_text( [10,10], [20,20,20,20], "fooo");
- You can also set the gfx font but passing a hash reference as shown below.
- my $f = '';
- open( my $FH, '<', 'test/data/5x7.fnt');
- binmode ($FH);
- read($FH, $f, 4096);
- close ($FH);
-
- my $font = {data=>$f, cw => 5, ch => 7};
- $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo", $font );
- Returns $self
- =head1 AUTHORS
- See L<SDL/AUTHORS>.