pods::SDLx::Text(3pm)

💖 SDLx::Text — the pods::SDLx::Text(3pm) glow-up 🎀

okay so bestie, this is the manpage for SDLx::Text, from the Perl User Contributed Documentation corner of the universe, and honestly? it's a whole vibe.

✨ NAME ✨

SDLx::Text — it's an SDL extension for manipulating text, and yes it's as iconic as it sounds 💅

🦋 CATEGORY 🦋

Extension. that's it, that's the category 🫶

🌸 SYNOPSIS 🌸

use SDL;
use SDLx::App;
use SDLx::Text;

my $app = SDLx::App->new;

my $message = SDLx::Text->new;

$message->write_to( $app, "Hello, World!" );
$app->update;

like, that's literally the whole thing. five lines and you're rendering text. slay ✨

💜 DESCRIPTION 💜

so the standard SDL API for handling fonts and rendering text is full of quirks and low-level functions just scattered all over the place — it's giving messy. this module is a sugar layer meant to let you easily handle text in your SDL apps. no cap, that's the whole pitch 🍓

---

🧚 CONSTRUCTION 🧚

new

new ( %attributes )

Instantiates a new SDLx::Text object. every single attribute is optional, which is so nice of it:

my $text = SDLx::Text->new(
        font    => '/path/to/my/font.ttf',
        color   => [255, 255, 255], # "white"
        size    => 24,
        x       => 0,
        y       => 0,
        h_align => 'left',
        shadow  => 1,
        bold    => 1,
        text    => 'All your base are belong to us.'
);

please check the accessors below for more info on each attribute 💖 all the values shown above are the default values — except text, which defaults to undef, and font, which if you don't provide one will load the Gentium Basic free font (see "COPYRIGHT & LICENSE" for more on that, iykyk).

🔥 ACCESSORS 🔥

All the accessors below can be used to get and set their respective attributes. for example:

my $font_size = $obj->size;   # gets the font size
$obj->size( 42 );             # sets a new font size

unless otherwise noticed, all accessors return their current value after being set. standard behavior, still cute 🎀

x

Gets/sets the left (x) positioning of the text to be rendered, relative to whatever surface you're placing it into. ⚠️ heads up though: if you set the h_align property to anything other than "left", the text might not start exactly where you set x to be — it'll be relative to that value instead.

Default value is 0, meaning the leftmost corner 👑

y

Gets/sets the top (y) positioning of the text to be rendered, relative to whatever surface you're placing it into.

Default value is 0, meaning top. yes, the top top 💅

h_align

Gets/sets the horizontal alignment of the text to be rendered, relative to whatever surface you're placing it into. available alignments are "left", "right" and "center". default is "left".

color

Gets/sets the text color. the color is an array reference in [R, G, B] or [R, G, B, A] format. see SDL::Color for more info on colors 🌈

size

Gets/sets the font size. that's it. simple, we love her 💜

font

Pass it a string containing the path to your desired font to use it. fonts can be in TTF, OTF or FON formats. generates an exception if the font cannot be loaded — so yeah, that's a whole thing 😭

Returns the SDL::TTF::Font object representing the font.

shadow

Set this to true to create a nice 3D shadow effect on the rendered text. how does it do it? by creating another version of the text below the original one, at a given offset. it's giving main character with a dramatic backlight ✨

shadow_color

Set the RGB color array for the shadow. defaults to black ([0,0,0]).

shadow_offset

Sets the offset in which to display the shadow. defaults to 1, meaning 1 pixel below and 1 pixel to the right of the original text.

🎀 Setting the Font Style 🎀

The following accessors can be used to set a rendering file for the loaded font. they will only work for the current font — so if you change fonts, make sure to re-apply your modifiers again, okay? a single font can have more than one modifier applied to it, eg:

my $text = SDLx::Text->new;

$text->bold(1);
$text->italic(1);

Set them to a true value to enable, false to disable. easy 🫶

normal

Sets the font style to normal.

bold

Sets the font style to bold.

italic

Sets the font style to italic.

underline

Sets the font style to underline.

