Hacker News new | past | comments | ask | show | jobs | submit login
WebGL Fundamentals (webglfundamentals.org)
406 points by unusximmortalis on Apr 6, 2015 | hide | past | web | favorite | 51 comments

I like the sheer number of running examples. When I first learned any OpenGL/WebGL, I had to imagine all of these examples from the text and static images.

I especially like the up-to-date examples for how to write WebGL in shorthand and the common practices examples. The explanations are phenomenal too. I guess what I'm trying to say is, this is likely the best WebGL reference I've seen yet.

Great work. This is precisely the kind of site every web API needs. I would like to see one for Sockets, Workers, Canvas, SVG, etc. I think this format could even work for transpiled language documentation (although that's a little more doubtful).

My only suggestion is that the author[1] name himself, and date the content (at least month/year)! Both of these can be inferred from the github link, but it belongs on the page itself.

[1] http://games.greggman.com/game/

> Sockets, Workers, Canvas, SVG, etc.

So does anyone here have links to similar documentation for the above?

This looks great. If you're interested in learning modern OpenGL (not WebGL) here are two similar resources:



its always good to see websites with nice 3d elements involved like this.

started reading the tutorials... and i have to say the quality is questionable. from very big things like the claim that the API is fundamentally 2D (really?) down to small things like doing the pixel space to clip space conversion in an inexperienced way (its one 2d vector multiply or a matrix multiply... surely?)

he is clearly aware of some of this stuff though (he mentions the magic perspective w divide in a later tutorial), so maybe its intended and i am just being over-critical since i understand how this stuff works and disagree with the approach taken to introduce it...

saying that he seems to have confused scene graph with a transform hierarchy. oh dear...

Thanks for the feedback. I addressed my 2d point here


TL;DR OpenGL 1.0 is a 3D library because you can give it 3d data and will draw a 3D with no 3D knowledge on your part. WebGL is not a 3D library because you have supply the 3D knowledge.

Arguably it would have been better to say WebGL is a rasterization library that has some features that make it good for rasterizing 3d. If you think about it though it is, by no reasonable definition, a 3D library.

As for any other issues patches and suggestions welcome.

Greggman, first off, these resources are great, thank you for making them available!

As for the 2d rasterization vs 3d math question, I've bumped into your philosophy online before and never commented but found it did touch a nerve with me as you suggest. I'm not entirely sure why, but its as much an emotional argument as a logical one.

After I thought about it for a while, I concluded that you have a valuable and interesting point. But every time I read it I keep wondering a couple of things, so since you're here I figured I'd just ask.

First, why deny so absolutely that WebGL is 3D? I've been feeling like your point might have more traction with graphics programmers if it left the question open than claim to close the book. Even though you're right, you need to do your own math, WebGL still does accept 3d data, and it does 3d operations on that data. WebGL enables 3d graphics, and denying that it does that is inherently problematic, isn't it? The argument that amount of prior knowledge necessary to use a library should dictate the category of a library also seems pretty subjective to me, and in my experience doesn't generally hold - not many libraries I use are truly black box libraries that don't require prior knowledge. My personal use of OpenGL has always involved me doing a lot of 3d math myself, just like my personal use of OpenCV requires a lot of prior image processing and computer vision knowledge.

Second, why try to convince the internet that WebGL is 2d and not 3d, as opposed to, say, the Khronos Group? If all the official sources of documentation call WebGL a 3d library, then isn't this argument probably going to be futile and never ending?

I can explain why this hits a nerve for me. When I was first learning about 3D rendering (in OpenGL/DirectX) I intuitively thought about the screen space being 2D. I was wrong, and it made me confused about a lot of issues, in particular, I couldn't understand why there must be a near and far clip plane.

The 3D perspective page http://webglfundamentals.org/webgl/lessons/webgl-3d-perspect... clearly describes the rasterization phase as having 3D: the automatic perspective divide and the triangle clipping to a 3D space. Clip space being 3D seems very strange if WebGL is only a 2D API.

My suggested patch would be to rephrase it for the beginner. "WebGL is largely a 3D rasterizing API and not a fire-and-forget scene rendering solution."

If WebGL were only 2D it would be trivial to implement 3D without shaders in <canvas> -- and that is not true, canvas cannot rasterize 3D triangles.

How does opengl know which triangles are in front and which are behind?


It is called depth testing. There is a depth buffer (or z buffer) which contains the depth value for each pixel. When a pixel is to be written, its depth is calculated and compared the value in depth buffer, if it is closer to camera then it is drawn and value of depth buffer is changed, else the pixel is ignored.

it may not know. it depends on the context... but basically you have to tell it somehow.

yeah, this is not really true either.

you should be careful with bold claims, especially if you don't have a great depth of knowledge (everyone should believe this...)

i commented on the post.

(don't let me nay-say too much. you have done a really wonderful thing here. that is what matters most.)

Can you explain why it isn't true? He goes into explicit detail why he thinks it's so, yet you have only repeated "you're wrong" without providing any counter example.

because you can throw 3d data down the pipe naively and it 'just work', it comes out with the same problems as naive use of 2d data - that the transform from world to clip-space becomes the identity matrix, which results in aspect-ratio stretching.

also the idea that old desktop OpenGL is valid any more grates and encourages using it... its something we would like to have died its death 5-10 years ago when it was already out of date.

its also the case that all of the 'desired' functionality for 3d which is 'missing' is equally applicable to 2d and so equally missing from the API. there are no rotations 'out of the box', no aspect ratio correction, no texture mapping, no anything. this is what we expect from a low-level API, the minimum set of features required to make the hardware do the job - not an encyclopaedic library of derivative functionality (this is the place of a higher level library than the hardware interface).

i think the author has confused it being a low-level API with it being 2D. these are not the same. its just as devoid of features regardless as to what space you are rendering in... i can really understand it if coming from a web background where the stack is gigantic and "low-level" is an utterly foreign concept.

(also, in my defence, i didn't go into great detail, since i commented on the post itself to avoid polluting HN with a conversation thread)

OpenGL certainly is a 3D library, but WebGL is based on OpenGL ES (the ES part being important here) and basically just provides facilities to transfer data to/from the GPU and run vertex and pixel shaders.

It is completely up to the user whether the position data for the triangles is given in 2D coordinates from the start or in 3D coordinates and then transformed to 2D coordinates in the vertex shader.

The fact that it makes it fast to do the math for 3D, does not make it a 3D API.

my issue is more with the specific criteria the author uses being invalid. there is no special 2d functionality, e.g. aspect ratio correction or rotations. there is special 3d functionality, and contrary to the authors claim, you can just throw 3d data down the pipe and have it work. you just have a fixed, non-aspect-ratio-corrected view, the same as you get when you naively throw 2d data down the pipeline.

also, please don't confuse OpenGL circa 1999 with modern OpenGL. the features removed in ES were considered bad practice 10-15 years ago... i do disagree with removing default shaders (our beautiful flexibility is now relegated to mere boilerplate) but i'm sure the OpenGL ARB had a good reason behind that choice (reducing driver responsibility, reducing points of failure etc.).

also, what is never up to the user is the perspective divide. if a naive user is not aware of this particular, very 3D specific gem, of the hardware/API then he will end up with subtle bugs and maybe even struggle to fix them due to the incomplete knowledge...

its got nothing to do with performance.

For novices like me, this site seems very useful. If there are some genuine problems, I hope you can take the time to report those issues on github.

Also, what's the final verdict on Fast InvSqrt()? Is the optimal magic number Q3's 0x5f3759df, Chris's 0x5f375a86, or your 0x5F375A7F?

i think i came to the conclusion of 0x5f375a84 at the end of that article. at least by the criteria the test program used to measure error.

the differences are tiny though, and there are other measures that can be used (which will result in different constants)

in any case, on most modern hardware it is not relevant since there is some lookup based instruction that is more accurate, and faster.

the problems here aren't enormous, a smart programmer will work them out for himself, but they are misleading. i think there is some confusion just because this is a low-level API, essentially a hardware abstraction layer, but the user is expecting high level features like a complete maths library. (maybe?)

These days sqrt and rsqrt are so cheap that they aren't a worthwhile optimization target. You're much better off optimizing cache usage.

Your terminology and reasoning are very mixed up here. Your argument that "WebGL is not a 3D library because you have supply the 3D knowledge" is complete nonsense.

For one thing, WebGL is not a userland "library", it's an API layer on top of device driver implementations of the OpenGL spec. It's not designed to be something that "makes 3D easy"; it's not even a "library" in the npm/jQuery sense of the word.

I would not recommend any tutorials written by an author whose reasoning about OpenGL is so fundamentally flawed. You should really re-think what you're claiming here.

You're getting close to sea lioning here.


Thank you! The demos and the comment section below each page is great, I wished every API gets such a great documentation.

Good that it covers really WebGL. And not Three.js as do several "WebGL" books and tutorials. (as I wrote two days ago: https://news.ycombinator.com/item?id=9320571 )

What are the applications of WebGL?

If you are doing a game or a 3d application on browsers- WebGL would be the way to go obviously. But apart from that, where could it be used? Could websites and web applications benefit from using WebGL? If so, in what way? Would it improve or worsen battery performance?

ps: Sorry for all the noob questions but i am genuinely curious about the implications of WebGL.

Currently it is a no go if you plan to target mobile devices.

Only the latest version of iOS supports it, on Android it is a joke with Chrome blacklisting many handsets[0] and Windows Phone only partially supports it.

[0] You can re-enable it via developer flags, but no normal user is going to know about it.

A minority of drivers/GPUs are blacklisted on desktop, and you have to deal with less than 100% WebGL coverage in any case. But yeah on mobile it's a sharper "reasonably recent devices only" division.

You can see (somewhat skewed) stats on http://webglstats.com/

Interestingly iOS is ahead of Android in tablets, but behind on phones.

Be careful to interpret the stats there correctly. Eg when you leave just the specific category checkmarked, the graph shows ios-smartphone webgl support rate at 79% and android-smartphone rate at 75%. The percentages in the sidebar are just browser shares and not WebGL support rates.

If you do anything graphical, be it 2D or 3D, you can use WebGL or Canvas2D (for 2D-only). For some domains it's enough to do redraw/render only if a mouse/touch-events fires which helps a lot with the battery performance.

Really like this, it seems just right for introducing someone with programmer experience but who doesn't have graphics experience.

Note, the "Frustum" example[0] linked on the 3D perspective page[1] is not working on Firefox (screenshot comparing FF and Chrome[2]).

[0] - http://webglfundamentals.org/webgl/frustum-diagram.html

[1] - http://webglfundamentals.org/webgl/lessons/webgl-3d-perspect...

[2] - http://nacr.us/media/pics/screenshots/screenshot--18-21-58.p...

> just right for introducing someone with programmer experience but who doesn't have graphics experience

Are you kidding? Most programmers with really no graphics experience are along the lines of "wtf is a shader?!" or "wtf is clip space?!"... this give absolutely no clear explanation of what those things are, even the fundamentals section assumes you already know the fundamentals...

Thanks! Fixed. Also learned something really scary about JavaScript in Firefox


I like how it starts by mentioning that WebGL, fundamentally, is 2D, and shaders are where all the 3D magic happens. It's true, and it's important for understanding it.

His notion of a "2d" library versus a "3d" library is weird. First, who cares? He's inventing this semantic argument that nobody else has even bothered with.

Second, WebGL has builtin depth buffers, vertices are specified with 3+ coordinates, and most of the shader math operates on things obviously in three dimensions... so, saying it's 2D is incredibly misleading.

The person that cares is the the person that expects a library called something to actually do what it says. If I download a physics library I expect to to do the physics, not just be a math library with some features that happen to help you write your own physics library.

If I download a png library I expect it to decode and/or encode PNGs not just be a zlib library and some pointers to some docs on the png format.

WebGL is not a 3D library by any possible definition as it does not provide 3D. It's a rasterization at best.

Why does that matter? Because if you want a 3D library, as in a library that does 3D then you want something else like three.js, (http://threejs.org). Knowing that WebGL is not a 3D library and that you're going to have to write your own from scratch if you use it directly seems like an important distinction

Clip space is in 3d. You have a depth buffer and three coordinates. There's no way around that: it's 3d.

What you're saying is "3d" is just utility functions to transform something into clip space. The reason they got rid of those in OpenGL ES (and WebGL is based on ES) is that most of it was useless outside of demos. pushMatrix/popMatrix/translate/rotate/scale are simple to use, but as soon as you need to do something like interpolate a camera between two rotations you end up doing your own vector math and using glLoadMatrix anyway.

three.js is a 3D engine. WebGL is a library that let's you interface with 3D graphic accelerators(rasterizers on steroids). That is it's main purpose. Rasterization is a fundamental of real-time 3D graphics. I am not sure why people are feeling deceived by finding this out?

Its a distinction, not a deception. If I'm going to write a game and I hear about WebGL, I have to make the distinction between where my art gets turned into an asset, and where that asset gets rendered. There is a lot of ground between those two points, and understanding the difference between a library that you can just throw artwork at, and a device-driver layer that expects data in a certain format (or it won't work at all), is where the application/engine/library lines must be drawn in the sand.

The author is (imho) correct in pointing this out from the perspective of having produced a tutorial for newcomers to this scene - so far my observation is that those who wish to argue with him about this point seem to want to generalize it into a ball of mystery, as they are more expert and know the territory better. That may well be the case, but use the rear-vision mirror and look at this from a total newbie perspective. You can't just load up Wavefront .obj's into a WebGL instance and expect to get a bouncing ball. You'll need a 3D engine - or library - to do that. There's room in this discussion to fill that void - for the newbie - by using terminology that allows a better understanding than, perhaps, those who understand it all, already, permit/allow/agree to.

The distinction seems to have a locus around the data formats - either of the files being loaded, or at the parameter/buffer-object layer. There is quite some territory between an .OBJ vector (for example) and some other vector format that needs to be loaded into buffers and passed over to the hardware device through a driver layer. Where does the physics go? What is a shader for and why bother with it in this context? These questions get answered by having firm terminology: WebGL is not a 3D library, because a 3D library would have some sort of blackbox'ed object loader, maybe a bit of physics/collision-detection too, and so on .. and it may well be an engine which uses WebGL simply as one of a series of front-ends, through a driver layer, successfully too - they're out there.

> so far my observation is that those who wish to argue with him about this point seem to want to generalize it into a ball of mystery, as they are more expert and know the territory better.

It's the opposite, this stuff is already hard, there's no need to make it more complicated by introducing a distinction that's misleading.

> WebGL is not a 3D library, because a 3D library would have some sort of blackbox'ed object loader, maybe a bit of physics/collision-detection too, and so on ..

That's a pretty arbitrary cutoff, but all the same: you're describing a 3d engine, not a library. Besides why would you want all that in one library? I'd rather have my mesh loading and my physics be separate libraries so I can have more choices and keep my includes small.

In one sense, WebGL is a 4D library, since most vertex and color buffers are vec4s. In another sense, WebGL is 3D, since the vertices (and colors, if you're using premultiplied alpha: http://core.ac.uk/download/pdf/1578955.pdf) are in 3-dimensional projective space. In another sense, WebGL is a 2D library, since it's outputting 2D fragments.

The author is just making it clear that there's no magic here. It's all just 2D points on a screen eventually.

The folks who consider WebGL as a 2D API include some of the the browser developers who implemented it. That said, I don't fully agree with them. If WebGL were simply a 2D API, this example, from a talk I gave way back in '13 wouldn't work. In this example, one triangle is clearly drawn behind the other using only raw 3D coordinates with no projection yet.


It also isn't a fully 3D API either, otherwise we wouldn't have to be so concerned about the order in which we draw transparent objects. This is the result of using a 2D drawing surface plus a depth buffer.

That said, it might be too subtle a point to open with. Especially since you are showing code, the understanding of which requires material that they haven't covered yet.

OpenGL is a collection of api calls that move buffer data around. It is an api for interacting with shaders compiled into a program. This is all done in 2D, 3D, and even 4D. The rendered product is a screen which only has 2 dimensions, but calling it 2D is a huge oversimplification.

its not exactly accurate or relevant. clip space is 2d because the monitor is.

all of the 3d operations and 3d relevant functionality breaks the argument. the depth buffer for instance, and even more so, the perspective transformation hack (1/w) have limited utility outside of 3D...

This is a fantastic resource for people with an understanding of Three.js that want to know what's going on under the hood.

Thank you for sharing this!

Nice examples, if I only had something interactive like this back in the day.

Although I have to recognize that NeHe tutorials were quite good.

Personally I think the biggest problem with modern 3D APIs is learning the shading languages and how to separate work across them.

It's cool but it still needs work when it comes to teaching glsl.

Just giving semi-commented code samples isn't enough when a student doesn't know what an attribute is.

What about The Book of Shaders?

It's not complete by any means, but will get there eventually, hopefully. :)


Looks like it will be pretty good when finished... pity you haven't gotten to textures yet.

This article expect you to already know 3d programming. You need to be familiar with vectors, matrices, buffers and shaders.

I love this teaching pattern. It's well broken down and interactive. Great role model.

This is fantastic. Particularly helpful to me is the antipatterns. I've been playing around with Canvas for about four years now and I never knew to use clientWidth and clientHeight to fix the problems I was having using width and height.


Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact