Package org.bzdev.gio

Class OutputStreamGraphics

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

public abstract class OutputStreamGraphics extends Object implements OSGraphicsOps, GraphicsCreator
Output some graphics to an output stream in a standard format. Various image formats are supported (the ones supported by Java). In addition, postscript is supported directly, and various other image formats may be supported via an SPI (Service Provider Interface). The image-format types one can expect to have are
  • png - provided by the Java imageio library.
  • jpeg - provided by the Java imageio library.
  • gif - provided by the Java imageio library.
  • bmp - provided by the Java imageio library.
  • wbmp - provided by the Java imageio library
  • ps - provided by the org.bzdev.gio package and the java.print package.
  • svg - this format will be activated if the Apache Batik package org.apache.batik and its subpackages are included on the class path. Batik-1.8 has some bugs that cause problems if an image is drawn. The symptom is a null pointer exception when a particular Batik method is used. As a work-around, the provider in org.bzdev.providers.osg for batik uses an anonymous class to override three methods where this bug may appear. The modification catches a null pointer exception and quietly continues. The result is that the image will not be drawn but the application will continue running. SVG providers should return instances of OutputStreamGraphics that implement the SvgOps interface.

The method named newInstance are used to create a new instance of this class. These newInstance methods use various subsets of the following arguments:

  • os - the input stream.
  • width - the width of the image when created in its normal orientation.
  • height - the height of the image when created in its normal orientation.
  • scaleFactor -a scale factor to change the image size. The scaling is the same in the X and Y directions, with (0.0, 0.0) always placed in the same location.
  • xtranslation - the translation in the X direction to apply after scaling. This can be used to center an image.
  • ytranslation - the translation in the Y direction to apply after scaling. This can be used to center an image.
  • orientation - either ImageOrientation.NORMAL (where the width and height have its normal meanings), ImageOrientation.CLOCKWISE90 (where the image is rotated clockwise 90 degrees and where the width and height are swapped), or ImageOrientation.COUNTERCLOCKWISE90 (where the image is rotated counterclockwise 90 degrees and where the width and height are swapped).
  • type - the type of the image format ("ps", "png", "jpeg", etc.). The static method getImageTypes() returns an array containing the valid image-format type names. The methods getImageTypeForFile(String) and getImageTypeForFile(File) can be used to look up the type given a file or file name. Similarly, getImageTypeForSuffix(String) can be used to look up an image-format type given a file-name extension.
  • preferAlpha - This is a boolean value. When true, it indicates that an image with an alpha channel is requested. Otherwise the value is false. Whether or not the request can be granted is dependent on the type of the image. Some image formats do not support alpha channels.

After obtaining a new instance of OutputStreamGraphics, the user should then call createGraphics() to create a graphics context for drawing. To finish creating the output stream, the user must call imageComplete(). As many graphics contexts as needed can be created.

Subclasses of OutputStreamGraphics are referenced by output-stream-graphics service providers. Subclasses used for this purpose must implement methods whose signature and modifiers are

  • public static Integer getDefaultWidth(ImageOrientation).
  • public static Integer getDefaultHeight(ImageOrientation).
