ogl-sample
[Top] [All Lists]

Re: [ogl-sample] Parameter semantics in .spec files

To: ogl-sample@xxxxxxxxxxx
Subject: Re: [ogl-sample] Parameter semantics in .spec files
From: Sven Panne <Sven_Panne@xxxxxxxxxxxxxxx>
Date: Fri, 22 Mar 2002 09:57:45 +0100
References: <3C96FF1D.689051E0@xxxxxxxxxxxxxxx> <20020321013100.C19046@xxxxxxxxxxxxxxxxxxxx>
Reply-to: ogl-sample@xxxxxxxxxxx
Sender: owner-ogl-sample@xxxxxxxxxxx
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

<Prev in Thread] Current Thread [Next in Thread>