Why is viewport so complex to read in the Spec?

I’m trying to read about “cameras” and I’ve stumbled upon what seems to be the area of “viewports”.

Well I went in the spec and realized the keyword does not exist in a lengthy manner until the 2.14 section ‘Coordinate Transformations’. Bizarrely, that section begins:

“Clip coordinates for a vertex result from vertex or, if active, geometry shader
execution, which yields a vertex coordinate gl_Position. Perspective division
on clip coordinates yields normalized device coordinates, followed by a viewport
transformation to convert these coordinates into window coordinates.”

aaaaaah? That couldn’t be more cryptic. It sounded like something in the middle of something, cut out of another text for something else.

Shouldn’t the spec describe the viewport/“cameras” ideas in the introductory paragraphs? Just as the pipeline is described? Even if it wasn’t that important or not too much “GL-ish” it already has sections there that describe that some parts are partly irrelevant such as the platform depended bring-up-a-context stuff.

EDIT: PS. I didn’t mean to go in length in the introductory sections, but to devote an introductory paragraph to its mechanism so people can know how the API works around it.

The wording is not perfect, but imho quite understandable. The first sentence needs to describe things in reversed order for easier reading-comprehension. Possibly turned-out this way by trying to add the geom-shaders note with minimum changes to the original text.

  1. Vertex shader writes to gl_Position.
  2. if the geometry shader is enabled, it must generate its own gl_Position.
  3. the final gl_Position is in clipspace coordinates.
  4. the hardware does vec3 NDC = gl_Position.xyz/ gl_Position.w;
  5. the hardware converts NDC to window-coordinates

There are books on the basics (orange book, etc) , which explain with perfect clarity the pipeline. It seems the specs are made in a fashion that experienced GL developers can spot the newly-introduced changes quickly and efficiently. (the specs even come in pre-highlighted versions, marking the diffs).
I wouldn’t have it any other way; re-reading 700 pages with drastically changed layout and wording to spot the few diffs is no fun :).

The specification is not a textbook for learning the basic stuff. :slight_smile:
You have missed something. It is a specification how something should be implemented. It should be very detailed and suitable for implementation by OpenGL vendors.

As Ilian said, there are plenty of books about OpenGL: OpenGL Programming Guide (7th ed.), OpenGL Shading Language (3rd ed.), OpenGL Superbible (5th ed.), OpenGL ES 2.0 Programming Guide, etc., where you can learn about OpenGL (both basic and advanced stuff). They are well written, and the knowledge they can give you cannot be found in any specification.

For the advanced programmers, OpenGL Registry is probably everything they need for learning about new functionalities.

P.S. By the way, the viewport transformation has nothing in common with cameras. In OpenGL there is no built-in scene-graph, objects, cameras etc. But speaking about these concepts is out of the scope of this post.

I know, but, it’s a very easy and enjoyable read for a long length (I know it doesn’t HAVE to be, but it is). It goes through several pages of the fundamentals without heavy math and event the first pages of pure API functionality are easy to read. It was up to this point that a page could be devoted to viewports/“cameras”.

aaaaaah? That couldn’t be more cryptic.

Of course it’s cryptic; it’s an introduction. It’s saying what this section is talking about. Every one of those sentences and new terms is explained in detail in the following paragraphs.

Indeed, the very next line explains what Normalized Device Coordinates are, by giving you a clip-space vertex.