pods::...Surface(3pm)

💖 NAME 💖

Okay bestie, this is the pods::...Surface(3pm) page from the User Contributed Perl Documentation, and it's all about SDLx::Surface — Graphic surface matrix extension. That's the whole name-and-tagline situation, no cap. 💅

🎀 CATEGORY 🎀

Extension. Cute, iconic, category secured. ✨

✨ SYNOPSIS ✨

Here's the vibe in code, bestie:

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 🦋

So an SDLx::Surface lets you do matrix read and write to a surface, safely. That's literally the whole point, and it's giving exactly what it needs to give. 🫶

🌸 CONSTRUCTOR 🌸

new

Takes a SDL::Surface in hash format, bestie.

If a surface is passed to 'surface =>', that one gets loaded. Otherwise you can define at least a width and a height. Boom, that's the rule. 💖

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

And for that last one? all pixels are colored with color (red). Periodt. 🍓

display

If SDLx::App::new or SDL::Video::get_video_mode was called before, then:

my $appx = SDLx::Surface::display();

gets the display if it's already made. Passed options are ignored — like, don't even bother, bestie.

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 it to a SDLx::Surface. Slay. 💅

duplicate

Does an attributes-only, no-pixel copy of another SDLx::Surface. Like a vibe check for the metadata only. 🎀

💅 ATTRIBUTES 💅

surface

If a SDL::Surface is passed, it gets attached to the matrix. Returns the SDL::Surface that is currently attached to this SDLx::Surface. Simple, iconic. ✨

w, h, format, pitch, flags

Returns the inner SDL::Surface's respective attribute. See "SDL::Surface". No cap, it's all right there. 🌈

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 the $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. No extra return line here, bestie — that's literally what the page says. 🙈

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 the given vector and 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, like this:

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. That's the whole author situation, bestie. 👑

---

💖 And that's the page, babes: pods::...Surface(3pm) from perl v5.42.3, dated 2026-08-19 — go forth and matrix-ify your surfaces safely! 💖