[Xr] Dealing with groups in Xr

[Owen Taylor]

On Wed, 2003-04-23 at 11:53, Carl Worth wrote:

>  > The only thing I can think of to reduce the verbosity would be
>  > move back a bit in the direction you had before by introducing
>  > the idea of a "temporary surface" that is part of the state.
> [...]
>  > Legibility could be improved at the expense of potential
>  > efficiency by removing the x,y,width,height arguments
>  > from XrStartTemp.
> 
> I think I'd like that. Since these are just convenience functions,
> they might as well be as convenient as possible.

It strikes me that making the user worry about the bounding
box of primitives drawn onto the temporary group is wrong; if creating
larger empty pixmaps becomes a time or memory bottleneck, it can
certainly be optimized out, at the cost of a moderate amount
of complexity. (For instance, with a tiled representation of the
surface.)

> In which case, we'd have the same functionality that was there with
> Push/PopGroup except with the needed improvement that the compositing
> of the temporary surface is not tangled up with the end of drawing to
> the surface.
> 
> Maybe we could go back to the old names as well:
> 
> 	XrPushGroup, XrPopGroup, XrShowGroup
> 
> What think ye?

Sounds reasonable to me; the "Temp" namings are clutter the
code a lot if the code if they are used extensively.

Just as a thought, perhaps Enter/Leave is better than Push/Pop?
Push/Pop seems to indicate tat

>  >         /* Draw 3 circles to the punch surface, then cut
>  >          * that out of the main circle in the overlay
>  >          */
>  >         if (XrStartTemp (r, XrFormatARGB8, 0, 0, width, height)) {
>  >             draw_3circles (r, xc, yc, radius);
>  > 
>  >             XrEndTemp (r);
>  >             XrSetOperator (r, XrOperatorOutReverse);
>  >             XrShowTemp (r);
>  >         }
> 
> BTW, the bracing here helps readability quite a bit. The
> error-handling concept in Xr[*] has void functions everywhere. But
> discretionary braces could be quite nice in a case like this, even
> without the if statement.

Yeah - I thought about removing the error handling since it wasn't
a disaster if pushing the group failed and you drew garbage, but
I liked the effect of the bracing.

I could certainly see using gratuitous bracing in examples.

Though, it does bring another API to mind. Something like

 {
   XrSurface *s = XrEnterGroup (r, XrFormatARGB8);
   
   draw_3circles (r, xc, yc, radius);

   XrLeaveGroup (r);

   XrShowSurface (r, s, 0, 0);
   XSurfaceDestroy (s);
 }

Just another point on the convenience/flexibility scale...

> \[*] I don't think I've ever talked much about the error-handling API
> in Xr. The idea that Keith and I were working with is that checking
> the return status of every function gets messy in the code, and worse,
> nobody bothers to do it. So instead, the functions are all void, and
> the user can check the error status at any given point with:
> 
> 	XrStatus
> 	XrGetStatus(XrState *xrs);
> 
> In addition, any error condition in an XrState object makes it just
> shut down. That is, calling more Xr functions after an error will
> never cause a crash -- the functions just won't do anything.
> 
> This way it should be easy to keep code clean by calling a collection
> of Xr functions and then just checking once at the end to make sure
> everything worked.

If we are going to use the API directly in GTK+, rather than wrapping
it, an API that minimizes error checking is certainly appreciated.

Though something even stronger would be appreciated; I'd like to be able
to set an OOM  handler that simply aborted the program, so that you
didn't have to check your XrCreateSurface() and nothing else in the GTK+
program.

I assume XrCreateSurface() is going to fail asynchronously in the
remote-server case, so there is a certain problem with error returns
in any case.

Regards,
                                          Owen