Learning WebGL

<< Lesson 7Lesson 9 >>

Welcome to my number eight in my series of WebGL tutorials, based on number 8 in the NeHe OpenGL tutorials. In it, we’ll go over blending, and as a useful side-effect run through roughly how the depth buffer works.

Here’s what the lesson looks like when run on a browser that supports WebGL (though sadly the transparency doesn’t show up all that well on the video):

Click here and you’ll see the live WebGL version, if you’ve got a browser that supports it; here’s how to get one if you don’t. You should see a semi-transparent slowly-spinning cube, apparently made of stained glass. Lighting should be the same as it was for the last lesson.

You can use the checkbox underneath the canvas to switch off or on the blending code, and thus the transparency effect. You can also adjust an alpha scaling factor (which we’ll explain later), and of course the lighting.

More on how it all works below…

The usual warning: these lessons are targeted at people with a reasonable amount of programming knowledge, but no real experience in 3D graphics; the aim is to get you up and running, with a good understanding of what’s going on in the code, so that you can start producing your own 3D Web pages as quickly as possible. If you haven’t read the previous tutorials already, you should probably do so before reading this one — here I will only explain the differences between the code for lesson 7 and the new code.

There may be bugs and misconceptions in this tutorial. If you spot anything wrong, let me know in the comments and I’ll correct it ASAP.

There are two ways you can get the code for this example; just “View Source” while you’re looking at the live version, or if you use GitHub, you can clone it (and the other lessons) from the repository there.

But before we start on the code, there’s a little bit of theory to go over. To start off with, I probably need to explain what blending actually is! And in order to do that, I should explain something about the depth buffer first.

The Depth Buffer

When you tell WebGL to draw something, as you may remember from lesson 2, it goes through a pipeline of stages. From a high level, it:

1. Runs the vertex shader on all of the vertices to work out where everything is.
2. Linearly interpolates between the vertices, which tells it which fragments (which for the moment you can treat as being the same as pixels) need to be painted.
3. For each fragment, run the fragment shader on it to work out its colour.
4. Write it to the frame buffer.

Now, ultimately the frame buffer is what is displayed. But what happens if you draw two things? For example, what if you draw a square with its centre at (0, 0, -5) and then another of the same size at (0, 0, -10)? You would not want the second square to overwrite the first, because it is clearly further away and should be hidden.

The way WebGL handles this is to use the depth buffer. When the fragments are written to the frame buffer after the fragment shader is finished with them, as well as the normal RGBA colour values, it also stores a depth value which is related to, but not exactly the same as, the Z value associated with the fragment. (Unsurprisingly, the depth buffer is often also referred to as the Z buffer.)

What do I mean by “related to”? Well, WebGL likes all of the Z values to be in the range from 0 to 1, with 0 closest and 1 furthest away. This is all hidden from us by the projection matrix we create with our call to perspective at the start of drawScene. For now all you need to know is that the larger the Z-buffer value, the further away something is; this is the opposite of our normal coordinates.

OK, so that’s the depth buffer. Now, you may remember that in the code that we’ve used to initialise our WebGL context ever since lesson 1, we’ve had the following two lines:

    gl.enable(gl.DEPTH_TEST);
    gl.depthFunc(gl.LEQUAL);

These are instructions to the WebGL system about what to do when writing to the a new fragment to the frame buffer. The first one says “pay attention to the depth buffer” and the second “if our fragment has a Z value that is less than or equal to the one that is currently there, use our new one rather than the old one”. This test on its own is enough to give us sensible behaviour; things that are close up obscure things that are further away. (You can also set the depth function to various other values, though I suspect they’re more rarely used.)

Blending

Blending is simply an alternative to this process. With depth-testing, we use the depth function to choose whether or not replace the existing fragment with the new one. When we’re doing blending, we use a blend function to combine the colours from both the existing and the new fragments to make an entirely new fragment, which we then write to the buffer.

Let’s take a look at the code now. Almost all of it is exactly the same as it was for lesson 7, and almost all of the important stuff is in a short segment in drawScene. Firstly, we check whether the “blending” checkbox is checked.

    var blending = document.getElementById("blending").checked;

If it is, we set the function that will be used to combine the two fragments:

    if (blending) {
      gl.blendFunc(gl.SRC_ALPHA, gl.ONE);

The parameters to this function define how the blending is done. This is fiddly, but not difficult. Firstly, let’s define two terms: the source fragment is the one that we’re drawing right now, and the destination fragment is the one that’s already in the frame buffer. The first parameter to the gl.blendFunc determines the source factor, and the second the destination factor; these factors are numbers used in the blending function. In this case, we’re saying that the source factor is the source fragment’s alpha value, and the destination factor is a constant value of one. There are other possibilities; for example, if you use SRC_COLOR to specify the source colour, you wind up with separate source factors for the red, green, blue and alpha values, each of which is equal to the original RGBA components.

Now, let’s imagine that WebGL is trying to work out the colour of a fragment when it has a destination with RGBA values of (R_d, G_d, B_d, A_d) and an incoming source fragment with values (R_s, G_s, B_s, A_s).

In addition, let’s say that we’ve got RGBA source factors of (S_r, S_g, S_b, S_a) and destination factors of (D_r, D_g, D_b, D_a)

For each colour component WebGL will calculate as follows:

• R_result = R_s * S_r + R_d * D_r
• G_result = G_s * S_g + G_d * D_g
• B_result = B_s * S_b + B_d * D_b
• A_result = A_s * S_a + A_d * D_a

So, in our case, we’re saying (just giving the calculation for the red component, to keep things simple):

• R_result = R_s * A_s + R_d

Normally this wouldn’t be an ideal way of creating transparency, but it happens to work very nicely in this case when the lighting is switched on. And this point is well worth emphasising; blending is not the same as transparency, it’s just a technique that can be used (among others) to get transparent-style effects. This took a while to percolate into my thick head when I was working my way through the Nehe lessons, so forgive me if I’m overemphasising it now :-)

