Need Help Understanding X11 Window Hierarchy and Drawing Commands

Question

I'm working on building an X11 server for Windows from scratch based on a copy of the "X Protocol Reference Manual: Volume Zero". I've made a lot of progress in deciphering the messages and getting a meaningful conversation going with clients, but I'm having trouble understanding what the drawing calls should actually do.

Messages in this example come from running xbiff on a Linux machine and having it talk to my xserver on Windows. It's entirely possible that I've gotten some things wrong in interpreting the protocol, but the data seems like it's about right so far.

The graphics calls start with this, with the client creating a graphics context with the root window ID (90) as the drawable:

X_CreateGC: ID: 2097152, Drawable: 90, ValueMask: 8, Value0: 16777215

What is the significance of creating a GC based on the root window?

Next, it creates two 48x48 pixmaps and puts images on them:

X_CreatePixmap: Depth: 1, ID: 2097153, Drawable: 90, Width: 48, Height: 48

X_CreateGC: ID: 2097154, Drawable: 2097153, ValueMask: 12, Value0: 1, Value1: 0

X_PutImage: Format: 0, Size: 408, Drawable: 2097153, GraphicsContext: 2097154, Width: 48, Height: 48, X: 0, Y: 0, LeftPad: 0, Depth: 1

X_FreeGC: Graphics Context: 2097154

X_CreatePixmap: Depth: 1, id: 2097155, Drawable: 90, Width: 48, Height: 48

X_CreateGC: ID: 2097156, Drawable: 2097155, ValueMask: 12, Value0: , Value1: 0

X_PutImage: Format: 0, Size: 408, Drawable: 2097155, Graphics Context: 2097156, WIdth: 48, Height: 48, X: 0, Y: 0, LeftPad: 0, Depth: 1

X_FreeGC: Graphics Context: 2097156

Am I correct in thinking that the GC in this is the equivalent of a MemoryDC and the end result should be two 48x48 bitmaps in memory containing the data that was in the PutImage call?

Here it creates another graphics context based on the root window, but I don't understand why:

X_CreateGC: ID: 2097157, Drawable: 90, ValueMask: 65544, Value0: 16777215, Value1: 0

Next it creates two 48x48 windows, one with the root as the parent and the next with the first window as the parent:

X_CreateWindow: Depth: 24, ID: 2097158, Parent: 90, X: 0, Y: 0, Width: 48, Height: 48, BorderWidth: 1, Class: 1, Visual: 0, Bitmask: 10266, Value0: 16777215, Value1: 0, Value2: 1, Value3: 6422576, Value4: 32

X_CreateWindow: Depth: 24, ID: 2097161, Parent: 2097158, X: 0, Y: 0, Width: 48, Height: 48, BorderWidth: 0, Class: 1, Visual: 0, Bitmask: 26650, Value0: 16777215, Value1: 0, Value2: 0, Value3: 163852, Value4: 32, Value5: 0

It seems like this is creating a 48x48 base window with a window inside it that has an identical size and origin. What's the sense of that? Won't the subwindow just cover up the root window making it a redundant call?

Next we get a CreatePixmap call based on the child window created above, with a width and height of 0:

X_CreatePixmap: ID: 2097162, Drawable: 2097161, Width: 0, Height: 0

What's the purpose of this?

Next, xbiff (the client) creates another graphics context based on the child window and performs a CopyPlane to it from one of the 48x48 pixmaps.

X_CreateGC: ID: 2097163, Drawable: 2097161, ValueMask: 65544, Value0: 16777215, Value1: 0

X_CopyPlane: SrcDrawable: 2097155, DestDrawable: 2097162, GraphicsContext: 2097163, SrcX: 0, SrcY: 0, DstX: 0, DstY: 0, Width: 0, Height: 0, Bitplane: 1

X_FreeGC: 2097163

The width and height are 0 for this call. Does that make it a NOOP, or do dimensions of 0x0 mean "copy everything"? If so, this should just blit the bitmap to the child window, right?

Next the client creates a 0x0 pixmap based on the child window:

X_CreatePixmap: Depth: 24, ID: 2097164, Drawable: 2097161, Width: 0, Height: 0

What good is a 0x0 pixmap? Does that somehow mean "copy the window dimensions"?

Here we create a GC for the child window and perform a CopyArea from one of the 48x48 bitmaps to the window:

X_CreateGC: ID: 2097165 Drawable: 2097161, ValueMask: 65548, Value0: 16777215, Value1: 0, Value2: 0

X_CopyArea: SrcDrawable: 2097153, DestDrawable: 2097164, GraphicsContext: 2097165, SrcX: 0, SrcY: 0, DstX: 0, DstY: 0, Width: 0, Height: 0, Bitplane: 1

This CopyArea call also has a width and height of 0. Does that mean "copy the whole thing?"

Next we map the subwindows of 2097158 (the parent that is attached to the root) and then map the parent itself.

X_MapSubwindows: Window: 2097158
[We send a MapNotify and Expose event for window 2097161]

X_MapWindow: Window: 2097158
[We send a MapNotify and Expose event for window 2097158]

I'm not sure why it calls ClearArea on the child window afterward:

X_ClearArea: Window: 2097161, X: 0, Width: 0, Width: 0, Height: 0

Does that clear nothing or the whole thing?

Then a CopyArea call copies the 0x0 pixmap from earlier to the child window at location 24x24:

X_CopyArea: SrcDrawable: 2097162, DestDrawable: 2097161, GraphicsContext: 2097157, SrcX: 0, SrcY: 0, DstX: 24, DstY: 24, Width: 0, Height: 0

Width and height are also zero. Yet again, I'm not sure why.

I would be happy to have some assistance in understanding the way X11 drawing calls work and why the odd (to me) calls are the way they are.

Answer 1

(Most of this can be found in the X Window System protocol specification, which is freely available in many places on the internet.)

The significance of creating a GC relative to the root window is that a root window names a screen, and screens are this weird thing in X that define a set of related state. Pixmaps and formats and windows and visuals and colormaps and so forth are bound to a particular screen. You can have multiple screens; if you do, windows from one can not cross to another. This is the so-called "Zaphod" mode of operation. But in most common multihead setups, you simply have one root window that covers multiple outputs.

The GC in the PutImage call determines the transfer mode of the pixels in the image to the Pixmap in the server: planemask, clipping, raster op, etc.

You're seeing multiple GCs created because the depth of a GC is a static property, and not something you can modify with ChangeGC. You have both a 1bpp pixmap, and windows and pixmaps that have inherited the root window depth, so they need different GCs.

The difference between the two CreateWindow calls is in the mask of properties associated with each. The second one, relative to the first, also has the CWCursor bit set; the client is asking for a particular cursor to be set when the mouse is inside that window. Why it would make two like that, I have no idea; I don't think anyone ever claimed xbiff was well written.

0x0 is not a legal size for a pixmap (or any drawable, for that matter), so I'm not sure what's going on there. The correct thing for the server to do is throw BadValue in that case, but it seems like that's a symptom of something else gone wrong.

Answer 2

Just to supplement the excellent answer by ajax. Notice one of the windows has a border while the other does not. And recall what exactly xbiff does (show a 'no mail' icon or a 'you have mail' icon). The two windows provide a double-buffering effect. To change the image, xbiff only has to map or unmap the child window (the one with no border).