pods::...urface(3pm)

🌸 NAME 🌸

okay bestie, welcome to the pods::...urface(3pm) page from User Contributed Perl Documentation 💖. This one is all about SDL::Surface — the Graphic surface structure. Yep, that's the name, that's the vibe, slay. ✨

🎀 CATEGORY 🎀

It's giving Core, Video, Structure — all three, no cap. 💅

✨ SYNOPSIS ✨

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

# Create the main surface (display)
SDL::init(SDL_INIT_VIDEO);
my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);

# Create other surfaces attached to the $display.
my $surface  = SDL::Surface->new(SDL_ASYNCBLIT | SDL_HWSURFACE, 640, 480, 16, 0, 0, 0, 0);
my $surface2 = SDL::Surface->new_from($surface, 100, 100, 8, 0, 0, 0, 0);

🦋 DESCRIPTION 🦋

An SDL_Surface defines a surfaceangular area of pixels. That's the whole mood. 💫

💖 CONSTANTS 💖

The constants for SDL::Surface belong to SDL::Video, under the export tag of ':surface'. Iconic. 👑

• SDL_ASYNCBLIT — Use asynchronous blit if possible
• SDL_SWSURFACE — Store in system memory
• SDL_HWSURFACE — Store in video memory

💅 METHODS 💅

new

my $surface = SDL::Surface->new(
    $flags, $width, $height, $depth, $Rmask, $Gmask, $Bmask, $Amask
);

The constructor creates a new surface with the specified parameter values. Very main character energy. 🫶

The four mask values are the bits that the channel will ignore. For example, an Rmask of 0xFF will ignore that channel completely, making everything on the surface more green/blue. 🍓

new_from

my $surface = SDL::Surface->new_from(
    $surface, $width, $height, $depth, $Rmask, $Gmask, $Bmask, $Amask
);

The constructor creates a new surface with the specified parameter values. The flags are taken from the specified $surface. Reuse era! 🌈

w

my $w = $surface->w;

Returns the width of the surface. SDL::Surface width is defined at construction so this is read-only. No take-backs, bestie. 🔒

h

my $h = $surface->h;

Returns the height of the surface. SDL::Surface height is defined at construction so this is read-only. Same locked-in vibe. 🔐

format

my $format = $surface->format;

The format of the pixels stored in the surface. See SDL::PixelFormat 👀

pitch

my $pitch = $surface->pitch;

The scanline length in bytes. Literally just that. 📏

✍️ Direct Write to Surface Pixel ✍️

Disclaimer: The following methods can be very slow, making them suitable for creating surfaces, but not for animations

Not me warning you bestie: slow and steady is cute for setup, not for animation. 🐢💀

get_pixel

my $pixel = $surface->get_pixel( $offset )

Returns the numeric pixel value for the given $offset. The pixel value depends on current pixel format. 🔍

Note: For surfaces with a palette (1 byte per pixel) the palette index is returned instead of color values.

set_pixels

$surface->set_pixels( $offset, $value );

Sets the pixel $value to the given $offset. The pixel value must fit the pixel format of the surface. 🎯

Note: For surfaces with a palette (1 byte per pixel) the palette index must be passed instead of color values.

Example:

sub putpixel {
    my ($x, $y, $color) = @_;
    $display->set_pixels( $x + $y * $display->w, $color);
}

See also examples/pixel_operations/sols/ch02.pl! 🫶

get_pixels_ptr

my $ptr = $surface->get_pixels_ptr;

Returns a reference to the surface's pixels. Pointy and powerful. 🪄

💜 SEE ALSO 💜

Check out SDL, SDL::PixelFormat, SDL::Video, SDL::Rect — the whole friend group. 🫂

🌟 AUTHORS 🌟

See "AUTHORS" in SDL. 📝

---

okay bye bestie — this was pods::...urface(3pm), from perl v5.42.0, dated 2024-05-01 💖✨ Go slay your surfaces! 🎀