# WebGL2Fundamentals.org

Fix, Fork, Contribute

# WebGL Implementing DrawImage

To implement most games in 2D requires just a single function to draw an image. Sure some 2d games do fancy thing with lines etc but if you only have a way to draw a 2D image on the screen you can pretty much make most 2d games.

The Canvas 2D api has very flexible function for drawing image called `drawImage`. It has 3 versions

``````ctx.drawImage(image, dstX, dstY);
ctx.drawImage(image, dstX, dstY, dstWidth, dstHeight);
ctx.drawImage(image, srcX, srcY, srcWidth, srcHeight,
dstX, dstY, dstWidth, dstHeight);
``````

Given everything you've learned so far how would you implement this in WebGL? Your first solution might be to generate vertices like some of the first articles on this site did. Sending vertices to the GPU is generally a slow operation (although there are cases where it will be faster).

This is where the whole point of WebGL comes into play. It's all about creatively writing a shader and then creatively using that shader to solve your problem.

``````ctx.drawImage(image, x, y);
``````

It draws an image at location `x, y` the same size as the image. To make a similar WebGL based function we could upload vertices that for `x, y`, `x + width, y`, `x, y + height`, and `x + width, y + height` then as we draw different images at different locations we'd generate different sets of vertices. In fact that's exactly what we did in our first article.

A far more common way though is just to use a unit quad. We upload a single square 1 unit big. We then use matrix math to scale and translate that unit quad so that it ends up being at the desired place.

Here's the code.

First we need a simple vertex shader

``````#version 300 es

in vec4 a_position;
in vec2 a_texcoord;

uniform mat4 u_matrix;

out vec2 v_texcoord;

void main() {
gl_Position = u_matrix * a_position;
v_texcoord = a_texcoord;
}
``````

``````#version 300 es
precision highp float;

in vec2 v_texcoord;

uniform sampler2D texture;

out vec4 outColor;

void main() {
outColor = texture(texture, v_texcoord);
}
``````

And now the function

``````function drawImage(tex, texWidth, texHeight, dstX, dstY) {
gl.useProgram(program);

// Setup the attributes for the quad
gl.bindVertexArray(vao);

var textureUnit = 0;
// The the shader we're putting the texture on texture unit 0
gl.uniform1i(textureLocation, textureUnit);

// Bind the texture to texture unit 0
gl.activeTexture(gl.TEXTURE0 + textureUnit);
gl.bindTexture(gl.TEXTURE_2D, tex);

// this matrix will convert from pixels to clip space
var matrix = m4.orthographic(0, gl.canvas.width, gl.canvas.height, 0, -1, 1);

// translate our quad to dstX, dstY
matrix = m4.translate(matrix, dstX, dstY, 0);

// scale our 1 unit quad
// from 1 unit to texWidth, texHeight units
matrix = m4.scale(matrix, texWidth, texHeight, 1);

// Set the matrix.
gl.uniformMatrix4fv(matrixLocation, false, matrix);

// draw the quad (2 triangles, 6 vertices)
var offset = 0;
var count = 6;
gl.drawArrays(gl.TRIANGLES, offset, count);
}
``````

Let's load some images into textures

``````// creates a texture info { width: w, height: h, texture: tex }
// when the image has loaded
var tex = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, tex);

gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

var textureInfo = {
width: 1,   // we don't know the size until it loads
height: 1,
texture: tex,
};
var img = new Image();
textureInfo.width = img.width;
textureInfo.height = img.height;

gl.bindTexture(gl.TEXTURE_2D, textureInfo.texture);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
gl.generateMipmap(gl.TEXTURE_2D);
});

return textureInfo;
}

var textureInfos = [
];
``````

And lets draw them at random places

``````var drawInfos = [];
var numToDraw = 9;
var speed = 60;
for (var ii = 0; ii < numToDraw; ++ii) {
var drawInfo = {
x: Math.random() * gl.canvas.width,
y: Math.random() * gl.canvas.height,
dx: Math.random() > 0.5 ? -1 : 1,
dy: Math.random() > 0.5 ? -1 : 1,
textureInfo: textureInfos[Math.random() * textureInfos.length | 0],
};
drawInfos.push(drawInfo);
}

function update(deltaTime) {
drawInfos.forEach(function(drawInfo) {
drawInfo.x += drawInfo.dx * speed * deltaTime;
drawInfo.y += drawInfo.dy * speed * deltaTime;
if (drawInfo.x < 0) {
drawInfo.dx = 1;
}
if (drawInfo.x >= gl.canvas.width) {
drawInfo.dx = -1;
}
if (drawInfo.y < 0) {
drawInfo.dy = 1;
}
if (drawInfo.y >= gl.canvas.height) {
drawInfo.dy = -1;
}
});
}

