Around a year ago I've explained in this article how to implement in C an interactive graphics display using GTK, multiprocess and a shared memory segment. In the present article I'll introduce another solution: X11 and multithread.

The X Window System (aka X11, official webpage here) is a low level windowing system primarily developped for Unix-like OSes and later ported to other OSes. It's very basic in the features it offers: create and manage windows on a display, draw some primitive 2D shapes, and interact with the mouse and keyboard; but also super versatile as it is architecture-independent and available in all *nix systems. It's now progressively replaced by its successor, Wayland, which is becoming the default for more and more systems since the late 2010s. The official webpage itself recommends to use GTK (cf my previous article), or for low-level development XCB. However, given that it has been the standard since several decades and is still the backbone of tons of code (see this page for an old but significative list of libraries and toolkits based on X11), it's not going to disappear anytime soon. Knowing about it is surely profitable in a way or another.

It's true that if you don't like to "do it yourself" and dive down to bit level X11 is not for you. In the other hand it is certainly not what some describe as a completely impractical monster only tamed by voodoo rituals inscribed in its arcane documentation. As I'll show below, less than 300 lines of code is all you need for multithread, triple RGB buffer, resizable window, buffered mouse/key events, clock, refresh/frame rate, all packed in a super easy to use structure and its dozen of functions. The only rebuke I would agree with is the mesmerizing absence of a complete workable example on the web. There are tons of code snippets here and there, but during my two days of X11 study to write this article I could never find something similar to what I provide below. All the code in this article is available for download (cf below), it will surely be helpful to someone else.

Enough chatting, let's see how it works. The first thing is to open a connection to the X server of a display device. The X Window System was developped to work remotely over a network for historical reason. Even if you want to open a window on your local machine, it uses a client-server model. However that doesn't mean you have to bother about the network layer, everything is done in one single line: Display* display = XOpenDisplay(displayName);. displayName is the network name of the device on which you want to display the window. On the first screen of the local machine it's as simple as :0.0, and you don't even need to specify it with the functions I provide, it is the default value. If you have several screens or want to display the window on a remote machine you can select it instead with hostname:server_number.screen_number, where hostname is the IP (or a name that resolves to it via DNS) of the machine, the server number is the ID of the X server on that machine (should be most often 0), and the screen number is the ID of the screen if several ones are connected to the machine (also most often 0 will do). Aaah the good ol' days at university when we discovered we could display at will "funny" pictures on classmates' terminal... :-)

Next step is to create the actual window. Windows are organised in a tree structure for management, so a new window's parent must be specfied. For a single window use-case there is no need to worry and a default one is fine: Window parentWindow = XDefaultRootWindow(display);. An initial color must be given to the new window's content. Given that the content is supposed to be rendered and updated later a default black will do: unsigned long black = XBlackPixel(display, 0). There are tons of other parameters if you want fine control, but default values are already enough for something functional. A window of given initial width and height can be created with Window window = XCreateSimpleWindow(display, parentWindow, 0, 0, width, height, 0, black, black);. Bonus, the window's title can be set with XStoreName(display, window, title);.

For the window to be interactive it must listen to events from the user. This is not the case by default, for performance reason. X11 being a client-server model, events occur on the X server side and are sent to the client side for processing. To avoid the transmission of useless events, one must specify those who are relevant. In the code I provide, window resize, mouse and keyboard events are selected with long evtMask = ExposureMask | StructureNotifyMask | KeyPressMask | KeyReleaseMask | ButtonPressMask | ButtonReleaseMask | PointerMotionMask; XSelectInput(display, window, evtMask);.

For performance reason too, the code I provide uses a separate thread to manage these events and the update of the window's graphical content. Upon reception of events from the server, the thread stores them in a queue until the main thread processes them. The reception of events from the server is done by, first checking if there are waiting events: XEvent event; bool waitingEvent = XCheckWindowEvent(display, window, evtMask, &event);, then if there was an event waiting, process it: if(waitingEvent) switch(event.type) { ... }.

