Graphics2D

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.awt
Class Graphics2D

    java.lang.Object
      java.awt.Graphics
          java.awt.Graphics2D

    public abstract class Graphics2D

extends Graphics

This `Graphics2D` class extends the `Graphics` class to provide more sophisticated control over graphics operations.

## Coordinate Spaces

All coordinates passed to a `Graphics2D` object are specified in a device-independent coordinate system called User Space, which is used by applications. The `Graphics2D` object behaves as if it contains a transform object as part of its internal rendering state that defines how to convert coordinates from user space to device-dependent coordinates in Device Space.

Some of the operations performed by the rendering attribute objects occur in the device space, but all `Graphics2D` methods take user space coordinates.

Every `Graphics2D` object is associated with a target that defines where rendering takes place. A `GraphicsConfiguration` object defines the characteristics of the rendering target, such as pixel format and resolution. The same rendering target is used throughout the life of a `Graphics2D` object.

When creating a `Graphics2D` object, the `GraphicsConfiguration` specifies the transform for the target of the `Graphics2D` (a `Component` or `Image`). This transform maps the user space coordinate system to screen and printer device coordinates such that the origin maps to the upper left hand corner of the target region of the device with increasing X coordinates extending to the right and increasing Y coordinates extending downward. The scaling of the transform is set to identity for those devices that are close to 72 dpi, such as screen devices. The scaling of the transform is set to approximately 72 user space coordinates per square inch for high resolution devices, such as printers. For image buffers, the transform is the identity transform.

## Rendering Process

The Rendering Process can be broken down into four phases that are controlled by the `Graphics2D` rendering attributes. The renderer can optimize many of these steps, either by caching the results for future calls, by collapsing multiple virtual steps into a single operation, or by recognizing various attributes as common simple cases that can be eliminated by modifying other parts of the operation.

The steps in the rendering process are:

1. Determine what to render.
2. Constrain the rendering operation to the current `Clip`. The `Clip` is specified by a `Shape` in user space and is controlled by the program using the various clip manipulation methods of `Graphics` . This user clip is transformed into device space by the target transform and combined with the device clip, which is defined by the visibility of windows and device extents. The combination of the user clip and device clip defines the composite clip, which determines the final clipping region. The user clip is not modified by the rendering system to reflect the resulting composite clip.
3. Determine what colors to render.
4. Apply the colors to the destination drawing surface using the current `Composite` attribute in the `Graphics2D` context.

The three types of rendering operations, along with details of each of their particular rendering processes are:

1. `Shape` operations
   1. If the operation is a `draw` operation, then the current `Stroke` attribute in the `Graphics2D` context is used to construct a new `Shape` object that contains the outline of the specified `Shape`.
   2. The `Shape` is transformed from user space to device space using the target transform in the `Graphics2D` context.
   3. The current `Color` in the `Graphics2D` context is used to determine the colors to render in device space.
2. Text operations
   1. The following steps are used to determine the set of glyphs required to render the indicated `String`:
      1. If the argument is a `String`, then the current `Font` in the `Graphics2D` context is asked to convert the Unicode characters in the `String` into a set of glyphs for presentation with whatever basic layout and shaping algorithms the font implements.
      2. If the argument is an `AttributedCharacterIterator`, its embedded font attributes are used to implement more sophisticated glyph layout algorithms .
   2. The current `Font` is queried to obtain outlines for the indicated glyphs. These outlines are treated as shapes in user space relative to the position of each glyph that was determined in step 1.
   3. The character outlines are filled as indicated above under `Shape` operations.
   4. The current `Color` is used to determine the colors to render in device space.
3. `Image` Operations
   1. The region of interest is defined by the bounding box of the source `Image`. This bounding box is specified in Image Space, which is the `Image` object's local coordinate system.
   2. In this Profile, the bounding box is always treated as if it is already in user space.
   3. The bounding box of the source `Image` is transformed from user space into device space using the target transform . Note that the result of transforming the bounding box does not necessarily result in a rectangular region in device space.
   4. The `Image` object determines what colors to render, sampled according to the source to destination coordinate mapping specified by the target transform .

## Default Rendering Attributes

The default values for the `Graphics2D` rendering attributes are:

`Color`
  The color of the `Component`.
`Font`
  The `Font` of the `Component`.
`Stroke`
  A square pen with a linewidth of 1, no dashing, miter segment joins and square end caps (unless restricted - see restrictions in `BasicStroke`) .
`Composite`
  The `AlphaComposite.SRC_OVER` rule.
`Clip`
  No rendering `Clip`, the output is clipped to the `Component`.

#### Restrictions

