[Xr] Xr surface management

[Owen Taylor]

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

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

Hmm.

 - 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.
  
Regards,
                                        Owen