Missing enumeration type information

[Simon_Arbon]

I am currently trying to create a strongly typed OpenGL binding for the pascal language.
I need a list of which enumerations are used with which OpenGL commands so I can use typed enums.
This will allow the compiler to flag incorrect enums used in a function as an invalid typecast error, detecting in milliseconds an error that could take a programmer a lot longer to find.

The gl.spec file contains an entry for each command that specifies the type of each parameter, including the individual enum types that I need:
DrawPixels(width, height, format, type, pixels)
return void
param width SizeI in value
param height SizeI in value
param format PixelFormat in value
param type PixelType in value
param pixels Void in array [COMPSIZE(format/type/width/height)]
category VERSION_1_0_DEPRECATED # old: pixel-rw
dlflags handcode
glxflags client-handcode server-handcode
version 1.0
deprecated 3.1
glxropcode 173
wglflags client-handcode server-handcode
offset 257

This shows that the 3rd parameter is called format and has a type “PixelFormat”.
The enum.spec file lists the enum values for this type:
PixelFormat enum:
COLOR_INDEX = 0x1900
STENCIL_INDEX = 0x1901
DEPTH_COMPONENT = 0x1902
RED = 0x1903
GREEN = 0x1904
BLUE = 0x1905
ALPHA = 0x1906
RGB = 0x1907
RGBA = 0x1908
LUMINANCE = 0x1909
LUMINANCE_ALPHA = 0x190A
use EXT_abgr ABGR_EXT
use EXT_cmyka CMYK_EXT
use EXT_cmyka CMYKA_EXT
use SGIX_icc_texture R5_G6_B5_ICC_SGIX
use SGIX_icc_texture R5_G6_B5_A8_ICC_SGIX
use SGIX_icc_texture ALPHA16_ICC_SGIX
use SGIX_icc_texture LUMINANCE16_ICC_SGIX
use SGIX_icc_texture LUMINANCE16_ALPHA8_ICC_SGIX
use SGIX_ycrcb YCRCB_422_SGIX
use SGIX_ycrcb YCRCB_444_SGIX

The “use” lines refer to values defined elsewhere in enum.spec that are to be reused with this type and hence with the commands that use this type.
BUT the OpenGL specification shows several other enums for this command that are not listed here.
In enum.spec those values are defined but are never referenced.
There seem to be hundreds of other values, (90%+ of the values 0x8000 and higher) which are never referenced by a use clause in a type definition, and hence cant be traced back to the functions that use them.

Why are hundreds of use clauses “missing” from enum.spec?
If this information is no longer being updated in the spec files, then where is it?
Where can i find a simple (parsable) list of which enums are used by which command?

[Alfonse_Reinheart]

I need a list of which enumerations are used with which OpenGL commands so I can use typed enums.

That’s not going to happen. The list of which enums are taken by which functions is implementation dependent. It depends on the OpenGL version number, core vs. compatibility, and which extensions are supported.

Yes, you could take the union of all of these. But then, your compile-time information would be… not particularly useful. You would be able to tell when someone is misusing the API (sending an internal format as the pixel format). But that’s about it.

Oh, and then if a new extension or GL version comes out, your bindings have to be rebuilt.

Why are hundreds of use clauses “missing” from enum.spec?

Because they stopped caring about such things. Really, what good does it do them?

If this information is no longer being updated in the spec files, then where is it?

In the OpenGL specification and the various extension specs. AKA: hundreds of places scattered around in plain-text and PDF files. It’s not parsable.

Where can i find a simple (parsable) list of which enums are used by which command?

You ask that as if such a thing exists. It doesn’t.

OK, that may not be 100% true. It’s true for the ARB, but there may be 3rd party sources. I believe the MESA GL project maintains some kind of list.

[Simon_Arbon]

You would be able to tell when someone is misusing the API (sending an internal format as the pixel format). But that’s about it.
Which is kind of the whole point of using a strongly typed language in the first place.
But thats far from it, i can also setup my development environment to popup a list of valid enums automatically when i type a function name, and i can just click on it instead of typing it in.
That also means i dont need to keep looking up the exact spelling every time i need an enum (or memorising hundreds of them).
But more importantly i can then extend this basic type system to also protect some very unsafe OpenGL calls.
GetFloatv() for example could return a single integer or several, writing them to consecutive memory locations based on a pointer.
If a programmer tries to store CURRENT_RASTER_POSITION (4 floats) into a single float variable then it will overwrite other variables, something that is very hard to debug.
By grouping its enums into subtypes by the result size and using typed pointers, the compiler can check that the enum used is valid for the destination type.

The list of which enums are taken by which functions is implementation dependent. It depends on the OpenGL version number, core vs. compatibility, and which extensions are supported.
Most of that information is already in the spec files, so it would be possible to generate a header file for each version of OpenGL, or even for a specific project that used specific extensions.

Because they stopped caring about such things. Really, what good does it do them?
It would make it much easier to create documentation such as the quick-reference card and keep it in sync with the spec and header files.
The GPU manufacturers could use it to generate or check their parameter verification code.
But mainly it would allow people to generate proper bindings for other languages instead of the current situation where they just do a translation of the C header, which doesn’t contain the information that is required to use the advanced type-safety features of modern languages.
OpenGL is defined as being usable by any programming language, and as Khronos only provides C language bindings themselves, they have a responsibility to at least make it possible for other people to generate bindings for these other languages by providing the needed information.

I believe the MESA GL project maintains some kind of list.
I found APIspec.xml which is a nice modern XML format that details the enums used with each command, and it does contain some enums not in enum.spec, but it is still missing many of them, and bizarrely its also missing some functions such as DrawPixels completely.

If anyone knows of any other source of OpenGL enum information, please post a link.

[Alfonse_Reinheart]

Which is kind of the whole point of using a strongly typed language in the first place.
But thats far from it, i can also setup my development environment to popup a list of valid enums automatically when i type a function name, and i can just click on it instead of typing it in.

Except that they’re not all valid. The actual valid list is only available at runtime. That’s my point.

You’ll catch some errors yes, but you’ll create others as you give users the false belief that, for example, GL_RED8 is a legal image format on OpenGL 2.1 (without the appropriate extension, of course).

It’s the illusion of safety. Strong typing for a runtime-defined system is not going to work.

OpenGL is defined as being usable by any programming language, and as Khronos only provides C language bindings themselves, they have a responsibility to at least make it possible for other people to generate bindings for these other languages by providing the needed information.

They do. But they are under no obligation to so in exactly the manor that you specifically desire. You can create a binding for your language of choice right now. It simply won’t be able to do exactly what you want it to do.

I’m not saying it wouldn’t be a good thing to have. But complaining that it hasn’t happened isn’t going to get it done. The ARB has more or less shown that the .spec files are intended to be merely functional, not good, and they’re not going to take the time to make them better. They’ll be up-to-date (mostly), and they’ll have a parseable format, but that’s it. So you can either do the legwork yourself or abandon the idea.

If you want to start a project to create a more reasonable database of this stuff, great. You could even use APIspec as a starting point. But unless you or someone else who’s interested actually does it, it almost certainly won’t happen.

Though if you’re going to start collating data, I’d suggest waiting until after SIGGRAPH, as a new spec and batch of extensions may be dropping.