There are three types of mouse events: when the pointer moves over the window (case MotionNotify:), and when a mouse's button is pressed or released (case ButtonPress: and case ButtonReleased:). In each case the event received with XCheckWindowEvent() is cast into the appropriate structure to get access to the event information: XMotionEvent* motionEvent = (XMotionEvent*)&event; (and XButtonEvent for press and release). Event's information includes the button ID, the state (shift/ctrl/...), the time, the location (cf the doc for details): motionEvent->x, motionEvent->y, etc... It's rather straightforward to use.

There are two types of keyboard events: when a key is pressed or released (case KeyPress: and case KeyReleased:). As for the button events, casting gives access to the event's information: XKeyEvent* keyEvent = (XKeyEvent*)&event;. However, to abstract keyboard mapping the returned event gives the pressed key as a keycode. It must be converted using unsigned long keysym = XLookupKeysym(keyEvent, 0); to get the actual useful keysym value. That value can be compared to predefined values XK_a, XK_b, ... XK_space, XK_Escape, ... (cf /usr/include/X11/keysymdef.h), which conveniently map to ASCII values (so if(keysym == XK_a) is the same as if(keysym == 'a')). Note, this is the "simple" version, refer to this gist instead if you're using an IME.

As for other events the resize event (case ConfigureNotify:) is cast (XConfigureEvent* configureEvent = (XConfigureEvent*)&event;) to get access to the window new width and height (configureEvent->width and configureEvent->height). These dimensions should be memorised and the content of the window should be rendered/updated accordingly (more on this later). The "philosophy" of X11 is to let the server side control the dimensions, and to obey them on the client side. Finally the exposure event (case Expose:) is used by the server to explicitly require the update of the window's content (normally the client decides freely when it wants to update it).

Now the interesting part: the window's content drawing. Contrary to the solution of my previous article I wanted this time to try something more responsive, able to display smooth animations (as long as the rendering part is fast enough). Thus, I've choosen to implement a triple buffer solution. It works as follow. The graphical content of the window is memorised as RGB values in an array unsigned char data[height * width * 3]. X11 allows for virtually any arrangement except that data must be stored by row. Three copies of that array are held in memory and used as a circular buffer. Two indices, \(i_d\) and \(i_r\), memorise the array corresponding to the currently displayed content and currently rendered content. The third array is a buffer which allows to solve synchronisation problems between the thread displaying the content and the thread rendering its content. The two following simple rules allow for real time rendering without the two threads ever interfering with or waiting for each other. 1) At the beginning of every display step, if \(((i_d+1)\bmod 3)\ne i_r\) then \(i_d=(i_d+1)\bmod 3\). 2) At the end of every rendering step (publication step), if \(((i_r+1)\bmod 3)\ne i_d\) then \(i_r=(i_r+1)\bmod 3\).

Note that as we allow for window resizing, the dimension of the array may vary at any time. It is then presented to the rendering algorithm in a structure including a pointer to the array itself and its actual dimensions. So, at each rendering step, array \(i_r\) is resized (realloc) if necessary, then the array plus dimensions is passed to the rendering algorithm and updated, then \(i_r\) is updated. The displaying thread always displays the content accordingly to the \(i_d\) (array + dimensions) pair. It means there may be discrepancy between the dimensions and the actual window dimensions at the time of display. Fortunately, X11 is sturdy enough to bear with that, clipping or filling as necessary until the following rendering pass catches up with the window new size.

The displaying thread sends the windows grahical content to the server using a XImage structure, encapsulating all the info necessary for the server to actually update the window. Except for the array values and dimensions that structure never changes, so it's a good idea to create it once at the beginning, update as necessary and reuse it. In the code below, I prepare that structure as follow: XImage image = {.xoffset = 0, .format = ZPixmap, .byte_order = MSBFirst, .bitmap_pad = 32, .depth = 24, .bits_per_pixel = 24, .red_mask = 0xff0000, .green_mask = 0x00ff00, .blue_mask = 0x0000ff, .obdata = NULL, .f = {0}}; XInitImage(&image); . All those values encode the format of the array as I've described it above. When it's time to send the image to the server, image is updated as follow: image.width = array[displayed].width;, image.height = array[displayed].height;, image.data = (char*)(array[displayed].data);, image.bytes_per_line = 3 * array[displayed].width;. And it is sent to the server as follow: XPutImage(display, window, gc, &image, 0, 0, 0, 0, array[displayed].width, array[displayed].height);, where gc is the graphical context which doesn't really matter in that context so the default one does the job: GC gc = XDefaultGC(that->display, 0);.

