Re: Some comments on Xr on Xc

On Nov 21, Owen Taylor wrote:
 > This is a write-up of observations on reading through the Xr
 > and Xc header files and a bit of the sources;

Owen, thanks for your feedback. This is precisely the kind of thing
that Xr/Xc need right now.

Some of the things you bring up are problems that Keith and I have
already discussed a bit in private. Now that more people are looking
at Xr/Xc, I'll keep any future discussions here on this list.

 > I have some general reservations about using a postscript-type API.  I
 > believe that on the low end, such an API is rather hard for
 > programmers to use -- they want "draw_circle", "draw_rectangle" type
 > primitives.

A toolkit built around Xr could easily add higher-level "primitives"
desired by application developers. That said, Xr is still far from
complete, but I'm cautious about putting too much into it. The current
plan is for Xr to have at least enough functionality to support the
rendering needs of PDF 1.4.

 >  * Shouldn't there be XrSetSurface (XrState *xrs, XcSurface *surface)
 >    instead of or in addition to XrSetDrawable, XrSetVisual?

Yes, I want XrSetSurface in place of XrSetDrawable and XrSetVisual. I
hadn't done this yet since the current implementation of Xc is
basically non-existent. I'm about to start on actually building an Xc
implementation that allows Xr to be used on X servers missing RENDER.

 >  * I think fonts are one area where following the lead of postscript
 >    is clearly a mistake. [...] we have a good font system now
 >    in fontconfig, and we should be integrating tightly with this.

Yes, the Xr font selection mechanism will be based around an exposed
function accepting fontconfig patterns.

 >    For font rendering, the functions should closely follow the
 >    lead of Xft.
 >
 >    [...]
 > 
 >     - Ability to draw with glyph codepoints instead of characters
 >     - Ability to draw with offsets for individual characters in the string
 >     - Ability to get metrics for characters and strings   

Right. This is all obviously missing.

I'd like to avoid a huge explosion in the font rendering APIs, and as
much as possible I'd like to have intuitively named functions. I don't
mind if the Xr API does not match Xft.

The plan is to support only the UTF8 encoding. So, can we drop all of
the 8/16/32/Utf8 distinctions from Xft?

If so, we could have the following functions for rendering characters
or glyph codepoints without explicit offsets:

	XrShowText
	XrShowGlyphs

The names can be changed if people have strong preferences.
/Show/Draw/ and /Text/String/ are obvious opportunities.

Beyond that, we need variations of each that allow explicit
offsets. I'm inclined to have a single structure for storing the
offsets for either a string or glyphs rather than separate
CharSpec/GlyphSpec structures ala Xft. Maybe something like:

	XrShowTextOffsets
	XrShowGlyphsOffsets

each accepting an array of XPointDouble?

Also, is the Xft model sufficient for application developers?
Postscript provides a substantial number of different variations for
adjusting offsets. Are there variations there that might be important?
I guess we can always add things later as needed.

 >  * It looks like the temporary surface created for XrPushGroup
 >    will always have the same format as the parent surface;
 >    I don't think this is right

You've peeked into the implementation here, which is clearly limited
and could be totally wrong. I'm more concerned about getting the API
right. Shouldn't XrPushGroup followed by XrSetFormat satisfy your need
here?

 >  * It looks to me like on XrPopGroup, the group is composited
 >    with the current alpha at the end of drawing the group,
 >    rather than the alpha before pushing the group; I think this
 >    is wrong - operations inside PushGroup/PopGroup shouldn't  
 >    affect drawing onto the parent surface.

I puzzled over this before implementing what you've seen, but I'm
still not totally satisfied.

I want a consistent model for drawing objects. For paths, there is
path creation followed by a drawing operation, (stroke or fill). The
values of the drawing parameters within the graphics state during path
creation do not affect the result. The only time these graphics
parameters matter is when the drawing operation is performed. In code,
rather than text:

	XrSetAlpha(0.2);	/* no effect */
	XrMoveTo(...);
	XrLineTo(...); XrLineTo(...); ...
	XrSetAlpha(0.5);
	XrFill(...);		/* fill uses alpha of 0.5 */

Consistency with this model is what prevents me from using the alpha
value from before the PushGroup.

But, you're also correct that graphics state modifications within a
group should not be visible outside the group.

So, the current semantics of XrPopGroup are that it contains an
implicit XrRestore contorted with an implicit "group draw operation"
in such a way that the group contents are rendered onto the parent
surface using the graphics state drawing parameters in effect at the
time of the XrPopGroup.

I'm very open to suggestions on how to clean this up. This might
involve making an explicit draw operation for the group that is
independent of an XrSave. Perhaps we simply need a way to composite
from one XrState object to another.

 >    I'm not sure how that translates to a reasonable C API - 
 >    maybe easiest just to expose the temporary buffers of 
 >    XrPushGroup/XrPopGroup as first-class objects

Something like this is probably what we need. And then perhaps
convenience functions that do common operations like
XrPushGroup/XrPopGroup. Currently, XrPushGroup/XrPopGroup cannot be
implemented in terms of other Xr functions.

 >  * Does the stack nature of XrSave/Restore really make sense
 >    outside the context of the Postscript language environment?
 >    Conceptually they are equivalent to a copy operation,
 >    and:
 >      
 >     XrState *local = XrStateCopy (xrs);
 >     /* Do stuff with local */
 >     XrStateDestroy (locale);

Yes, I do need a function to copy an XrState object. I still might
leave a stack inside Xr just to allow convenience XrSave/XrRestore
functions.

For naming, should the new function be XrCopy? or should I add
XrStateCopy and change XrCreate/XrDestroy to
XrStateCreate/XrStateDestroy?

 > On Xc:

Thanks for the suggestions. I'll look more closely at these as I begin
to actually implement Xc over the next few weeks.

-Carl

-- 
Carl Worth                                        
USC Information Sciences Institute                 [email protected]
3811 N. Fairfax Dr. #200, Arlington VA 22203		  703-812-3725