[Xr] Xr surface management

Carl Worth cworth at east.isi.edu
Mon Apr 21 18:33:11 PDT 2003

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

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:

	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);

XrSurfaceDestroy(XrSurface *surface);


Carl Worth                                        
USC Information Sciences Institute                      cworth at isi.edu

More information about the cairo mailing list