[Xcb] xcb_render_util_composite_text

[Ian Osgood]

I'm starting to write the XCB renderutil equivalent of libXrender's  
XRenderCompositeText, and would like to discuss possible interfaces.  
My goal is to keep the API as close to the wire protocol as possible  
while minimizing user error, avoiding duplicated code, and retaining  
full flexibility. I expect then first user of this interface to be  
the cairo XCB backend.

Please forward this to anyone you know who has used the  
XRenderCompositeText interfaces. Later I could implement  
composite_string methods which would be as convenient as  
XRenderCompositeString but layered on top of the composite_text methods.

The wire protocol for CompositeGlyphs consists of a base request  
containing among other parameters the initial GLYPHSET (an xid) and a  
stream of commands (GLYPHELT + data payload).

Each request flavor (8,16,32) contains a stream of two possible  
command types:

1. a GLYPHELT followed by a short array of glyph indices
	uint8_t count
	uint8_t pad[3]
	uint16_t dx, dy
	uint{8,16,32}_t glyphs[count]
where the maximum count is 252 for text_8, and 254 otherwise.

2. a GLYPHELT with count==255 followed by a new GLYPHSET to switch to
	uint8_t count = 255
	uint8_t pad[3]
	uint16_t dx = dy = 0
	xcb_render_glyphset_t glyphset


I'm thinking that a stream-like API captures this flexibly yet simply.

   composite_text_stream_t stream;
   stream = composite_text_stream(initial_glyphset,  
total_glyph_count, total_glyphset_changes)
   composite_text_glyphs_8( stream, uint32_t count, uint8_t *glyphs,  
int16_t dx, int16_t dy)
   composite_text_glyphs_16( stream, uint32_t count, uint16_t  
*glyphs, int16_t dx, int16_t dy)
   composite_text_glyphs_32( stream, uint32_t count, uint32_t  
*glyphs, int16_t dx, int16_t dy)
   composite_text_change_glyphset( stream, xcb_render_glyphset_t  
glyphset)
   xcb_void_cookie_t  composite_text( connection, op, src, dst,  
mask_format, src_x, src_y, stream )
   xcb_void_cookie_t  composite_text_checked( connection, op, src,  
dst, mask_format, src_x, src_y, stream )

This would build up the stream of commands incrementally. The stream  
is allocated in _stream and deallocated when sent.

Advantages:
* type-safe
* close to wire protocol
* allows optional preallocation of the potentially large stream buffer
* abstracts the 8/16/32 request types
* abstract enough to allow command merging underneath if desired
* should result in less duplicated code to handle text_8/16/32 and  
checked/unchecked
* no extra types (besides opaque stream); libXrender exposes XGlyphElt 
{8,16,32) to bundle glyphset, glyphs, and dx/dy together.

Disadvantages:
* allows incorrectly mixing 8,16,32 glyphs (though this would be  
detected at runtime)
* different from the libXrender API

Please let me know what you all think, especially if I have mistaken  
how the XRender protocol works.

Ian