pods::...::Layer(3pm)

💜 pods::...::Layer(3pm) — the user-contributed Perl docs, bestie edition

Okay so this is a page from the User Contributed Perl Documentation and it's literally the manual for pods::...::Layer(3pm). Grab a strawberry 🍓, we're learning about layers.

---

✨ NAME ✨

SDLx::Layer — the storage object for surface and position info. It's giving "little container that holds your vibes together." 🎀

🦋 CATEGORY 🦋

Extension. Yep, that's the whole category. Iconic of it, honestly.

🌈 SYNOPSIS 🌈

Bestie, here's the whole look, copied exactly character for character so you can just run it:

use SDLx::Layer;
use SDLx::LayerManager;

use SDL::Image;
use SDL::Surface;
use SDL::Video;

# creating layers
my $layer1 = SDLx::Layer->new( SDL::Image::load('image1.png'), {userdata => '7'} );
my $layer2 = SDLx::Layer->new( SDL::Image::load('image2.png'), 100, 200, {userdata => '42'} );

# creating the manager that holds the layers
my $layermanager = SDLx::LayerManager->new();
$layermanager->add( $layer1 );
$layermanager->add( $layer2 );

my $display = # create your video surface here

$layer1->foreground;
printf( "%s\n", $layer1->behind->[0]->data->{userdata} ); # prints 42

Notice that printf at the end lowkey printing 42? That's $layer1->behind->[0] reaching behind and grabbing the userdata. Chef's kiss. 💅

🌸 DESCRIPTION 🌸

So a layer (peep SDLx::Layer) is literally three things stacked into one slay little object:

• an SDL::Surface
• the position of the surface on screen
• some additional information, e.g. ingame states

That's it. That's the vibe. 🫶

---

👑 METHODS 👑

💖 new

my $layer = SDLx::Layer->new( $surface );
my $layer = SDLx::Layer->new( $surface,                                   %data );
my $layer = SDLx::Layer->new( $surface, $pos_x,                           %data );
my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y,                   %data );
my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y, $clip_w,          %data );
my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y, $clip_w, $clip_h, %data );

This constructs the layer object. Yes bestie, look at all those forms — you can literally omit the position and dimension of the layer. Slay, no required coords.

The hash %data is for your use only — the layer object just passes it through. It's not judging your data, it's not touching your data, it's just holding it. Main character energy: the layer is the messenger, not the message. 🔥

💖 index

my $index = $layer->index;

The method "index" represents the z-index of this layer within its layermanager. Front-to-back ordering, yk? Stack 'em.

💖 x

my $x = $layer->x;

This is a shortcut for $layer->pos->x. Shortcut culture, we stan.

💖 y

my $y = $layer->y;

This is a shortcut for $layer->pos->y. Matching set with x, periodt.

💖 w

my $w = $layer->w;

This is a shortcut for $layer->clip->w.

💖 h

my $h = $layer->h;

This is a shortcut for $layer->pos->h.

Ngl, w grabs from clip and h grabs from pos in this doc — that's exactly what the page says, so that's exactly what we're saying. 💀 Don't come for me, I'm just the messenger.

💖 surface

my $surface = $layer->surface;
my $surface = $layer->surface( $new_surface );

Example, copy-paste ready:

SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );

This method lets you retrieve the current surface or set a new one. Dual-purpose icon. 🦋

💖 pos

my $rect = $layer->pos;

The method "pos" returns an SDL::Rect object. The pos x and y are stored there.

Example:

SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );

💖 clip

my $rect = $layer->clip;

The method "clip" returns an SDL::Rect object. The clip width and height are stored there.

Example:

SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );

Same blit call, different argument in the hot seat. It's giving consistency. ✨

💖 data

my %data = %{ $layer->data };
my %data = %{ $layer->data( %new_data) };

This method returns the hash %data. You can set %data by passing a hash. Your data, your rules. 🎀

💖 ahead

my @layers = $layer->ahead;

This method returns all layers that are ahead of the given layer. Ahead means a layer has a higher z-index and is blitted over the given layer.

Note: This method doesn't check for transparency. This will change in future versions. 🙈 (So for now, transparency is not on the guest list.)

💖 behind

my @layers = $layer->behind;

This method returns all layers that are behind the given layer. Behind means a layer has a lower z-index and is blitted over the given layer.

Note: This method doesn't check for transparency either. This will change in future versions. 🌸 (Same caveat, no gatekeeping.)

💖 attach

$layer->attach( $x, $y );

This function makes the given layer sticky to the mouse. Move the mouse, the layer follows. Obsessed. 🐭✨ The layermanager blits this layer at last, so attached layers appear on top of all layers.

$x and $y should be set to the coords of the mouse, e.g. the coords of the mouse click. If you omit $x and $y, the layer obtains them via SDL::Events::get_mouse_state.

Note: The z-index is not changed for the given layer. Attach ≠ reorder, bestie, don't get it twisted.

💖 detach_xy

$layer->detach_xy( $x, $y );

"detach_xy" detaches the previously attached layer to the given coords. The upper left corner of this layer will be at $x and $y. So it lands exactly where you point it. 🎯

💖 foreground

$layer->foreground;

This method moves the given layer to the foreground so that it is blitted on top of the other layers. Front row seats, no cap. 👑

---

💀 BUGS 💀

Report at sdlperl.ath.cx. Yes, that's the address, write it down.

🌈 SUPPORT 🌈

#sdl on irc.perl.org. Come hang, the group chat is literally there. 🫶

⭐ AUTHORS ⭐

See "AUTHORS" in SDL.

🎀 COPYRIGHT 🎀

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

🧚 SEE ALSO 🧚

perl(1), SDL(2).

---

And that's the whole page, bestie 💖✨ slay responsibly, and remember: the layers are stacked, the data is yours, and the transparency check is coming in a future version.

This page is from perl v5.42.0, dated 2024-05-01, and lives at pods::...::Layer(3pm) — mwah, go build something iconic 🦋💅