OK, let’s move on:

      gl.enable(gl.BLEND);

A pretty simple one — like many things in WebGL, blending is disabled by default, so we need to switch it on.

      gl.disable(gl.DEPTH_TEST);

This is a little more interesting; we have to switch off depth testing. If we don’t do this, then the blending will happen in some cases and not in others. For example, if we draw a face of our cube that happens to be at the back before one at the front, then when the back face is drawn it will be written to the frame buffer, and then the front one will be blended on top of it, which is what we want. However, if we draw the front face first and then the back one, the back one will be discarded by the depth test before we get to the blending function, so it will not contribute to the image. This is not what we want.

Sharp-eyed readers will have noticed from this (and from the blend function above) that there’s a strong dependency when blending on the order in which you draw things that we haven’t encountered in previous lessons. More about this later; let’s finish with this bit of code first:

      gl.uniform1f(shaderProgram.alphaUniform, parseFloat(document.getElementById("alpha").value));

Here we’re loading an alpha value from a text field in the page and pushing it up to the shaders. This is because the image we’re using for the texture doesn’t have an alpha channel of its own (it’s just RGB, so has an implicit alpha value of 1 for every pixel) so it’s nice to be able to adjust the alpha to see how it affects the image.

The remainder of the code in drawScene is just that which is necessary to handle things in the normal fashion when blending is switched off:

    } else {
      gl.disable(gl.BLEND);
      gl.enable(gl.DEPTH_TEST);
    }

There’s also a small change in the fragment shader to use that alpha value when processing the texture:

  #ifdef GL_ES
  precision highp float;
  #endif

  varying vec2 vTextureCoord;
  varying vec3 vLightWeighting;

  uniform float uAlpha;

  uniform sampler2D uSampler;

  void main(void) {
     vec4 textureColor = texture2D(uSampler, vec2(vTextureCoord.s, vTextureCoord.t));
     gl_FragColor = vec4(textureColor.rgb * vLightWeighting, textureColor.a * uAlpha);
  }

That’s everything that’s changed in the code!

So let’s get back to that point about the drawing order. The transparency effect we get with this example is pretty good — it really does look like stained glass. But now try looking at it again, but change the directional lighting so that it’s coming from a positive Z direction — just remove the “-” from the appropriate field. It still looks pretty cool, but the realistic “stained glass” effect is gone.

The reason for that is that with the original lighting, the back-facing face of the cube is always dimly-lit. This means that its R, G and B values are low, so when the equation

• R_result = R_s * R_a + R_d

…is calculated, they show less strongly. To put it another way, we’ve got lighting that means that the stuff that is at the back is less visible. If we switch the lighting around so that stuff at the front is less visible, then our transparency effect works less well.

So how would you get “proper” transparency? Well, the OpenGL FAQ says that you need to use a source factor of SRC_ALPHA and a destination factor of ONE_MINUS_SRC_ALPHA. But we still have the problem that the source and the destination fragments are treated differently, and so there’s a dependency on the order in which stuff is drawn. And this point finally gets us to what I think of as the dirty secret of transparency in Open-/WebGL; again, quoting the OpenGL FAQ:

When using depth buffering in an application, you need to be careful about the order in which you render primitives. Fully opaque primitives need to be rendered first, followed by partially opaque primitives in back-to-front order. If you don’t render primitives in this order, the primitives, which would otherwise be visible through a partially opaque primitive, might lose the depth test entirely.

So, there you have it. Transparency using blending is tricky and fiddly, but if you control enough other aspects of the scene, like we controlled the lighting in this lesson, you can get the right effect without too much complexity. You can do it properly, but you’ll need to take care and draw stuff in a very specific order to get it looking good.

Luckily, blending is also useful for other effects, as you’ll see in the next lesson. But for now, you know all there is to learn from this lesson: you have a solid foundation for understanding the depth buffer, and you know how blending can be used to provide simple transparency.

If you have any questions, comments, or corrections, please do leave a comment below — in particular for this lesson. I personally felt that this was the hardest part of the NeHe lessons to really understand properly when I first did it, and I hope I’ve managed to make everything as clear as if not clearer than the original.

Next time, we’ll start improving the structure of the code, so that we can support a large number of different objects in the scene without all these messy global variables.

<< Lesson 7Lesson 9 >>

Acknowledgments: talking to Jonathan Hartley (no mean OpenGL coder himself) made the depth buffer and blending much clearer to me, and Steve Baker’s description of the Z buffer was also very useful. As always, I’m deeply in debt to NeHe for his OpenGL tutorial for the script for this lesson.