Week #4 status

This week I spent writing some documentation about XCB and OpenGL. Today, I posted the docs on this blog and asked for feedback, corrections and help from the XCB mailing list. I hope the documentation will be useful to others struggling with XCB and OpenGL issues, there is really no documentation on the subject easily available. If my documentation recieves positive feedback, I will post it to the XCB wiki.

I have also studied some possibilities of future projects. I still have plenty of summer left and my current path seems to be a dead end. I really need to find something entirely different to work on for the rest of the summer. Finding a good two month project sure isn’t easy and I’m fresh out of ideas.

One possible project would be desigining a new XCB-only GLX replacement API and implementing it to MESA, an open source OpenGL implementation. The API and it’s implementation could serve as a proof-of-concept for a future XCB-based GLX API. However, the new API would only be available to MESA and using proprietary OpenGL implementations (which are the most common on regular desktops) would not be affected. My fear is that the project would not catch any attention and would end up gathering dust. That being said, I feel that it’s not a very rewarding project.

Still clueless about the future, but at least the documentation is coming along.

XCB and OpenGL documentation draft

Here’s a draft of the XCB and OpenGL documentation I am working on. It may contain errors, typos and factual mistakes. All feedback, comments, corrections welcome.

The big picture: OpenGL, Xlib and GLX

A typical X Windowing System application is built using Xlib to communicate with the X server. Xlib has been the standard programming interface to the X Windowing System for decades. An OpenGL application on X Windows must use GLX, a standardized API, to set up a rendering context. The GLX API is closely coupled with Xlib.

In a typical desktop Linux or Unix set up, the OpenGL implementation library is provided by the graphics adapter drivers. The OpenGL library also provides the GLX API implementation. The GLX system has two roles, it communicates with the X server and initializes client-side and hardware state. The GLX client-server communication takes place using a standardized GLX wire protocol, which is an extension to the X network protocol. The GLX library abstracts all client-side and hardware initialization and the internals of the process are hidden in the OpenGL implementation library. The GLX functions may also communicate with the X server using proprietary X network protocol extensions.

The GLX API is specified in terms of Xlib, the glX functions use Xlib Displays, Windows, Visuals, etc. The GLX implementations are also built using Xlib.

typical Xlib and GLX setup

XCB and XCB-GLX

XCB is a low level programming interface library to the X Windowing system. It consists of C language bindings to X network protocol requests and responses. The bindings are automatically generated from an XML-based description of the underlying network protocol. XCB-GLX is the C binding to the GLX wire protocol and it too is generated from XML descriptions transcribed from the GLX wire protocol specifications.

XCB-GLX only communicates with the X server, it does not perform any hardware initialization or touch the OpenGL client-side state. Because of this XCB-GLX cannot be used as a replacement for the GLX API. To use OpenGL in the X Windowing system, one must use the GLX API, and the GLX API is closely coupled with Xlib. As a result, an OpenGL application on the X Windows must use Xlib and thus can’t be done using only XCB.

Although the XCB-GLX API has little value to end-user XCB application developers, it may be used in the development of new XCB-based OpenGL and GLX implementations. XCB could potentially improve the speed and quality of the OpenGL libraries.

Using OpenGL in XCB applications (w/ Xlib)

Although writing a OpenGL application on X Windows using pure XCB is not possible, it is possible to use a XCB-based Xlib implementation to configure a rendering context in a hybrid XCB/Xlib application. Xlib is used with the GLX functions while XCB can be used for everything else. You do get all the advantages of using XCB, but you can’t get entirely rid of Xlib.

The process of setting up a hybrid XCB/Xlib application with OpenGL is rather simple. XOpenDisplay is used to set up a Xlib Display, and XGetXCBConnection and XSetEventQueueOwner (from X11/Xlib-xcb.h) is used to get the XCB connection and configure XCB to handle the event queue instead of Xlib. The Xlib Display can then be used for the GLX context setup while the XCB connection can be used for everything else. Communication between XCB and GLX is done using integer-based identifiers (XID’s), which are safe to pass around between XCB and Xlib/GLX.

XCB-based Xlib hybrid setup

Future work

