OpenGL API Documentation | Hacker News Reader

OpenGL API Documentation

docs.gl

166 pointsaw3c243 comments

Cool! But some ideas to make it even better:

* Support distinction between compatibility and core profiles. As is, it looks like GL3 is compatibility and GL4 is core.

* For GL4, show the version which introduced the feature (e.g., GL4.2). For GL3 and earlier I don't care.

* Allow compatibility functions to be filtered out entirely. I don't want glLightModel() or other old fixed-function stuff cluttering up the screen.

* GLSL 3.

* Minor cheat sheet showing differences between, say, GLSL 120, 330, and 4x0. For example, 120 has "attribute" and "varying", while 330 has "in" and "out".

I recommend that everyone use the compiler to help avoid functions and constants from later versions of OpenGL, if you are targeting old versions. For example, if you are targeting 3.3, then you can either use a header file that only defines 3.3, or you can use a header file that puts functions and constants in a namespace (e.g. "using namespace gl_3_3;").

The ability to filter to a specific API version would be wonderful as well.

Hey there, dev of docs.gl here.

There's a button above the command list that lets you hide stuff that's not available for the version that you have selected. It should be core for all GL versions. If you select 3.0/3.1 then the fixed function stuff is there but when you select 3.2 it gets removed. It's possible the page's design isn't clear here.

The rest of your stuff is in my to do list. Thanks for the feedback. Pull requests welcome :)

Chrome shows an unexpected sense of humour:

    This page is in "Galician". Would you like to translate it?

That's what you get for abusing TLDs. Leave .gl to the Galicians!

It might be time for another letter to the Galicians: to let them know they're squatting on Greenland's TLD.

Also good is https://open.gl/ which has a good modern introduction to OpenGL.

Thank you for this link! I first used gl ages ago when it was a library that came with Irix, and I've been away from it for about 15 years. I was curious about modern OpenGL, but had no idea where to start.

http://learnopengl.com/ is also excellent

Looks nice, but for example this: http://docs.gl/es3/glBindImageTexture has less error codes than this: https://www.khronos.org/opengles/sdk/docs/man31/html/glBindI...

Is this generated from khronos itself or some other sneaky way?

The source, including the generation scripts, is here: https://github.com/BSVino/docs.gl

I haven't got around to reading through the repo yet, so I can't say.

Hello, dev of web.gl here.

I scraped the docs from the Khronos website when I started the project, about ten months ago. They may be getting out of date by now. At some point I intend to check out all of the changes that Khronos has made since them and apply them to docs.gl. Help maintaining it would be much appreciated :)

I went to add the additional error code and I noticed that Khronos says the invalid operation error should be thrown if texture is NOT the name of an immutable texture object. Is it me or is that not a copy paste error that shouldn't be there?

As a complete newcomer to OpenGL, my first thought was "where's the WebGL column?"

Now, that makes probably no sense; can someone clarify what these versions mean (apart from API availability described by this table, obviously), and if there's a relationship to the WebGL subset (it is a subset, right?).

https://www.khronos.org/webgl/

"WebGL: OpenGL ES 2.0 for the Web"

Simple. Was expected something more complicated, I could have looked further before asking ^^.

Anyway, thanks!

There are some minor differences beyond types. For example, getShaderParameter is WebGL only.

See https://github.com/BSVino/docs.gl/issues/9.

WebGL is based on OpenGL ES, so look at the es2 column.

WebGL has some differences from OpenGL ES, but the functions mostly have the same functionality. For example, instead of passing a pointer to glTexImage2D(), you can pass a typed array or an image element from the HTML DOM. Objects such as textures are also passed to the API as opaque objects rather than integer indexes.

Hello, dev of docs.gl here. I would be happy to support WebGL but I don't use it myself so I've not prioritized adding it. I'm happy to work with any enterprising person who wants to help add it :)

This looks useful as a quick reference and it's very nicely laid out. Nice work!

I'm a little disappointed that the text is essentially the same as the man pages, which means all the same failings. It would be great if there was actually useful text in there.

For example, this little zinger:

"glBindTexture lets you create or use a named texture."

It mentions in this single sentence that it lets you create a texture, but there's not a single word of that in the rest of the text, leaving you wondering under what circumstances that happens or why or whether you should do it that way normally.

Then we get the opposite in the paragraph about where a texture is first bound:

