1 2=pod 3 4=head1 NAME 5 6SDLx::Surface - Graphic surface matrix extension 7 8=head1 CATEGORY 9 10Extension 11 12=head1 SYNOPSIS 13 14 use SDL; 15 use SDL::Video; 16 use SDLx::Surface; 17 18 # Create the main surface (display) 19 SDL::init(SDL_INIT_VIDEO); 20 my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE); 21 22 my $surf_matrix = SDLx::Surface->new( surface => $display); 23 24 $surf_matrix->[10][10] = 0xFFFF; #for 16bpp write white at x = 10 and y=10 25 26 $surf_matrix->surface( $new_surface ); 27 28 my $orig_surface = $surf_matrix->surface(); 29 30=head1 DESCRIPTION 31 32An C<SDLx::Surface> allows matrix read and write to a surface, safely. 33 34=head1 CONSTRUCTOR 35 36=head2 new 37 38Takes a SDL::Surface in hash format. 39 40If a surface is passed to 'surface =>' that is loaded. Otherwise you can define at least a width and a height. 41 42 SDLx::Surface->new( surface => $surface) # The $surface is loaded 43 44 SDLx::Surface->new( width=> 400, height=>200) 45 # A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32) is loaded 46 47 SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>24 ) 48 # A SDL::Surface->new( SDL_SWSURFACE, 400, 200, 24) is loaded 49 50 SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>32, greenmask=>0xFF000000 ) 51 # A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32, 0, 0xFF000000,0, 0, 0 ) is loaded 52 SDLx::Surface->new( w => 1, h => 1, color => 0xFF0000FF ) 53 # A SDL::Surface->new( SDL_ANYFORMAT, 1, 1, 32, 0, 0, 0, 0 ) is loaded 54 all pixels are colored with color (red) 55 56=head2 display 57 58If L<SDLx::App::new|SDLx::App/"new"> or L<SDL::Video::get_video_mode|SDL::Video/"get_video_mode"> called before then: 59 60 my $appx = SDLx::Surface::display(); 61 62gets the display if it is already made. Passed options are ignored. Otherwise you can quickly make the display with : 63 64 SDLx::Surface::display( width => 20, height => 20) #depth => 32 and SDL_ANYFORMAT used 65 66or you can also pass flags and depth. 67 68 SDLx::Surface::display( width => 20, height => 20, flags=> SDL_HWSURFACE, depth=>24) 69 70You can also use the keys C<w> and C<h> in place of C<width> and C<height>, as with C<new>. 71 72Get or create the main display surface and attach to a C<SDLx::Surface>. 73 74=head2 duplicate 75 76Does a attributes only, no pixel, copy of another SDLx::Surface. 77 78=head1 ATTRIBUTES 79 80=head2 surface 81 82If a SDL::Surface is passed it is attached to the matrix. Returns the SDL::Surface that is currently attached to this SDLx::Surface 83 84=head2 w, h, format, pitch, flags 85 86Returns the inner SDL::Surface's respective attribute. See C<SDL::Surface>. 87 88=head2 clip_rect 89 90Sets the passed C<SDL::Rect> as the new clip_rect for the surface. Returns the SDL::Surface's clip_rect. See 91L<SDL::Video::get_clip_rect|SDL::Video/"get_clip_rect"> and L<SDL::Video::set_clip_rect|SDL::Video/"set_clip_rect">. 92=head1 EXTENSIONS 93 94=head2 load 95 96 my $surface = SDLx::Surface->load( 'hero.png' ); 97 my $surface = SDLx::Surface->load( 'hero.dat', 'bmp' ); 98 99Loads the given image file into a I<new> SDLx::Surface surface. A new 100surface is B<always> created, even if you call it from an already crafted 101object. Croaks on errors such as no support built for that image extension 102or a file reading error (the error message is SDL::get_error and should 103give more details). 104 105Note that load() will automatically figure out the extension based on the 106filename you provide. If you wish to force an extension for whatever reason 107(like having a filename with a different extension or none at all), you can 108optionally pass the file type as a second parameter. Case is not relevant. 109 110If you don't have SDL_image in your build, only bitmap images will be 111supported. 112 113Returns the new Surface. 114 115 116=head2 blit 117 118 $sdlx_surface->blit( $dest, $src_rect, $dest_rect ); 119 120Blits C<SDLx::Surface> onto $dest surface. 121$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, 122it 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>. 123 124Note that the final blit rectangle is stored in $dest_rect after clipping is performed. 125 126Returns $self 127 128=head2 blit_by 129 130 $sdlx_surface->blit_by( $src, $src_rect, $dest_rect ); 131 132Does the same as C<blit> but the C<SDLx::Surface> is the one being blitted to. 133This is useful when the surface you have isn't an C<SDLx::Surface>, but the surface it is being blitted to is. 134 135Note that the final blit rectangle is stored in $dest_rect after clipping is performed. 136 137=head2 flip 138 139Applies L<SDL::Video::flip|SDL::Video/"flip"> to the Surface, with error checking. 140 141Returns $self 142 143=head2 update 144 145 $sdlx_surface->update(); # whole surface is updated 146 $sdlx_surface->update([0,0,1,1]); # only that area (0,0,1,1) is updated 147 148 $sdlx_surface->update( [ SDL::Rect->new(0,0,1,2) ... ]); # defined rects are updated 149 150Applies L<SDL::Video::update_rect|SDL::Video/"update_rect"> for no rect or 1 array ref. Applies 151L<SDL::Video::update_rects|SDL::Video/"update_rects"> for array of L<SDL::Rect>s. 152 153Returns $self 154 155 156=head2 draw_rect 157 158 $sdlx_surface->draw_rect( [$x,$y,$w,$h], 0xFFFF00FF ); 159 $sdlx_surface->draw_rect( SDL::Rect->new($x,$y,$w,$h), 0xFFFF00FF ); 160 161Draws a rect on the surface with the given color. If the rect is omitted, the colored rect will be drawn to the entire surface. 162 163Returns $self 164 165=head2 draw_line 166 167 $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], $color, $antialias); # $color is a number 168 $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], \@color, $antialias); # 169 170Draws a line on the surface. Antialias is turned on if $antialias is true. 171 172Returns $self 173 174=head2 draw_circle 175 176 $sdlx_surface->draw_circle( [$x1, $y1], $radius, \@color, $antialias ); 177 178Draws an unfilled circle at C<($x1,$y1)> of size $radius and $color. 179Antialias is turned on if $antialias is true. 180Returns $self 181 182=head2 draw_circle_filled 183 184 $sdlx_surface->draw_circle_filled( [$x1, $y1], $radius, \@color ); 185 186Draws an B<filled> circle at C<($x1,$y1)> of size $radius and $color. 187Antialias is turned on automatically. 188Returns $self 189 190=head2 draw_trigon 191 192 $sdlx_surface->draw_trigon( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color, $antialias ); 193 194Draws an unfilled trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>, 195C<($x3,$y3)> and $color. 196Antialias is turned on if $antialias is true. 197Returns $self 198 199=head2 draw_trigon_filled 200 201 $sdlx_surface->draw_trigon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color ); 202 203Draws an B<filled> trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>, 204C<($x3,$y3)> and $color. 205Antialias is turned on automatically. 206Returns $self 207 208=head2 draw_polygon 209 210 $sdlx_surface->draw_polygon( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color, $antialias ); 211 212Draws an unfilled polygon with vertices C<($xN,$yN)> and $color. 213Antialias is turned on if $antialias is true. 214Returns $self 215 216=head2 draw_polygon_filled 217 218 $sdlx_surface->draw_polygon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color ); 219 220Draws an B<filled> polygon with vertices C<($xN,$yN)> and $color. 221Antialias is turned on automatically. 222Returns $self 223 224=head2 draw_arc 225 226 $sdlx_surface->draw_arc( [ $x, $y ], $radius, $start, $end, $color ); 227 228Draws an arc around C<($x,$y)> with $radius, $start radius, $end radius 229and $color. 230 231Returns $self 232 233=head2 draw_ellipse 234 235 $sdlx_surface->draw_ellipse( [ $x, $y ], $rx, $ry, $color ); 236 237Draws an unfilled ellipse centered at C<($x,$y)> with horizontal radius $rx, 238vertical radius $ry and $color. 239Antialias is turned on if $antialias is true. 240 241Returns $self 242 243=head2 draw_ellipse_filled 244 245 $sdlx_surface->draw_ellipse_filled( [ $x, $y ], $rx, $ry, $color ); 246 247Draws an B<filled> ellipse centered at C<($x,$y)> with horizontal radius $rx, 248vertical radius $ry and $color. 249Antialias is turned on automatically. 250 251Returns $self 252 253=head2 draw_bezier 254 255 $sdlx_surface->draw_bezier( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], $s, $color ); 256 257Draws a bezier curve of points C<($xN,$yN)> using $s steps for 258interpolation and $color. 259Antialias is turned on automatically. 260 261Returns $self 262 263=head2 draw_gfx_text 264 265Draw text using gfx (not pretty but fast) at give vector, color. 266 267 $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo"); 268 $surf->draw_gfx_text( [10,10], [20,20,20,20], "fooo"); 269 270You can also set the gfx font but passing a hash reference as shown below. 271 272 my $f = ''; 273 open( my $FH, '<', 'test/data/5x7.fnt'); 274 binmode ($FH); 275 read($FH, $f, 4096); 276 close ($FH); 277 278 my $font = {data=>$f, cw => 5, ch => 7}; 279 $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo", $font ); 280 281Returns $self 282 283=head1 AUTHORS 284 285See L<SDL/AUTHORS>. 286 287