Image Observer

Drawing an image in a Java program is a request, not a self-contained action. The image does not paint itself onto the screen. Instead, the Graphics class provides the methods that copy an image onto a drawing surface, which is usually the screen but can also be an off-screen canvas. Most often this copying happens inside paintComponent() of a JComponent, where a Graphics object arrives as a parameter and you use it to draw.

This article starts from the simplest drawing statement and treats the more specialized variants as changes to that same call. Scaling and drawing only part of an image are both changes to the argument list. If you can read one drawImage() call carefully, the other forms become much easier to read.

The basic form places an image at a position. Inside a paintComponent() method, the call looks like this. The method receives a Graphics object named g, and the call draws the image named img at the position x and y, with this passed as the final argument.

Each argument has one job. The first argument, g, is the Graphics object that does the drawing. The second, img, is the image being copied. The x and y values give the position where the image is placed. The last argument, this, is the image observer. The source states that the image observer is required when an image is drawn and is passed as the final parameter. In the source's examples, this refers to the JComponent that contains the drawing code.

The drawImage() method has a variation that scales the image as it is drawn, so that it fills a width and height you specify. The form that does this inserts two size values after the position values. The position is still set by x and y, but the drawn size is now set by the width and height you pass rather than the size the image already has.

The most detailed form of drawImage() takes eight coordinates instead of a position and a size. The arguments are the destination coordinates first, then the source coordinates, then the image observer. The source pair describes two corners of a rectangle inside the original image, and only the pixels inside that rectangle are copied. The destination pair describes the rectangle on the drawing surface that receives those pixels.

The two rectangles are specified separately. The destination rectangle does not have to match the source rectangle in size. In the example above, a 100 by 80 pixel region is placed into a 200 by 150 destination area, so the taken portion is stretched as it is placed. The portion you take and the place you put it are independent choices.

When a drawn image is not what you expected, the cause is usually one argument in one call. Read each mistake below as a question to ask about your own code: at which argument did my expectation and the call stop agreeing?

When the drawn image looks wrong, work through the call argument by argument instead of rewriting it. Start with the argument that controls the outcome you are looking at. For a misplaced image, check x and y. For an image that is the wrong size, check width and height, or the destination corners in the eight-coordinate form. For an image that shows the wrong part of the picture, check the source corners.