Colors in Java Graphics

Imagine a Java program that draws three filled rectangles, then installs a new paint, then draws two more shapes. Before reading on, decide for yourself which shapes end up with the new paint. The answer depends on one method call, setPaint(), and on where that call appears in the code. This article follows a single idea from start to finish: a Paint object is only a description of a color, and it takes effect on the drawing surface only when it is installed and used by later drawing operations.

The source material illustrates the same idea with a polygon filled two different ways. One fill uses a gradient, the other uses a texture, and the outline is drawn in plain black. Those pictures were produced by a sample program called PaintDemo, which lets you choose among several paints and adjust their properties. Keep that picture in mind as you read, because the central question is how a single line of code can change the fill of everything drawn after it.

A Paint object and a Graphics2D object play different roles. The Paint object holds the colors and the rules for how they are distributed across a surface. The Graphics2D object is the drawing context that performs the actual drawing. Every drawing operation in Graphics2D takes its color from whichever Paint object is currently installed. This means the way you install a paint determines everything that follows it.

The flow in this diagram runs in one direction. Nothing flows backward: a drawing call made before the installation does not pick up the new paint, because the installation had not happened yet. Only calls made after setPaint() see the new paint, until another paint is installed or the paint is replaced.

A basic gradient paint is created with a constructor that takes two points, a color for each point, and a boolean called cyclic. The first four parameters together determine the geometry of the gradient. The constructor creates a gradient that has color c1 at the point (x1,y1) and color c2 at the point (x2,y2).

Moving along the straight line between the two points, the color changes smoothly from c1 to c2. Along any line perpendicular to that line, the color stays constant. The gradient is therefore organized in bands that run across the direction of the line joining the two points. The two points define both a direction and a length, so moving them changes the width and orientation of the gradient. A short distance between the points produces a sharp transition, while a long distance produces a gentle one.

The last parameter of the gradient constructor is the cyclic flag. The source describes its job precisely: it decides whether colors keep changing beyond the second endpoint. The gradient itself is defined between the two points, and the flag controls what happens on the far side of the second point. Because the source does not describe the appearance in more detail, the safe way to reason about it is to compare the two settings directly: with cyclic set to false, the gradient is defined by the two endpoints alone, while with cyclic set to true, the colors continue to change past the second endpoint.

The source also mentions two related classes. LinearGradientPaint is similar to GradientPaint but can be based on more than two colors. RadialGradientPaint colors pixels by their distance from a central point, which produces rings of constant color instead of bands. The source refers readers to the API documentation for details on these classes, so this article does not cover them further.

A TexturePaint creates a texture effect from an image. To construct one you need two things: a BufferedImage that holds the texture, and a rectangle in which that image will be drawn. The rectangle is a Rectangle2D anchor rectangle. The image is scaled, if necessary, so that it exactly fills the anchor rectangle.

Outside the anchor rectangle, the image repeats horizontally and vertically to cover the whole plane. This repetition is what makes the paint behave like a tiled texture rather than a single picture. The size and position of the rectangle control the scale of the texture and where its pattern lines up on the drawing surface.

Ordinarily the upper left corner of the rectangle sits at (0,0), and the rectangle has the same width and height as the image itself. In that common case the image is not scaled at all, and it tiles at its natural size. The source gives this pattern as the usual way to write the constructor call. Changing the rectangle is the way to change the scale of the texture, and moving its corner is the way to shift where the pattern begins.

The following program is an original illustration built around the gradient from the earlier section. It draws two shapes before setPaint() and two shapes after it. Trace it line by line and note which paint each fill uses at the moment it runs.