XvCreateImage(3)

💖 XvCreateImage — creating an XvImage, bestie edition 💖

okay so real quick, this page lives in the libXv Functions section of the manual (third section, (3), we love a library call), and it's about making yourself an XvImage. it's giving "let's build a video image struct together" energy and honestly? iconic. 🎀

---

✨ NAME ✨

XvCreateImage, XvShmCreateImage — create an XvImage 💅

---

🌸 SYNOPSIS 🌸

#include <X11/extensions/Xvlib.h>

XvImage * XvCreateImage (Display *dpy, XvPortID port,
                         int id, char *data,
                         int width, int height);

XvImage * XvShmCreateImage (Display *dpy, XvPortID port,
                            int id, char *data,
                            int width, int height,
                            XShmSegmentInfo *shminfo);

---

🦋 ARGUMENTS 🦋

• dpy — the connection to the X server. your whole link-up, basically.
• port — the port this XvImage is gonna be used with.
• id — the format of the image you're creating, given as an XvImageFormatValues id.
• data — the image data. yes, the actual pixels-in-waiting.
• width, height — the width and height you want the image to be. your desired dimensions, no cap.

---

💜 DESCRIPTION 💜

XvCreateImage(3) is like XCreateImage(3)'s little sibling, and XvShmCreateImage(3) is the same deal but matched up with XShmCreateImage(3). fr fr, same vibe, different extension.

so here's the tea: the library allocates the XvImage structure and fills out every single field — except data. every field but that one. 🙈

also heads up, width and height may get enlarged in some YUV formats. so don't come for the library when your numbers come back bigger. the size of the data buffer you actually need to allocate will be handed to you in the data_size field of the XvImage.

and no, image data is NOT allocated by this function. not even a little. so you've got options:

1. pass a pointer to memory you already preallocated as data, or
2. let the server fill out the data_size field first, then allocate the memory and fill in the XvImage structure's data field yourself.

either way, you're the one doing the allocating. main character responsibilities, unfortunately. 👑

when you're done with it, the XvImage structure can be freed with XFree(3). and shared memory segments? those get attached/detached with XShmAttach(3) / XShmDetach(3). keep those paired, bestie, it's a whole thing. 🫶

---

🔥 RETURN VALUES 🔥

XvImage has this structure, and it's exactly this:

typedef struct {
   int id;
   int width, height;
   int data_size;
   int num_planes;
   int *pitches;
   int *offsets;
   char *data;
   XPointer obdata;
} XvImage;

and here's what every field is doing:

• id — a descriptor for the format, from the XvImageFormatValues structure that XvListImageFormats(3) hands back.
• width, height — the width and height of the image in pixels.
• data_size — the size of the data buffer, in bytes.
• num_planes — how many image planes there are.
• pitches — an array of size num_planes showing the scanline pitch in bytes. and bestie, each plane can have a different pitch. they're all individuals. ✨
• offsets — an array of size num_planes showing the byte offset from data to the start of each plane.
• data — a pointer to the start of the data buffer.
• obdata — a private field for holding SHM info. the client libraries set this one up for you, so honestly the programmer generally doesn't need to worry about it at all. it's giving "don't perceive me". 💀

---

⭐ DIAGNOSTICS ⭐

• [XvBadPort] — generated if the port you asked for does not exist. she's not there, bestie.
• [XvBadAlloc] — generated if the X server couldn't allocate the resources it needed to finish the operation. the server is going through it. 😭
• [BadMatch] — generated if you supplied incompatible arguments — like a port that isn't capable of displaying XvImages. wrong port for the job, ngl.

---

🌈 SEE ALSO 🌈

XvListImageFormats(3), XCreateImage(3), XShmCreateImage(3), XShmAttach(3), XShmDetach(3).

the whole friend group, go read them too. 🍓

---

okay and that's the page!! 🧚 this one shipped with X Version 11, from libXv 1.0.13, and it's XvCreateImage(3) if you're trying to find it again — slay, go make some images, you've got this. 💖✨