If "pure XCB" OpenGL is impossible, then what's the use of the XCB/GLX API found in xcb/glx.h?

Question

The official XCB documentation tells us that using OpenGL purely with XCB is impossible: one must also use Xlib.

This post by Bart Massey (creator of XCB) doesn't suggest this should be impossible. But I'm sure I'm missing something.

I've spent hours browsing xcb/glx.h, which is nicely organized here. It seems to me like a full-fledged API. But I can't get it to work.

Questions

1. Is the XCB/GLX API useless? What's the purpose of xcb/glx.h?
2. How can one use the API?

(Note. This is part of an ongoing effort to understand how XCB works.)

Relevant SO thread.

---

Secondary, long-winded stuff

If someone's willing to take a crack at it, here's the source from the original post at the XCB mailing list, stripped down a bit and placed into a single file.

You'll notice xcb_glx_make_context_current returns error 169 (no idea what that means), but only if xcb_glx_create_window takes 0 and NULL for its last two arguments. These arguments involve an array of attributes, which seems to be returned by the function xcb_glx_create_window_attribs, but I can't figure out how to use it...

The long helper functions before int main() are only meant two return two integers, xcb_glx_fbconfig_t fbconfig xcb_visualid_t glx_visual, corresponding to the first "matching" framebuffer configuration. On my platform, these are 0xa7 and 0x24. They are precisely what an Xlib/GLX routine (which actually works) returns, so I know my chosen framebuffer config is fine.

So, the problem seems to happen somewhere between xcb_glx_create_window and xcb_glx_make_context_current...

// gcc main2.c -o main -lxcb -lxcb-glx -lGL && ./main2
// TODO free replies

#include <stdio.h>
#include <stdlib.h>
#include <xcb/glx.h>
#include <GL/gl.h>

#define W 1024
#define H 1024

// parameter types returned by xcb_glx_get_fb_configs
#define GLX_DRAWABLE_TYPE               0x8010
#define GLX_RENDER_TYPE                 0x8011
#define GLX_DOUBLEBUFFER                5
#define GLX_RED_SIZE                    8
#define GLX_GREEN_SIZE                  9
#define GLX_BLUE_SIZE                   10
#define GLX_RGBA_BIT                    0x00000001
#define GLX_RGBA_TYPE                   0x8014
#define GLX_STENCIL_SIZE                13
#define GLX_DEPTH_SIZE                  12
#define GLX_BUFFER_SIZE                 2
#define GLX_ALPHA_SIZE                  11
#define GLX_X_RENDERABLE                0x8012

#define GLX_FBCONFIG_ID                 0x8013
#define GLX_VISUAL_ID                   0x800b

#define GLX_WINDOW_BIT                  0x00000001
#define GLX_PIXMAP_BIT                  0x00000002
#define GLX_PBUFFER_BIT                 0x00000004


// ------------------------------------------------------------------------------------------------
// fbconfig and visual?
uint32_t glx_attrs[] = {
  GLX_DOUBLEBUFFER, 1,
  GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT|GLX_PIXMAP_BIT|GLX_PBUFFER_BIT,
  GLX_X_RENDERABLE, 1,  
  GLX_RED_SIZE, 8,
  GLX_GREEN_SIZE, 8,
  GLX_BLUE_SIZE, 8,
  GLX_ALPHA_SIZE, 8,
  GLX_STENCIL_SIZE, 8,
  GLX_DEPTH_SIZE, 24,
  GLX_BUFFER_SIZE, 32,
  GLX_RENDER_TYPE, GLX_RGBA_BIT,
};

// ------------------------------------------------------------------------------------------------
// This function searches for an @param prop_name in the @param property list of properties of size @param prop. Prop is property count and not buffer size.
uint32_t glx_get_property(const uint32_t* property, const uint props, uint32_t prop_name){
  uint i=0;
  while(i < props*2){
      if(property[i] == prop_name)
        return property[i+1];
      else i += 2;
  }
  return -1;
}

