XvGetStill(3)

💖 XvGetStill(3) 💖

okay so bestie, welcome to libXv ✨ this one's called XvGetStill, and it's the glow-up moment where you grab one single frame of video off a drawable. literally just one. a lil snapshot. a still. 🎀

---

🌸 NAME 🌸

XvGetStill — capture a single frame of video from a drawable 🫶

---

✨ SYNOPSIS ✨

#include <X11/extensions/Xvlib.h>

int XvGetStill(Display *dpy, XvPortID port, Drawable d, GC gc,
               int vx, int vy, unsigned int vw, unsigned int vh,
               int dx, int dy, unsigned int dw, unsigned int dh);

---

🦋 ARGUMENTS 🦋

no cap, every single one of these matters, so let's go one by one 💅

• dpy — the connection to the X server. your lil phone line to the server, basically.
• port — the port that the still gets output to. that's where the magic lands.
• d — the drawable the still is captured from. heads up though: pixmaps are currently not supported, so don't even try it 😭
• gc — the graphical context. the GC components in play are: subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. that's the whole list, no extras.
• vx, vy, vw, vh — these define the location and size of the destination video region, aka where the still gets written into. vx and vy are the x and y coords of the upper-left corner of the video region; vw and vh are the width and height, in pixels, of the video region.
• dx, dy, dw, dh — these define the location and size of the source drawable, aka where the still image is captured from. dx and dy are the x and y coords of the upper-left corner of the drawable region; dw and dh are the width and height, in pixels, of the drawable region.

---

👑 DESCRIPTION 👑

so what does it actually do? it captures a single frame of video from a drawable. that's the whole vibe. 📸

the position and size of the destination (video) rectangle is specified by vx, vy, vw, and vh. the position and size of the source (drawable) rectangle is specified by dx, dy, dw, and dh. two rectangles, one still, slay.

drawable data gets clipped to the bounds of the drawable, then scaled to the requested video region size (or the closest size supported — sometimes it just does its best, okay?), and then clipped to the bounds of the video encoding. and here's the part you need to know: the contents of any region not updated with drawable data is undefined. undefined behaviour is not the vibe, so be aware. 💀

also, if the port is grabbed by another client, this request is ignored, and an XvVideoNotify event with detail XvBusy is generated for the drawable. so like, if someone else is holding the aux cord, you're not getting it. 🙈

---

🌈 RETURN VALUES 🌈

• [Success] — returned if XvGetStill(3) completed successfully. we love a happy ending ✨
• [XvBadExtension] — returned if the Xv extension is unavailable. no extension, no party 😭
• [XvBadAlloc] — returned if XvGetStill(3) failed to allocate memory to process the request.

---

💜 DIAGNOSTICS 💜

• [XvBadPort] — generated if the requested port does not exist.
• [BadDrawable] — generated if the requested drawable does not exist.
• [BadGC] — generated if the requested graphics context does not exist.
• [BadAlloc] — generated if there were insufficient resources to process the request.

---

🧚 SEE ALSO 🧚

XvPutStill(3), XvGetVideo(3), XvPutVideo(3), XvVideoNotify(3)

go read those too, they're all part of the same friend group fr fr 🫶

---

and that's the whole page, bestie 💖 this was X Version 11, libXv 1.0.13, page XvGetStill(3) — periodt. now go capture that frame, you absolute main character 👑✨