Drawing Shapes and Text with the Graphics Class

Suppose a Java program needs to show a picture. The picture might already exist as a file on the hard disk, or it might not exist at all until the program draws it. In both cases an image ends up in the computer's memory, but the two cases are not the same. Java's image library gives you a single idea, the Image, that sits underneath both situations. Before you write any drawing code, it helps to know which kind of image you are holding, because the kind determines how you can use it.

In this article you will follow one image through two stages. First you will see it as something loaded from outside the program, and then as a surface the program builds for itself. Watch for the moment the image changes from a passive thing you receive into something you actively write on.

The class java.awt.Image represents an image stored in the computer's memory. Java distinguishes two fundamentally different kinds of Image. The first kind is an image read from a source outside the program, such as a file on the computer's hard disk or a network connection. The program does not create the pixels of this image. It receives them from outside.

The second kind is an image created by the program itself, by drawing to it using a graphics context. The source calls this second type an off-screen canvas. Both kinds are images in memory, but only the second kind starts blank and is filled in by your code.

Notice what this definition does and does not promise. It says the canvas is a region of memory that can serve as a drawing surface. It does not say the canvas is always visible, and it does not say the canvas is the same thing as the window on the screen. Keeping those two ideas apart will make the rest of this article easier to follow.

An off-screen canvas can be represented by an object of the class BufferedImage. The source says this class is defined in the package java.awt.image, so to use it you refer to that package. BufferedImage is the concrete tool Java provides for the program-built kind of image described above.

The most important relationship is inheritance. BufferedImage is a subclass of Image. Because of this, a BufferedImage is still an Image, so it can be used anywhere the program expects an Image. The source states the practical consequence directly: once you have a BufferedImage, you can copy it into a graphics context g using one of the g.drawImage() methods, just as you would do with any other image.

Creating a canvas is only half of the story. The canvas becomes useful when something is drawn onto it. The source explains that it is possible to draw to an off-screen image using the same Graphics class used for drawing on the screen. The drawing code therefore looks much like the drawing code you would write for the screen. The difference is the destination: the Graphics object points at the off-screen canvas instead of the visible window.

Once the canvas has content, the source describes a second step. A BufferedImage can be copied into a graphics context g with a g.drawImage() method. This is how a finished off-screen canvas reaches a visible surface. Read the diagram below from left to right as a story. The program issues drawing instructions through a Graphics object. Those instructions change the canvas, which is the piece whose content is being built. Only at the end does the canvas leave the picture: a g.drawImage() call copies it into the destination graphics context g.