Package org.bzdev.gio

Class ThreadedOSGraphics

java.lang.Object
org.bzdev.gio.OutputStreamGraphics
org.bzdev.gio.ThreadedOSGraphics
All Implemented Interfaces:
GraphicsCreator, OSGraphicsOps

public abstract class ThreadedOSGraphics extends OutputStreamGraphics implements GraphicsCreator
Multithreaded OutputStreamGraphics class using a paint method. In order to create some images with some formats (e.g., postscript), the existing class libraries require that one provide a "paint" method, whose argument is a graphics context to create the image. This paint method may be called multiple times with possibly different graphics contexts. In some cases one call is used to find the size of a bounding box, which is represented near the start of the output stream, and a second call is used to actually create the graphics. By contrast, the image formats supported by the javax.imageio package can be created by using a BufferedImage to create the image and then using an ImageIO write method. By contrast, OutputStreamGraphics has a subclass named ImageGraphics that uses an instance of BufferedImage internally and that provides createGraphics method to provide graphics contexts for drawing the image.

This class provides a paint method for use by an instance of an interface named GraphicsWriter, whose writeGraphics() method is called in a separate thread from the thread calling the constructor. The paint method creates a Graphics2DRecorder initialized with the graphics context provided by the paint method's argument. The paint method then waits until imageComplete is called. Until that happens, one may call createGraphics (perhaps multiple times) to obtain graphics contexts and use those graphics contexts to draw the graphics. After imageComplete is called, the paint method continues execution. On any additional calls to the paint method, the Graphics2DRecorder is used to replay the original sequence of operations. Finally, the output file or stream is created.

Subclasses of this class do not have to explicitly manage threads. They must provide the following:

  • the method newGraphicsWriter() to create a GraphicsWriter.
  • an implementation of GraphicsWriter that calls paint as needed, triggered by calling the GraphicsWriter method writeGraphics.
  • Constructor Details

    • ThreadedOSGraphics

      protected ThreadedOSGraphics(OutputStream os, int width, int height, ImageOrientation orientation, String type, boolean prefersAlpha)
      Constructor. The parameters (some of them) will typically be passed to a constructor for a class implementing GraphicsWriter. An instance of GraphicsWriter will be created, and a thread that will call the GraphicsWriter's writeGraphics method will be started. writeGraphics will call paint, which will block when it is safe for the constructor to return.
      Parameters:
      os - an output stream to which a image file will be written.
      width - the image width
      height - the image height
      orientation - the image orientation
      type - the string "ps"
      prefersAlpha - true if an alpha channel is desired (but ignored for postscript); false otherwise
  • Method Details

    • newGraphicsWriter

      protected abstract ThreadedOSGraphics.GraphicsWriter newGraphicsWriter()
      Create a new instance of GraphicsWriter. This is called by the constructor of ThreadedOSGraphics after its superclass has been initialized.
      Returns:
      a new graphics writer
    • getImplScaleFactor

      protected double getImplScaleFactor(ImageOrientation orientation)
      Get an additional implementation-specific scale factor. This method should be overridden in cases where the print area cannot be set directly (e.g., for postscript) and where the implementation will have to scale the dimensions so they will fit into the space provided. Currently (Java version 1.7 when this was written), Java postscript printing does not seem to let you set the dimensions of the area that will be displayed without clipping, so scaling is necessary. Other formats may have similar issues.

      The default implementation returns a value of 1.0 and that value will not be used to add an affine transformation.

      Parameters:
      orientation - the image orientation
      Returns:
      the scale factor
    • paint

      protected void paint(Graphics2D g2d)
      Draw the image. This method may be called multiple times. A subclass may have to override this method to make it visible to other classes in a package. This should be done as follows:
      
          protected void paint(Graphics2D g2d) {
             super.paint(g2d);
          }
       
      It is intended to be called from a thread that the constructor for this class (ThreadedOSGraphics) creates where the writeGraphics method of a GraphicsWriter is called. The method paint may be called multiple times. On the first call, the graphics operations are performed. On subsequent calls, these are replayed transparently. When paint is called the first time, the thread calling paint will block until all the graphics operations that are recorded have been completed.
      Parameters:
      g2d - the graphics context
    • setWriteException

      protected void setWriteException(Exception e)
      Log an exception. This should be set by subclasses if an error occurs. After it is called with a non-null argument, subsequent calls are ignored.
      Parameters:
      e - the exception
    • getColorModel

      public ColorModel getColorModel()
      Description copied from class: OutputStreamGraphics
      Get the color model for the image that will be produced.
      Specified by:
      getColorModel in interface OSGraphicsOps
      Specified by:
      getColorModel in class OutputStreamGraphics
      Returns:
      the color model
    • createGraphics

      public Graphics2D createGraphics()
      Get a graphics context for constructing the image file.
      Specified by:
      createGraphics in interface GraphicsCreator
      Specified by:
      createGraphics in interface OSGraphicsOps
      Specified by:
      createGraphics in class OutputStreamGraphics
      Returns:
      the graphics context
    • imageComplete

      public void imageComplete() throws IOException
      Complete writing the image file to the image stream. Does not close the stream, but will flush it.
      Specified by:
      imageComplete in interface OSGraphicsOps
      Specified by:
      imageComplete in class OutputStreamGraphics
      Throws:
      IOException - IO failure or a PrintException (which will be provided as the cause of the IOException)