xcb_poly_line(3)

💅 xcb_poly_line — draw lines

okay bestie, welcome to xcb_poly_line(3), a page from the XCB Requests corner of the libxcb universe. it draws lines. that's the whole vibe. but the way it draws them?? lowkey iconic. let's get into it 🎀

---

✨ NAME ✨

xcb_poly_line — draw lines

---

🌸 SYNOPSIS 🌸

first things first, you gotta pull in the header:

#include <xcb/xproto.h>

🦋 Request function

xcb_void_cookie_t xcb_poly_line(xcb_connection_t *conn,
       uint8_t coordinate_mode, xcb_drawable_t drawable,
       xcb_gcontext_t gc, uint32_t points_len, const
       xcb_point_t *points);

that's the whole signature, no cap. ✨

---

💖 REQUEST ARGUMENTS 💖

here's what you're feeding her, one by one:

• conn — The XCB connection to X11. your lil hotline to the server, fr.
• coordinate_mode — One of the following values:
  • XCB_COORD_MODE_ORIGIN — Treats all coordinates as relative to the origin. every point is measured from the same starting spot, main character energy for the origin.
  • XCB_COORD_MODE_PREVIOUS — Treats all coordinates after the first as relative to the previous coordinate. so each point is like "i'm this far from the last one" 🫶
• drawable — The drawable to draw the line(s) on. this is the canvas, the stage, the moment.
• gc — The graphics context to use. your whole aesthetic config, pens and colors and all.
• points_len — The number of xcb_point_t structures in points.
• points — An array of points. literally just a lil lineup of coordinates, standing there, waiting to be connected 💅

---

🎀 DESCRIPTION 🎀

so what does it actually do. okay so:

Draws points_len-1 lines between each pair of points (point[i], point[i+1]) in the points array. The lines are drawn in the order listed in the array. They join correctly at all intermediate points, and if the first and last points coincide, the first and last lines also join correctly.

no gaps, no awkward corners, everything connects like it was always meant to be. ✨

For any given line, a pixel is not drawn more than once. If thin (zero line-width) lines intersect, the intersecting pixels are drawn multiple times. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire request were a single, filled shape.

so basically: thin lines that cross over each other re-draw the overlap (they're each doing their own thing, independent girlies), but wide lines get treated like one single filled shape, so the overlap only gets painted once. no double-dipping. periodt.

---

⭐ 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_poly_line_checked. See xcb-requests(3) for details.

so like, you got a cookie 🍪 and you gotta check on it later. that's just how the event loop works bestie.

---

😭 ERRORS 😭

here's the roster of things that can go wrong, and yes, the docs are still a WIP:

• xcb_drawable_error_t — TODO: reasons?
• xcb_g_context_error_t — TODO: reasons?
• xcb_match_error_t — TODO: reasons?
• xcb_value_error_t — TODO: reasons?

(they literally left the reasons as TODO in the source, we're not making anything up here 💀)

---

🌈 EXAMPLE 🌈

okay here's a whole actual example, verbatim, go off:

/*
 * Draw a straight line.
 *
 */
void my_example(xcb_connection_t *conn, xcb_drawable_t drawable, xcb_gcontext_t gc) {
    xcb_poly_line(conn, XCB_COORD_MODE_ORIGIN, drawable, gc, 2,
                  (xcb_point_t[]) { {10, 10}, {100, 10} });
    xcb_flush(conn);
}

two points, one horizontal line, one xcb_flush(conn) to actually make it show up. ate. 💅

---

💜 SEE ALSO 💜

go read these next, i'm obsessed:

• xcb-requests(3)
• xcb-examples(3)

---

🧚 AUTHOR 🧚

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

---

and that's the page!! this beauty ships with X Version 11 as part of libxcb 1.17.0, and yeah, it really is called xcb_poly_line(3) — iykyk 🦋✨ stay slay, draw responsibly, and may all your pixels land exactly where you meant them to 💖🎀