And that's it, that's already enough to have a resizable window responding to mouse and keyboard and ready to display graphics in real time. I've added a measure of frame rate (number of frame rendered per second) and refresh rate (number of frame sent to the X server per second), hidden the details and packed everything in a little structure and its functions for convenience. The example code below shows how to use it:

#include "x11display.h" #include <stdio.h> #define WIDTH 800 #define HEIGHT 600 int main(void) { // Create the X11Display and show it X11Display* display = X11DisplayAlloc(WIDTH, HEIGHT, NULL, "Example X11Display"); X11DisplayShow(display); // Loop until the user close the display while(X11DisplayIsShown(display)) { // Get the input buffer X11DisplayBuffer buffer = X11DisplayGetBuffer(display); // Draw a basic pattern varying with time on the screen float timeMs = X11DisplayGetTimeMs(display); for(unsigned int x = 0; x < buffer.width; ++x) { for(unsigned int y = 0; y < buffer.height; ++y) { unsigned long shift = timeMs * 0.1; unsigned char val = 255 * ((((x + shift) / 100) & 1) || ((y / 100) & 1)); buffer.rgb[(y * buffer.width + x) * 3 + 0] = val; buffer.rgb[(y * buffer.width + x) * 3 + 1] = 0; buffer.rgb[(y * buffer.width + x) * 3 + 2] = (unsigned char)y; } } // Publish the rendered image X11DisplayPublish(display); // For the remaining time with a 60 frames per second time budget, process // the events float t; do { t = (float)X11DisplayGetTimeMs(display); // Process the events, close the display when the user press 'q' X11DisplayEvt evt = X11DisplayGetNextEvent(display); if(evt.type == X11Evt_press && evt.src == X11Evt_key && evt.val == 'q') { X11DisplayHide(display); } } while(t - timeMs < 16.0); } // Display the frame and refresh rates float frameRate = X11DisplayGetFrameRate(display); float refreshRate = X11DisplayGetRefreshRate(display); printf("frameRate:%f/s refreshRate:%f/s\n", frameRate, refreshRate); // Free memory X11DisplayFree(&display); // Exit return 0; }

compile with the following Makefile:

Edit on 2023/07/24: added -D_POSIX_C_SOURCE=199309L needed to define clock related functions and macros, and correct a bug in X11DisplayGetBuffer().

main: main.o x11display.o Makefile gcc -o main main.o x11display.o -lX11 main.o: main.c x11display.h Makefile gcc -c main.c x11display.o: x11display.h x11display.c Makefile gcc -c x11display.c -D_POSIX_C_SOURCE=199309L

The header file x11display.h is as follow:

