[Xr] Xr surface management

[Carl Worth]

I'd like to pick up a discussion that had started on
render at xfree86.org but had never continued after that mailing list was
dissolved.

In November and December, Owen Taylor had some useful comments about
the Xr/Xc APIs. Since the recent code is starting to address some of
these, I'll respond here.

I'll break his original message into several separate messages to
enable new discussion on a per-topic basis as needed.

Long ago, on a mailing list far, far away,
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;
[...]
 >  * Shouldn't there be XrSetSurface (XrState *xrs, XcSurface *surface)
 >    instead of or in addition to XrSetDrawable, XrSetVisual?

This is in place now, as:

	void
	XrSetTargetSurface (XrState *xrs, XrSurface *surface);

To support this, there are new surface creation functions. A surface
can be created for an X drawable or a local image buffer. There's also
a mechanism (XrSurfaceCreateNextTo) to create a surface of the same
kind as an existing surface. Maybe that one could use a better name.

The XrSetTargetDrawable call is now a convenience function for
XrSurfaceCreateForDrawable and XrSetTargetSurface.

I'm always interested in API feedback, and I still have some open
questions as appear below in the prototypes for the new functions:

/* XXX: This is a mess from the user's POV. Should the Visual or the
   XrFormat control what render format is used? Maybe I can have
   XrSurfaceCreateForWindow with a visual, and
   XrSurfaceCreateForPixmap with an XrFormat. Would that work?
*/
XrSurface *
XrSurfaceCreateForDrawable (Display     *dpy,
                            Drawable    drawable,
                            Visual      *visual,
                            XrFormat    format,
                            Colormap    colormap);

XrSurface *
XrSurfaceCreateForImage (char           *data,
                         XrFormat       format,
                         int            width,
                         int            height,
                         int            stride);

XrSurface *
XrSurfaceCreateNextTo (XrSurface        *neighbor,
                       XrFormat         format,
                       int              width,
                       int              height);

/* XXX: One problem with having RGB and A here in one function is that
   it introduces the question of pre-multiplied vs. non-pre-multiplied
   alpha. Do I want to export an XrColor structure instead? So far, no
   other public functions need it. */
XrSurface *
XrSurfaceCreateNextToSolid (XrSurface   *neighbor,
                            XrFormat    format,
                            int         width,
                            int         height,
                            double      red,
                            double      green,
                            double      blue,
                            double      alpha);

void
XrSurfaceDestroy(XrSurface *surface);

-Carl

-- 
Carl Worth                                        
USC Information Sciences Institute                      cworth at isi.edu