[Xcb] xcb_render_util_composite_text

[Jamey Sharp]

Hi Ian! I love this proposal, and as far as I can tell you've correctly
understood the protocol. I think bringing this up on the xorg list would
catch the attention of more of its prospective users though.

This approach should help with PolyText8 and PolyText16 from the core
protocol, too, as CompositeGlyphs was pretty clearly modeled after
those -- not that anybody should be using them any more.

On Sat, Oct 14, 2006 at 11:39:11AM -0700, Ian Osgood wrote:
>   composite_text_stream_t stream;
>   stream = composite_text_stream(initial_glyphset,  
> total_glyph_count, total_glyphset_changes)

Would this assume that the glyphs are 32-bit for the purposes of memory
allocation? And, I guess, also assume that every glyph might need its
own header with a non-zero dx or dy.

For code-as-documentation purposes, perhaps "max_glyph_count" and
"max_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)

I would have stuck the dx and dy parameters before count, since these
mean "First move the pen by (dx,dy) pixels, then draw count glyphs."

I note that this interface allows for a lot more than 254 glyphs per
call. :-) I guess this obligates us to split the glyph sequences into
254-glyph groups.

You haven't indicated how errors should be handled: mainly, what if the
caller tries to pass in more glyphs or glyphsets than they allocated
space for?

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

I wonder whether it should be deallocated when sent? The caller might
want to composite the same stream multiple times. They might also want
to free it without sending it, perhaps because an error occurred.

If we don't free it when sent, should we allow more glyphs to be added
afterwards? I'm thinking no: sending the stream makes it constant.

> Disadvantages:
> * allows incorrectly mixing 8,16,32 glyphs (though this would be  
> detected at runtime)

We can define sensible semantics for such a mixture, and it might be
useful. Semantically, these are all equivalent to 32-bit glyphs: the
server zero-extends the glyph indexes. When we're handed a sequence of
glyphs, we could check what the smallest possible representation is for
those glyphs. When we're ready to send the request, we can pick the
smallest request type that can handle the largest glyph we've been
handed.

Another obvious optimization we could apply is that if the last thing
added to the stream was a glyph sequence with fewer than 254 glyphs and
we're adding a glyph sequence with (dx,dy) == (0,0), then we can avoid
producing a new glyph header.

Of course, you noted that this interface was nice for being close to the
wire protocol. Since these optimizations don't affect the API you've
suggested, we could have a second constructor that disables them.
Perhaps composite_text_stream_raw? Probably raw mode would make it a
run-time error to mix 8-bit, 16-bit, or 32-bit glyph sequences in the
same stream.

> * different from the libXrender API

I think you've miscategorized this last point. It's an advantage. ;-)

--Jamey
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/xcb/attachments/20061014/23ae5954/attachment.pgp