--- name: "SDLx::Surface" section: "3pm" platform: "linux" package: "libsdl-perl" version: "2.548-5+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SDLx::Surface" --- # SDLx::Surface(3pm) Graphic surface matrix extension ## NAME SDLx::Surface - Graphic surface matrix extension ## CATEGORY Extension ## 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(); ``` ## DESCRIPTION An `"SDLx::Surface"` allows matrix read and write to a surface, safely. ## CONSTRUCTOR ### 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) ``` ### display If SDLx::App::new or 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 `"w"` and `"h"` in place of `"width"` and `"height"`, as with `"new"`. Get or create the main display surface and attach to a `"SDLx::Surface"`. ### duplicate Does a attributes only, no pixel, copy of another SDLx::Surface. ## ATTRIBUTES ### 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 ### w, h, format, pitch, flags Returns the inner SDL::Surface's respective attribute. See `"SDL::Surface"`. ### clip\_rect Sets the passed `"SDL::Rect"` as the new clip\_rect for the surface. Returns the SDL::Surface's clip\_rect. See SDL::Video::get\_clip\_rect and SDL::Video::set\_clip\_rect. =head1 EXTENSIONS ### load ``` my $surface = SDLx::Surface->load( 'hero.png' ); my $surface = SDLx::Surface->load( 'hero.dat', 'bmp' ); ``` Loads the given image file into a *new* SDLx::Surface surface. A new surface is **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. ### blit ``` $sdlx_surface->blit( $dest, $src_rect, $dest_rect ); ``` Blits `"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 `"(0, 0)"`. `$src_rect` or `$dest_rect` can be array refs or `"SDL::Rect"`. `$dest` can be `"SDLx::Surface"` or `"SDL::Surface"`. Note that the final blit rectangle is stored in `$dest_rect` after clipping is performed. Returns `$self` ### blit\_by ``` $sdlx_surface->blit_by( $src, $src_rect, $dest_rect ); ``` Does the same as `"blit"` but the `"SDLx::Surface"` is the one being blitted to. This is useful when the surface you have isn't an `"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. ### flip Applies SDL::Video::flip to the Surface, with error checking. Returns `$self` ### 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 SDL::Video::update\_rect for no rect or 1 array ref. Applies SDL::Video::update\_rects for array of SDL::Rects. Returns `$self` ### 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` ### 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` ### draw\_circle ``` $sdlx_surface->draw_circle( [$x1, $y1], $radius, \@color, $antialias ); ``` Draws an unfilled circle at `"($x1,$y1)"` of size `$radius` and `$color`. Antialias is turned on if `$antialias` is true. Returns `$self` ### draw\_circle\_filled ``` $sdlx_surface->draw_circle_filled( [$x1, $y1], $radius, \@color ); ``` Draws an **filled** circle at `"($x1,$y1)"` of size `$radius` and `$color`. Antialias is turned on automatically. Returns `$self` ### draw\_trigon ``` $sdlx_surface->draw_trigon( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color, $antialias ); ``` Draws an unfilled trigon (triangle) with vertices `"($x1,$y1)"`, `"($x2,$y2)"`, `"($x3,$y3)"` and `$color`. Antialias is turned on if `$antialias` is true. Returns `$self` ### draw\_trigon\_filled ``` $sdlx_surface->draw_trigon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color ); ``` Draws an **filled** trigon (triangle) with vertices `"($x1,$y1)"`, `"($x2,$y2)"`, `"($x3,$y3)"` and `$color`. Antialias is turned on automatically. Returns `$self` ### draw\_polygon ``` $sdlx_surface->draw_polygon( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color, $antialias ); ``` Draws an unfilled polygon with vertices `"($xN,$yN)"` and `$color`. Antialias is turned on if `$antialias` is true. Returns `$self` ### draw\_polygon\_filled ``` $sdlx_surface->draw_polygon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color ); ``` Draws an **filled** polygon with vertices `"($xN,$yN)"` and `$color`. Antialias is turned on automatically. Returns `$self` ### draw\_arc ``` $sdlx_surface->draw_arc( [ $x, $y ], $radius, $start, $end, $color ); ``` Draws an arc around `"($x,$y)"` with `$radius`, `$start` radius, `$end` radius and `$color`. Returns `$self` ### draw\_ellipse ``` $sdlx_surface->draw_ellipse( [ $x, $y ], $rx, $ry, $color ); ``` Draws an unfilled ellipse centered at `"($x,$y)"` with horizontal radius `$rx`, vertical radius `$ry` and `$color`. Antialias is turned on if `$antialias` is true. Returns `$self` ### draw\_ellipse\_filled ``` $sdlx_surface->draw_ellipse_filled( [ $x, $y ], $rx, $ry, $color ); ``` Draws an **filled** ellipse centered at `"($x,$y)"` with horizontal radius `$rx`, vertical radius `$ry` and `$color`. Antialias is turned on automatically. Returns `$self` ### draw\_bezier ``` $sdlx_surface->draw_bezier( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], $s, $color ); ``` Draws a bezier curve of points `"($xN,$yN)"` using `$s` steps for interpolation and `$color`. Antialias is turned on automatically. Returns `$self` ### 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` ## AUTHORS See "AUTHORS" in SDL.