On Tue, Mar 19, 2002 at 10:04:29AM +0100, Sven Panne wrote:
> I'm a bit puzzled by the semantics of the .spec files: Given the 9
> possible combinations of directions (in, out, in/out) and transfer
> types (value, reference, array), what do they mean exactly? E.g.
> what are the exact differences between
> param foo BarPointer in value
In C-speak, roughly
> param foo Bar in reference
func(const Bar *foo)
> param foo Bar in array [<whatever>]
func(const Bar foo[<whatever>])
The generator scripts and spec files evolved over many years
(judging from the comments, early work was actually done by Gary Tarolli
about 10 years ago), and no formal grammar or well-defined semantics
document exists - the generator scripts *are* the documentation. It is a
sad opposite to the very well defined OpenGL API.
In any event: the param tags are just a (somewhat) language neutral
way to define parameter types. I know there were IDLs around over a
decade ago, they just didn't get used for this purpose. I think (wasn't
around at the time) that the spec files started out very simple and grew
and grew. 'in' basically means 'not modified' (in a contemporary C-speak
sense, this would usually be 'const', unless a simple scalar is being
passed), 'out' means 'may be modified'. 'value' and 'reference' are
pass-by-value and pass-by-reference (pointer) in C speak. 'array [size]'
means 'array of specified size, passed by reference'. The
[COMPSIZE(params)] terminology means that the expected size is some
complex function of the specified input parameters.
> Looking into gl.spec and glu.spec, these seem to be arbitrarily mixed.
They are not arbitrary; they map precisely onto the signatures
defined by the GL specification and the extension specifications whose
entry points are being documented. But the OpenGL API and the
conventions used even today in developing extension APIs came about back
when K&R C was still predominant, so e.g. 'const' doesn't tend to show
up much. This is unfixable at this point since changing it would break a
huge amount of code.
> Regarding "in/out": There is some confusion in the scripts and their
> comments whether it should read "in/out" or "inout", but neither of it
> is used in the .spec files, so this distinction is only academic and we
> could leave it out of the current discussion.
There is a lot of ugliness in the scripts; they have grown messily
for over a decade (there were IrisGL .spec scripts preceding these, back
into the late 80s), and are probably not nearly so general as they would
like to depict themselves to be. There is also a lot of stuff in the
scripts that looks like gratuitous bloat but is really there because,
behind the scenes, the spec files are used in many ways besides
generating header files (frex, on IRIX we have additional libspec tools
for generating dispatch tables at multiple levels of client and X
> Another point is the "retained" attribute, which probably means: "The
> location of this buffer is remembered across the current call" (vertex
> arrays, feedback buffers, etc.) and makes only sense for reference and
> array. Is this correct?
Yes. This mostly applies to GL client state, e.g. vertex arrays and
> So we are basically left with
> 2 (in,out) * 3 (value,reference,array) * 2 (optionally retained) = 12
> possible combinations. A translation of these into e.g. DCE IDL or its
> close relative Microsoft IDL would be very helpful.
I don't know IDL, unfortunately. It is easy (assuming you can get
the glext.h generator scripts working) to create a spec file entry with
parameters of all those different types and see what comes out the back
end, which might be some help.
> Looking for enlightenment,
I'm not sure anyone in the world completely understands this stuff -
spec files get used for so many different purposes by so many different
people on so many different platforms. The usages in the SI tree are
just the tip of the iceberg. Sometimes I get gl.spec entries from
vendors that contain stuff I haven't a hope of understanding, so you're
not alone in wanting enlightenment :-)