Page 14: Web Graphics APIs

On Previous: Graphics101: Some Foundations , we learned about primitive-based graphics where we describe (program) pictures in terms of collections of geometric primitives.

The basic idea is that we create pictures not by describing the color of each pixel (as image-based graphics would do), but rather by using a set of “primitives” (basic objects) that we put together to make pictures.

When we program, we rarely handle the conversion to pixels ourselves. We use APIs (Application Programming Interface) - interfaces to other aspects of the software system (we used to say libraries) that take care of the “low level stuff” for us.

Graphics APIs allow us to write our programs at the level of abstraction that we like (primitives), and converts that to whatever it takes to get things on the screen.

Graphics APIs can take many different forms, based on the primitives they support, the kinds of abstractions they present, the style of programming they encourage, and of course the system they fit into. In practice, we choose APIs based on what we are doing. In class, I want you to have the experience of working with different kinds of APIs.

Fortunately, there are several graphics APIs built into modern web browers. And there are many others that provide layers on top of the built in ones.

Some Web APIs:

• HTML5 2D Canvas (or simply Canvas) - This is an immediate mode API (I’ll explain this later on the page) that provides a direct implementation of the common concepts of computer graphics. This is the API we will focus on for the 2D part of class as it provides a nice way to explore graphics concepts.
• Scalable Vector Graphics (or SVG) - SVG uses browser elements (the DOM) to represent pictures. It also works as a file format (just as HTML writes out the DOM to represent web pages). We’ll learn about SVG because it is useful, and it represents a retained mode API to contrast Canvas’ immediate mode.
• WebGL - WebGL is an API designed to provide efficient access to the graphics hardware. This makes it possible to write very efficient programs. However, the abstractions it provides are designed to map directly to the hardware, rather than to be convenient for programming computer graphics. We will learn about OpenGL, but we won’t program in it directly: we’ll use a higher level library to make it more convenient.
• WebGPU - Is a newer API that is designed to replace WebGL. It also is designed to provide convenient access to the graphics hardware for efficient programming. One big feature is that it allows using the graphics hardware for things other than making pictures.
• THREE.js - Is an API that is written as a layer over the built in APIs that provides a convenient set of abstractions to write graphics programs. Threejs lets us write programs using the concepts we learn about in class, and takes care of the messy parts of mapping things to the hardware. It is a retained mode API (like SVG, and unlike Canvas).
• D3 - Is an API that creates a layer on top of SVG making it more convenient for manipulating SVG in JavaScript.

In class, we will use Canvas, SVG and Threejs. We will mention WebGL, WebGPU, and D3. Technically, we will be using WebGPU or WebGL (since Threejs) is implemented on top of that.

Outside of class, you will probably use some other API if you program something other than the web browser. However, the concepts of the web APIs will be the same. Other programming languages have APIs that offer similar choices and abstractions.

The lecture video explains APIs and introduced Canvas. It then gives a quick tour of Canvas, covering the topics on the next few pages in a different order. The videos might be useful if you want to see things explained a different way.

2D Graphics APIs for the Web

For doing object-based (2D) graphics on web pages, there are two main APIs: Canvas and SVG. The naming of canvas is a little unfortunate - not only does it have the same name as the learning management system we use at UW, it also refers to more than just the 2D drawing API. It might be more precise to say the canvas 2D drawing API - but that’s a mouthful. In general, I’ll just refer to it as “Canvas”.

In class, we’ll mainly be using Canvas, but we will look at SVG as well. For the purpose of this workbook, SVG is important because it represents a very different kind of API than Canvas. They both do similar things, but they do it in very different ways. Beyond class, SVG is important because it is often used to make diagrams.

An important distinction we can make for graphics APIs is between immediate vs. retained mode.

• Immediate mode APIs draw immediately. When you make a function call to create, for example, a rectangle, the rectangle gets drawn immediately. (Conceptually) The system colors the pixels right away. In practice, you may not see the changes immediately (more on that in a bit). But, when you make a drawing call (like to the rectangle function), conceptually, the system colors the pixels. It forgets why it colored the pixels after it’s done. Canvas is an immediate mode API.
• Retained mode APIs create a list of objects that are drawn on demand. Function calls create objects in some storage (e.g., a list of objects), and eventually this list is drawn. The system remembers the objects, and refers to these when coloring the pixels. SVG is a retained mode API. Retained mode APIs are sometimes called display-list APIs since they keep a list of things to display.

This distinction will become clearer as we work through some examples.

Graphics Elements

Web pages are made up of elements - like paragraphs, headings, and buttons, we learned about that in the earlier pages.

To do graphics, we make special elements that give us a rectangular region that we can draw in. For the Canvas API (and actually some other APIs), we create “canvas” elements using the canvas tag. For SVGs, we create “svg” elements using the SVG tag.

Here’s an example with one of each, side by side - 01-14-01.html:

Note that these are normal HTML elements. We can give them ids (and classes), as well as styling them (here they have red borders). In fact, we can use CSS to style them.

By themselves, these elements are pretty boring - we need to write some JavaScript to make them more interesting by drawing something in the box. SVGs will have an alternative, but we’ll get to that later.

Drawing 2 Ways

Now I am going to use those same boxes, but draw in them. The HTML is basically the same as box 1. The difference is that the JavaScript is going to add a rectangle to each. Be sure to go look at the JavaScript in 01-14-02.js , which gets loaded at the end of the HTML file 01-14-02.html. You probably want to look at it (and any .js files) in vs code, rather than your browser, to get proper syntax highlighting.

You might notice that this code (and almost all of the examples in this workbook) do not use the window.onload event. Because we load our scripts, we can defer their execution using the script tag.

The canvas code (with comments removed) looks like:

1
2
3
4