For a sustainable XCB-based OpenGL solution, a new replacement API for GLX would have to be designed and implemented. The GLX API could, in theory, be redesigned on top of XCB, using the XCB connection and the XCB-GLX for the X server communication internally. The new XCB’ified GLX API could be used to write OpenGL application with pure XCB without the dependancy to Xlib.

The obvious problem is that the GLX is a standardized API and has dozens of different implementations. The GLX standard is governed by the Khronos group and they are the ones to make the initiative for a new API standard. Implementing the new API would be up to the graphics driver vendors.

A proof-of-concept design and implementation could be done using MESA, an open source OpenGL implementation.

Proposed pure-XCB setup

To maintain backward compatibility and providing an incremental porting path, the current GLX API could be implemented using the XCB’ified API underneath like the XCB-based Xlib implementation does.

Wasted week

Last week was not really productive, I started a thread in the XCB mailing list about XCB and OpenGL in general and on what to do next. The discussion there did not really take me very far, although it did confirm most of my findings that I have posted in earlier blog posts. It also gave me some ideas about the future of this project. Looking at MESA GLX stuff was one of these.

I also managed to waste a lot of time dealing with personal computer issues, which steered my attention further away from the actual work I’m supposed to get done.

This week I intend to write some documentation about OpenGL/XCB, along with a piece sample code to use OpenGL in a XCB/Xlib hybrid program I came up earlier on. I have also planned of making some clarifying diagrams about the OpenGL/GLX/Xlib/XCB ecosystem.

I’m also going to build MESA and see how they do their OpenGL context setup. This could give me ideas for future work.

I also have some school work this week, I am studying the Structure and Interpretation of Computer Programs (yeah, Scheme) as a summer course and I’m a bit behind schedule with my excercises. I also have a lecture to attend this week.

After more or less striking a dead end early on in my project, I will try to finalize my work so far by the end of this week/month and then move on to a different subject. I’m still a bit short on ideas and all feedback will be welcome.

Submitted a bug, future thoughts

Today I submitted a bug report (along with a solution) about a simple C++ linking problem I found in X.org’s Xlib implementation.

For the next week or two I intend to document my recent discoveries about Xlib, XCB and GLX and after that I’ll try to find another subject to focus on.

Discoveries about XCB, Xlib, GLX and OpenGL

After hacking away and studying the inner workings of OpenGL on X Windows for the last week, I have made some discoveries about how things relate to each other.

First of all, the GLX API and the GLX wire protocol. An OpenGL implementation provides the GLX API. The glX*-functions are located in the OpenGL shared library libGL.so and they are used to set up an OpenGL context. The GLX functions do two things: they modify local client state and send requests to inform the X server of server-side state changes using the GLX wire protocol.

XCB has got bindings for the GLX wire protocol, but no access to the GLX/OpenGL internal client-side state. The wire protocol itself isn’t enough for configuring an OpenGL context. The GLX API on the other hand is closely tied to Xlib and uses Xlib internally. In other words, it seems like it’s not possible to use OpenGL in X Windows applications without Xlib.

As I was getting desperate, I had a revelation. I figured out that it is possible to use OpenGL with XCB. How? By mixing Xlib and XCB. Instead of using xcb_connect to set up a connection, create a Xlib Display using XOpenDisplay, get the XCB connection using XGetXCBConnection and acquire ownership of the event queue using XSetEventQueueOwner. Then use the Xlib Display with all your glX functions and the XCB connection for everything else (window setup, event handling, etc). Apart from the Display object, XCB, Xlib and GLX communicate mostly by using integer-based identifiers (XID’s) for windows, contexts, etc and they can be used across XCB and Xlib-based code.

Using OpenGL with XCB as described above requires you to have a XCB-based version of Xlib. You can’t get rid of Xlib, but you do get the benefits of using XCB. Your libGL.so probably depends on Xlib, so you can’t get rid the Xlib dependency anyway. I might post some example code later on, but the description above should be pretty straightforward.

What are the XCB-GLX protocol bindings good for then? They cannot be used as a replacement for the GLX API and can’t thus be used to set up an OpenGL context in XCB-based end-user applications, but they could be used internally by the OpenGL and GLX API implementations to communicate with the X server. The MESA OpenGL implementation makes some use of XCB-GLX in it’s backend, for example.