/* X11Display - a C data structure and the functions to manipulate it, to simply display and interact with a graphical display based on X11 Copyright (C) 2022 Pascal Baillehache baillehache.pascal@gmail.com https://baillehachepascal.dev This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. */ #ifndef X11DISPLAY #define X11DISPLAY #include <stdbool.h> #include <X11/Xlib.h> #include <X11/keysym.h> // X11Display opaque structure typedef struct X11Display X11Display; // Labels for values in X11DisplayEvt #define X11Evt_noEvent 0 #define X11Evt_press 1 #define X11Evt_release 2 #define X11Evt_key 0 #define X11Evt_mouse 1 // X11DisplayEvt structure returned by X11DisplayGetNextEvent() typedef struct { // 0: no event, 1: press, 2: release int type; // 0: key, 1: mouse int src; // Time of the event in millisecond (not sure relative to what) unsigned long long time; // key or button mask, 'or' combination of: // NoModMask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, // Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, // Mod3Mask, Mod4Mask, and Mod5Mask unsigned int state; // key/button value, one of: // for key: NoSymbol or the XK_... value (see complete list here: // /usr/include/X11/keysymdef.h) which map to ASCII (XK_a == 'a') // for button: Button1, Button2, Button3, Button4, Button5 unsigned long val; // Coordinates of the pointer at the time of event int x, y; } X11DisplayEvt; // X11DisplayPos structure returned by X11DisplayGetPointerPos() typedef struct { // Position (0,0 is the top-left corner, x toward right, y toward bottom) int x, y; } X11DisplayPos; // X11DisplayBuffer structure returned by X11DisplayBufferPublish() typedef struct { // Dimensions of the buffer unsigned int const width; unsigned int const height; // RGB buffers, three channels, ordered by row of RGB pixel value in [0, 255] unsigned char* const rgb; } X11DisplayBuffer; // Allocate memory and create a new X11Display instance // Input: // width: initial width of the display // height: initial height of the display // displayName: the display name as hostname:server_number.screen_number, if // NULL ":0.0" is used instead // title: the title of the window // Output: // Return a new X11Display instance, or NULL if it couldn't be created X11Display* X11DisplayAlloc( unsigned int const width, unsigned int const height, char const* const displayName, char const* const title); // Free the resource used by a X11Display instance // Input: // that: pointer to the X11Display instance // Output: // *that is set to NULL, the display is closed if it has been shown, all // memory allocated by the instance is released void X11DisplayFree(X11Display** const that); // Display the X11Display instance and starts its main loop in a separate // thread. The thread will end when the window has focus and the user presses // ctrl-c (the key combination, not the signal), or X11DisplayHide() is called, // or X11DisplayFree() is called. // Input: // that: the X11Display instance void X11DisplayShow(X11Display* const that); // Hide the X11Display instance. The display is unmapped and its thread is // terminated but its reources are not freed and it is ready to be shown again // anytime. // Input: // that: the X11Display instance void X11DisplayHide(X11Display* const that); // Check if a display is currently shown // Input: // that: the X11Display instance // Output: // Return true if the display is shown, else false bool X11DisplayIsShown(X11Display const* const that); // Get the average refresh rate (number of times the window content is updated // per second) since the last call to X11DisplayGetRefreshRate() or // X11DisplayShow(). // Input: // that: the X11Display instance // Output: // Return the refresh rate float X11DisplayGetRefreshRate(X11Display* const that); // Get the average frame rate (number of times the image buffer is updated // per second) since the last call to X11DisplayGetFrameRate() or // X11DisplayShow(). // Input: // that: the X11Display instance // Output: // Return the frame rate float X11DisplayGetFrameRate(X11Display* const that); // Return the next event in the queue of events // Input: // that: the X11Display instance // Output: // Pop the next event from the queue and return it. If there was no event in // the queue an event with type == 0 is returned instead. X11DisplayEvt X11DisplayGetNextEvent(X11Display* const that); // Flush the event queue // Input: // that: the X11Display instance void X11DisplayFlushEvent(X11Display* const that); // Get the las known position of the pointer in the display // Input: // that: the X11Display instance // Output: // Return the last known position. X11DisplayPos X11DisplayGetPointerPos(X11Display const* const that); // Get the current rendering buffer. // Input: // that: the X11Display instance // Output: // Return the buffer to write on. The content of the buffer is undefined. // The width and height of the buffer may be different from the previous // buffer. X11DisplayBuffer X11DisplayGetBuffer(X11Display* const that); // Publish the current editing buffer // Input: // that: the X11Display instance void X11DisplayPublish(X11Display* const that); // Get the elapsed time in millisecond since the display is shown // Input: // that: the X11Display instance // Output: // Return the elapsed time. unsigned long long X11DisplayGetTimeMs(X11Display const* const that); // Set the title of the window // Input: // that: pointer to the X11Display instance // title: the window's new title void X11DisplaySetTitle( X11Display const* const that, char const* const title); #endif

And the body x11display.c is as follow:

/* X11Display - a C data structure and the functions to manipulate it, to simply display and interact with a graphical display based on X11 Copyright (C) 2022 Pascal Baillehache baillehache.pascal@gmail.com https://baillehachepascal.dev This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. */ #include <stdlib.h> #include <stdio.h> #include <stdarg.h> #include <pthread.h> #include <time.h> #include <string.h> #include "x11display.h" // Helper macros #define loop(varName, nbIter) \ for(__typeof__((nbIter) + 0) (varName) = 0; \ (varName) < (nbIter); ++(varName)) // Helper functions static char* StrCreate(char* fmt, ...); // Default display name, cf X11DisplayAlloc static char const* const defaultDisplayName = ":0.0"; // Size of the buffer event #define EVT_BUFFER_SIZE 1024 // Indices for the frame and refresh rates property of X11Display typedef enum RateIdx { frame, refresh } RateIdx; // X11Display structure struct X11Display { // X11 data Display* display; Window window; Window parentWindow; long evtMask; Atom wmDelete; XEvent event; char* displayName; GC gc; XImage image; // Dimensions of the display unsigned int width; unsigned int height; // Flag to memorise if the child thread is running bool isChildRunning; // Flag to memorise the request for the termination of the child bool flagTerminateThread; // Thread data pthread_t thread; pthread_attr_t threadAttr; // Counters and timers for the frame rate and refresh rate struct { unsigned int count; struct timespec start; struct timespec stop; } rates[2]; // Timer for the whole window (measure time during display only) struct timespec timer; // Event buffer X11DisplayEvt evts[EVT_BUFFER_SIZE]; unsigned int evtHead; unsigned int evtTail; // Last known position of the pointer X11DisplayPos pointerPos; // Buffers to manage displayed data X11DisplayBuffer buffers[3]; int inputBuffer; int outputBuffer; }; // Set the title of the window // Input: // that: pointer to the X11Display instance // title: the window's new title void X11DisplaySetTitle( X11Display const* const that, char const* const title) { XStoreName(that->display, that->window, title); } // Allocate memory and create a new X11Display instance // Input: // width: initial width of the display // height: initial height of the display // displayName: the display name as hostname:number.screen_number, if NULL // ":0.0" is used instead // title: the title of the window // Output: // Return a new X11Display instance, or NULL if it couldn't be created X11Display* X11DisplayAlloc( unsigned int const width, unsigned int const height, char const* const displayName, char const* const title) { // Allocate memory for the instance X11Display* that = malloc(sizeof(X11Display)); if(that == NULL) return NULL; memset(that, 0, sizeof(X11Display)); // Initialise dimensions that->width = width; that->height = height; // Set the display name char const* name = defaultDisplayName; if(displayName != NULL) name = displayName; that->displayName = StrCreate("%s", name); // Initialise the buffers size_t sizeBuffer = width * height * 3; loop(i, 3) { *((unsigned int*)&(that->buffers[i].width)) = width; *((unsigned int*)&(that->buffers[i].height)) = height; *((unsigned char**)&(that->buffers[i].rgb)) = malloc(sizeBuffer); memset(that->buffers[i].rgb, 0, sizeBuffer); } that->inputBuffer = 2; that->outputBuffer = 0; // Open the connection to the server that->display = XOpenDisplay(that->displayName); if(that->display == NULL) { X11DisplayFree(&that); return NULL; } // Get the parent window of the window we are going to create, we use the // the root of the display that->parentWindow = XDefaultRootWindow(that->display); // Set the graphical context to the default one that->gc = XDefaultGC(that->display, 0); // Prepare the XImage wrapper for the rgba array // ZPixmap: interlaced RGBA channels, XYPixmap: RGBA channels in // sequential order // bitmap_pad: equal to the number of bit per pixel given there is no // offset on scanlines (xoffset = 0) // depth: number of bit per pixel that->image = (XImage){ .xoffset = 0, .format = ZPixmap, .byte_order = MSBFirst, .bitmap_pad = 32, .depth = 24, .bits_per_pixel = 24, .red_mask = 0xff0000, .green_mask = 0x00ff00, .blue_mask = 0x0000ff, .obdata = NULL, .f = {0}, }; XInitImage(&(that->image)); // Create the window that->window = XCreateSimpleWindow( that->display, that->parentWindow, 0, 0, // at the top-left corner of the parent window that->width, that->height, 0, // no border XBlackPixel(that->display, 0), XBlackPixel(that->display, 0)); // Set the window's title X11DisplaySetTitle(that, title); // Create the event mask for the event types we want the window to respond to that->evtMask = ExposureMask | StructureNotifyMask | KeyPressMask | KeyReleaseMask | ButtonPressMask | ButtonReleaseMask | PointerMotionMask; XSelectInput(that->display, that->window, that->evtMask); // Avoid the window to be closed by the user pressing the X button // When this happens it is said that a ClientMessage event whould be sent // and could be processed as follow // switch(event.type) { // case ClientMessage: // if ((Atom)(event.xclient.data.l[0]) == wmDelete) // however I don't receive that event and can't understand why, so I give up that->wmDelete = XInternAtom(that->display, "WM_DELETE_WINDOW", false); XSetWMProtocols(that->display, that->window, &(that->wmDelete), 1); // Return the new instance return that; } // Free the resource used by a X11Display instance // Input: // that: pointer to the X11Display instance // Output: // *that is set to NULL, the display is closed if it has been shown, all // memory allocated by the instance is released void X11DisplayFree(X11Display** const that) { if(that == NULL || *that == NULL) return; X11DisplayHide(*that); XCloseDisplay((*that)->display); if((*that)->displayName != NULL) free((*that)->displayName); loop(i, 3) free((*that)->buffers[i].rgb); *that = NULL; } // Repaint the window as necessary // Input: // that: the X11Display instance static void RepaintWindow(X11Display* const that) { // If a new buffer has been published int idxBuffer = (that->outputBuffer + 1) % 3; if(idxBuffer != that->inputBuffer) { // Update the output buffer index that->outputBuffer = idxBuffer; // Send the new buffer content to the server // Here, the buffer dimensions may be different from the current window // dimensions. This is fine, XPutImage take care of that for us. X11DisplayBuffer* buffer = that->buffers + that->outputBuffer; that->image.width = buffer->width; that->image.height = buffer->height; that->image.data = (char*)(buffer->rgb); that->image.bytes_per_line = 3 * buffer->width; XPutImage( that->display, that->window, that->gc, &(that->image), 0, 0, 0, 0, buffer->width, buffer->height); // Update the refresh rate ++(that->rates[refresh].count); } } // Queue a new event if the queue is not full // Input: // that: pointer to the X11Display instance // evt: the event to queue static void AddEventToQueue( X11Display* const that, X11DisplayEvt const evt) { // If the buffer is not full unsigned int nextIdx = (that->evtHead + 1) % EVT_BUFFER_SIZE; if(nextIdx != that->evtTail) { // Add the event in the buffer and update the head that->evts[that->evtHead] = evt; that->evtHead = nextIdx; } } // Process an event from the X11 server. // Input: // that: pointer to the X11Display instance static void ProcessEvent(X11Display* const that) { switch(that->event.type) { // Expose event case Expose: { RepaintWindow(that); }; break; // Pointer motion event case MotionNotify: { XMotionEvent* motionEvent = (XMotionEvent*)&(that->event); that->pointerPos.x = motionEvent->x; that->pointerPos.y = motionEvent->y; }; break; // Window structure change event case ConfigureNotify: { XConfigureEvent* configureEvent = (XConfigureEvent*)&(that->event); that->width = configureEvent->width; that->height = configureEvent->height; }; break; // Key event case KeyPress: case KeyRelease: { // If the key event is 'ctrl-c' (the key combination, not the signal) // hide the window, else add the event to the queue XKeyEvent* keyEvent = (XKeyEvent*)&(that->event); unsigned long keysym = XLookupKeysym(keyEvent, 0); if(keyEvent->state == ControlMask && keysym == XK_c) { that->flagTerminateThread = true; } else { X11DisplayEvt evt = { .type = that->event.type == KeyPress ? 1 : 2, .src = 0, .time = keyEvent->time, .state = keyEvent->state, .val = keysym, .x = keyEvent->x, .y = keyEvent->y, }; AddEventToQueue(that, evt); } }; break; // Button event case ButtonPress: case ButtonRelease: { // Add the event to the queue XButtonEvent* btnEvent = (XButtonEvent*)&(that->event); X11DisplayEvt evt = { .type = btnEvent->type == ButtonPress ? 1 : 2, .src = 0, .time = btnEvent->time, .state = btnEvent->state, .val = btnEvent->button, .x = btnEvent->x, .y = btnEvent->y, }; AddEventToQueue(that, evt); }; break; // Other events are simply ignored default: break; } } // Main loop executed in its own thread. Update the content of the display, // and process the events from the X11 server // Input: // arg: to be cast to a X11Display* // Output: // Always return NULL. static void* Main(void* arg) { // Cast the argument X11Display* that = (X11Display*)arg; // Reset the rates loop(i, 2) { that->rates[i].count = 0; clock_gettime(CLOCK_MONOTONIC, &(that->rates[i].start)); } // Reset the flag to control the main loop that->flagTerminateThread = false; // Main loop while(that->flagTerminateThread == false) { // Ask the server if there is an event waiting in the queue, if so process // it bool waitingEvent = XCheckWindowEvent( that->display, that->window, that->evtMask, &(that->event)); if(waitingEvent) ProcessEvent(that); // Repaint the window as necessary RepaintWindow(that); } // Unmap the display XUnmapWindow(that->display, that->window); // Flush the remaining events X11DisplayFlushEvent(that); // Set the flag that->isChildRunning = false; // No return value at the end of the thread return NULL; } // Display the X11Display instance and starts its main loop in a separate // thread. The thread will end when the window has focus and the user presses // ctrl-c (the key combination, not the signal), or X11DisplayHide() is called, // or X11DisplayFree() is called. // Input: // that: the X11Display instance void X11DisplayShow(X11Display* const that) { // If the display is not already displayed if(that->isChildRunning == false) { // Map the window to the display XMapWindow(that->display, that->window); // Start the main loop in its own thread that->thread = (pthread_t){0}; pthread_create(&(that->thread), &(that->threadAttr), Main, that); that->isChildRunning = true; // Wait for the thread to start while(!X11DisplayIsShown(that)); // Start the timer clock_gettime(CLOCK_MONOTONIC, &(that->timer)); } } // Hide the X11Display instance. The display is unmapped and its thread is // terminated but its resources are not freed and it is ready to be shown again // anytime. // Input: // that: the X11Display instance void X11DisplayHide(X11Display* const that) { // If the child thread is running if(that->isChildRunning == true) { // Set the flag to terminate the main loop that->flagTerminateThread = true; // Join the thread pthread_join(that->thread, NULL); that->thread = (pthread_t){0}; } } // Check if a display is currently shown // Input: // that: the X11Display instance // Output: // Return true if the display is shown, else false bool X11DisplayIsShown(X11Display const* const that) { return that->isChildRunning; } // Get the average rate (code commonalisation for X11DisplayGetFrameRate and // X11DisplayGetRefreshRate) // Input: // that: the X11Display instance // type: type of rate measured (frame or refresh) // Output: // Return the rate static float GetRate(X11Display* const that, RateIdx type) { // Measure the rate clock_gettime(CLOCK_MONOTONIC, &(that->rates[type].stop)); unsigned long long count = that->rates[type].count; unsigned long long timeMs = (that->rates[type].stop.tv_sec * 1000 + that->rates[type].stop.tv_nsec / 1000000) - (that->rates[type].start.tv_sec * 1000 + that->rates[type].start.tv_nsec / 1000000); float rate = (float)count / (float)timeMs * 1000.0; // Reset the timer and counter clock_gettime(CLOCK_MONOTONIC, &(that->rates[type].start)); that->rates[type].count = 0; // Return the rate return rate; } // Get the average refresh rate (number of times the window content is updated // per second) since the last call to X11DisplayGetRefreshRate() or // X11DisplayShow() // Input: // that: the X11Display instance // Output: // Return the refresh rate float X11DisplayGetRefreshRate(X11Display* const that) { return GetRate(that, refresh); } // Get the average frame rate (number of times the image buffer is updated // per second) since the last call to X11DisplayGetFrameRate() or // X11DisplayShow() // Input: // that: the X11Display instance // Output: // Return the frame rate float X11DisplayGetFrameRate(X11Display* const that) { return GetRate(that, frame); } // Return the next event in the queue of events // Input: // that: the X11Display instance // Output: // Pop the next event from the queue and return it. If there was no event in // the queue an event with type == 0 is returned instead. X11DisplayEvt X11DisplayGetNextEvent(X11Display* const that) { // If there are events waiting in the buffer if (that->evtHead != that->evtTail) { // Update the head and tail and return the event X11DisplayEvt evt = that->evts[that->evtTail]; that->evtTail = (that->evtTail + 1) % EVT_BUFFER_SIZE; return evt; // Else, there is no event waiting in the buffer } else { // Return a "no event" return (X11DisplayEvt){0}; } } // Flush the event queue // Input: // that: the X11Display instance void X11DisplayFlushEvent(X11Display* const that) { that->evtHead = that->evtTail; } // Get the las known position of the pointer in the display // Input: // that: the X11Display instance // Output: // Return the last known position. X11DisplayPos X11DisplayGetPointerPos(X11Display const* const that) { return that->pointerPos; } // Get the current rendering buffer. // Input: // that: the X11Display instance // Output: // Return the buffer to write on. The content of the buffer is undefined. // The width and height of the buffer may be different from the previous // buffer. X11DisplayBuffer X11DisplayGetBuffer(X11Display* const that) { // Ensure the buffer's dimensions match the current window dimensions X11DisplayBuffer* buffer = that->buffers + that->inputBuffer; unsigned int width = that->width; unsigned int height = that->height; if(width != buffer->width || height != buffer->height) { unsigned char* rgb = *((unsigned char**)&(buffer->rgb)); rgb = realloc(rgb, width * height * 3); memset(rgb, 0, width * height * 3); *((unsigned char**)&(buffer->rgb)) = rgb; *((unsigned int*)&(buffer->width)) = width; *((unsigned int*)&(buffer->height)) = height; } // Return the buffer return *buffer; } // Publish the current editing buffer // Input: // that: the X11Display instance void X11DisplayPublish(X11Display* const that) { // If the third buffer is available int idxBuffer = (that->inputBuffer + 1) % 3; if(idxBuffer != that->outputBuffer) { // Update the input buffer index that->inputBuffer = idxBuffer; } // Update the frame rate ++(that->rates[frame].count); } // Get the elapsed time in millisecond since the display is shown // Input: // that: the X11Display instance // Output: // Return the elapsed time. unsigned long long X11DisplayGetTimeMs(X11Display const* const that) { // Measure and return the elapsed time struct timespec now; clock_gettime(CLOCK_MONOTONIC, &now); unsigned long long timeMs = (now.tv_sec * 1000 + now.tv_nsec / 1000000) - (that->timer.tv_sec * 1000 + that->timer.tv_nsec / 1000000); return timeMs; } // Clone of asprintf static char* StrCreate(char* fmt, ...) { char* str = NULL; char c[1]; va_list argp; va_start(argp, fmt); int len = vsnprintf(c, 1, fmt, argp) + 1; va_end(argp); str = malloc(len); if(str != NULL) { va_start(argp, fmt); vsnprintf(str, len, fmt, argp); va_end(argp); } return str; }

Download the code here or with the command wget https://baillehachepascal.dev/2022/Data/X11/x11display.tar.gz, and extract it with tar xvf x11display.tar.gz.

Edit on 2023/07/28: I've modified the tarball such as it extract in a subdirectory 'X11Display' instead of the current directory.