# Class LineTracer

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.LineTracer

public class LineTracer extends Object
Draws lines composed of a sequence of points, submitted one at a time. To use it make multiple calls of `addVertex`, followed by a call to `flush()`.

Where possible, sub-sequences of the point sequence are aggregated in supplied work arrays and plotted using `Graphics2D.draw(Shape)`. This is superior to the more obvious strategy of calling `Graphics.drawLine` for every pair of points. It is probably faster, it can work with non-integer coordinates, I think the line joining is better, and it is necessary to get the dashing right for dashed strokes, otherwise the dash starts anew for each edge. However, this is only possible for runs of points of the same colour; line segments of different colours have to be drawn separately, which means that lines of varying colour may look worse than single colour ones (poorer sub-pixel positioning, nastier line joins, incorrect dash phase).

This class does some other useful things like avoid attempts to plot lines which are extremely long or which are known to be outside the clip.

Since:
  12 Jun 2013
Author:
  Mark Taylor

## Constructor Summary

Constructors
Constructor
Description
`LineTracer(Graphics g, Rectangle bounds, Stroke stroke, boolean antialias, int nwork, boolean isPixel)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`void`
`addVertex(double dx, double dy, Color color)`
Adds a point to the sequence to be plotted.
`void`
`flush()`
Ensures that all points have been drawn.

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### LineTracer

public LineTracer(Graphics g, Rectangle bounds, Stroke stroke, boolean antialias, int nwork, boolean isPixel)
Constructor. The `nwork` parameter determines the number of points aggregated into a single plotting call. There may be visual anomalies every `nwork` points, so it should not be too small, but arrays of this size are allocated, so it should not be too large either.

Parameters:
  `g` - the base graphics context
  `bounds` - bounds beyond which lines should not be drawn
  `stroke` - line stroke
  `antialias` - whether lines are to be antialiased
  `nwork` - workspace array size
  `isPixel` - if true, the graphics context is considered to be pixellised, allowing some optimisations to be made that should not be visible

## Method Details

### addVertex

public void addVertex(double dx, double dy, Color color)
Adds a point to the sequence to be plotted. A null value for the `color` argument results in a break in the line.

Parameters:
  `dx` - graphics X coordinate
  `dy` - graphics Y coordinate
  `color` - line colour at point

### flush

public void flush()
Ensures that all points have been drawn. Since points are plotted in bursts for reasons of aesthetics and efficiency, this must be called after all `addVertex(double, double, Color)` calls to ensure that the drawing has actually been done.