OpenGL 2.0 specification nits to fix

Some OpenGL 2.0 specification nits for fixing in OpenGL 2.1:

page 29: There’s an technical inconsistency that DrawElements accepts the type UNSIGNED_INT yet ArrayElement accepts a (signed) int. Perhaps this can go unresolved.

page 116: “ARB_imaging” -> “GL_ARB_imaging”

page 126: “host memory” -> “client memory”

page 128: delete the sentence “These data are represented with one of seven GL data types, specified by type.” There are actually 20 allowed values for type as explained by the next sentence.

page 128: Change “is” to “are” in this sentence: “Some additional constraints … [are] discussed below.”

page 129: “host memory” -> “client memory”

pages 248 to 253: language from the ARB_depth_texture specification is missing. This language allows DEPTH_COMPONENT as a format for GetTexImage but then disallows DEPTH_COMPONENT for GetColorTable, GetConvolutionFilter, GetSeparableFilter, GetHistogram, and GetMinmax.

page 150: “host memory” -> “client memory”

page 152: The open parenthesis beginning: “(The definition of …” should be closed at the end of the sentence ending “for all other components.”

page 158: “internalformat, width,” -> “internalformat, border, width,”

page 220: The “convert RGB to L” box should have a solid outline rather than being dashed. This operation cannot be enabled/disable as the dashed outline is supposed to indicate.

page 268: missing VERTEX_ATTRIB_ARRAY_BUFFER_BINDING state

page 269: missing “-” in first row of Get value column

page 367: missing VERTEX_ATTRIB_ARRAY_BUFFER_BINDING from index

I hope this helps.

  • Mark

A few more corrections:

page 206 : Drop LOGIC_OP from the end of the first “Blend Equation” paragraph.

page 207 : Drop LOGIC_OP from Table 4.1 and the logic op sentence in the table’s caption.

page 262 : add “min/max LOD, base/max level,” to the list “restored to their pushed values” in the last sentence of the second paragraph.

page 281 : Fix table 6.20 to say “Z5” (Z-subscript-5) instead of just “Z” in the BLEND_EQUATION_RGB and BLEND_EQUATION_ALPHA Type columns.

page 342 : Insert a section between the current I.5 and I.6 titled “Separated Blend Equation” reading (based on the language of section G.9:

"Blending capability is extended with BlendEquationSeparate to allow independent setting of the RGB and alpha blend equations for blend operations.

Separate blend equations was promoted from the GL_EXT_blend_equation_separate extension.

BlendEquation and BlendEquationSeparate do not support LOGIC_OP (unless the EXT_blend_logic_op extension is explicitly advertised)."

Appendices C, D, E, and H name OpenGL extensions without a GL_ suffix but appendices F, G, I, and J include the GL_ prefix. For consistency, appendices F, G, I, and J should follow the convention of C, D, E, H, and the rest of the OpenGL specification and not includes the GL_ prefix for extension names.

I hope this helps.

  • Mark

here are a few typographical corrections:

Page 212: remove the extra is in “If DrawBuffer is is supplied with a constant”

Page 313: replace The by They in “The are collectively referred to as the imaging subset”

Page 350: remove the extra the interaction in “to add shadow 1D, 2D, and 3D texture targets, and re-move the interaction the interaction with ARB_shadow.”

some tables are a bit too large:

Page 127: The legend of figure 3.7 is overlapping the document footer.

Page 268: The table 6.7 “Vertex Array Data (cont.)” is overlapping the document footer.

.ash

… and what about adding proper gl and GL_ prefixes in the spec and extenstions docs ??? It is really hard to google for it.

Just compare the search results for “GetBufferSubData” and “glGetBufferSubData”, which one do you find to more relevant ?

Is there any real reason to forget all those prefixes, besides making beginners lost and disabling web search ?

It’s explained in the introduction of specification.

<p lang=“fr”>
En fait c’est simple, à la base c’est pour ne pas répéter inutilement un préfixe qui nuirait à la lisibilité du document. Il faut savoir que le document a été écrit il y a plus de dix ans, et qu’à l’époque SGI était loin de se douter de la popularité que cette API obtiendrait, donc ce genre de débat ne s’est pas imposé. Personnellement ça ne me choque pas, on s’y fait vite.

Is there any real reason to forget all those prefixes, besides making beginners lost and disabling web search ?
Sure. Do you want to type that many “GL_” and “gl”'s in front of everything?

Originally posted by Korval:
[quote]Is there any real reason to forget all those prefixes, besides making beginners lost and disabling web search ?
Sure. Do you want to type that many “GL_” and “gl”'s in front of everything?
[/QUOTE]And what about a 10 lines perl script to get all proper names from gl.h/glext.h, generate the unprefixed versions, and replace those in the spec with proper names ?

At least any new extension spec should be written with the prefixes.

My concern is not so much about humans reading the docs, but more about automatic search engines.

So there is no reason besides “it needs someone to work on it” ?

If the focus is on the web search engine, then they should simply include an “OpenGL” option which prefixes automatically everything you’re trying to search, or remove the prefix automatically. In any case, it would would be up to the search engines to do that work, not documentation authors IMHO.

vincoof, don’t you think it’s unreasonable to expect every search engine in the world to magically compensate for your unwillingness to type the real symbol names? (Saving you only 2 or 3 characters per symbol… maybe a hundredth of a second typing time).

I agree with ZBuffer. In the docs and standards the missing gl, glu, GL_, etc. prefixes were a major source of confusion to me as a beginner and still annoy me while doing research now that I’m experienced.

Whoever made the “save time by dropping prefixes” decision was kidding themselves. The savings are approximately zero and the costs are high.

How many beginners are we barring from entry to OpenGL development with this nonsense convention in the documentation?

I’m not telling everyone should be happy about the prefix issue. At some time, I also have been worried about that too. I’m just explaining that when the spec came out, back in 1992, there was no search engine to worry about. So it would be more logical that search engines adapt to the spec rather than the opposite. jm2c