pods::...:Cursor(3pm)

🖱️ NAME ✨

SDL::Cursor — it's the mouse cursor structure, bestie. Like, the literal little arrow thing on your screen? Yeah. That. 💅

Oh also hiii, this page is from the pods::...:Cursor manual, section 3pm (Perl modules, if you were wondering) 🎀

---

🌸 CATEGORY 🌸

Core, Mouse, Structure. So it's core, it's about mice (the pointing kind, not the squeaky kind 🐭), and it's a structure. Slay.

---

✨ SYNOPSIS ✨

Okay so here's the whole vibe in code form:

my $cursor = SDL::Cursor->new(
    \@data,
    \@mask,
    $width,
    $height,
    $hotspot_left,
    $hotspot_top
);

SDL::Mouse::set_cursor($cursor);

Build a cursor, then hand it to SDL::Mouse::set_cursor. That's the whole journey. 🦋

---

💖 DESCRIPTION 💖

The SDL::Cursor module handles mouse cursors and lets you, yes you, the developer, make custom-made cursors. Main character cursor energy, truly 👑

But lowkey important: cursors can only be in black and white. That's it. Two colors. Monochrome realness. No cap.

---

🎀 METHODS 🎀

⭐ new

my $cursor = SDL::Cursor->new(
    \@data, \@mask, $width, $height, $hotspot_left, $hotspot_top
);

This makes a cursor out of the data and mask you give it (in MSB format, iykyk). The cursor comes out black and white based on this little lookup situation:

• 0 / 1 → White pixel on screen
• 1 / 1 → Black pixel on screen
• 0 / 0 → Transparent
• 1 / 0 → Inverted color if possible, black if not

(That's Data / Mask → Resulting pixel on screen, for the record ✨)

If you want a color cursor, then this function is not for you, bestie, it's giving monochrome only 😭 Instead, you should hide the cursor with SDL::Mouse::show_cursor(SDL_DISABLE). Then in your main loop, when you draw graphics, draw a SDL::Surface at the location of the mouse cursor. Fake it till you make it, basically 💅

Example — a whole working-ish situation:

use SDL;
use SDL::Video;
use SDL::Mouse;
use SDL::Cursor;

SDL::init(SDL_INIT_VIDEO);
SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);

my @data = (
    0b00000000,
    0b00111100,
    0b01111110,
    0b01111110,
    0b01111110,
    0b01111110,
    0b00111100,
    0b00000000
);
my @mask = (
    0b00111100,
    0b01111110,
    0b11100111,
    0b11000011,
    0b11000011,
    0b11100111,
    0b01111110,
    0b00111100
);
my $cursor = SDL::Cursor->new(\@data, \@mask, 8, 8, 0, 0);
sleep(1);

SDL::Mouse::set_cursor($cursor);
sleep(5);

Okay and here's the part that trips people up, so listen up 🫶 The width of cursors works in groups of 8. If the width is above 8, twice the amount of elements in @data and @mask are required. If the width is above 16, three times are required, and so on. Math is mathing, okay?

For example, if you wanted a 9 pixel crosshair you might do the following:

my @data = (
    0b00001000,0b00000000,
    0b00001000,0b00000000,
    0b00001000,0b00000000,
    0b00001000,0b00000000,
    0b11111111,0b10000000,
    0b00001000,0b00000000,
    0b00001000,0b00000000,
    0b00001000,0b00000000,
    0b00001000,0b00000000,
);
my @mask = @data;

my $cursor = SDL::Cursor->new(\@data, \@mask, 9, 9, 4, 4);

And why 4, 4 for the hotspot? Because the hotspot is offset by 4 pixels — a crosshair clicks from the center instead of the top left. Centered icon behavior, we love to see it 🎯

---

👑 AUTHORS 👑

See "AUTHORS" in SDL. (Not me, I'm just the messenger 💜)

---

🌈 SEE ALSO 🌈

• perl
• SDL::Mouse

---

That's the whole page, bestie, you're basically a cursor expert now 🧚✨

Little sign-off: this was perl v5.42.0, dated 2024-05-01, filed under pods::...:Cursor(3pm). Go make something iconic with it 💖🌸