xcb_image_text_16(3)

📦
version 1.17.0 · 4 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, debian trixie, fedora 43, fedora 44, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 xcb_image_text_16 — the "draw text but make it 16-bit" request 💖

okay bestie, pull up a chair, we're reading xcb_image_text_16(3) from the XCB Requests section of the manual and honestly? it's giving "niche but iconic." this is a <pink>libxcb</pink> page, so it lives in the libxcb part of the world, and it's all about asking the X server to paint some text for you. no cap. let's go 🦋

✨ NAME ✨

xcb_image_text_16 — Draws text 💅

🌸 SYNOPSIS 🌸

first things first, you gotta include the header, or nothing happens, periodt:

#include <xcb/xproto.h>

🎀 Request function

here's the whole function signature, copy it exactly bestie, no typos:

xcb_void_cookie_t xcb_image_text_16(xcb_connection_t *conn,
       uint8_t string_len, xcb_drawable_t drawable, xcb_gcontext_t gc,
       int16_t x, int16_t y, const xcb_char2b_t *string);

🔥 REQUEST ARGUMENTS 🔥

so here's every single thing you're handing over, one by one:

  • conn — The XCB connection to X11. it's your lil phone line to the server 📞
  • string_len — The length of the string in characters. ⚠️ and here's the tea: this parameter is limited by 255 because it's using 8 bits! so no, you cannot be extra about it. 255 characters max, that's the vibe check.
  • drawable — The drawable (Window or Pixmap) to draw text on. that's your canvas, your stage, your main character surface ✨
  • gc — The graphics context to use.

The following graphics context components are used: plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. yep, all eight of those. don't forget them, they're all pulling up to the function 💅

  • x — The x coordinate of the first character, relative to the origin of drawable. so where the text starts horizontally, relative to the drawable's corner.
  • y — The y coordinate of the first character, relative to the origin of drawable. same deal but vertical.
  • string — The string to draw. Only the first 255 characters are relevant due to the data type of string_len. Every character uses 2 bytes (hence the 16 in this request's name). 🧚 two whole bytes per character, that's the whole bit.

💜 DESCRIPTION 💜

okay so here's what actually happens when you call this thing:

It fills the destination rectangle with the background pixel from gc, then paints the text with the foreground pixel from gc. The upper-left corner of the filled rectangle is at [x, y - font-ascent]. The width is overall-width, the height is font-ascent + font-descent. The overall-width, font-ascent and font-descent are as returned by xcb_query_text_extents (TODO).

🚨 the whole "TODO" up there is not me being lazy, that's literally what the manual says, so I'm passing it along verbatim, iykyk.

Note that using X core fonts is deprecated (but still supported) in favor of client-side rendering using Xft. so like, it still works, but it's lowkey old news and Xft is the moment now. deprecated but supported, bestie, not deleted. 🙈

⭐ RETURN VALUE ⭐

Returns an xcb_void_cookie_t. Errors (if any) have to be handled in the event loop.

If you want to handle errors directly with xcb_request_check instead, use xcb_image_text_16_checked. See xcb-requests(3) for details.

so basically: default version = errors slide into your event loop later. checked version = you get the tea immediately. pick your fighter 💀

🌈 ERRORS 🌈

here's every way this can go wrong, and the drama is real:

  • xcb_drawable_error_t — The specified drawable (Window or Pixmap) does not exist. 💀 you tried to draw on a ghost. it's not there.
  • xcb_g_context_error_t — The specified graphics context does not exist. also not there. also a problem.
  • xcb_match_error_t — TODO: reasons? 🫠 the manual genuinely just shrugs here. iconic of it honestly.

👑 SEE ALSO 👑

go read these next, bestie, they're the sister pages:

🫶 AUTHOR 🫶

Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.

so like, it wasn't hand-written by one cool person, it was auto-generated from XML, and if you spot something wrong you email the list. do with that what you will 💌

and that's the whole page!! this came to you from X Version 11, libxcb 1.17.0, filed under xcb_image_text_16(3). slay, go draw your little 16-bit characters, just remember the 255 limit and the deprecated-font situation. mwah 💖✨🎀

📦 where this page comes from