Imager...::BBox(3pm)

💖 NAME 💖

Okay bestie, so Imager::Font::BBox — it's the object class that hands you back a whole little vibe check of info about a string of text, aka its bounding box. That's the name, that's the manual (it lives in the Perl User Contributed Documentation corner of the world, section 3pm, iykyk). ✨

---

🌸 SYNOPSIS 🌸

Here's the whole flow, literally copy-paste blessed:

use Imager::Font;

# get the object
my $font = Imager::Font->new(...);
my $bbox = $font->bounding_box(string=>$text, size=>$size);

# methods
my $start = $bbox->start_offset;
my $left_bearing = $bbox->left_bearing;
my $right_bearing = $bbox->right_bearing;
my $end = $bbox->end_offset;
my $gdescent = $box->global_descent;
my $gascent = $bbox->global_ascent;
my $ascent = $bbox->ascent;
my $decent = $bbox->descent;
my $total_width = $bbox->total_width;
my $fheight = $bbox->font_height;
my $theight = $bbox->text_height;
my $display_width = $bbox->display_width;

(And yes, $box vs $bbox — that's in the original, don't come for me 😭 it's a vibe, not a typo I invented.)

---

🦋 DESCRIPTION 🦋

So here's the tea: objects of this class are what you get returned to you by the Imager::Font bounding_box() method when you call it in scalar context. 👑

The whole point? Making all that info from the method way more accessible. Which, honestly, slay. 🫶

---

🎀 METHODS 🎀

start_offset(), neg_width, left_bearing

Returns the horizontal offset from the drawing location you picked to the left edge of the very first character drawn. If this number's positive, your first glyph is sitting to the right of the drawing location. ✨

• The alias neg_width() exists to match the bounding_box() documentation for list context.
• The alias left_bearing() exists to match font terminology.

Both aliases = same energy, different label. 💅

advance_width()

The advance width of the string — if the driver supports that. If it doesn't, it's just the same as end_offset. No cap.

right_bearing

The distance from the right side of the last glyph to the end of the advance point. 🎯

Heads up bestie: if the glyph overflows the right side of the advance width, this value goes negative.

display_width

The distance from the left-most pixel of the left-most glyph all the way to the right-most pixel of the right-most glyph. 📏

Equals advance_width - left_bearing - right_bearing — and it's literally implemented that way, they said so.

global_descent()

The lowest position (relative to the font baseline) that any character in the font reaches in the character cell. Normally negative. 📉

Not me finding out at least one font out there has reported a positive number for this. 🙈 Weird but true.

global_ascent()

The highest position (relative to the font baseline) that any character in the font reaches in the character cell. Normally positive. 📈

descent()

The lowest position (relative to the font baseline) that any character in the supplied string reaches. Negative whenever any character's glyph dips below the baseline. 🌊

ascent()

The highest position (relative to the font baseline) that any character in the supplied string reaches. Positive if any character's glyph reaches above the baseline. 🦅

font_height()

The maximum displayed height of any string using this font. The ceiling. The limit. 👑

text_height()

The displayed height of the supplied string. Specifically yours. 💖

---

💀 OBSOLETE METHODS 💀

Okay so real talk: these methods include bugs kept for backwards compatibility and genuinely shouldn't be used in new code. Like, don't. 🚫

total_width()

The total displayed width of the string.

New code should use display_width() instead. Periodt.

This one depends on end_offset(), and it's limited by its backward compatibility.

end_offset, pos_width

The offset from the drawing location you picked to the right edge of the last character drawn. Should always be positive. ✨

You can use the alias pos_width() if you're used to the bounding_box() documentation for list context.

For backwards compatibility, this method returns the maximum of the advance width and the offset of the right edge of the last glyph. Yes, really. That's the deal. 🫠

---

⚙️ INTERNAL FUNCTIONS ⚙️

new(...)

Called by Imager::Font->bounding_box() to create the object. That's it, that's the job — internal business, nothing for you here bestie. 🙈

---

🐛 BUGS 🐛

So it doesn't reproduce the functionality you'd get using the x and y parameters to Imager::Font->bounding_box(). 😭 And they genuinely considered this:

my ($left, $top, $right, $bottom) = $box->offset(x=>$x, y=>$y)

...but honestly that's about as clumsy as the original. 💀 So, yeah. Noted, not fixed.

---

👑 AUTHOR 👑

Tony Cook <tony@develop-help.com> — an icon, a legend, the moment. 🌟

---

🌈 SEE ALSO 🌈

• Imager(3)
• Imager::Font(3)

---

That's the whole page, bestie — go forth and measure your glyphs with confidence. 💜

This masterpiece of a manual comes to you as perl v5.42.3, dated 2026-08-19 — write that down, cite it in your group chat, it's giving documentation excellence. 🎀✨