These methods return the default height and width. In most cases the image orientation is ignored. One exception is for postscript, due to the use of a printer-based software that has dependencies are the sizes of various types of paper. The image orientation indicates how the image is intended to be viewed, and the height and width indicates the height and width when viewed from the desired orientation.
  • Constructor Details

    • OutputStreamGraphics

      protected OutputStreamGraphics(OutputStream os, int width, int height, ImageOrientation orientation, String type, boolean preferAlpha)
      Constructor. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.

      Constructors of subclasses must have these arguments. The constructor for subclasses will be called by one of the newInstance methods.

      Parameters:
      os - the output stream
      width - the image width (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
  • Method Details

    • getSuffixes

      public static String[] getSuffixes()
      Get all the file-name suffixes associated with graphics output streams. These may be used as file-name extensions.
      Returns:
      the suffixes
    • getSuffixesForImageType

      public static String[] getSuffixesForImageType(String imageType)
      Get the suffixes appropriate for an image-format type. These may be used as file-name extensions.
      Parameters:
      imageType - the image-format type
      Returns:
      the suffixes; null if there are none (e.g., if the image-format type is not recognized)
    • getSuffixesForMediaType

      public static String[] getSuffixesForMediaType(String mediaType)
      Get the suffixes appropriate for a media type. These may be used as file-name extensions.
      Parameters:
      mediaType - the media type
      Returns:
      the suffixes; null if there are none (e.g., if the image-format type is not recognized)
    • getMediaTypeForImageType

      public static String getMediaTypeForImageType(String imageType)
      Get the media type (MIME type) for an image-format type.
      Parameters:
      imageType - the image-format type
      Returns:
      the media type; null if there is none (e.g., if the image-format type is not recognized)
    • getSuffixForImageType

      public static String getSuffixForImageType(String imageType)
      Get the preferred suffix for an image-format type.
      Parameters:
      imageType - the image-format type
      Returns:
      the suffix; null if there is none (e.g., if the image-format type is not recognized)
    • getImageTypeForMediaType

      public static String getImageTypeForMediaType(String mediaType)
      Get the preferred image-format type for a media type. Multiple image-format types can have the same media type. This method picks a preferred one to use.
      Parameters:
      mediaType - the media type
      Returns:
      the corresponding image-format type; null if there is none (e.g., if the media type is not recognized)
    • getAliasesForMediaType

      public static String[] getAliasesForMediaType(String mediaType)
      Get all image-format types for a media type. Multiple image-format types can have the same media type. This method lists them. The first element of the array that is returned will contain the preferred image-format type. Other names are either aliases (e.g. "PS" for "ps") or indicate an image-format type and a specific provider.
      Parameters:
      mediaType - the media type
      Returns:
      the corresponding image-format types; null if there is none (e.g., if the media type is not recognized)
    • getAliasesForImageType

      public static String[] getAliasesForImageType(String imageType)
      Get all aliases for an image-format type. Multiple image-format types can have the same media type. This method lists all that have the same media type. The first element of the array that is returned will contain the preferred image-format type. Other names are aliases (e.g. "PS" for "ps", or indicate an image-format type and a specific provider).
      Parameters:
      imageType - the image-format type
      Returns:
      the corresponding image-format types; null if there is none (e.g., if the media type is not recognized)
    • getSuffixForMediaType

      public static String getSuffixForMediaType(String mediaType)
      Get the preferred suffix for a media type. Multiple suffixes can have the same media type. This method picks a preferred one to use.
      Parameters:
      mediaType - the media type
      Returns:
      the corresponding image-format type; null if there is none (e.g., if the media type is not recognized)
    • getImageTypes

      public static String[] getImageTypes()
      Get the supported image-format types. These include the image-format types supported by Java (the format names used in the javax.imageio package) plus an image-format type named "ps" for images that use Postscript. Aliases for the image-format types are not listed. An SPI (Service-Provider Interface) allows additional ones to be added.
      Returns:
      an array of strings naming these types
    • getAllImageTypes

      public static String[] getAllImageTypes()
      Get the supported image-format types, including aliases. These include the image-format types supported by Java (the format names used in the javax.imageio package) plus image-format types named "ps" or "PS" for images that use Postscript. An SPI (Service-Provider Interface) allows additional ones to be added.
      Returns:
      an array of all image-format type names.
    • getMediaTypes

      public static String[] getMediaTypes()
      Get the supported media types. These include the media types supported by Java (the media types used in the javax.imageio package) plus "application/postscript". An SPI (Service-Provider Interface) allows additional ones to be added.
      Returns:
      an array of strings naming these types.
    • getFilenameExtension

      public static String getFilenameExtension(File file)
      Get the extension for a file.
      Parameters:
      file - the file
      Returns:
      the file extension; null if there is no extension
    • getFilenameExtension

      public static String getFilenameExtension(String filename)
      Get the extension for a file name.
      Parameters:
      filename - the filename
      Returns:
      the file extension; null if there is no extension; an empty string if the file name ends in a period
    • getImageTypeForFile

      public static String getImageTypeForFile(File file)
      Get the image-format type given a file. The image-format type is determined by the file's extension. Image-format types are the format names used in the javax.imageio package, extended to include "ps".
      Parameters:
      file - the file
      Returns:
      the format name for the file; null if unknown or if there is none
    • getImageTypeForFile

      public static String getImageTypeForFile(String filename)
      Get the image-format type given a file name. The image-format type is determined by the file's extension. Image-format types are the format names used in the javax.imageio package, extended to include "ps".
      Parameters:
      filename - the file name
      Returns:
      the format name for the file name; null if unknown or if there is none
    • getImageTypeForSuffix

      public static String getImageTypeForSuffix(String extension)
      Get the image-format type given a file-name extension or suffix.
      Parameters:
      extension - the suffix or file-name extension
      Returns:
      the image-format type; null if there is none or if the image-format type is not recognized by Java
    • getOrientation

      public ImageOrientation getOrientation()
      Get the image orientation. Logically, an image is first drawn and then possibly rotated depending on the value of the image orientation.
      Returns:
      the image orientation (either ImageOrientation.NORMAL, ImageOrientation.COUNTERCLOCKWISE90, or ImageOrientation.CLOCKWISE90)
      See Also:
    • getBBScaleFactor

      public static double getBBScaleFactor(String type, int width, int height, ImageOrientation orientation)
      Get the scale factor to fit in a bounding box of the default size given an explicit image orientation.
      Parameters:
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      width - the width of the image in user-space coordinates
      height - the height of the image in user-space coordinates
      orientation - the image orientation
      Returns:
      the scale factor
    • getScaleFactor

      public double getScaleFactor()
      Get the scale factor. A scale factor can be used to scale the image created. The scaling occurs in user space and affects the size of everything drawn. The default scale factor is 1.0. Values above 1.0 may result in clipping.
      Returns:
      the scale factor
    • getTranslation

      public Point2D getTranslation()
      Get the user-space translation. A user-space translation is set by calling newInstance. This translation applies to the point 0.0 after scaling.
      Returns:
      the result of translating the point at the location (0.0, 0.0)
    • getOutputStream

      protected OutputStream getOutputStream()
      Get the output stream.
      Returns:
      the output stream
    • close

      public void close() throws IOException
      Close the underlying output stream. This is equivalent to the expression getOutputStream().close(). Note: in some cases, close should not be called. For example, when the output stream is an instance of ZipOutputStream, close() would close the whole stream. Instead one could use the expression ((ZipOutputStream)getOutputStream()).closeEntry().
      Specified by:
      close in interface OSGraphicsOps
      Throws:
      IOException - if an IO error occurred
    • getWidth

      public int getWidth()
      Get the image width parameter. This is the value determined by the method newInstance. Unless a graphics context is modified, this value represents an upper bound on the X coordinate of points that will appear in the image in the coordinate system used by the graphics context independent of the orientation
      Specified by:
      getWidth in interface OSGraphicsOps
      Returns:
      the width in user-space coordinates
    • getHeight

      public int getHeight()
      Get the image height parameter. This is the value determined by the method newInstance. Unless a graphics context is modified, this value represents an upper bound on the Y coordinate of points that will appear in the image in the coordinate system used by the graphics context independent of the orientation.
      Specified by:
      getHeight in interface OSGraphicsOps
      Returns:
      the height in user-space coordinates
    • getType

      public String getType()
      Get the image-format type parameter. This is the value passed to the method newInstance.
      Returns:
      the image-format type
    • getDefaultWidth

      public static int getDefaultWidth(String type, ImageOrientation orientation)
      Return the default width for a given type and image orientation. For many image formats, the returned value is not dependent on the orientation. Some (e.g., Postscript) will be orientation dependent as the default size is tied by the underlying Java implementation to sizes of paper supported by printers.
      Parameters:
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      orientation - the image orientation
      Returns:
      the default width
    • getDefaultHeight

      public static int getDefaultHeight(String type, ImageOrientation orientation)
      Return the default height for a given type and image orientation. For many image formats, the returned value is not dependent on the orientation. Some (e.g., Postscript) will be orientation dependent as the default size is tied by the underlying Java implementation to sizes of paper supported by printers.
      Parameters:
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      orientation - the image orientation
      Returns:
      the default height
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics.
      Parameters:
      os - the output stream
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics, possibly with an alpha channel.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, ImageOrientation orientation, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying an image orientation. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.
      Parameters:
      os - the output stream
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, ImageOrientation orientation, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying an image orientation, possibly with an alpha channel. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics given a height and width. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.
      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (ignored for determining the size of a Postscript image)
      height - the image height in user-space coordinates (ignored for determining the size of a Postscript image)
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics given a height and width, preferably with an alpha channel. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (ignored for determining the size of a Postscript image)
      height - the image height in user-space coordinates (ignored for determining the size of a Postscript image)
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, ImageOrientation orientation, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics given a height, width, and image orientation. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.
      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (ignored for determining the size of a Postscript image)
      height - the image height in user-space coordinates (ignored for determining the size of a Postscript image)
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, ImageOrientation orientation, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics given a height, width, and image orientation. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (ignored for determining the size of a Postscript image)
      height - the image height in user-space coordinates (ignored for determining the size of a Postscript image)
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true the caller requests an alpha channel; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics with a scale factor.
      Parameters:
      os - the output stream If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor; 0.0 or negative values indicate that the scale factor should be computed to match any size constraints set by the image-format type
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics with a scale factor, preferably with an alpha channel.
      Parameters:
      os - the output stream If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor; 0.0 or negative values indicate that the scale factor should be computed to match any size constraints set by the image-format type
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, ImageOrientation orientation, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, and image orientation. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.
      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor; 0.0 or negative values indicate that the scale factor should be computed to match any size constraints set by the image-format type
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, ImageOrientation orientation, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, and image orientation, preferably with an alpha channel. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor; 0.0 or negative values indicate that the scale factor should be computed to match any size constraints set by the image-format type
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, double xt, double yt, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, and translation. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.
      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor
      xt - the x translation in user space (the value of x that the point (0.0, 0.0) will be moved to)
      yt - the y translation in user space (the value of y that the point (0.0, 0.0) will be moved to)
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, double xt, double yt, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, and translation, preferably with an alpha channel. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor
      xt - the x translation in user space (the value of x that the point (0.0, 0.0) will be moved to)
      yt - the y translation in user space (the value of y that the point (0.0, 0.0) will be moved to)
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, double xt, double yt, ImageOrientation orientation, String type) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, translation, and image orientation. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.
      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor
      xt - the x translation in user space (the value of x that the point (0.0, 0.0) will be moved to)
      yt - the y translation in user space (the value of y that the point (0.0, 0.0) will be moved to)
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • newInstance

      public static OutputStreamGraphics newInstance(OutputStream os, int width, int height, double scaleFactor, double xt, double yt, ImageOrientation orientation, String type, boolean preferAlpha) throws IllegalArgumentException, RuntimeException
      Create an instance of OutputStreamGraphics specifying a height, width, scale factor, translation, and image orientation, preferably with an alpha channel. If the X value of a pixel that will be drawn is in the range (0, width), it will be visible in the image created. If the Y value of a pixel that will be drawn is in the range (0, height), it will be visible in the image created. When an image orientation other than ImageOrientation.NORMAL is specified, the operations are the same as if the image was drawn with an image orientation of ImageOrientation.NORMAL, and then (for other values of the image orientation) rotated by 90 degrees clockwise or counterclockwise, in which case the image produced will have its height and width exchanged.

      Note: while an alpha channel can be requested, so that the image created will support transparency, it may not be possible to grant this request, as some output formats, determined by the type argument, do not support alpha channels.

      Parameters:
      os - the output stream
      width - the image width in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      height - the image height in user-space coordinates (used by Postscript only for determining an aspect ratio, as the image will be scaled to fit on a page)
      scaleFactor - a positive real number giving the scale factor
      xt - the x translation in user space (the value of x that the point (0.0, 0.0) will be moved to)
      yt - the y translation in user space (the value of y that the point (0.0, 0.0) will be moved to)
      orientation - the image orientation
      type - a string naming an image-format type (valid types are discovered by calling getImageTypes()
      preferAlpha - true if an alpha channel is requested; false otherwise
      Returns:
      a new instance of OutputStreamGraphics
      Throws:
      IllegalArgumentException - an argument was illegal
      RuntimeException - a runtime exception occurred, possibly due to an error in a service provider (check the cause for the exception)
      See Also:
    • setupGraphicsForImages

      protected void setupGraphicsForImages(Graphics2D g2d)
      Sets up graphics assuming a graphics context is a typical image. When the orientation is COUNTERCLOCKWISE90 or CLOCKWISE90, the graphics context will be translated by the width or height, and then a rotation whose absolute value is 90 degrees will be applied. When the orientation is normal, there is no translation or rotation. Users can then draw objects as if width was horizontal and height was vertical. In addition, if an alpha channel was not requested, the image will be filled with a white background.

      Note: some classes (e.g., postscript graphics) do not use this method. It is not appropriate for all cases.

      Parameters:
      g2d - the graphics context
    • applyInitialTransform

      protected void applyInitialTransform(Graphics2D g2d)
      Apply the AffineTransform implied by a scale factor and translation set by a call to newInstance.

      This method should be used by subclasses when creating a graphics context. The main exception is postscript - the postscript print drivers will scale an image to fit on a page, so the use of this transform is pointless.

      Parameters:
      g2d - the graphics context
    • requestsAlpha

      public boolean requestsAlpha()
      Determine if this instance is requesting an alpha channel. The value may be changed from that provided in the constructor due to the capabilities of a particular image format.
      Specified by:
      requestsAlpha in interface OSGraphicsOps
      Returns:
      true if an alpha channel is requested; false otherwise
    • cancelRequestedAlpha

      protected void cancelRequestedAlpha()
      Cancel a request for an alpha channel. This method allows subclasses to cancel a request for an alpha channel. It will typically be called in a constructor for a subclass.
    • getColorModel

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

      public abstract Graphics2D createGraphics() throws UnsupportedOperationException
      Get a graphics context for drawing. The graphics context returned will implicitly handle any scaling or translations specified in the call to newInstance.
      Specified by:
      createGraphics in interface GraphicsCreator
      Specified by:
      createGraphics in interface OSGraphicsOps
      Returns:
      a new graphics context.
      Throws:
      UnsupportedOperationException - this operation is not supported, typically because the implementation can only create an instance of Graphics, not Graphics2D (something that would rarely, if ever, occur in practice)
    • flush

      public void flush() throws IOException
      Flush the output. The default implementation does not do anything. Subclasses for which providing a partial image makes sense may choose to implement this method. Such subclasses should be implemented so that a call to flush() is not needed after a call to {#link #imageComplete()}.;
      Specified by:
      flush in interface OSGraphicsOps
      Throws:
      IOException - - if an IO exception occurred
      See Also:
    • canReset

      public boolean canReset()
      Description copied from interface: OSGraphicsOps
      Test if the method OSGraphicsOps.reset() is supported.
      Specified by:
      canReset in interface OSGraphicsOps
      Returns:
      true if OSGraphicsOps.reset() is supported; false otherwise
    • reset

      public void reset() throws UnsupportedOperationException
      Description copied from interface: OSGraphicsOps
      Reset this graphics output stream. This is an optional operation as it is appropriate for some graphics output streams but not others
      Specified by:
      reset in interface OSGraphicsOps
      Throws:
      UnsupportedOperationException - an instance does not support resets
    • imageComplete

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