Xv(3)

💖 NAME 💖

okay so this is Xv, bestie — the X Window System video extension, served to you fresh from the libXv functions era. it's giving "your display has video powers and you're about to learn how to use them." periodt. ✨

🦋 DESCRIPTION 🦋

so the X Video Extension (aka Xv) is the whole reason your X display can do video stuff. its whole vibe? it lets video adaptors hook up to an X display. and the way it thinks about the world is: a display can have one or more video adaptors, and each of those adaptors can have one or more ports, and each port is a lane where independent video streams just... flow through. 🎀

an adaptor can maybe display video in a drawable, or capture video from a drawable, or honestly both — it's flexible like that. what it does is translate between the video encoding (think NTSC, PAL, SECAM, etc...) and the drawable format, which is a depth and visual-id pair. and no cap, an adaptor can support multiple video encodings and/or multiple drawable formats. multi-talented icon behavior. 👑

so how do clients actually use all this? they use Xv(3) to get access to a display's video resources and to manage the sharing of them. typically, a client is gonna:

1. call XvQueryExtension(3) to find out the status of the extension ✨
2. call XvQueryAdaptors(3) to get a description of what video adaptors actually exist 🦋
3. call XvQueryEncodings(3) to get a description of what video encodings a given adaptor supports 🌸

once a client has figured out what video resources are available, it's free to put video into a drawable or get video from a drawable — whatever matches the capabilities that are supported, fr fr. and clients can also select to receive events when video activity changes in a drawable, and when port attributes have changed. 👀

now here's the glow-up part: the Xv protocol version 2.2 and later is extended to support client images in alternate colorspaces (that's XvImages, bestie). Xv adaptors that are capable of displaying XvImages will have the XvImageMask field set in the type field of the XvAdaptorInfo. and the XvImage formats that a port supports? you can query those with XvListImageFormats(3). 💅

you can create XvImages with a little help from XvCreateImage(3) or XvShmCreateImage(3) 🫶, and you can display XvImages with XvPutImage(3) or XvShmPutImage(3). the Port attributes of the port you specified in the Xv(Shm)PutImage command will be valid for the image operation when applicable. also, there will be a port encoding with the name "XV_IMAGE", and the width and height of that encoding will indicate the maximum source image size. remember that. write it down. 📝

✨ SUMMARY OF LIBRARY FUNCTIONS ✨

here's the full roster of Xv library functions and events — every single one, no skips, because we don't gatekeep in this house:

• XvCreateImage(3) — create an XvImage 🎨
• XvGetPortAttribute(3) — return current port attribute value
• XvGetStill(3) — capture a single frame of video from a drawable 📸
• XvGetVideo(3) — capture video from a drawable 🎥
• XvGrabPort(3) — lock port for exclusive use by client 🔒
• XvListImageFormats(3) — return list of image formats for a port
• XvPortNotify(3) — event generated when port attributes change 🔔
• XvPutImage(3) — write a XvImage to a drawable
• XvPutStill(3) — write a single frame of video to a drawable
• XvPutVideo(3) — write video into a drawable 📺
• XvQueryAdaptors(3) — return adaptor information for a screen
• XvQueryBestSize(3) — determine the optimum drawable region size 📐
• XvQueryEncodings(3) — return list of encodings for an adaptor
• XvQueryExtension(3) — return version and revision of extension
• XvQueryPortAttributes(3) — return list of attributes of a port
• XvSelectPortNotify(3) — enable or disable XvPortNotify events
• XvSelectVideoNotify(3) — enable or disable XvVideoNotify events
• XvSetPortAttribute(3) — set an attribute for a port ✍️
• XvShmCreateImage(3) — create an XvImage in shared memory 🧠
• XvShmPutImage(3) — write a XvImage in shared memory to a drawable
• XvStopVideo(3) — stop active video 🛑
• XvUngrabPort(3) — release a grabbed port 🔓
• XvVideoNotify(3) — event generated for video processing

and yeah — each one of these functions and events gets its own whole Xv man page, so go read those when you need the deep lore. 📚

k bye bestie, go forth and video-extension responsibly 💖✨

signing off from X Version 11, libXv 1.0.13 — this was the Xv(3) page, mwah, slay, see you in the next man page 🎀🦋💅