- Only instances of `AlphaComposite` are permitted when setting the `Composite` of the graphics context. See:
  - `setComposite(java.awt.Composite)`
- Only instances of `BasicStroke` are permitted when setting the `Stroke` of the graphics context. See:
  - `setStroke(java.awt.Stroke)`
  - `BasicStroke`
- A Graphics2D implementation may ignore the `BasicStroke` attributes end cap, line join, and miter limit. See:
  - `setStroke(java.awt.Stroke)`
  - `BasicStroke`
  - Profile-specific properties.

Version:
  1.78, 01/23/03
Author:
  Jim Graham

Method Summary
`abstract void` | `drawString(String str, int x, int y)` Draws the text given by the specified string, using this graphics context's current font and color.
`abstract Composite` | `getComposite()` Returns the current `Composite` in the `Graphics2D` context.
`abstract GraphicsConfiguration` | `getDeviceConfiguration()` Returns the device configuration associated with this `Graphics2D`.
`abstract Stroke` | `getStroke()` Returns the current `Stroke` in the `Graphics2D` context.
`abstract void` | `setComposite(Composite comp)` Sets the `Composite` for the `Graphics2D` context.
`abstract void` | `setStroke(Stroke s)` Sets the `Stroke` for the `Graphics2D` context.

Methods inherited from class java.awt.Graphics
`clearRect, clipRect, copyArea, create, create, dispose, draw3DRect, drawArc, drawBytes, drawChars, drawImage, drawImage, drawImage, drawImage, drawImage, drawImage, drawLine, drawOval, drawPolygon, drawPolygon, drawPolyline, drawRect, drawRoundRect, drawString, fill3DRect, fillArc, fillOval, fillPolygon, fillPolygon, fillRect, fillRoundRect, finalize, getClip, getClipBounds, getClipBounds, getColor, getFont, getFontMetrics, getFontMetrics, hitClip, setClip, setClip, setColor, setFont, setPaintMode, setXORMode, toString, translate`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Method Detail

### drawString

    public abstract void drawString(String str,
                                    int x,
                                    int y)

  Draws the text given by the specified string, using this graphics context's current font and color. The baseline of the leftmost character is at position (x, y) in this graphics context's coordinate system.

  Specified by:
    `drawString` in class `Graphics`
  Parameters:
    `str` - the string to be rendered
    `x` - the x coordinate of the location where the `String` should be rendered
    `y` - the y coordinate of the location where the `String` should be rendered
  Throws:
    `NullPointerException` - if `str` is `null`
  Since:
    JDK1.0
  See Also:
    `Graphics.drawBytes(byte[], int, int, int, int)`, `Graphics.drawChars(char[], int, int, int, int)`

### getDeviceConfiguration

    public abstract GraphicsConfiguration getDeviceConfiguration()

  Returns the device configuration associated with this `Graphics2D`.

  Returns:
    the device configuration of this `Graphics2D`.

### setComposite

    public abstract void setComposite(Composite comp)

  Sets the `Composite` for the `Graphics2D` context. The `Composite` is used in all drawing methods such as `drawImage`, `drawString`, `draw`, and `fill`. It specifies how new pixels are to be combined with the existing pixels on the graphics device during the rendering process.

  Note: This operation is subject to restriction in this Profile. If the `Composite` is a custom object rather than an instance of the `AlphaComposite` class then `IllegalArgumentException` is thrown.

  Parameters:
    `comp` - the `Composite` object to be used for rendering
  Throws:
    `IllegalArgumentException` - If `comp` is not an instance of `AlphaComposite`.
  See Also:
    `getComposite()`, `AlphaComposite`

### setStroke

    public abstract void setStroke(Stroke s)

  Sets the `Stroke` for the `Graphics2D` context.

  Parameters:
    `s` - the `Stroke` object to be used to stroke a `Shape` during the rendering process

    Note: This operation is subject to restriction in this Profile. If the `Stroke` is a custom object rather than an instance of the `BasicStroke` class then `IllegalArgumentException` is thrown.

  See Also:
    `BasicStroke`, `getStroke()`

### getComposite

    public abstract Composite getComposite()

  Returns the current `Composite` in the `Graphics2D` context.

  Returns:
    the current `Graphics2D` `Composite`, which defines a compositing style.
  See Also:
    `setComposite(java.awt.Composite)`

### getStroke

    public abstract Stroke getStroke()

  Returns the current `Stroke` in the `Graphics2D` context.

  Returns:
    the current `Graphics2D` `Stroke`, which defines the line style.
  See Also:
    `setStroke(java.awt.Stroke)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD