sim.portrayal.grid
Class FastValueGrid2DPortrayal

java.lang.Object
  extended bysim.portrayal.FieldPortrayal
      extended bysim.portrayal.FieldPortrayal2D
          extended bysim.portrayal.grid.ValueGrid2DPortrayal
              extended bysim.portrayal.grid.FastValueGrid2DPortrayal
All Implemented Interfaces:
Portrayal, Portrayal2D, java.io.Serializable

public class FastValueGrid2DPortrayal
extends ValueGrid2DPortrayal

This class works like a ValueGrid2DPortrayal, except that it doesn't use an underlying Portrayal for the object (instead it always draws a rectangle), and may ignore the getColor() method, so you shouldn't override that method to customize the color function in nonlinear ways any more. setColorTable() and setLevels() are still supported. Use this class instead of ValueGrid2DPortrayal unless you need to customize how the values are drawn (other than the color range or lookup table).

Additionally, FastValueGrid2DPortrayal is useful if your grid never changes past its first drawing. For example, if you're drawing static obstacles, cities, etc., which never change in value during the invocation of the simulation, then FastValueGrid2DPortrayal can draw them efficiently by just drawing once into its buffer and re-displaying the buffer over and over again. Just pass in true in the constructor.

If your grid does change but only occasionally, you can also use this technique as well; just manually call reset() whenever the grid changes to inform the FastValueGrid2DPortrayal that it needs to re-compute the buffer. reset() is threadsafe.

Important Note on Drawing Methods

FastValueGrid2DPortrayal can draw a grid in two ways. First, it can draw each of the rects individually ("USE_BUFFER"). Second, it can create a bitmap the size of the grid (one pixel per grid location), poke the colors into the bitmap, then stretch the bitmap over the area and draw it ("DONT_USE_BUFFER"). You can specify the method by calling the setBuffering() method; optionally you can just let FastValueGrid2DPortrayal guess which to use ("DEFAULT"). But you should know what you're doing, as methods can be much faster than each other depending on the situation. Use the following as guides
MacOS X
USE_BUFFER is much faster than DONT_USE_BUFFER in all cases, but can draw incorrectly aliased ("fuzzed out") rectangles when writing to media (a movie or a snapshot). The DEFAULT is for MacOS X is set to USE_BUFFER in ordinary drawing, and DONT_USE_BUFFER when writing to media.
Windows and X Windows
If you're not using any transparency (alpha), then DONT_USE_BUFFER is a tad faster than USE_BUFFER. But if you're using transparency, then DONT_USE_BUFFER is very slow -- in this case, try USE_BUFFER. Note however that in any case USE_BUFFER requires a lot of memory on Windows and X Windows due to poor implementation by Sun. You'll want to increase the default memory capacity, and expect occasional pauses for full garbage collection. You can test how often full garbage collection by running with java -verbose:gc ... and looking at the FULL GC printouts happen. Ordinary GC you shouldn't worry about. You can increase the default memory capacity to 50 Megabytes, for example (the default is about 20) by running with java -Xms20M ... The DEFAULT is for XWindows and Windows to use DONT_USE_BUFFER. You'll want to change this for sure if you're doing any transparency.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes inherited from class sim.portrayal.FieldPortrayal
FieldPortrayal.CustomInspector
 
Field Summary
static int DEFAULT
           
static int DONT_USE_BUFFER
           
static int USE_BUFFER
           
 
Fields inherited from class sim.portrayal.grid.ValueGrid2DPortrayal
clearColor, COLOR_DISCRETIZATION, colors, field, maxAlpha, maxBlue, maxGreen, maxLevel, maxRed, minAlpha, minBlue, minColor, minGreen, minLevel, minRed, valueName
 
Fields inherited from class sim.portrayal.FieldPortrayal
classPortrayals, portrayalForAll, portrayalForNull, portrayalForRemainder, portrayals
 