function draw() {
webglUtils.resizeCanvasToDisplaySize(gl.canvas);

// Tell WebGL how to convert from clip space to pixels
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);

// Clear the canvas
gl.clearColor(0, 0, 0, 0);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

drawInfos.forEach(function(drawInfo) {
drawImage(
drawInfo.textureInfo.texture,
drawInfo.textureInfo.width,
drawInfo.textureInfo.height,
drawInfo.x,
drawInfo.y);
});
}

var then = 0;
function render(time) {
var now = time * 0.001;
var deltaTime = Math.min(0.1, now - then);
then = now;

update(deltaTime);
draw();

requestAnimationFrame(render);
}
requestAnimationFrame(render);
``````

You can see that running here

Handling version 2 of the original canvas `drawImage` function

``````ctx.drawImage(image, dstX, dstY, dstWidth, dstHeight);
``````

Is really no different. We just use `dstWidth` and `dstHeight` instead of `texWidth` and `texHeight`.

``````*function drawImage(tex, texWidth, texHeight, dstX, dstY, dstWidth, dstHeight) {
+  if (dstWidth === undefined) {
+    dstWidth = texWidth;
+  }
+
+  if (dstHeight === undefined) {
+    dstHeight = texHeight;
+  }

gl.useProgram(program);

// Setup the attributes for the quad
gl.bindVertexArray(vao);

var textureUnit = 0;
// The the shader we're putting the texture on texture unit 0
gl.uniform1i(textureLocation, textureUnit);

// Bind the texture to texture unit 0
gl.activeTexture(gl.TEXTURE0 + textureUnit);
gl.bindTexture(gl.TEXTURE_2D, tex);

// this matrix will convert from pixels to clip space
var matrix = m4.orthographic(0, canvas.width, canvas.height, 0, -1, 1);

// translate our quad to dstX, dstY
matrix = m4.translate(matrix, dstX, dstY, 0);

// scale our 1 unit quad
*  // from 1 unit to dstWidth, dstHeight units
*  matrix = m4.scale(matrix, dstWidth, dstHeight, 1);

// Set the matrix.
gl.uniformMatrix4fv(matrixLocation, false, matrix);

// draw the quad (2 triangles, 6 vertices)
var offset = 0;
var count = 6;
gl.drawArrays(gl.TRIANGLES, offset, count);
}
``````

I've updated the code to use different sizes

So that was easy. But what about the 3rd version of canvas `drawImage`?

``````ctx.drawImage(image, srcX, srcY, srcWidth, srcHeight,
dstX, dstY, dstWidth, dstHeight);t
``````

In order to select part of the texture we need to manipulate the texture coordinates. How texture coordinates work was covered in the article about textures. In that article we manually created texture coordinates which is a very common way to do this but we can also create them on the fly and just like we're manipulating our positions using a matrix we can similarly manipulate texture coordinates using another matrix.

Let's add a texture matrix to the vertex shader and multiply the texture coordinates by this texture matrix.

``````#version 300 es

in vec4 a_position;
in vec2 a_texcoord;

uniform mat4 u_matrix;
+uniform mat4 u_textureMatrix;

out vec2 v_texcoord;

void main() {
gl_Position = u_matrix * a_position;
*   v_texcoord = (u_textureMatrix * vec4(a_texcoord, 0, 1)).xy;
}
``````

Now we need to look up the location of the texture matrix

``````var matrixLocation = gl.getUniformLocation(program, "u_matrix");
+var textureMatrixLocation = gl.getUniformLocation(program, "u_textureMatrix");
``````

And inside `drawImage` we need to set it so it will select the part of the texture we want. We know the texture coordinates are also effectively a unit quad so it's very similar to what we've already done for the positions.

``````*function drawImage(
*    tex, texWidth, texHeight,
*    srcX, srcY, srcWidth, srcHeight,
*    dstX, dstY, dstWidth, dstHeight) {
+  if (dstX === undefined) {
+    dstX = srcX;
+    srcX = 0;
+  }
+  if (dstY === undefined) {
+    dstY = srcY;
+    srcY = 0;
+  }
+  if (srcWidth === undefined) {
+    srcWidth = texWidth;
+  }
+  if (srcHeight === undefined) {
+    srcHeight = texHeight;
+  }
if (dstWidth === undefined) {
*    dstWidth = srcWidth;
+    srcWidth = texWidth;
}
if (dstHeight === undefined) {
*    dstHeight = srcHeight;
+    srcHeight = texHeight;
}

gl.bindTexture(gl.TEXTURE_2D, tex);

// this matrix will convert from pixels to clip space
var matrix = m4.orthographic(
0, gl.canvas.clientWidth, gl.canvas.clientHeight, 0, -1, 1);

// translate our quad to dstX, dstY
matrix = m4.translate(matrix, dstX, dstY, 0);

// scale our 1 unit quad
// from 1 unit to dstWidth, dstHeight units
matrix = m4.scale(matrix, dstWidth, dstHeight, 1);

// Set the matrix.
gl.uniformMatrix4fv(matrixLocation, false, matrix);

+  // Because texture coordinates go from 0 to 1
+  // and because our texture coordinates are already a unit quad
+  // we can select an area of the texture by scaling the unit quad
+  // down
+  var texMatrix = m4.translation(srcX / texWidth, srcY / texHeight, 0);
+  texMatrix = m4.scale(texMatrix, srcWidth / texWidth, srcHeight / texHeight, 1);
+
+  // Set the texture matrix.
+  gl.uniformMatrix4fv(textureMatrixLocation, false, texMatrix);

// draw the quad (2 triangles, 6 vertices)
gl.drawArrays(gl.TRIANGLES, 0, 6);
}
``````