// This function chooses and returns specific fbconfig id depending on attributes specified in 
// @param attrib list. @param attribsz is the number of properties(not list size)
int32_t glx_choose_fbconfig(xcb_connection_t* connection, uint32_t screen_num, uint32_t* attrib, uint32_t attribsz){
  xcb_generic_error_t* xerror;

  xcb_glx_get_fb_configs_reply_t* fbconfigs = xcb_glx_get_fb_configs_reply(connection, xcb_glx_get_fb_configs(connection, screen_num), NULL);
  uint32_t* prop = xcb_glx_get_fb_configs_property_list(fbconfigs);

  uint32_t* fbconfig_line   = prop;
  uint32_t  fbconfig_linesz = fbconfigs->num_properties * 2;

  for(uint i=0 ; i<fbconfigs->num_FB_configs; i++){  // for each fbconfig line
      uint good_fbconfig = 1;

    for(uint j=0 ; j<attribsz*2; j += 2){  // for each attrib
    // if property found != property given
        if(glx_get_property(fbconfig_line, fbconfigs->num_properties, attrib[j]) != attrib[j+1]) {
            good_fbconfig = 0; // invalidate this fbconfig entry, sine one of the attribs doesn't match
            break;
        }
    }

    // if all attribs matched, return with fid
    if(good_fbconfig){
        uint32_t fbconfig_id = glx_get_property(fbconfig_line, fbconfigs->num_properties , GLX_FBCONFIG_ID);
        free(fbconfigs);
        return fbconfig_id;
    }

    fbconfig_line += fbconfig_linesz; // next fbconfig line;
  }
  return -1;
}

// This function returns @param attrib value from a line containing GLX_FBCONFIG_ID of @param fid
// It kind of queries particular fbconfig line for a specific property.
uint32_t glx_get_attrib_from_fbconfig(xcb_connection_t* connection, uint32_t screen_num, uint32_t fid, uint32_t attrib){
  xcb_glx_get_fb_configs_reply_t* fbconfigs = xcb_glx_get_fb_configs_reply(connection, xcb_glx_get_fb_configs(connection, screen_num), NULL);
  uint32_t* prop   = xcb_glx_get_fb_configs_property_list(fbconfigs);

  uint i = 0;
  uint fid_found = 0;
  while(i < fbconfigs->length){
    if(prop[i] == GLX_FBCONFIG_ID) {
      if(prop[i+1] == fid){
        fid_found = 1;
        i -= i%(fbconfigs->num_properties * 2); // going to start of the fbconfig  line
        uint32_t attrib_value = glx_get_property(&prop[i], fbconfigs->num_properties, attrib);
        free(fbconfigs);
        return attrib_value;
      }
    }
    i+=2;
  }
  if(fid_found) printf("glx_get_attrib_from_fbconfig: no attrib %u was found in a fbconfig with GLX_FBCONFIG_ID %u\n", attrib, fid);
  else printf("glx_get_attrib_from_fbconfig: GLX_FBCONFIG_ID %u was not found!\n", fid);
  return -1;
}

// ------------------------------------------------------------------------------------------------
int main(){
  xcb_generic_error_t* xerror; // To hold errors!
  int screen_number;

  xcb_connection_t* connection = xcb_connect(NULL, &screen_number);
  xcb_screen_t* screen = xcb_setup_roots_iterator(xcb_get_setup(connection)).data;   // getting the default screen
  printf("screen %d  root %d\n", screen_number, screen->root);

  xcb_colormap_t    colormap    = xcb_generate_id(connection);  // generating XID's for our objects!
  xcb_window_t      window      = xcb_generate_id(connection);
  xcb_glx_context_t glx_context = xcb_generate_id(connection);
  xcb_glx_window_t  glx_window  = xcb_generate_id(connection);

  // ----------------------------------------------------------------------------------------------
  xcb_glx_query_version_reply_t* glx_version = xcb_glx_query_version_reply(connection, xcb_glx_query_version(connection, 0, 0), NULL);
  printf("glx %d.%d  response_type %x  pad0 %x  sequence %x  length %d\n",
    glx_version->major_version, glx_version->minor_version, glx_version->response_type,
    glx_version->pad0, glx_version->sequence, glx_version->length);

  // ----------------------------------------------------------------------------------------------
  xcb_glx_fbconfig_t fbconfig   = glx_choose_fbconfig(connection, screen_number, glx_attrs, sizeof(glx_attrs)/2/sizeof(uint32_t));
  xcb_visualid_t glx_visual     = glx_get_attrib_from_fbconfig(connection, screen_number, fbconfig, GLX_VISUAL_ID);
  printf("fbconfig %x  glx_visual %x\n", fbconfig, glx_visual);

  // ----------------------------------------------------------------------------------------------
  xcb_glx_create_new_context(connection, glx_context, fbconfig, screen_number, GLX_RGBA_TYPE, 0, 1);  // New-style context?
  // xcb_glx_create_context(connection, glx_context, glx_visual, 0, 0, 1);  // Alt method! Old-style context?

  if(!(xcb_glx_is_direct_reply(connection, xcb_glx_is_direct(connection, glx_context), NULL)->is_direct))
    puts("glx context is not direct!");

  // ----------------------------------------------------------------------------------------------
  xcb_create_colormap(connection , XCB_COLORMAP_ALLOC_NONE, colormap, screen->root, glx_visual);  // creating colormap

  // creating a window, using our new colormap
  uint32_t window_mask = XCB_CW_BACK_PIXEL|XCB_CW_EVENT_MASK|XCB_CW_COLORMAP;
  uint32_t window_attrs[] = {0x444444, XCB_EVENT_MASK_EXPOSURE|XCB_EVENT_MASK_KEY_PRESS, colormap};

  xcb_create_window(connection, screen->root_depth, window, screen->root, 0,0, W,H, 0, XCB_WINDOW_CLASS_INPUT_OUTPUT, glx_visual, window_mask, window_attrs);
  xcb_map_window(connection, window);

  xcb_glx_create_window(connection, screen_number, fbconfig, window, glx_window, 0, NULL);
  xcb_flush(connection);

  // ----------------------------------------------------------------------------------------------
  xcb_glx_make_context_current_reply_t* reply_ctx = xcb_glx_make_context_current_reply(connection, xcb_glx_make_context_current(connection, 0, glx_window, glx_window, glx_context), NULL);
  if(!reply_ctx)  puts("ERROR  xcb_glx_make_context_current returned NULL!");
  xcb_glx_context_tag_t glx_context_tag = reply_ctx->context_tag;

  // alternative ?
  // xcb_glx_make_current_reply_t* reply_mc = xcb_glx_make_current_reply(connection, xcb_glx_make_current(connection, glx_window, glx_context, 0), NULL);
  // xcb_glx_context_tag_t glx_context_tag = reply_mc->context_tag;

  // ----------------------------------------------------------------------------------------------
  xcb_glx_get_error_reply(connection, xcb_glx_get_error(connection, glx_context_tag), &xerror);
  if(xerror)  printf("\nERROR  xcb_glx_get_error %d\n", xerror->error_code);

  // ----------------------------------------------------------------------------------------------
  xcb_generic_event_t* event;
  uint running = 1;
  while(running){
    event = xcb_poll_for_event(connection);
    if(event){
      switch (event->response_type) {
        case XCB_EXPOSE:
          glClearColor(0, .5, 1, 1);  // Blue
          glFlush();
          xcb_glx_swap_buffers(connection, glx_context_tag, glx_window);
          puts("Expose!");
          break;
        case XCB_KEY_PRESS: // exit on key press
          running = 0;
          break;
      }
    }
    free(event);
  }

  xcb_disconnect(connection);
}

