On Fri, Mar 22, 2002 at 09:57:45AM +0100, Sven Panne wrote:
> OK, perhaps the example was not really good, but I still can't grasp the
> intended differences between e.g.
> param foo BarPointer in value
> param foo Bar out reference
There really isn't one from the standpoint of what the .spec files
are used for today, though I wouldn't recommend using the prior form
because it throws away some information and requires another typemap
entry. Perhaps there should be 'canonical form' guidelines for writing
Note that the base type (e.g. Bar) usually maps onto a scalar type,
like one of the GLint/float/etc. or underlying C types. There are
weaknesses in the descriptive power of the .spec files (e.g. there is no
straightforward way to describe a C type like 'const GLXContext ctx')
which make it hard to describe some types. This can be covered for by
defining arbitrary out mappings in the auxiliary typemap file, which
controls how the symbolic type in the .spec file is converted into an
underlying real language type.
> Granted, they map to the same C types, but other languages have a much
> richer type system than C (which is not *that* difficult :-) and an array
> could be something very different from a pointer to the elements.
That's an inconsistency which could stand to be fixed. There are
lots of them, probably mostly because spec file entries were written by
different people at different times without good guidelines.
Underlying that, the OpenGL APIs, by design, only take scalars,
references to scalars, or arrays of scalars whose size and internal
structure are almost always not known at compile time, but are dependent
on other call parameters.
> No need for excuses: The .spec files are cool! If every API had such a
> detailed formal description, the world would be a better place... :-)
> Despite of my criticism, I like them, I'm only suggesting some minor
> improvements which would make them even more usable. IMHO it's a pity that
> e.g. Mesa uses its own variant of .spec files and declares the registry/SI
> stuff as a PITA...
Well, at least it's a reasonably useful PITA. I think Mesa's usage
may have mostly to do with Brian liking to write Python scripts instead
of Perl :-) I haven't looked at the Mesa build for a long time so don't
know what he's doing there; at some point, though, it would be nice to
get at least the GLX portion of the SI build brought up to date with the
changes they made to the SI GLX to support DRI, and integrated into
XFree86, so they could leverage the generator scripts to add extension
protocol wrappers more easily. Unfortunately when we initially open
sourced GLX we didn't include all the specfile/generator stuff, so that
wasn't an option for the Precision Insight guys at the time and nobody
seems to have had time for it since then.
> > [...] so you're not alone in wanting enlightenment :-)
> :-) To improve the situation a bit, I'm planning (after Easter?) to write
> down a few lines about the syntax and semantics of the two types of .spec
> files and put it up on my web site. There are very probably a lot of people
> using the .spec files who had to figure things out the hard way (like me),
> and some tiny bits of information could help a lot...
That would be nifty. If you want, I'd be happy to put such a
document in some suitable spot on oss.sgi.com too.