Suggestions for teaching OpengGL

For several months I have been trying to learn OpenGL to go beyond displaying a single 3D object. I have watched a lot of videos, read books, and lots of online documentation. In my opinion, the documentation on OpenGL is so poor that the technology would be dead today if it weren't for OpenGL ES and mobile devices and to a much lesser degree the Mac. Even for these platforms the use of 3D really isn't all that great. The vast majority of graphics on these platforms remains 2D.

But that's enough of my complaining. Here are some suggestions for those who aspire to create tutorials and other documentation.

First, indicate which version of OpenGL your tutorial refers to. Nothing has been more frustrating that reading through a tutorial only to discover it provides details about a version other than the one I have been trying to learn. In my case I have bee trying to learn 3.2core because that is what is available on my mac.

Second, define terms. I have read the specs for several versions of OpengGL. They are riddled with undefined terms. Many of these terms have only a passing similarity to other terms in computer science. A good example is "binding point." It seems like this should be a pointer of some sort. However, I have not found a single clear definition of the term. I can only infer what it means by the various vague descriptions that use the term. There are many other such terms.

Third, use figures to depict a process. Words don't always convey how a process works unless they are really well written. A figure, on the other hand, can go a long ways to clarify the meaning of text. I have found no figures illustrating the use of state variables, for example, and how they change as functions are called. But figures need not be limited to state variables. Using them, in my opinion, is a must.

Lastly, someone needs to write a really good explanation about vertex arrays, buffer objects, and vertex array objects and how to use these things to create entire scenes of objects. I am inventing my own techniques because, frankly, there is no good documentation.

I have found no figures illustrating the use of state variables, for example, and how they change as functions are called.

And what exactly would the figure display? Would it have a picture that shows the text, `glTexParameteri(GL_TEXTURE_MAG_FILTER, GL_LINEAR)`, with an arrow pointing from that call to a location in a texture called "GL_TEXTURE_MAG_FILTER"? I fail to see how that's an improvement.

I can think of lots of ways that graphics could be used to explain concepts. For example, OpenGL has a client/server architecture. The client and server sides of this architecture also have internal complexity. Well designed graphics can illustrate the details of this architecture.

Data resides in the client and server. Graphics could illustrate where this data resides and with what components.

Also, information must pass between client and server and the internal components of each. Well designed graphics could illustrate how the communications works for various scenarios.

Frankly, I am surprised that you would belittle using graphics to educate others on how OpenGL works.

They say a picture is worth a thousand words. I fail to see how an image with the word "buffer object" on it that sits in an area labeled "server" conveys the idea that buffer objects live on the server any better than saying, well, "buffer objects live on the server." The latter certainly takes up a lot less space.

Frankly, I am surprised that you would belittle using graphics to educate others on how OpenGL works.

I'm belittling the idea of using graphics to "illustrate the use of state variables, for example, and how they change as functions are called," which is what you suggested.

How state changes when you call a function is trivial. Making a bunch of diagrams to show off what happens after every function is only good for doing Power-point video presentations. It's stuff that anyone with a passing familiarity with how programs work will understand.

The difficulty is in describing complex interactions between objects and state entirely through text. This is where a diagram or two is useful.

State charts are good examples of graphics that illustrate the behavior of a system. A state chart can capture the state changes caused by one or more function calls. For OpenGL state charts showing state transitions as particular functions are called and showing which state variables are changed for various scenarios would be useful. Also showing where those state variables reside (with a VAO, buffer object, etc) would also be useful. State charts can be simple line drawings or more stylistic depending on the author.

Also, diagrams come in a variety of shapes and sizes. See the works of Edward Tufte. One graphic of Tufte's that I like are sparklines - small, high resolution images embedded in text (see http://www.edwardtufte.com/bboard/q-...?msg_id=0001OR for details). A small graphic (not a PowerPoint sized diagram with title and caption) could illustrate state changes even for simple individual functions.

State charts are good examples of graphics that illustrate the behavior of a system. A state chart can capture the state changes caused by one or more function calls.

What is a "state chart"? I mean, you obviously have some image in mind for this. Draw it. Show us exactly what you're talking about. After all, you're arguing that charts communicate better than words. This is your best chance to prove it; give us a concrete example of exactly what you're talking about.

However, to *teach* OpenGL, I would recommend starting with an OpenGL 1.2 example program with GLUT. Then, replace the gl_begin and gl_end immediate mode stuff with a VBO, learn that. Learn how a camera matrix works, learn about perspective. Start in 2D Ortho, learn about texture coordinates and how they correspond to vertex coordinates and get comfortable with that, learn about the FBO and how it's better than the 1.2 method of texture manipulation, then move to 3D. Integrate little chunks of GLSL into your test program. Figure out what you can do with GLSL. -Then replace your fixed function pipeline with a GLSL system.

Jumping into OpenGL post 2.1 is a frickin' nightmare for a newbie, not to mention the scatter of different versions of documentation out there.

Personally I'm waiting for OpenGL 6.0 when Kronos decides to officially integrate GLM into the bundle to replace the exact same functions they threw out in The Great Purge of OpenGL 3.x.