XvListImageFormats(3)

✨ XvListImageFormats ✨

okay bestie, welcome to XvListImageFormats — a lil function from the libXv crew (that's part of X Version 11, we're fancy here 💅). She's a libXv Function and she's about to spill the whole tea on what image formats a video port can handle. no cap.

---

🌸 NAME 🌸

XvListImageFormats — gimme the list of image formats that a video port supports, bestie 📋✨

---

🎀 SYNTAX 🎀

#include <X11/extensions/Xvlib.h>

XvImageFormatValues * XvListImageFormats (Display *dpy,
                 XvPortID port,  int *p_num_formats);

like, that's the whole incantation. copy it exactly, don't freestyle it 💖

---

🦋 ARGUMENTS 🦋

• dpy — the connection to the X server. your whole vibe link to the server, basically 🔌
• port — the port whose adaptor we're gonna interrogate about its list of attributes. we're asking this one specifically, main character energy 👑
• p_num_formats — a pointer to where the number of formats returned in the array gets written. so she hands you the array, and she writes the count over here so you know how many you got 🧮

---

💖 DESCRIPTION 💖

XvListImageFormats(3) returns the XvImageFormatValues that the specified port supports. that's it, that's the whole job. she ate and left no crumbs 🔥

⚠️ important bestie: this list needs to be freed with XFree(3). she's handing you malloc'd memory, so you gotta let her go. don't just leave her hanging 😭

---

🌈 RETURN VALUES 🌈

XvImageFormatValues has the following structure, and it's literally giving struct realness:

typedef struct {
  int id;                      /* Unique descriptor for the format */
  int type;                    /* XvRGB, XvYUV */
  int byte_order;              /* LSBFirst, MSBFirst */
  char guid[16];               /* Globally Unique IDentifier */
  int bits_per_pixel;
  int format;                  /* XvPacked, XvPlanar */
  int num_planes;

  /* for RGB formats */
  int depth;
  unsigned int red_mask;
  unsigned int green_mask;
  unsigned int blue_mask;

  /* for YUV formats */
  unsigned int y_sample_bits;
  unsigned int u_sample_bits;
  unsigned int v_sample_bits;
  unsigned int horz_y_period;
  unsigned int horz_u_period;
  unsigned int horz_v_period;
  unsigned int vert_y_period;
  unsigned int vert_u_period;
  unsigned int vert_v_period;
  char component_order[32];    /* eg. UYVY */
  int scanline_order;          /* XvTopToBottom, XvBottomToTop */
} XvImageFormatValues;

and now, field by field, because every single one matters 🫶

• id — a unique descriptor for the format. it's often the FOURCC for the format, when that applies. this id is what describes the format when you're doing XvImage creation. it's her government name fr fr 🪪
• type — XvRGB or XvYUV. pick your fighter 🌈
• byte_order — the byte order of the image. either LSBFirst or MSBFirst. which way do the bytes go, bestie? 🤔
• guid — the Globally Unique IDentifier (aka the Universally Unique IDentifier, same thing, different wig). when it's not applicable, all the characters are NULL. so like, empty. nothing. void. 💀
• bits_per_pixel — the bits taken up (but not necessarily used) by each pixel. and heads up: for some planar formats with fractional bits per pixel (like IF09) this number may be rounded _down_. rounded down!! keep that in your notes 📝
• format — XvPacked or XvPlanar ✨
• num_planes — the number of planes in planar formats. planes on planes on planes ✈️
• depth — significant bits per pixel 🧠
• red_mask, green_mask, blue_mask — the red, green and blue bitmasks. RGB formats only, so if you're on YUV this part is not for you 🚫
• ?_sample_bits — the size of each sample in bits. YUV formats only 💜
• horz_?_period, vert_?_period — the period (in pixels) on which samples occur in the horizontal and vertical directions. YUV formats only 📐
• component_order — upper case ascii characters representing the order that samples are stored within packed formats. for planar formats, this represents the ordering of the planes. so like, UYVY vibes 🔤
• scanline_order — XvTopToBottom or XvBottomToTop. which way do we scroll? ⬆️⬇️

---

⭐ NOTES ⭐

since some formats (particularly some planar YUV formats) may not be completely defined by the parameters above, the guid — when it's available — should give you the most accurate description of the format. so when in doubt, trust the guid, she knows 💅

---

🚨 DIAGNOSTICS 🚨

• [XvBadPort] — generated if the requested port does not exist. you asked for a port that isn't real, bestie, and the server said no 🙈

---

👀 SEE ALSO 👀

• XvCreateImage(3)
• XvCreateShmImage(3)

go read those next, iykyk 📚✨

---

k bye ily, that's the whole page 💖 — this was libXv 1.0.13 from X Version 11, dated whenever this got shipped, and you just read XvListImageFormats(3). slay, go free that array with XFree(3) 🎀🦋