Answer 1

What is important to understand here is that the XCB functions map directly onto the X11 protocol requests. This means that xcb_glx_* functions are direct mapping to X11 GLX protocol requests. See "Chapter 4" in https://www.khronos.org/registry/OpenGL/specs/gl/glx1.4.pdf It lists all available GLX requests. For example glAreTexturesResident maps to xcb_glx_are_textures_resident_* APIs from xcb/glx.h ( https://xcb.freedesktop.org/manual/glx_8h_source.html). In Khronos spec you can read what requests does what.

What's the purpose of xcb/glx.h?

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. [1]

Hardware initialization and the other GL stuff is done by openGL lib. And that is where the "other half" of the specification is implemented. On Linux libGL is provided by mesa (https://cgit.freedesktop.org/mesa/mesa/tree/src/glx). You can see that files in glx directory include Xlib.h, so I guess this is where the Xlib dependency comes from. Which explains 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." [1].

Is the XCB/GLX API useless?

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. [1]

So to get a pure XCB GLX, somebody needs to reimplement GLX in openGL lib:

• expose XCB based APIs to init a hardware and etc.
• should utilize the xcb_glx APIs to talk to X server, instead of Xlib.

The document from [1] says "The GLX system has two roles, it communicates with the X server and initializes client-side and hardware state."

xcb-glx takes care of the communication role. The other role (XCB-based OpenGL and GLX implementation) currently is not implemented and unlikely ever will.

"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." (see the exported symbols of libGL.so). To fulfil the second role we would need an equal API that uses XCB connection, windows, visuals.

EDIT: If the goal is write an X11 application that does not depend on Xlib, then perhaps Vulkan can be used for rendering.

[1] https://xcb.freedesktop.org/opengl/

Disclaimer: This is my understanding from what I gather.

Answer 2

To make the accepted answer even more clear: the xcb_glx_* functions are all completely useless. Do not use them, don't even bother including xcb/glx.h in your files (the example on the xcb website doesn't include them either). They will not work because the vendors do not implement the full functionality for them. They exist for the off chance that they decide to start implementing this functionality for xcb as well rather than only Xlib. Any time you need a glx function, your only option is Xlib, even if the some xcb function happens to work and give the same output.

The example code shown may work to varying degrees. On my computer, the window opens but the context is invalid. You may get more or less functionality. In any case, your code will almost certainly not work the same anywhere else, so please do not use xcb_glx_* at all. I certainly wasted enough of my own time on this so you don't have to 😅.