XCB programming is hard

I have been looking at writing a program with XCB today. I seem to pick projects that are an exercise in undocumented frustration.

All I wanted to do was have an x window open and be able to plot an arbitrary changeable image to it (no I am not writing yet another image viewer!). The XCB documentation seems to be a cross between "good luck with that" and some rather erratic doxygen output.

The utility libraries are rather skimpy on examples and its tiresome worrying that when you feed any of the xcb function names into Google (web or codesearch) there are very, very few hits beyond the freedesktop API docs.

My favourite has to be the xcb_image_create documentation, go on I challenge anyone to follow that logic without going and reading the sources! The answer (afaict) is that if you pass a pointer in base that pointer will be freed by xcb_image_destroy otherwise the data pointer will be used, unless the bytes value is too small in which case memory will be allocated with malloc and the passed pointer ignored.

Anyhow, I have succeeded and the result is below, mainly so I do not loose it :-)

/* XCB application drawing an updating bitmap in a window
*
* Inspired by the xcb black rectangle in a window example
*
* Copyright 2010 V. R. Sanders, released under the MIT licence
*/

/* compile with:
*   gcc -Wall -lxcb-icccm -lxcb -lxcb-image -o disp disp.c
*/

#include <string.h>

#include <xcb/xcb.h>
#include <xcb/xcb_image.h>
#include <xcb/xcb_atom.h>
#include <xcb/xcb_icccm.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>

static xcb_format_t *
find_format (xcb_connection_t * c, uint8_t depth, uint8_t bpp)
{
 const xcb_setup_t *setup = xcb_get_setup(c);
 xcb_format_t *fmt = xcb_setup_pixmap_formats(setup);
 xcb_format_t *fmtend = fmt + xcb_setup_pixmap_formats_length(setup);
 for(; fmt != fmtend; ++fmt)
  if((fmt->depth == depth) && (fmt->bits_per_pixel == bpp)) {
   /* printf("fmt %p has pad %d depth %d, bpp %d\n",
      fmt,fmt->scanline_pad, depth,bpp); */
   return fmt;
  }
 return 0;
}

void
fillimage(unsigned char *p, int width, int height)
{
 int i, j;
 for(i=0; i < width; i++)
 {
  for(j=0; j < height; j++)
  {
   if((i < 256)&&(j < 256))
   {
    *p++=rand()%256; // blue
    *p++=rand()%256; // green
    *p++=rand()%256; // red
   } else {
    *p++=i%256; // blue
    *p++=j%256; // green
    if(i < 256)
     *p++=i%256; // red
    else if(j < 256)
     *p++=j%256; // red
    else
     *p++=(256-j)%256; // red
   }
   p++; /* unused byte */
  }
 }
}

xcb_image_t *
CreateTrueColorImage(xcb_connection_t *c,
       int width,
       int height)
{
 const xcb_setup_t *setup = xcb_get_setup(c);
 unsigned char *image32=(unsigned char *)malloc(width*height*4);
 xcb_format_t *fmt = find_format(c, 24, 32);
 if (fmt == NULL)
  return NULL;

 fillimage(image32, width, height);

 return xcb_image_create(width,
    height,
    XCB_IMAGE_FORMAT_Z_PIXMAP,
    fmt->scanline_pad,
    fmt->depth,
    fmt->bits_per_pixel,
    0,
    setup->image_byte_order,
    XCB_IMAGE_ORDER_LSB_FIRST,
    image32,
    width*height*4,
    image32);
}

