PDA

View Full Version : Documentation



H. Guijt
11-14-2014, 02:29 AM
I wanted to separate this from my previous posting in this thread since it is really a different issue.

The current level of documentation on OpenGL is, to put it mildly, not amazing. I have two copies of the OpenGL programming guide (2 and 4.3, both subtitled "the official guide to learning OpenGL"). The first book explains what features actually are, in addition to how you use them. There is not just an enumeration of APIs, but also some theoretical underpinning and a sense of how it all hangs together. The second book, sadly, doesn't have any of that, and assumes you already know what all the features are and just need help with what the functions are called.

To give just one example: nowhere is it actually explained what a "vertex array object" really is. It tells us how to allocate one, how to bind it, how to delete it, and even how to test if one is valid or not - but there's no clue _what they are or why you'd want them_. There is no indication what a good strategy for their use is either: create one and use it everywhere? Create a few dozen? Create thousands of them?

This is just an example, and this posting is categorically not a request to explain vertex array objects. What it _is_ a request for, is for an OpenGL "official guide to learning" that actually gives you a chance to _learn_, by explaining what things are, what you use them for, and what good strategies for their use is. Getting into OpenGL at this stage is far more difficult than it needs to be. I guess I'm lucky because I did some OpenGL 1.x/2.x work back in the day, and thus at least some concepts make sense to me, but for someone who is new to this thing this would be extremely difficult.

Providing a new API is not enough. It must also be documented well enough that people can actually start using it, even if they don't have twenty years of experience with predecessor APIs.

l_belev
12-04-2014, 10:01 AM
To give just one example: nowhere is it actually explained what a "vertex array object" really is. It tells us how to allocate one, how to bind it, how to delete it, and even how to test if one is valid or not - but there's no clue _what they are or why you'd want them_.


Yeah, such is the style of the spec. Its like formal math definitions. It doesn't attempt to draw an easy to grasp picture that is friendly for your intuition but just formally describes the rules. I agree it could be a hard to read.
Personally I like it because it is very powerful in the sense that it leaves no room for corner cases where the the opengl's behaviour is unknown. (I'm not talking about cases where the behavior is explicitly stated to be undefined.) When you are in doubt about something, you can always find the answer by reading the spec carefully enough. Well at least in theory. In practice there are quite a few errors and inconsistences, but still its nice.

I prefer it over the microsoft's documentations that attempts to informally explain some fuzzy concepts, but when you get to really use APIs, you constantly come across questions that have no answers. And you are forced to experiment in order to find out what the api will do in the strange cases (which can be very time consuming and difficult) or try to find the answer in the internet.

Well, thats about the spec, it is good to be formal and rigorous.
But of course this doesn't mean another more intuitive documentation (for newcomers) shouldn't exist at the same time.

H. Guijt
12-07-2014, 03:41 AM
Yeah, such is the style of the spec. Its like formal math definitions. It doesn't attempt to draw an easy to grasp picture that is friendly for your intuition but just formally describes the rules. I agree it could be a hard to read.
Personally I like it because it is very powerful in the sense that it leaves no room for corner cases where the the opengl's behaviour is unknown. (I'm not talking about cases where the behavior is explicitly stated to be undefined.) When you are in doubt about something, you can always find the answer by reading the spec carefully enough. Well at least in theory. In practice there are quite a few errors and inconsistences, but still its nice.

I completely agree, but I was explicitly talking about "OpenGL Programming Guide, The Official Guide to Learning OpenGL, Version 4.3". Note those words in the middle: "official guide to learning".

I'm fine with a formal spec being hard to read if that's necessary for the sake of rigor(!), but this book is supposed to help you learn about OpenGL, not figure out obscure corner cases that are likely only of interest to driver developers or some such. This book doesn't do much to help you learn, something which I very much expect from an official Khronos publication that is marked as "the official guide to learning".

Aleksandar
12-07-2014, 04:59 AM
I completely agree, but I was explicitly talking about "OpenGL Programming Guide, The Official Guide to Learning OpenGL, Version 4.3". Note those words in the middle: "official guide to learning".
It is a part of the legacy title, which is just inherited from the predecessors. ;)

We are all witnesses of the proliferation of the books. Nowadays it is hard to find a good one.
Furthermore, even new editions are faint image of their predecessors. I've got almost all OpenGL books published in recent years, and cannot recommend a single book to my student as a learning guide.
But, there are some books that can be marked off as concise and well written. I would recommend you:
- OpenGL ES 2.0/3.0 Programming Guide and
- OpenGL 4 Shading Language Cookbook.

l_belev
12-13-2014, 09:12 AM
but I was explicitly talking about "OpenGL Programming Guide, The Official Guide to Learning OpenGL, Version 4.3".
Sorry for not reading your post carefully enough :) For some reason I assumed you were talking about the spec.