Constructor Summary
FastValueGrid2DPortrayal()
           
FastValueGrid2DPortrayal(boolean assumeImmutableGrid)
          If assumeImmutableGrid is true, we presume that the grid doesn't change.
FastValueGrid2DPortrayal(java.lang.String valueName)
           
FastValueGrid2DPortrayal(java.lang.String valueName, boolean assumeImmutableGrid)
          If assumeImmutableGrid is true, we presume that the grid doesn't change.
 
Method Summary
 void draw(java.lang.Object object, java.awt.Graphics2D graphics, DrawInfo2D info)
          Draws the field with its origin at [info.draw.x,info.draw.y], relative to the scaled coordinate system defined by [info.draw.width,info.draw.height].
 int getBuffering()
           
 java.awt.Color getColor(double level)
          Why is this version final? Because in some cases we call it and in others we compute the color on our own -- thus we don't want to be inconsistent if the user attempts to subclass FastValueGrid2DPortrayal and change this method.
 void reset()
           
 void setBuffering(int val)
           
 
Methods inherited from class sim.portrayal.grid.ValueGrid2DPortrayal
getDefaultPortrayal, getField, getValueName, getWrapper, hitOrDraw, newValue, setColorTable, setField, setLevels
 
Methods inherited from class sim.portrayal.FieldPortrayal2D
hitObjects
 
Methods inherited from class sim.portrayal.FieldPortrayal
getDefaultNullPortrayal, getInspector, getName, getPortrayalForAll, getPortrayalForNull, getPortrayalForObject, getPortrayalForRemainder, setPortrayalForAll, setPortrayalForClass, setPortrayalForNull, setPortrayalForObject, setPortrayalForRemainder, setSelected
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface sim.portrayal.Portrayal
getInspector, getName, setSelected
 

Field Detail

DEFAULT

public static final int DEFAULT
See Also:
Constant Field Values

USE_BUFFER

public static final int USE_BUFFER
See Also:
Constant Field Values

DONT_USE_BUFFER

public static final int DONT_USE_BUFFER
See Also:
Constant Field Values
Constructor Detail

FastValueGrid2DPortrayal

public FastValueGrid2DPortrayal(java.lang.String valueName,
                                boolean assumeImmutableGrid)
If assumeImmutableGrid is true, we presume that the grid doesn't change. This allows us to just re-splat the buffer.


FastValueGrid2DPortrayal

public FastValueGrid2DPortrayal(java.lang.String valueName)

FastValueGrid2DPortrayal

public FastValueGrid2DPortrayal(boolean assumeImmutableGrid)
If assumeImmutableGrid is true, we presume that the grid doesn't change. This allows us to just re-splat the buffer.


FastValueGrid2DPortrayal

public FastValueGrid2DPortrayal()
Method Detail

reset

public void reset()

getBuffering

public int getBuffering()

setBuffering

public void setBuffering(int val)

getColor

public final java.awt.Color getColor(double level)
Why is this version final? Because in some cases we call it and in others we compute the color on our own -- thus we don't want to be inconsistent if the user attempts to subclass FastValueGrid2DPortrayal and change this method.

Overrides:
getColor in class ValueGrid2DPortrayal

draw

public void draw(java.lang.Object object,
                 java.awt.Graphics2D graphics,
                 DrawInfo2D info)
Description copied from class: FieldPortrayal2D
Draws the field with its origin at [info.draw.x,info.draw.y], relative to the scaled coordinate system defined by [info.draw.width,info.draw.height]. The only parts that need be drawn are those which fall within the [info.clip] rectangle. Since your draw and hitObjects methods are likely to be nearly identical, you can choose instead to override the hitOrDraw method to handle both of them. By default this method simply calls hitOrDraw. FieldPortrayals will receive null for the object; they should just draw their own fields.

Specified by:
draw in interface Portrayal2D
Overrides:
draw in class FieldPortrayal2D