int
main (int argc, char **argv)
{
 xcb_connection_t *c;
 xcb_screen_t *s;
 xcb_window_t w;
 xcb_pixmap_t pmap;
 xcb_gcontext_t gc;
 xcb_generic_event_t *e;
 uint32_t mask;
 uint32_t values[2];
 int done=0;
 xcb_image_t *image;
 uint8_t *image32;
 xcb_expose_event_t *ee;
 char *title="Hello World!";
 xcb_size_hints_t *hints;

 /* open connection with the server */
 c = xcb_connect (NULL, NULL);

 if (!c) {
  printf ("Cannot open display\n");
  exit (1);
 }

 s = xcb_setup_roots_iterator (xcb_get_setup (c)).data;

 /* printf("root depth %d\n",s->root_depth); */

 /* create image */
 image = CreateTrueColorImage(c, 640, 480);
 if (image == NULL) {
  printf ("Cannot create iamge\n");
  xcb_disconnect(c);
  return 1;
 }
 image32 = image->data;

 /* create window */
 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
 values[0] = s->white_pixel;
 values[1] = XCB_EVENT_MASK_EXPOSURE |
  XCB_EVENT_MASK_KEY_PRESS |
  XCB_EVENT_MASK_BUTTON_PRESS;

 w = xcb_generate_id (c);
 xcb_create_window (c, XCB_COPY_FROM_PARENT, w, s->root,
      10, 10, image->width, image->height, 1,
      XCB_WINDOW_CLASS_INPUT_OUTPUT,
      s->root_visual,
      mask, values);

 /* set title on window */
 xcb_set_wm_name(c, w, STRING, strlen(title), title);

 /* set size hits on window */
 hints = xcb_alloc_size_hints();
 xcb_size_hints_set_max_size(hints, image->width,image->height);
 xcb_size_hints_set_min_size(hints, image->width,image->height);
 xcb_set_wm_size_hints(c, w, WM_NORMAL_HINTS, hints);

 /* create backing pixmap */
 pmap = xcb_generate_id(c);
 xcb_create_pixmap(c, 24, pmap, w, image->width, image->height);

 /* create pixmap plot gc */
 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND;
 values[0] = s->black_pixel;
 values[1] = 0xffffff;

 gc = xcb_generate_id (c);
 xcb_create_gc (c, gc, pmap, mask, values);

 /* put the image into the pixmap */
 xcb_image_put(c, pmap, gc, image, 0, 0, 0);

 /* show the window */
 xcb_map_window (c, w);
 xcb_flush (c);

 /* event loop */
 while (!done && (e = xcb_wait_for_event (c))) {
  switch (e->response_type) {
  case XCB_EXPOSE:
   ee=(xcb_expose_event_t *)e;
   /* printf ("expose %d,%d - %d,%d\n",
      ee->x,ee->y,ee->width,ee->height); */
   xcb_copy_area(c, pmap, w, gc,
          ee->x,
          ee->y,
          ee->x,
          ee->y,
          ee->width,
          ee->height);
   xcb_flush (c);
   image32+=16;
   break;

  case XCB_KEY_PRESS:
   /* exit on keypress */
   done = 1;
   break;

  case XCB_BUTTON_PRESS:
   fillimage(image->data, image->width, image->height);
   memset(image->data, 0, image32 - image->data);
   xcb_image_put(c, pmap, gc, image, 0, 0, 0);
   xcb_copy_area(c, pmap, w, gc, 0,0,0,0,image->width,image->height);
   xcb_flush (c);
   break;
  }
  free (e);
 }

 /* free pixmap */
 xcb_free_pixmap(c, pmap);

 /* close connection to server */
 xcb_disconnect (c);

 return 0;
}

Claudia black makes this look good

OK maybe the title is a bit of a reach, but she is pretty and my topic is dull.

It is the school holidays and between entertaining the kids I have been experimenting with the vala (see there is the link to the title) language. Overall I really like it, building a usable graphical GTK application is a snap and that side of it works well.

Unfortunately, and here comes a a whole pile of fail, the documentation is lacking, not just poor but mostly non-existent. You rapidly discover yourself using the Glib and GTK library documentation to try and infer how things work.

Underneath, the vala compiler is clever, it is really a c code generator. It takes your vala source file converts it to c and compiles it. When it works smoothly it works very well, when something is not quite right you can end up with a large pile of pieces complete with the C compiler spitting out cryptic nonsense.

This is all exasperated to new heights of madness when you want to access a simple c library. I say simple because if you want to access a Glib based library its easy and "there is an app for that". Because vala is object oriented c interfaces must be described as an object. This description is performed using vapi files. The file format is documented by the simple approach of "we already wrapped a load of libs go look at their vapi files"

For my small starter project I wanted to access a tiny c library I had written. The entire interface described in a single header header (excluding copyright) is:

typedef enum motor_dir {
 motor_off = 0,
 motor_forward = 1,
 motor_back = 2,
 motor_brake = 3,
} motor_dir;

int edgerbtarm_init(void);
int edgerbtarm_close(void);
void edgerbtarm_ctrl_motor(int motorn, motor_dir direction);

Yes that is it! one enum, an initialise a finalise and a single operation function. The vapi file I came up with after a great deal of trial, error and head scratching was.

[CCode(cheader_filename = "libedgerbtarm.h",
    lower_case_cprefix = "edgerbtarm_",
    cprefix = "")]
    namespace edgerbtarm {
 [CCode(cprefix = "motor_")]
 public enum motor_dir {
     off,
     forward,
     back,
     brake
 }

  public int init();
  public int close();
  public void ctrl_motor(int motorn, motor_dir direction);
}

This seemed to work until I tried to use the motor_dir type within my vala code at which point the c compiler started throwing errors about undeclared macros

arm.vala.c:297: error: ‘EDGERBTARM_TYPE_MOTOR_DIR’ undeclared (first use in this function)

I struggled for some time and finally ended up asking my friend Enrico for help. He initially suggested I simply use an int instead of the motor_dir type and cast when I needed to. This approch worked and let me compile the program, it did however seem a bit grubby and removed the type safety of the enum.

Then Enrico came up with the "correct" solution. the enum description in the in the vapi file needed an extra parameter so vala would know the enum did not have a Glib type...yeah it was obvious to me too :-/

so by altering the vapi file enum declaration to

[CCode(cprefix = "motor_", has_type_id = false)]
public enum motor_dir {
   off,
   forward,
   back,
   brake
}

Everything works as you might expect and the motor_dir enum can be used as a type within the vala program with no more fuss.

So the outcome of all this is that while vala is an interesting language which I may well use again in future, one should be aware that it is still very immature as a solution and has nowhere near enough documentation especially round the awkward stuff where it needs it most.