Scissor Test

In which you to confine rendering to a particular region of the window.

Perhaps you've played a game with a split-screen or a mini-map. Or perhaps you recently explored orthographic projections with this renderer:

There's a picture-in-picture display in the bottom-left corner.

Split-screens, mini-maps and picture-in-picture displays are all achieved by rendering to multiple viewports. Each display's viewport is defined with a call to gl.viewport. For example, to set up a horizontal split-screen effect, which you might see in a two-player racing game, you might write this code:

const halfHeight = canvas.height / 2;

// gl.viewport's parameters are (x, y, width, height)
gl.viewport(0, 0, canvas.width, halfHeight);
// draw bottom content

gl.viewport(0, halfHeight, canvas.width, halfHeight);
// draw top content

Setting the viewport is usually not enough. If any geometry falls outside the viewport, it will bleed into neighboring viewports. You must perform two additional steps to staunch this bleeding:

Define the scissor box, which is the rectangle in which you want to restrict the rendering. Often this will be the same as the viewport.
Turn on the scissor test, which discards any pixels that don't fall within the scissor box.

Applying these steps results in this code:

gl.enable(gl.SCISSOR_TEST);

gl.viewport(0, 0, canvas.width, halfHeight);
gl.scissor(0, 0, canvas.width, halfHeight);
// draw bottom content

gl.viewport(0, halfHeight, canvas.width, halfHeight);
gl.scissor(0, halfHeight, canvas.width, halfHeight);
// draw top content

For the split-screen effect, the gl.viewport and gl.scissor calls use the same parameters. The viewport merely defines the transformation that converts normalized space coordinates into pixel coordinates. The scissor test discards fragments whose pixel coordinates lie outside of the scissor box.