"When a texture is first bound, it assumes the specified target: A texture first bound to GL_TEXTURE_1D becomes one-dimensional texture, a texture first bound to GL_TEXTURE_2D becomes two-dimensional texture,..."

and on and on for every constant you can pass in.

Anyway, I'd love to see a docs site that fixes these very confusing problems with GL's documentation. This is a great first step, but if you're looking for future directions, consider fixing what's broken in the existing docs!

Hello, dev of docs.gl here.

The entire site is here: https://github.com/BSVino/docs.gl

I would love for people help improve the language, which I agree is terrible in places. I don't consider myself an OpenGL expert so I haven't tried to improve the language except in places I know very well. That's why I went for including examples instead of reworking the language. But I would be thrilled if some good writers helped clean it up and expand and clarify etc.

Thank you for the feedback. :)

There is something oddly satisfying about just the methods names on the left.

What else would be there?

("Method" as the column name is actually incorrect... they're just bare C functions.)

https://github.com/BSVino/docs.gl/pull/24 :D

Being pedantic on a pedantic commit: You should use English sentences when writing commit messages. :P

Thanks, fixed the PR :)

I find term "function" rather confusing and improper for programming language construct, because we use the same term in natural languages that is not necessarily 1:1 mapping. Consider commit message: "Implemented function `sort()` implementing sort(ing) function(ality)".

In that case you can omit the left side: "Implemented sorting functionality" or the right side: "Implemented function: sort".

If we want to get really picky, they are procedures.

I think we should start to transition to using the word function only in the connotation provided in functional programming languages, where functions are first class citizens and can be treated as values. Also, should probably prefer to imply a lack of side effects from the word function.

Method is clearly a certain function or procedure that is scoped to a class. So that leaves procedure as a name left over for the type of bare function that isn't a value, that is a statement rather than an expression.

I think subroutine and subprogram are just archaic sounding, and don't really imply anything that the others don't. Method, functions, procedures, I think that's all we need.

So, the distinction that I've learnt is that functions return values and procedures are run for their side effects.

So, strlen, for example, is a function, and printf is a procedure.

(Yes I know prints returns an int, but it's run for it's side effects primarily.)

"Function" comes from mathematics, where it is a well-defined and total relation. The main place programmers use it wrong is that they often use the same term for partial functions, but that's easy to overlook, since a partial function is a 'kind' of function. (That and side effects, but those can be considered to be elided parts of the domain and codomain.)

What you are talking about might be called a relation, which is more general.

I think they are typically called "entry points", at least in the spec. The term "function" is used for GLSL functions and for things like blending functions.

What else would be there?

It's pretty standard to have the function's type signature and possibly a short description in the function lists of API docs. Here's a random example:

http://ffmpeg.org/doxygen/trunk/group__lavc__fft.html#func-m...

If a function has the same name across different versions of the OpenGL API, does it also have the same type signature? If so, it would be nice to have a version of this with more details.

What good is showing the function signature? It will be different per language implementing the OpenGL bindings.

The docs should be just about the OpenGL functions, not about how C implements them.

Here is a little JS snippet you can adapt to filter the list down to remove the procedures not supported by a particular profile you want to view.

    Array.prototype.filter.call(document.querySelectorAll(".disabled"), function(v){return v.innerHTML === "es2";}).forEach(function(v){v.parentElement.parentElement.removeChild(v.parentElement);});

Notice the "es2", that is where you select the profile.

One suggestion: see if there's a way to preserve the "dark" background between page loads. If you select Dark, then go to another page, it initially loads in Light before flashing to Dark. I imagine that this would be unwanted if using Dark at night.

Hello, dev of web.gl here. It should be preserving automatically. If it doesn't, that's a bug. What browser/OS are you on?

GL ES and regular GL aren't sorted in the same order :-(

Where's Vulcan?

The Vulkan spec hasn't been published yet. It's also a very different API so it wouldn't make sense to show on a page of docs for OpenGL.

What would be really useful is if you could compare API behaviour between different graphics cards and driver versions.

I don't know what it is but web devs seem to have a horrible idea on how to present documentation. This fails as a quick reference and as an index. It should show the function signature (unless it's an class?) and should be separated into sections either by alphabet or by some category (I see Images and Samplers as possible sections).

What's strange is that the categories and function signature are hidden from the main view. Weird.

Looks good, I think the author should also add a short description on the index page.

Reply on news.ycombinator.com