[Xcb] Some comments on XCB

[Jeremy A. Kolb]

So what do we do about naming conventions?  We really need a standard 
convention, something readable.  If there is one, it is not on the wiki.  
I can write one if need be.  But we do need a convention with 
types/variable names/etc..

As for the XCBAux libs it may be a good idea to sit down and figure out 
what needs to go in those and how we should break up extension specific 
auxilliary functions.  I can think of a few for record/randr that would be 
nice to have.

Once we get a design I can toss it up on the wiki.  But I think this stuff 
does need to be standardized and probably sooner rather than later.

Jeremy

On Tue, 31 May 2005, Jamey Sharp wrote:

> I wrote a detailed reply to this a few days after you sent it, Carl, but
> just as I finished, Evolution ate it. I was too frustrated about that to
> re-type it at the time. I'll try again now.
> 
> On Mon, 2005-05-16 at 15:57 -0700, Carl Worth wrote:
> > The first thing I ran across was an inconsistent case convention in
> > XCB types. I found the following in the code I was using:
> > 
> > 	XCBConnection
> > 	XCBGCONTEXT
> > 	XCBDRAWABLE
> > 	XCBVISUALTYPE
> > 	XCBRenderPICTURE
> > 
> > The result is that it's impossible for me to discern a consistent rule
> > for capitalization. I imagine there might actually be a consistent
> > rule, but I would argue it's not helpful to the user, as it's not
> > discernible and therefore likely to just be a source of confusion and
> > consternation. (Not to mention the fact that three words strung
> > together in ALLCAPS as in XCBVISUALTYPE makes it REALLYHARDTOREAD even
> > when ThisIsBadEnough.)
> 
> Yeah, it's been mentioned occasionally on this list XCB's general policy
> of following Xlib's capitalization convention is maybe unfortunate. What
> you've noticed is that the protocol specifications' capitalization
> currently trumps anything else, which certainly is worse.
> 
> I fixed one of these sorts of issues back in the M4 era, and Josh
> provided a fine implementation of that fix in XSLT. The idea is to have
> the XML protocol description follow the English specification as closely
> as possible, and then automatically apply a case convention appropriate
> for the target language during code generation. So in the special case
> we handle already, "visual_type" is transformed to "VisualType" (or
> whatever): '_' is a word separator, and the first letter of each word is
> forced uppercase.
> 
> To fix this, I propose to:
>       * Add '-' and ' ' to the accepted separators, as these are often
>         used in protocol specs as well.
>       * Apply the above-described transformation to all function and
>         type names, and extend it to force the letters after the first
>         to lowercase.
>       * Add a new transformation with the same separators, to be used
>         for all structure fields and function parameter names. For C
>         this would presumably be all-lowercase and underscore separated.
>       * Mark-up the XML with spaces at word boundaries.
> 
> > The second thing I ran into is that the useful prototypes I needed to
> > consult while coding are in XCB/xproto.h but this file has a reckless
> > disregard for helpful whitespace, containing things like:
> 
> Josh did a great job fixing this. I think we can agree it's OK now?
> 
> > Another minor snag I hit was with specifically with the
> > XCBCreatePixmap call. If I have the pid of my new pixmap in
> > "drawable.pixmap", it's tempting to look at the prototype above and
> > think that I might need to pass "drawable" in for the drawable
> > parameter. ...
> > 
> > Maybe the "drawable" parameter just needs a more descriptive name to
> > indicate its purpose, (along similar lines as "XCBWINDOW parent" in
> > XCBCreateWindow). But what? "screen_drawable" ? I'm not sure.
> > 
> > It occurs to me that if we were just inventing a new API here, it's
> > the screen that is really relevant to XCBCreatePixmap, so passing an
> > XCBSCREEN* rather than an XCBDRAWABLE, (which the server uses to
> > identify the screen), would work fine and would be simpler. But, since
> > XCB is intended to be a tight binding to the actual protocol, that
> > would not be a good idea.
> 
> I think that would make the expected use cases more difficult. My
> reading of the intent of the request is to make it easy to create a
> pixmap that's compatible with some specific other window or pixmap, for
> later CopyArea operations. If a screen were required, then you'd need to
> wait a GetGeometry round-trip to find out the root of that other
> drawable before you could make your CreatePixmap request.
> 
> This means that your comparison with the "parent" argument of
> CreateWindow is apt, though. This is maybe more of a "cousin"?
> 
> I leave it to others to edit the X protocol specification, though. My
> goal is for XCB's XML descriptions to match the English specifications
> as closely as possible, and so I'm not inclined to fix this in XCB
> unless somebody fixes it in the English.
> 
> > OK, so finally, let's look at the code I came up with to get an
> > XCBDRAWABLE from a screen, (let's assume screen 0), to pass into this
> > parameter for XCBCreatePixmap. I wrote:
> > 
> > 	XCBSCREEN *root;
> > 	XCBDRAWABLE root_drawable;
> > 	root = XCBConnSetupSuccessRepRootsIter(XCBGetSetup(c)).data;
> > 	root_drawable.window = root->root;
> > 
> > Ouch. Am I bringing pain upon myself, or is there no more convenient
> > way to pull this off in XCB?
> 
> Well, in this case you don't need the 'root' temporary variable. ;-)
> 
> > Note that the equivalent code from Xlib is:
> > 
> > 	DefaultRootWindow (dpy)
> 
> Note too that XCB refuses to track the screen number for you, so any XCB
> equivalent is going to require that you provide the screen number too.
> 
> > I certainly won't recommend Xlib's namespace polluting naming
> > convention, but it is nice that there is a single call to get the job
> > done here.
> 
> Vincent's XCBAux bits, previously mentioned, I guess are the way to deal
> with this. I'm still waiting to see a coherent, orthogonal, etc. model
> appear for the functions in that library, but it makes a good
> development playground right now.
> 
> > Let me mention a few specifics about the block of XCB code above:
> > 
> > "XCBConnection" seems a fine name for the primary opaque handle.
> > 
> > "XCBConnSetupSuccessRep" seems rather unwieldy, but I can imagine the
> > name choice might be somewhat constrained by naming conventions. But,
> > assuming this name is as commonly used as I suspect, it would be
> > really nice to make it shorter if possible.
> 
> "ConnSetupSuccessRep" is a string that appears in the XML description.
> We can change that to anything we want. I picked it not long after
> starting work on XCB, and simply haven't touched it since. So what would
> you recommend?
> 
> > Is there a one-to-one mapping between XCBConnection and
> > XCBConnSetupSuccessRep? (I'm guessing so since one is opaque and one
> > is not). If so, is there really a benefit to passing the
> > XCBConnSetupSuccessRep* rather than the XCBConnection* to the iterator
> > fetch functions like XCBConnSetupSeccussRepRootsIter ? It leads to the
> > nesting in the calls above and also more use of the longer name. Could
> > something like this work instead (or in addition):
> > 
> > 	XCBConnectionRootsIter (c).data;
> 
> In normal usage, there certainly is one and only one setup data chunk
> for every connection. I could imagine somebody creating their own setup
> data chunk somehow, but I'm not sure how or why they would. So from an
> API perspective, this suggestion seems fine to me.
> 
> Due to code generation it's hard to implement, though, except by
> hand-writing wrapper functions like:
> 
> XCBSCREENIter XCBConnectionRootsIter(XCBConnection *c)
> {
>         return XCBConnSetupSuccessRepRootsIter(XCBGetSetup(c));
> }
> 
> And I have trouble seeing the point of that.
> 
> > Finally, once I do get an XCBSCREEN* through the above, I can find a
> > root->root XCBWINDOW but XCBCreatePixmap needs an XCBDRAWABLE
> > instead. Hence, I'm forced to do the root_drawable wrapping
> > above. This is a rather annoying side effect of the otherwise very
> > useful feature of extra type checking. Anyone have a suggestion for
> > simplifying this "casting" operation which is known to be safe in this
> > direction?
> 
> Two suggestions, and both have problems.
> 
> GCC has an extension for a "transparent_union" attribute for types (see
> http://gcc.gnu.org/onlinedocs/gcc-3.4.4/gcc/Type-Attributes.html). But
> "Transparent unions are designed for library functions that have
> multiple interfaces for compatibility reasons." I figure the
> non-portability makes this a non-option, but it sure is tempting.
> 
> I've previously demonstrated, with XCL, that GCC's optimizer can replace
> inline functions that do these type conversions with zero instructions,
> at least on x86. A function that unwraps the CARD32 from a window and
> wraps it in a drawable requires no C type-casts anywhere, keeping
> type-safety intact; but this still requires the syntax of a function
> call everywhere the cast is required. Probably worse is the problem that
> I don't know how to implement this portably: I think compilers that, for
> whatever reason, ignore the 'inline' keyword are going to do weird
> things, and I don't think this can be implemented in macros without
> using more GCC extensions.
> 
> (The third suggestion, of course, is "don't use C", but I guess we'd
> best not go there just now.)
> 
> > Anyway, I hope these few random thoughts might be useful. I know it's
> > nothing like a comprehensive overview of the API, but I did want to
> > pass along the few things that I ran into.
> 
> Yeah, this is great, Carl. Thanks!
> 
> --Jamey
> 
> _______________________________________________
> xcb mailing list
> xcb at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/xcb
>