Jon Leech wrote:
> On Tue, Mar 19, 2002 at 10:04:29AM +0100, Sven Panne wrote:
> > [...]
> > param foo BarPointer in value
>
> In C-speak, roughly
>
> func(BarPointer foo)
>
> > param foo Bar in reference
>
> func(const Bar *foo)
>
> > param foo Bar in array [<whatever>]
>
> func(const Bar foo[<whatever>])
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
and
param foo Bar out reference
> > 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.
They *are* quite arbitrary in the sense that the .spec files (could)
contain much more info than plain C headers and that additional info is
sometimes lost due to glitches in the .spec files. Take for example
Build1DMipmaps. The Red Book tells me:
int gluBuild1DMipmaps(GLenum target, GLint components, GLint width,
GLenum format, GLenum type, void *data);
int gluBuild2DMipmaps(GLenum target, GLint components, GLint width,
GLint height, GLenum format, GLenum type,
void *data);
Constructs a series of mipmaps and calls glTexImage*D() to load the
images. The parameters for target, components, width, height, format,
type, and data are exactly the same as those for glTexImage1D() and
glTexImage2D(). A value of 0 is returned if all the mipmaps are
constructed successfully; otherwise, a GLU error code is returned.
Looking into glu.spec and gl.spec, the argument types are not really the
same:
Build1DMipmaps(target, internalFormat, width, format, type, data);
return Int32
param target TextureTarget in value
param internalFormat Int32 in value
param width SizeI in value
param format PixelFormat in value
param type PixelType in value
param data void in reference
TexImage1D(target, level, internalformat, width, border, format, type,
pixels)
return void
param target TextureTarget in value
param level CheckedInt32 in value
param internalformat TextureComponentCount in value
param width SizeI in value
param border CheckedInt32 in value
param format PixelFormat in value
param type PixelType in value
param pixels Void in array
[COMPSIZE(format/type/width)]
category drawing-control
dlflags handcode
glxflags client-handcode server-handcode
version 1.0
glxropcode 109
glsflags pixel-null pixel-unpack
glsopcode 0x00A0
wglflags client-handcode server-handcode
offset 182
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.
> [...] There is a lot of ugliness in the scripts; they have grown messily
> for over a decade [...]
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...
> [...] 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.
I've already done this, but as already mentioned, some info is lost during
this conversion because different .spec file constructs map to the same
C construct (e.g. 'in array' and 'in reference', etc.).
I was hoping to get some info marshaling like the following:
'Bar in value': The value of the given parameter is copied (marshaled in
IDL terms) to OpenGL.
'Bar out value': A pointer to an (uninitialized) buffer of a size large
enough to hold a Bar value is passed to OpenGL. The callee puts a value
into this buffer and this can be read (unmarshaled) by the caller after
the call.
Note that (un)marshaling might be more than plain copying if the caller
uses a different representation of values than the callee (which is
probably the case for non-C OpenGL bindings), remote calls take place,
etc.
> [...] 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...
Thanks for the information,
S.
--
Sven Panne Fon: +49/89/99567000 Fax: +49/89/99567461
BetaResearch GmbH, Betastr. 1, D-85774 Unterfoehring
mailto:Sven_Panne@xxxxxxxxxxxxxxx http://www.betaresearch.de
|