[Xr] Xr surface management

Owen Taylor otaylor at redhat.com
Tue Apr 22 11:55:33 PDT 2003

On Mon, 2003-04-21 at 21:33, Carl Worth wrote:

> 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. 

Sounds good.

> 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.

XrSurfaceClone() ? (It's not necessarily identical, but has the
same genes)

> 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:

I haven't looked at the code yet, so this is just my opinion
from looking at the headers and guessing how they work.

> /* 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?
> */

People might find it useful to have pixmap+visual
as well, which is certainly not a problem to implement.
(Common case, you are rendering on a pixmap that you
will XCopyArea to the final drawable.)

The question that comes to mind is:

 When do you want to create a server side surface 
 for a non-RENDER server that doesn't match a visual/colormap
 on the server.

I believe the answer to this is "never". So, the operations
we want to make easy are:

 - Create a surface for an existing destination with a 
   specified visual/colormap.

 - Create a surface with unspecified location and
   specified format that can be rendered on efficiently.

Anything else can be as hard/messy/clumsily-named as it needs to be.

My suggestion for the primary interfaces might be to
drop the XrFormat argument from XrSurfaceCreateForDrawable
and add:
 XrSurfaceCreateScratch (Display *display,
                         XrFormat format,
                         int      width,
                         int      height);

That creates an image/pixmap as necessary and renders on it.

Then you maybe add a XrSurfaceCreateForDrawableFormat
that takes drawable and format and that applications don't

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


 - With the current Xr API, the colors here would have to be
   non-premultiplied, since red/green/blue have to 
   mean the same thing here as in XrSetRGBColor.

 - My gut feeling is that you should create an XrColor structure
   and use it. It seems like more than a hinderence than a help 
   with the current API, but experience with other graphics APIs 
   is that manipulating colors as a "whole" is a a common operation,
   and that if nothing else, applications will have to
   reinvent this wheel if you don't have it.

   void MyDrawImageText (XrState        state,
                         const char    *string,
                         const MyColor *fg_color,
                         const MyColor *bg_color);

   void MyColorSetHSV   (MyColor *color,
                         double   h,
                         double   s,
                         double   v);

   You can come up with lots of other APIs that become much
   uglier and harder to use if you pass around colors
   as r,g,b triplets.

More information about the cairo mailing list