986498 - [META] Complete WebGL documentation

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: API: Miscellaneous, defect)

Description

[Robert Kaiser]

When trying to make my Lantea Maps web app use WebGL instead of 2D canvas for more performance (and to learn a bit of WebGL), I found that the WebGL documentation on MDN is seriously lacking.

What we have right now is basically just one single tutorial, on creating a rotating cube with a (mirrored) Firefox logo on it - and even there, a lot of the GL commands used are not completely explained and matrix operations are being used from an external library that acts as a black box.

In the end, I found the tutorial at http://www.html5rocks.com/en/tutorials/webgl/webgl_fundamentals/ a better learning experience than ours, and for a reference I had to turn to MSDN - http://msdn.microsoft.com/en-us/library/ie/dn621085%28v=vs.85%29.aspx and its sub-pages - which feels somewhat awkward (esp. as Mozilla pioneered that standard with Khronos and MS was a bit late to the party, IIRC). 

I think we should have at least a good reference of the GL context on the JS side (and only go into shader language once we have that).
We possibly also should have an entry-level tutorial where what the code means is easier to grasp, like the html5rocks one - things don't need to be 3D and animated in the beginner's tutorial, that can be the next step.

Comment 1

[Jean-Yves Perrier [:teoli]]

I made a quick estimation of the size of the reference we need to create, using our format for API: 175 pages. (Not all of the same priority of course)

Comment 2

[David Bruant]

Some guide content on Hacks already https://hacks.mozilla.org/2013/04/the-concepts-of-webgl/

Comment 3

[Liz Henry (:lizzard) (relman/hg->git project)]

Jeff, this came up today in a QA meeting -- do you all have any plans to document WebGL or if that's already happening, do you know who might be working on it? Thanks!

Comment 4

[Robert Kaiser]

Oh, FWIW, webglcontextlost/webglcontextrestored should probably be mentioned in the docs somewhere as anyone doing a longer-running WebGL-using web app might run into this and wonder why their GL stuff went away.
See http://www.khronos.org/webgl/wiki/HandlingContextLost for some details about that. :)


And here's a snippet from bjacob on dev-platform:
-------------
Not expressing any opinion on whether WebGL should be prioritized, but
recently I had to teach some WebGL and, not being fully satisfied with
existing tutorials, I made a code-only "tutorial" made of 12 increasingly
involved WebGL examples,

http://bjacob.github.io/webgl-tutorial/

and I would be happy to work a bit with someone to turn it into proper
documentation.

Benoit
-------------

Comment 5

[Kelsey Gilbert [:jgilbert]]

(In reply to Liz Henry :lizzard from comment #3)
> Jeff, this came up today in a QA meeting -- do you all have any plans to
> document WebGL or if that's already happening, do you know who might be
> working on it? Thanks!

There aren't any current plans to do this that I know of. I can do tech review for any articles that do get written, though.

Comment 6

[Eric Shepherd [:sheppy]]

We need to complete this documentation. We have written a documentation plan (https://developer.mozilla.org/en-US/docs/MDN/Plans/WebGL) and hope to find a writer for it soon. I'm turning this into a meta/tracking bug for the project. Dependencies should be filed as appropriate as the project ramps up.

Comment 7

[Florian Scholz (Open Web Docs)]

Given WebGL2 and all the extensions, the WebGL world seems to be quite rich to me and there are many switches to document, depending if you just use WebGL1 or have WebGL2 enabled or various extensions. 
Nevertheless, I had a go at this in the last few weeks.

This is the landing page:
https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API

There are now 272 pages describing the WebGL API and the bulk of pages are:
17 Interfaces
26 Extensions
3 Events
112 WebGL1 methods
68 WebGL2 methods

These pages might not be perfect and could use better examples oftentimes, but I hope that they become more visible over time and I guess the community will improve them. This is usually how it worked in the past: Someone bootstrapped a set of docs and the community improves them. I saw these new pages already referenced in StackOverflow questions, so I think they begin to be used. (will also look at Google Analytics).

This page is a nice example for what I mean with the versioning jungle and why I believe these docs are good to have now: https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getTexParameter


(In reply to Robert Kaiser (don't count on reactions on anything) from comment #0)
> learning experience than ours, and for a reference I had to turn to MSDN -
> http://msdn.microsoft.com/en-us/library/ie/dn621085%28v=vs.85%29.aspx and
> its sub-pages - which feels somewhat awkward (esp. as Mozilla pioneered that
> standard with Khronos and MS was a bit late to the party, IIRC). 
> 
> I think we should have at least a good reference of the GL context on the JS
> side (and only go into shader language once we have that).

MSDN only documents WebGL1, so as of now we are better with WebGL1, WebGL extensions and WebGL2 reference material on MDN. ;-)

> We possibly also should have an entry-level tutorial where what the code
> means is easier to grasp, like the html5rocks one - things don't need to be
> 3D and animated in the beginner's tutorial, that can be the next step.

A volunteer recently started https://developer.mozilla.org/en-US/Learn/WebGL/By_example
Not complete, but a start.

There are more ideas listed at https://developer.mozilla.org/en-US/docs/MDN/Doc_status/API/WebGL We will see how more WebGL docs will get prioritized for staff writers to continue here. We might want to create some specific campaign-like or tutorial material for WebGL2, but we will see with time available. Contributions welcome at any time.

This bug said we have nothing about WebGL on MDN, but that isn't the case anymore. I encourage to file more specific bugs against our WebGL docs now. 

Closing here and going into vacation :)

Comment 8

[Kelsey Gilbert [:jgilbert]]

Thank you so much!