let canvas = document.getElementById("canvas1"));
let context = canvas.getContext('2d');
context.fillStyle = "#F00";
context.fillRect(30,30,30,30);

On line 1 (which is line 15 of 01-14-02.js , we find the canvas element (that we have given the id “canvas1” when we made it in 01-14-02.html). We need to find the element to draw in it.

On line 2, we pull the context object from the element - this is the object that actually takes care of drawing.

On line 3, we set the color that we are going to draw (the fillStyle). If you don’t remember why #F00 is red, please review Graphics101: Some Foundations (color).

On line 4, we actually draw the filled rectangle. The first 30,30 means put the top left corner 30 units to the right and 30 units down from the top of the element, and make the square be 30 units wide and 30 units high. In both SVG and Canvas, Y is measured downwards - this is different than you might be used to from math classes. We’ll come back to talk about this later.

The fillRect function draws the rectangle “immediately” - it colors the pixels in the element. No rectangle is actually remembered - once the function is done, all that’s left are the pixels. The browser will not show you things immediately (we need to return to the event loop so it can do a “swap buffers”). It might seem obvious, but fillRect draws with the “current color” (that we had set with the fillStyle variable).

SVG is a very different kind of API. The graphics objects (like the rectangle) are actual objects on the web page (in the DOM - document object model, which you should remember from eariler pages). The rectangle will be an object just like the spans of text, buttons and sliders we saw.

The SVG example works very differently than the Canvas one. This is slightly simplified (you can see the actual code in 01-14-02.js which has comments that explain the missing details).

1
2
3
4
5
6
7
8

let svg = document.getElementById("svg1");
let square = document.createElementNS('rect');
square.setAttribute("x", "30");
square.setAttribute("y", "30");
square.setAttribute("width", "30");
square.setAttribute("height", "30");
square.setAttribute("fill", "#F00");
svg.appendChild(square);

Just like with canvas, we start by getting the element we’re drawing in (with id svg) on line 1 (which is line 25 of 01-14-02.js ). Line 2 is where things get very different: note that we make an element in the DOM - just like we would make a button or piece of text or any other HTML element. The rectangle is a rect element - part of the HTML page, just like any other element. Once we’ve created this element, it stays around. We can set its properties (its position, size and color), and we can add it as part of the SVG element (on line 8).

Note the contrast: with SVG, we made a rectangle object that stays around (since SVG is a retained API - we retain the objects). With Canvas, once we draw and color the pixels, the rectangle only exists to the extent that the pixels are colored.

For this simple example, there isn’t much difference.

When you look at the actual code in 01-14-02.js , you’ll notice that when we make the rect element, we need an extra parameter that tells the web browser that rect is a kind of SVG element.

Programming SVG by using the standard browser element manipulations is verbose and inconvenient. In practice, we often use another API to create an easier to use layer. In this workbook, I am doing everything directly to emphasize the SVG elements are DOM elements just as other things on the HTML page.

Moving Squares

Here’s a more interesting example that shows the difference between Canvas and SVG…

Again, look at the code (since this is box 3 of page 14, it’s 01-14-03.js ). You should recognize the animation loop using requestAnimationFrame from the previous workbook.

For each frame, we update the position of the rectangle (variable newX is set by reading the clock). But how we cause the square to appear in the new place is completely different.

For SVG, we simply need to change the position of the square we had created earlier.

With Canvas, there is no “earlier square” (since it was immediately turned to pixels). To draw a square in a new place, we need to draw a new square. But before that, we need to get rid of any old stuff (by clearing the picture using clearRect). Then we draw a new blue square.

This example hopefully highlights the difference between the immediate mode API (Canvas) and the retained mode API (SVG). In retained mode, the primitives (in this case the square) are represented as data. To move them, we change the data structure. In immediate mode, the primitives are drawn - they are only represented in the code. To animate things, we need to erase the picture and re-draw the picture.

In some ways, immediate mode is easier: we draw what we want, when we want. We can use whatever data structures we want to represent things. In other ways, retained mode is easier: we can create objects, and then alter them as needed.

Understanding SVG

We will come back to look at SVG more later in the semester. The rest of this workbook focuses on Canvas, with a little SVG thrown in for contrast. If you’re curious, you could start with CS559 SVG Tutorial Part 1: Getting Started with SVG and CS559 SVG Tutorial Part 2: Coordinate Systems, to learn more about SVG. In future modules, you’ll actually write some SVG yourself and will read those tutorials.

But for now, I want to emphasize the basic idea of SVG. Each graphics object (like the square) is an HTML element in the DOM; they are the same as any other web element (paragraphs, buttons, scripts, …). Adding the rectangle to the SVG element is just like adding a button to a paragraph.

Many of the things we can do with “normal” HTML elements (like text or buttons) can be done with the SVG graphics elements (like rectangles). We can do the same basic things: assign them an id, give them classes, use style sheets, etc. We can even create them right in the HTML using tags. They generate events just like many other kinds of HTML elements. Try moving the mouse over the rectangle on the right, or clicking the red rectangle. Then look into the JavaScript to see that this works just like any other event.

In 01-14-04.html, I’ve made the initial picture right in the HTML file. Note how I color the rectangles using a style sheet (although the style sheet is right inside the HTML file). Understand why some rectangles are blue. Notice how I respond to the events on the rectangles (the rightmost one gets enter and leave events - the leftmost one gets click events).

We will come back to SVG, but from this box, note how we can create SVG elements right in our HTML, refer to them from JavaScript, and attach events to them.

Summary: Two APIs

On this page, you got to see two different ways to do graphics on web pages. One using Canvas (an immediate mode API), and the other using SVG (a retained mode API).

We will learn to draw something more interesting than a rectangle using Canvas in the next pages.