[cairo] cairo macros and public API

[Chris Vine]

Hi,

I am porting some pre-GtkPrint code to use the GtkPrint print system,
to print some monotone tiff images.

The easiest way of doing that appears to be to convert the tiff images
to raw (one bit per pixel) PBM format and load them into a buffer to
create a cairo surface with cairo_image_surface_create_for_data() with
the CAIRO_FORMAT_A1 format, from which I can then obtain a cairo
pattern with the tiff image on it.

The cairo documentation states that with CAIRO_FORMAT_A1 format "Pixels
are packed together into 32-bit quantities. The ordering of the bits
matches the endianess of the platform. On a big-endian machine, the
first pixel is in the uppermost bit, on a little-endian machine the
first pixel is in the least-significant bit".  Accordingly, with big
endian systems it appears I can do a direct PBM pixel raster transfer
to the image buffer array of type unsigned char, because the raw PBM
standard states that pixels bits are packed into bytes with an order of
storage of most significant bit to least significant bit.

It also appears to follow that for little endian systems, although the
bytes in PBM format would be in the correct order (left hand packed
pixels to least significant byte), the bits in each byte are not
- the bit order in each byte would require to be reversed.

If I have that part of it correct, then the cairoint.h header provides a
convenience CAIRO_BITSWAP8_IF_LITTLE_ENDIAN macro which seems to be just
what is required, but it is not listed in the index of symbols in the
cairo documentation. Does this mean that it is for internal cairo use
only and that I should not rely on it as part of the public cairo API?

Regards,

Chris