Actually this is not a suggestion for the next release only, but also a suggestion for the current releases 1.2-1.3.
The OpenGL man pages haven’t been updated since version 1.1 (I’d love to be wrong in this case). So it seems necessary to update these, since it’s to tedious to look through the specification. Secondly, it should be required that extension must be accompanied with man pages (additional to the extension doc in the registry) for let’s say ARB (or maybe even EXT) extensions.
This would justify the often seen claim that OpenGL is much better documented than DirectX.
I think that GLU should be better documented. I have the PDF for 1.3 but there are only a few explanations on how to use them. What I would like is some more detail as to how the tesselation is performed, how memory is used by each function in GLU, and so on. Basically, I want more details so that I’ll know more about the GLU library and the source code as well.
You can download the MesaGL source code if you want access to some GLU source. I think GLU, like the core of OpenGL, is implementation dependent, so particulars about memory usage is implementation dependent.
I know that the source for both GL and GLU is available, but a technical document explaining the concepts, the methods used to attack the problem, and what functions are doing whatever should be provided. I’m still thinking of the tesselator in particular in this case. The rest is easy to understand.
It’s more than two weeks since I posted this message, but there is quite little feedback for this suggestion.
I definitely can’t understand why!Documentation is the real important part of an API.
Could someone please explain me how you all (that didn’t post) work with opengl?
I can imagine three cases:
You don’t need any help, 'cause you know the spec by heart.
You use Microsoft’s help, 'cause you only use OpenGL 1.1
You can’t use a help / man page, 'cause the internet explorer/mozilla/opera (used to copy and paste from nehe’s examples) is eating up all the memory?
But honestly: Do you think the OpenGL Reference Manual could calm me (though I don’t like books as a replacement for help files)? Is there documentation for ARB extensions (for OpenGL 1.2) like multitexturing included?
[This message has been edited by stefan (edited 10-30-2001).]
Heh, I downloaded and printed the 1.2.1 OpenGL specification for all my less-than-common needs… but as for memorizing it, that’s kinda what you’d have to do to get much good at OpenGL I have all 278 pages of it in a 3" binder next to me.
The best OpenGL documentation is OpenGL code. No doubts about it; little is a better example than seeing the functional code. For really advanced stuff, or really simple stuff, you’ll need a manual, which the OpenGL spec book gives you for everything except extensions. Look at [NeHe’s page](http://"nehe.gamedev.net) for a ton of good OpenGL coding examples. Very helpful indeed
I think the OpenGL 2.0 documentation should be like in DirectX. It must include AppWizards for VC++ and other compilers, importer/exporters, a lot of examples, tutorials, links, algorithm and effects addendum, etc…
I have all 278 pages of it in a 3" binder next to me.