Note: due to libSDL design and depending on the chosen font, sometimes the underline may be outside of the generated text surface, and thus not visible when blitted to the screen 😭 in these cases, you should probably turn off the option and draw your own underlines in the target surface.

strikethrough

Sets the font style to strikethrough.

Note: due to libSDL design and depending on the chosen font, sometimes the strikethrough may be outside of the generated text surface, and thus not visible when blitted to the screen 💀 in these cases, you should probably turn off the option and draw your own strikethroughs in the target surface.

---

🌟 METHODS 🌟

text( $some_text )

Sets the text to be displayed by the SDLx::Text object. if you call it without any arguments, you'll get the current text string back:

my $string = $obj->text();

Otherwise, text() will return the SDLx::Text object itself, so you can easily chain this method around like the icon you are:

my $obj = SDLx::Text->new->text( "Hello, Dave." );

note that this will happen even if it's an empty string, or undef. you pass an argument, you get an object. that's the rule, periodt 💅

Text will always be rendered as utf8, so you can pass any string containing regular ASCII or valid utf8 characters. international slay 🌍✨

write_to( $target_surface )

write_to( $target_surface, "text to write" )

Renders the text onto $target_surface (usually the app itself). the text string may be passed as a parameter — otherwise it'll use whatever is already set (via the new() or text() methods).

write_xy( $target_surface, $x, $y )

write_xy( $target_surface, $x, $y, $text )

Same as write_to(), but will render the text using the given top (y) and left (x) coordinates. coordinates? handed to you. no cap 🫶

👑 READ-ONLY ATTRIBUTES 👑

As you set or update your text, font or size, SDLx::Text updates the surface that represents it. you don't usually need to worry about this at all, and we strongly recommend you use the "METHODS" above to render your text.

If however you need to know how tall or wide the rendered text will be (in pixels), or if you want to retrieve the surface so you can manipulate and render it yourself, you can use the following getters:

surface

Returns the underlying surface representing the text itself. you probably don't need this, unless you're doing something really funky 🕺

w

Shortcut to see the width of the underlying surface representing the text.

h

Shortcut to see the height of the underlying surface representing the text.

font_filename

Returns the file name for the loaded font. use font() to get the font object itself, or to set a new font.

---

💀 ERRORS AND DIAGNOSTICS 💀

• "SDL_ttf support has not been compiled" — in order to render text in SDL you must have enabled SDL_ttf while building Alien::SDL. build-time problem, not you, bestie 🫶
• "Cannot init TTF: <some error>" — in order to load fonts and render text, we need to initialize SDL::TTF, that is, in case it hasn't been initialized already. the error above will appear in the rare event of any problem during initialization.
• "Error opening font: <some error>" — the font file you set either via font( 'font.ttf' ) or during construction could not be loaded. the file may not exist in the given path, have wrong permissions, be corrupted, or be of an unsupported format 😭 please refer to the "<some error>" message in the message itself for further information.
• "TTF rendering error: <some error>" — when you call text(), it renders the provided string onto an internal SDL::Surface object. if there was any problem rendering the text, this message will appear.

🦋 BUGS 🦋

Please report any bugs or feature requests to the bug tracker. we will be notified, and then you'll automatically be notified of progress on your bug as we make changes. teamwork, fr fr 💖

🌸 SUPPORT 🌸

You can find documentation for this module with the perldoc command.

perldoc SDLx::Text

⭐ AUTHORS ⭐

See "AUTHORS" in SDL. (yes, that's the whole section. king behavior 👑)

🎀 COPYRIGHT & LICENSE 🎀

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

This module ships with a default font, Gentium Basic, Copyright 2003-2008 SIL International (http://sil.org), released under the SIL Open Font License 1.1 (OFL). the font is available for use in free and commercial products, with some minor restrictions. please read the OFL.txt and OFL-FAQ.txt for further information. ✨

🌈 SEE ALSO 🌈

SDL, SDLx::App, SDL::TTF — go read those too, bestie, they're all part of the family 🫶

---

and that's the whole page!! 💖 brought to you by perl v5.42.3, dated 2026-08-19, archived forever under pods::SDLx::Text(3pm) — go render something iconic, ily, bye 🎀✨