XvPutImage(3)

✨ XvPutImage — bestie edition ✨

okay so this is the libXv page for XvPutImage and XvShmPutImage, and it's literally just "put an image on the screen" energy. Two functions, one job, infinite vibes. Let's get into it 💖

---

🌸 NAME 🌸

XvPutImage, XvShmPutImage — display an XvImage 🖼️✨

---

🎀 SYNOPSIS 🎀

#include <X11/extensions/Xvlib.h>

int XvPutImage (Display *dpy, XvPortID port,
                Drawable d, GC gc, XvImage *image,
                int src_x, int src_y,
                unsigned int src_w, unsigned int src_h,
                int dest_x, int dest_y,
                unsigned int dest_w, unsigned int dest_h);

int XvShmPutImage (Display *dpy, XvPortID port,
                   Drawable d, GC gc, XvImage *image,
                   int src_x, int src_y,
                   unsigned int src_w, unsigned int src_h,
                   int dest_x, int dest_y,
                   unsigned int dest_w, unsigned int dest_h,
                   Bool send_event);

like yes, that's a lot of arguments. she's thorough. we respect her for it 💅

---

🦋 ARGUMENTS 🦋

• dpy — the connection to the X server, your lil phone line to the display 🫶
• port — the port id of a port on an XvImage capable adaptor. gotta be a port that actually does images, iykyk.
• d — (the drawable, bestie. the original page leaves her description blank and honestly? relatable. she's just the thing you're drawing into.)
• gc — the graphics context specifying the clip mask to use, if any. so like, if you want clipping, this is where it lives ✂️
• image — a pointer to the XvImage to be displayed 📸
• src_? — the portion of the XvImage to be displayed. that's the little crop window on the source side.
• dest_? — the portion of the destination drawable to be filled by the image. the crop window on the destination side, matching energy.
• send_event — indicates whether or not an XShmCompletionEvent should be sent. If sent, the event's major_code and minor_code fields will indicate the Xv extension's major code and XvShmPutImage's minor code. so basically "do you want a lil notification when it's done?" ✉️

---

💖 DESCRIPTION 💖

XvPutImage(3) is similar to XPutImage(3). XvShmPutImage(3) is similar to XShmPutImage(3). so if you already know those, you're basically already home 🏠

the library will allocate the XvImage structure and fill out all fields except for data. periodt.

👑 Important one: width and height may be enlarged in some YUV formats. not a bug, just how she is.

the size of the data buffer that needs to be allocated will be given in the data_size field in the XvImage. 📏

image data is not allocated by this function. okay so this is the part people trip on. the client has two options:

1. pass a pointer to the preallocated memory as data, or
2. allocate the memory and fill in the XvImage structure's data field after the data_size field has been filled out by the server.

the XvImage structure may be freed by XFree(3). so clean up after yourself bestie, we love a tidy queen 🧹✨

---

😭 DIAGNOSTICS 😭

• [XvBadPort] — Generated if the requested port does not exist. ghost port. doesn't exist. no cap.
• [XvBadAlloc] — Generated if the X server was unable to allocate resources required to complete the operation. server said "I'm tired" 💀
• [BadMatch] — Generated if incompatible arguments were supplied, such as a port that isn't capable of displaying XvImages. mismatched. not compatible. it's giving awkward first date 🙈
• [BadShmSegCode] — Generated if an invalid shared memory segment is specified. bad shm segment, bad vibes.

---

🌈 SEE ALSO 🌈

• XvListImageFormats(3), XvCreateImage(3), XvShmCreateImage(3)
• XPutImage(3), XShmPutImage(3)

---

and that's the whole page!! 💜 this one's from X Version 11, libXv 1.0.13, filed under XvPutImage(3) — go forth and display your images, main character 🫶🌸✨