DMXGetWindowAttributes(3)

💖 DMXGetWindowAttributes — the libdmx one, section 3 💖

okay bestie, sit down, we're doing Xdmx internals today and honestly? it's giving detective work. this is DMXGetWindowAttributes, a function from the libdmx library (that's the Library Functions Manual, section 3, iykyk).

---

✨ NAME ✨

DMXGetWindowAttributes — figure out what the back-end windows are actually doing, attribute-wise 🫶

---

🌸 SYNOPSIS 🌸

#include <X11/extensions/dmxext.h>

Bool DMXGetWindowAttributes(Display *dpy,
                            Window window,
                            int *screen_count,
                            int available_count,
                            DMXWindowAttributes *attr);

---

🦋 DESCRIPTION 🦋

so when you call DMXGetWindowAttributes(), the window arg is the window ID of a window that lives on the Xdmx(1) server, and available_count is how long your attr array is. like, how much room you're giving it. be generous, okay?

the number of screens that actually have info for you comes back in screen_count, and the actual info about those screens lands in attr. and here's the vibe:

• if screen_count is less than available_count, you get info for all of the screens. slay.
• otherwise, you get info for the first available_count screens. that's it. that's the deal.

the DMXWindowAttributes structure is literally this, no cap:

typedef struct {
    int          screen;
    Window       window;
    XRectangle   pos, vis;
} DMXWindowAttributes;

so for every back-end X server that's displaying a chunk of window, this struct holds:

• the physical screen containing that chunk,
• the window ID on the back-end X server of the window containing that chunk,
• the position and dimensions of the window on the back-end — that's pos, and it's in screen coordinates,
• the visible area of the window on the back-end — that's vis, and it's in window-relative coordinates. heads up: it's all zeros if the window isn't visible on that backend. 🙈

want more tea about the physical screen? go call DMXGetScreenAttributes(3). it's right there.

note the chaos: DMX lets multiple back-end windows overlap in their view of the DMX logical window. and a logical window doesn't even have to be fully covered by back-end windows — there can be literal gaps. it's not a perfect puzzle piece situation.

🎀 the iconic example 🎀

picture this: a 500x500 window that spans the top two 1024x768 back-end displays (A and B) of a 2048x1536 DMX display, which is composed of 4 1024x768 back-end displays arranged in a cube:

A B
C D

in that case, the DMXGetWindowAttributes call would hand you back this for the 500x500 window:

display A: 500x500 window at 1024-250,0 (relative to back end)
           with 250x500 visible at 0,0 (relative to window origin)

display B: 500x500 window at -250,0 (relative to back end)
           with 250x500 visible at 250,0 (relative to window origin)

display C: 500x500 window at 1024-250,-768 with 0x0 visible at 0,0

display D: 500x500 window at -250,-768 with 0x0 visible at 0,0

C and D are just sitting there with 0x0 visible, and honestly? relatable. not their moment. 💀

---

💅 RETURN VALUE 💅

DMXGetWindowAttributes() returns True unless there's a protocol error. that's it, main character behaviour.

it can also generate BadWindow and BadAlloc errors, so like... watch out. 👑

---

🌈 NOTES 🌈

because this call transports a great deal of information over the wire (it's a lot, it's a whole vibe, it's a data girlie), please call DMXGetScreenCount(3) first, and make sure attr is big enough. do not skip this. fr fr.

also — and this is the sneaky one — on a particular back-end server, it's possible that the associated window hasn't been mapped yet, because the XMapWindow(3) call that will eventually map it had been buffered by Xlib's normal buffering system. 😭 classic race condition behaviour.

to avoid this race condition, please call DMXSync(3) before communicating directly with the back-end X server. this is not optional if you like things working.

---

⭐ SEE ALSO ⭐

• DMXGetScreenCount(3)
• DMXSync(3)
• DMXGetScreenAttributes(3)
• DMX(3)
• Xdmx(1)

---

and that's the whole page, bestie 🎀 this was X Version 11, libdmx 1.1.5, and the date on this one is DMXGetWindowAttributes(3). go forth and query those window attributes, you absolute icon 💖✨🦋