net.groboclown.gui.paintpipe.v1
Class SimpleZOrderPainter

java.lang.Object
  |
  +--net.groboclown.gui.paintpipe.v1.PainterThread
        |
        +--net.groboclown.gui.paintpipe.v1.OutputPainter
              |
              +--net.groboclown.gui.paintpipe.v1.PipePainter
                    |
                    +--net.groboclown.gui.paintpipe.v1.SortingPainter
                          |
                          +--net.groboclown.gui.paintpipe.v1.SimpleZOrderPainter

public abstract class SimpleZOrderPainter

extends SortingPainter

The SimpleZOrderPainter works like a PipePainter, but sends the subclass methods waiting on events, the events in correct Z-Order.

The basis for Z-Ordering is the ZDepth attribute associated with several events (ImageDoneEvent and ZDepthDoneEvent). The lower the number, the lower in Z-Order, and so the higher the priority for drawing. This follows the Painter's Algorithm for back-to-forward painting. Other algorithms require more indepth knowledge of the data being processed, and so cannot be covered in a generic way such as this.

These are all dependent upon the threads which draw each z-depth. If a lower depth takes longer then a higher depth, then all depths above the slow depth will be idly waiting. But that's the cost of Z-Ordering.

There are two methods for implementing Z-Order. The first way is simple and straight-forward. The second, however, requires help from the particular instance.

1. Only one ImageDoneEvent is stored per Z-Depth. This allows for fast processing, as the images are processed as quickly as they come in order. So this is a single-key sorting, which is fast, but isn't very flexible. This is encapsulated in the current class.
2. Multiple ImageDoneEvents can be on the same Z-Depth. The routine #sortDepth, implemented by the subclass, figures out how to sort one depth, and returns it as an Enumeration (maybe use a List or Set, where the subclass provides the sorter?). A Z-Order depth can be flushed out by three methods:
   1. A call to #flushDepth is the most straight forward way, and in fact all other flushing methods call this one.
   2. A ZDepthDoneEvent is received in the pipe, which informs the sorter to close off and sort the given depth.
   3. A FlushPaintingEvent is received in the pipe, which informs the sorter to close off all the depths and pass them through.
   The flushed depth is not necessarily automatically passed to the pipe. Rather, it depends on the lower order Z-depths to be passed first.

So the Z-Order painters are just examples of the Sorting Painter pattern. In general, the Sorting Painter cannot send incremental updates to the pipe. Instead, the Sorting Painter spends its time in a thread sorting each paint event. In some cases, this is a complex problem requiring laborious computations.

Version:

1.0

Author:

Matt Albrecht

See Also:

OutputPainter, PaintQueue

Inner Class Summary

(package private) class

SimpleZOrderPainter.ZOrderCollection The only operations used are: clear(), add( Object ), and iterator().

Inner classes inherited from class net.groboclown.gui.paintpipe.v1.PainterThread

PainterThread.PaintRunnable

Field Summary

private ImageDoneEvent	ideFiller
private int	nextDepth
private ImageDoneEvent[]	zorder

Fields inherited from class net.groboclown.gui.paintpipe.v1.SortingPainter

sortedEvents

Fields inherited from class net.groboclown.gui.paintpipe.v1.PipePainter

inQ

Fields inherited from class net.groboclown.gui.paintpipe.v1.OutputPainter

outq

Fields inherited from class net.groboclown.gui.paintpipe.v1.PainterThread

frameNumber, group, isPainting, METRICS, metricsListeners, name, numberPaintAttempts, numberWaitForEvent, painter, priority, RUN_NEVER_STARTED, RUN_PAUSED, RUN_REQUESTED_PAUSE, RUN_REQUESTED_STOP, RUN_RUNNING, RUN_STOPPED, runState, sentPaintFinishedEvent, startTimeMillis, syncThis, totalPaintTimeMillis, totalWaitForEventTimeMillis

Constructor Summary

SimpleZOrderPainter(PaintQueue in, PaintQueue out, int maxZDepth)
Creates a new SimpleZOrderPainter with the given input and output PaintQueues.

Method Summary

protected boolean

areMoreEvents() Checks if any more events need to be pulled from the queue.

Methods inherited from class net.groboclown.gui.paintpipe.v1.SortingPainter

finishPaint, flushEvents, paintFinished, processEvent, processImage, setCollection

Methods inherited from class net.groboclown.gui.paintpipe.v1.PipePainter

getInputQueue, paint

Methods inherited from class net.groboclown.gui.paintpipe.v1.OutputPainter

firePaintEvent, getOutputQueue

Methods inherited from class net.groboclown.gui.paintpipe.v1.PainterThread

addMetricsListener, canPause, canStop, cleanup, fireMetricsPaint, fireMetricsWait, getFrameNumber, getNumberPaintCalls, getNumberWaitForEventTimes, getStartTimeMillis, getTotalPaintTimeMillis, getTotalWaitForEventTimeMillis, initialize, isAlive, isInterrupted, isRunning, isStopImpending, isStopping, isSuspended, isWaitingForEvent, join, killPainting, removeMetricsListener, resume, start, stop, stopInterrupt, stopInterruptJoin, stopJoin, suspend, suspendInterrupt

Methods inherited from class java.lang.Object

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

Field Detail

zorder

private ImageDoneEvent[] zorder

nextDepth

private int nextDepth

ideFiller

private ImageDoneEvent ideFiller

Constructor Detail

SimpleZOrderPainter

public SimpleZOrderPainter(PaintQueue in,
                           PaintQueue out,
                           int maxZDepth)

Creates a new SimpleZOrderPainter with the given input and output PaintQueues.

Parameters:

in - the input queue, listened to by this thread.

out - the output queue, in which events are fired to.

Method Detail

areMoreEvents

protected final boolean areMoreEvents()

Checks if any more events need to be pulled from the queue.

Overrides:

areMoreEvents in class SortingPainter

Returns:

true if it is believed that more PaintEvents are going to be used in the current frame creation.