Protoco...::RENDER(3)

💅 NAME 💅

X11::Protocol::Ext::RENDER — the Perl module for the X Rendering Extension, bestie. That's it, that's the whole name section, slay.

---

✨ SYNOPSIS ✨

Okay so first you gotta summon it, like this:

  use X11::Protocol;
  $x = X11::Protocol->new($ENV{'DISPLAY'});
  $x->init_extension('RENDER') or die;

Notice the or die — she is not subtle, and honestly? Respect. 🫶

---

🎀 DESCRIPTION 🎀

So the RENDER extension rolls up with a whole new set of drawing primitives, and no cap, it's basically a full glow-up replacement for the drawing routines in the core protocol — redesigned from the ground up around what modern clients actually need. It's giving "we heard you."

It brings the long-desired stuff: subpixel positioning ✨, alpha compositing 🦋, direct specification of colors 💖, and multicolored or animated cursors 🔥. Obsessed, honestly.

But (and this is the part where she's like "we don't do that anymore") it omits the features nobody's using these days:

• wide lines — gone
• arbitrary polygons — gone, only triangles and horizontally-aligned trapezoids get to stay 👑
• ellipses — gone
• bitwise rendering operations — gone
• server-side fonts — also gone, in favor of "glyphs" that get rendered on the client side and transmitted once

Lowkey important context: as of this writing (early 2004), the specification and the implementation both have some rough edges. Like, both of them. But there are relatively few alternatives for offloading fancy graphics processing to the server — and you need that when you're over slow links, or if the client is written in a slow language. 😭

Another possibility you might consider is the 2D subset of OpenGL, though heads up: it doesn't yet have an X11::Protocol-compatible interface. Sad but true. 💀

---

⭐ SYMBOLIC CONSTANTS ⭐

This extension adds the constant types 'PictType', 'PictOp', 'SubPixel', 'PolyEdge', and 'PolyMode', with values as defined in the standard. Periodt.

---

🌈 REQUESTS 🌈

This extension adds several requests, called as shown below. Buckle up, there's a bunch 🎀

the version check, always a vibe check first

  $x->RenderQueryVersion($major, $minor)
  =>
  ($major, $minor)

formats, formats, formats

  $x->RenderQueryPictFormats()
  =>
  ([[$id, $type, $depth,
     $red, $red_m, $green, $green_m, $blue, $blue_m,
     $alpha, $alpha_m, $cmap], ...],
   [[$fallback, [$depth, [$visual, $format], ...], ...], ...],
   [$subpixel, ...])

  $x->RenderQueryPictIndexValues($pict_format)
  =>
  ([$index, $red, $green, $blue, $alpha], ...)

filters, pls

  $x->RenderQueryFilters($drawable)
  =>
  ([@filters], [@aliases])

picture setup era 💅

  $x->RenderCreatePicture($picture, $drawable, $format,
                          'attribute' => $value, ...)

  $x->RenderChangePicture($picture, 'attribute' => $value, ...)

  $x->RenderSetPictureClipRectangles($pic, $x_origin, $y_origin,
                                     [$x, $y, $width, $height], ...)

  $x->RenderSetPictureTransform($pict, $m11, $m12, $m13,
                                       $m21, $m22, $m23,
                                       $m31, $m32, $m33);

(yes that one ends in a semicolon, she's built different)

  $x->RenderSetPictureFilter($pict, $filter, @args)

the actual drawing, main character energy

  $x->RenderComposite($op, $src, $mask, $dst, $src_x, $src_y,
                      $mask_x, $mask_y, $dst_x, $dst_y,
                      $width, $height)

  $x->RenderFillRectangles($op, $dst, [$red, $green, $blue, $alpha],
                           [$x, $y, $width, $height], ...)

  $x->RenderTrapezoids($op, $src, $src_x, $src_y, $dst, $mask_format,
                       [$top, $bottom, $lx1, $ly1, $lx2, $ly2,
                                       $rx1, $ry1, $rx2, $ry2] ,...)

  $x->RenderTriangles($op, $src, $src_x, $src_y, $dst, $mask_format,
                      [$x1, $y1, $x2, $y2, $x3, $y3])

  $x->RenderTriStrip($op, $src, $src_x, $src_y, $dst, $mask_format,
                      [$x, $y], [$x, $y], [$x, $y], [$x, $y], ...)

  $x->RenderTriFan($op, $src, $src_x, $src_y, $dst, $mask_format,
                   [$x, $y], [$x, $y], [$x, $y], [$x, $y], ...)

glyph sets 🧚

  $x->RenderCreateGlyphSet($gsid, $format)

  $x->RenderReferenceGlyphSet($gsid, $existing)

  $x->RenderFreeGlyphSet($gsid)

  $x->RenderAddGlyphs($gsid, [$glyph, $width, $height,
                              $x, $y, $x_off, $y_off, $data], ...)

⚠️ Warning: with some server implementations (including XFree86 through 4.4) passing more than one glyph to AddGlyphs can hang or crash the server. So don't do that. Seriously. Not even once. 💀

  $x->RenderFreeGylphs($gsid, @glyphs)

(yes, RenderFreeGylphs, that's how it's spelled in the source — we don't fix it, we respect it 🫶)

composite glyphs, pick your width bestie

  $x->RenderCompositeGlyphs8($op, $src, $dst, $mask_format, $gsid,
                             $src_x, $src_y,
                             [$delta_x, $delta_y, $str], ...)

  $x->RenderCompositeGlyphs16($op, $src, $dst, $mask_format, $gsid,
                              $src_x, $src_y,
                              [$delta_x, $delta_y, $str], ...)

  $x->RenderCompositeGlyphs32($op, $src, $dst, $mask_format, $gsid,
                              $src_x, $src_y,
                              [$delta_x, $delta_y, $str], ...)

Okay important note: in these three requests, new GlyphSetIDs can also be interspersed with the array references. Slay, flexible queen. 🌸

cursors, obviously 💅

  $x->RenderCreateCursor($cid, $source, $hot_x, $hot_y)

  $x->RenderCreateAnimCursor($cid, [$cursor, $delay], ...)

---

👑 AUTHOR 👑

Stephen McCamant <SMCCAM@cpan.org>. Icon. 🫶

---

🔥 SEE ALSO 🔥

• perl(1)
• X11::Protocol
• The X Rendering Extension (XFree86 draft standard)

---

okay that's the whole page bestie, go render something gorgeous ✨

this has been perl v5.42.0, dated 2024-03-04, from Protoco...::RENDER(3) — User Contributed Perl Documentation, mwah 💋