I also updated the code to pick parts of the textures. Here's the result

Unlike the canvas 2D api our WebGL version handles cases the canvas 2D `drawImage` does not.

For one we can pass in a negative width or height for either source or dest. A negative `srcWidth` will select pixels to the left of `srcX`. A negative `dstWidth` will draw to the left of `dstX`. In the canvas 2D api these are errors at best or undefined behavior at worst.

Another is since we're using a matrix we can do any matrix math we want.

For example we could rotate the texture coordinates around the center of the texture.

Changing the texture matrix code to this

``````*  // just like a 2d projection matrix except in texture space (0 to 1)
*  // instead of clip space. This matrix puts us in pixel space.
*  var texMatrix = m4.scaling(1 / texWidth, 1 / texHeight, 1);
*
*  // We need to pick a place to rotate around
*  // We'll move to the middle, rotate, then move back
*  var texMatrix = m4.translate(texMatrix, texWidth * 0.5, texHeight * 0.5, 0);
*  var texMatrix = m4.zRotate(texMatrix, srcRotation);
*  var texMatrix = m4.translate(texMatrix, texWidth * -0.5, texHeight * -0.5, 0);
*
*  // because were in pixel space
*  // the scale and translation are now in pixels
*  var texMatrix = m4.translate(texMatrix, srcX, srcY, 0);
*  var texMatrix = m4.scale(texMatrix, srcWidth, srcHeight, 1);

// Set the texture matrix.
gl.uniformMatrix4fv(textureMatrixLocation, false, texMatrix);
``````

And here's that.

you can see one problem which is that because of the rotation sometimes we see past the edge of the texture. As it's set to `CLAMP_TO_EDGE` the edge just gets repeated.

We could fix that by discarding any pixels outside of the 0 to 1 range inside the shader. `discard` exits the shader immediately without writing a pixel.

``````#version 300 es
precision highp float;

in vec2 v_texcoord;

uniform sampler2D texture;

out vec4 outColor;

void main() {
+   if (v_texcoord.x < 0.0 ||
+       v_texcoord.y < 0.0 ||
+       v_texcoord.x > 1.0 ||
+       v_texcoord.y > 1.0) {
+   }
outColor = texture(texture, v_texcoord);
}
``````

And now the corners are gone

or maybe you'd like to use a solid color when the texture coordinates are outside the texture

``````#version 300 es
precision highp float;

in vec2 v_texcoord;

uniform sampler2D texture;

out vec4 outColor;

void main() {
if (v_texcoord.x < 0.0 ||
v_texcoord.y < 0.0 ||
v_texcoord.x > 1.0 ||
v_texcoord.y > 1.0) {
*     outColor = vec4(0, 0, 1, 1); // blue
+     return;
}
outColor = texture(texture, v_texcoord);
}
``````

The sky's really the limit. It's all up to your creative use of shaders.

### A minor optimization

I'm not recommending this optimization. Rather I want to point out more creative thinking since WebGL is all about creative use of the features it provides.

You might have noticed we're using a unit quad for our positions and those positions of a unit quad exactly match our texture coordinates. As such we can use the positions as the texture coordinates.

```#version 300 es
in vec4 a_position;
-in vec2 a_texcoord;

uniform mat4 u_matrix;
uniform mat4 u_textureMatrix;

out vec2 v_texcoord;

void main() {
gl_Position = u_matrix * a_position;
*   v_texcoord = (u_textureMatrix * a_position).xy;
}
```

We can now remove the code that setup the texture coordinates and it will work just the same as before.

• Fundamentals
• WebGL2 vs WebGL1
• Image Processing
• 2D translation, rotation, scale, matrix math
• 3D
• Lighting
• Structure and Organization
• Geometry
• Textures
• Rendering To A Texture