What would be required to run OpenGL apps using XCB without the Xlib legacy? A high level XCB-based replacement for the GLX API, based on the XCB-GLX protocol bindings perhaps? The current Xlib-based GLX API could then be re-written using the XCBified version. The problem is that the GLX API is standardized and replacing it would be more of a political issue than a technical one.

It took me two weeks to get all this figured out. It’s not very much and I’m very dissapointed to get this little done and frustrated about what to do next.

First week progress and problems

My first task this week was to check out XCB source code from Git repositories and build a development version of the library. The whole process went rather fluently, and I got XCB and required libraries built. For a library built with a bunch of shell scripts and GNU Autotools from sources generated from XML description files by a Python script, the build process worked surprisingly well.

Once I had myself a development library, I started to study how XCB and GLX work. There was no real documentation on how to use the XCB-GLX functions, but I figured it out by cross-referencing the XCB function calls with the GLX programming specification and the GLX protocol specification.

I started out by trying to write a simple application that opens a window on the screen and sets up an OpenGL context that can draw into that window. I could quite quickly get things set up, querying framebuffer configurations, opening an X window, creating an OpenGL context and everything else that’s needed. But the application didn’t work. All I got was a window with nothing on it, the client area of the window didn’t get drawn or the window didn’t show up at all if I created a window without a border. I checked all error conditions and underwent all my standard debugging procedures but the damn thing just wouldn’t work.

Next I started working on a reference appication made with Xlib and GLX, the standard tools used with X windowing and OpenGL. I wrote an application that did the same things that my XCB application was doing and guess what, it worked. I tried to isolate the cause of the problem by comparing my Xlib/GLX implementation with my XCB-GLX version, but I couldn’t find a difference by looking at the source code. Everything seemed perfectly sane and consistent, but my XCB version just didn’t work. There had to be something mysterious going on.

Since my two “identical” applications were working differently, I wanted to see what’s going on under the hood. I used xtrace to intercept the communication between the X client and server. The results: a clear difference. The Xlib/GLX application was sending out lots of requests that my XCB version didn’t send. Some of the requests I knew to expect, like some glXQueryVersion and glXQueryServerString requests done by the GLX implementation, but something bigger came up. I found out that there are lots of requests going on using an X extension named “NV-GLX”. It seems to be a proprietary Nvidia protocol used by their GLX implementation. I also noted some other differences, like glXCreateNewContext sending out GLX_ARB_create_context requests instead of the one it should and that glXSwapBuffers does not send any X requests.

So the big picture is this: an application wishing to use OpenGL with Xlib uses GLX to set up a rendering context. The GLX routines are bundled with OpenGL functions in shared library libGL.so, provided by the OpenGL implementation, which usually resides in the display drivers provided your graphics hardware vendor, in my case Nvidia. Nvidia’s GLX implementation does wierd things in the scenes and doesn’t seem to be controllable using standard GLX requests and is making my work awfully hard.

What I’ll start doing next is diving deeper into the problem and gathering more information about the issue, I hope I’m not going to find a dead end here.

Kickoff

Today, I’ll start my summer job. My summer job is not of the conventional kind, I’ll be working on an open source project in the Kesäkoodi 2009 campaign. My project is to get XCB, a new programming interface to the X Window System,  working with OpenGL 3.0.

Today, I’ll get cracking with the project. This is on my list for today:

1. Found a blog.
2. Grab a copy of XCB development repositories.
3. Get the XCB library built from sources.
4. Study XCB’s bells and whistles

I’m almost done founding a blog and grabbing a copy of the XCB Git repositories should be a simple task, but building XCB might not be that easy. Building non-trivial software written in C or C++ (or worse, C code that comes from a code generator) tends to be a PITA and my worst case time estimate for this is wasting the entire week on dependency and version mismatch issues and the like you’d expect to bump into when building software. Finally, I’ll need to study XCB, since I don’t really have any experience working with it. My plan is to write a simple test application, try to get a window open on my screen and something drawn into it with OpenGL.

So, time to get my development environment set up and start familiarizing with XCB.