pods::...Surface(3pm)

hey bestie! welcome to the pods::...Surface(3pm) page — aka the manual for SDLx::Surface 💖

🌸 NAME 🌸

SDLx::Surface — Graphic surface matrix extension ✨

🦋 CATEGORY 🦋

Extension — yes, it’s giving extension energy 💅

✨ SYNOPSIS ✨

okay so here’s the whole vibe, no cap:

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. That’s literally the whole mood 🫶

🎀 CONSTRUCTOR 🎀

new

Takes a SDL::Surface in hash format.

If a surface is passed to surface =>, that one 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 an attributes-only, no-pixel copy of another SDLx::Surface. iconic behavior honestly 💅

🎀 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.

🧚 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 a 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 a 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 a 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 a 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 given 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 by 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.

---

okay that’s the page bestie! it came from perl v5.42.0, dated 2024-05-01, and the manual is pods::...Surface(3pm). mwah, go make something iconic 💖