org.apache.xmlgraphics.image

## Class GraphicsUtil

- java.lang.Object
- - org.apache.xmlgraphics.image.GraphicsUtil

-     public final class GraphicsUtil
      extends java.lang.Object

  Set of utility methods for Graphics. These generally bypass broken methods in Java2D or provide tweaked implementations.
  Version:
    $Id$ Originally authored by Thomas DeWeese.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.awt.geom.AffineTransform` | `IDENTITY`
    `static java.awt.image.ColorModel` | `Linear_sRGB` Standard prebuilt Linear_sRGB color model with no alpha
    `static java.awt.image.ColorModel` | `Linear_sRGB_Pre` Standard prebuilt Linear_sRGB color model with premultiplied alpha.
    `static java.awt.image.ColorModel` | `Linear_sRGB_Unpre` Standard prebuilt Linear_sRGB color model with unpremultiplied alpha.
    `static java.awt.image.ColorModel` | `sRGB` Standard prebuilt sRGB color model with no alpha.
    `static java.awt.image.ColorModel` | `sRGB_Pre` Standard prebuilt sRGB color model with premultiplied alpha.
    `static java.awt.image.ColorModel` | `sRGB_Unpre` Standard prebuilt sRGB color model with unpremultiplied alpha.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.awt.image.ColorModel` | `coerceColorModel(java.awt.image.ColorModel cm, boolean newAlphaPreMult)` Create a new ColorModel with it's alpha premultiplied state matching newAlphaPreMult.
    `static java.awt.image.ColorModel` | `coerceData(java.awt.image.WritableRaster wr, java.awt.image.ColorModel cm, boolean newAlphaPreMult)` Coerces data within a bufferedImage to match newAlphaPreMult, Note that this can not change the colormodel of bi so you
    `static CachableRed` | `convertToLsRGB(CachableRed src)` This method will return a CacheableRed that has it's data in the linear sRGB colorspace.
    `static CachableRed` | `convertTosRGB(CachableRed src)` This method will return a CacheableRed that has it's data in the sRGB colorspace.
    `static void` | `copyBand(java.awt.image.Raster src, int srcBand, java.awt.image.WritableRaster dst, int dstBand)`
    `static void` | `copyBand(java.awt.image.Raster src, java.awt.Rectangle sR, int sBand, java.awt.image.WritableRaster dst, java.awt.Rectangle dR, int dBand)`
    `static void` | `copyData_FALLBACK(java.awt.image.Raster src, java.awt.image.WritableRaster dst)`
    `static void` | `copyData_INT_PACK(java.awt.image.Raster src, java.awt.image.WritableRaster dst)` An internal optimized version of copyData designed to work on Integer packed data with a SinglePixelPackedSampleModel.
    `static void` | `copyData(java.awt.image.BufferedImage src, java.awt.image.BufferedImage dst)` Copies data from one bufferedImage to another paying attention to the state of AlphaPreMultiplied.
    `static void` | `copyData(java.awt.image.BufferedImage src, java.awt.Rectangle srcRect, java.awt.image.BufferedImage dst, java.awt.Point destP)` Copies data from one bufferedImage to another paying attention to the state of AlphaPreMultiplied.
    `static void` | `copyData(java.awt.image.Raster src, java.awt.image.WritableRaster dst)` Copies data from one raster to another.
    `static java.awt.image.WritableRaster` | `copyRaster(java.awt.image.Raster ras)` Creates a new raster that has a copy of the data in `ras`.
    `static java.awt.image.WritableRaster` | `copyRaster(java.awt.image.Raster ras, int minX, int minY)` Creates a new raster that has a copy of the data in `ras`.
    `protected static void` | `divide_BYTE_COMP_Data(java.awt.image.WritableRaster wr)`
    `protected static void` | `divide_INT_PACK_Data(java.awt.image.WritableRaster wr)`
    `static void` | `divideAlpha(java.awt.image.WritableRaster wr)`
    `static java.awt.image.Raster` | `getAlphaRaster(java.awt.image.RenderedImage image)` Extracts an alpha raster from a RenderedImage.
    `static boolean` | `is_BYTE_COMP_Data(java.awt.image.SampleModel sm)`
    `static boolean` | `is_INT_PACK_Data(java.awt.image.SampleModel sm, boolean requireAlpha)`
    `static java.awt.image.ColorModel` | `makeLinear_sRGBCM(boolean premult)` Method that returns either Linear_sRGB_Pre or Linear_sRGB_UnPre based on premult flag.
    `static java.awt.image.BufferedImage` | `makeLinearBufferedImage(int width, int height, boolean premult)` Constructs a BufferedImage with a linear sRGB colorModel, and alpha.
    `static java.awt.image.WritableRaster` | `makeRasterWritable(java.awt.image.Raster ras)` Coerces `ras` to be writable.
    `static java.awt.image.WritableRaster` | `makeRasterWritable(java.awt.image.Raster ras, int minX, int minY)` Coerces `ras` to be writable.
    `protected static void` | `mult_BYTE_COMP_Data(java.awt.image.WritableRaster wr)`
    `protected static void` | `mult_INT_PACK_Data(java.awt.image.WritableRaster wr)`
    `static void` | `multiplyAlpha(java.awt.image.WritableRaster wr)`
    `static CachableRed` | `wrap(java.awt.image.RenderedImage ri)` Convertes any RenderedImage to a CacheableRed.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### IDENTITY

          public static final java.awt.geom.AffineTransform IDENTITY

    - #### Linear_sRGB

          public static final java.awt.image.ColorModel Linear_sRGB

      Standard prebuilt Linear_sRGB color model with no alpha

    - #### Linear_sRGB_Pre

          public static final java.awt.image.ColorModel Linear_sRGB_Pre

      Standard prebuilt Linear_sRGB color model with premultiplied alpha.

    - #### Linear_sRGB_Unpre

          public static final java.awt.image.ColorModel Linear_sRGB_Unpre

      Standard prebuilt Linear_sRGB color model with unpremultiplied alpha.

    - #### sRGB

          public static final java.awt.image.ColorModel sRGB

      Standard prebuilt sRGB color model with no alpha.

    - #### sRGB_Pre

          public static final java.awt.image.ColorModel sRGB_Pre

      Standard prebuilt sRGB color model with premultiplied alpha.

    - #### sRGB_Unpre

          public static final java.awt.image.ColorModel sRGB_Unpre

      Standard prebuilt sRGB color model with unpremultiplied alpha.

  - ### Method Detail

    - #### makeLinear_sRGBCM

          public static java.awt.image.ColorModel makeLinear_sRGBCM(boolean premult)

      Method that returns either Linear_sRGB_Pre or Linear_sRGB_UnPre based on premult flag.
      Parameters:
        `premult` - True if the ColorModel should have premultiplied alpha.
      Returns:
        a ColorMdoel with Linear sRGB colorSpace and the alpha channel set in accordance with `premult`

    - #### makeLinearBufferedImage

          public static java.awt.image.BufferedImage makeLinearBufferedImage(int width,
                                                                             int height,
                                                                             boolean premult)

      Constructs a BufferedImage with a linear sRGB colorModel, and alpha.
      Parameters:
        `width` - The desired width of the BufferedImage
        `height` - The desired height of the BufferedImage
        `premult` - The desired state of alpha premultiplied
      Returns:
        The requested BufferedImage.

    - #### convertToLsRGB

          public static CachableRed convertToLsRGB(CachableRed src)

      This method will return a CacheableRed that has it's data in the linear sRGB colorspace. If `src` is already in linear sRGB then this method does nothing and returns `src`. Otherwise it creates a transform that will convert `src`'s output to linear sRGB and returns that CacheableRed.
      Parameters:
        `src` - The image to convert to linear sRGB.
      Returns:
        An equivilant image to `src` who's data is in linear sRGB.

    - #### convertTosRGB

          public static CachableRed convertTosRGB(CachableRed src)

      This method will return a CacheableRed that has it's data in the sRGB colorspace. If `src` is already in sRGB then this method does nothing and returns `src`. Otherwise it creates a transform that will convert `src`'s output to sRGB and returns that CacheableRed.
      Parameters:
        `src` - The image to convert to sRGB.
      Returns:
        An equivilant image to `src` who's data is in sRGB.

    - #### wrap

          public static CachableRed wrap(java.awt.image.RenderedImage ri)

      Convertes any RenderedImage to a CacheableRed.

      If `ri` is already a CacheableRed it casts it down and returns it.

      In cases where `ri` is not already a CacheableRed it wraps `ri` with a helper class. The wrapped CacheableRed "Pretends" that it has no sources since it has no way of inteligently handling the dependency/dirty region calls if it exposed the source.

      Parameters:
        `ri` - The RenderedImage to convert.
      Returns:
        a CacheableRed that contains the same data as ri.

    - #### copyData_INT_PACK

          public static void copyData_INT_PACK(java.awt.image.Raster src,
                                               java.awt.image.WritableRaster dst)

      An internal optimized version of copyData designed to work on Integer packed data with a SinglePixelPackedSampleModel. Only the region of overlap between src and dst is copied. Calls to this should be preflighted with is_INT_PACK_Data on both src and dest (requireAlpha can be false).
      Parameters:
        `src` - The source of the data
        `dst` - The destination for the data.

    - #### copyData_FALLBACK

          public static void copyData_FALLBACK(java.awt.image.Raster src,
                                               java.awt.image.WritableRaster dst)

    - #### copyData

          public static void copyData(java.awt.image.Raster src,
                                      java.awt.image.WritableRaster dst)

      Copies data from one raster to another. Only the region of overlap between src and dst is copied. `Src` and `Dst` must have compatible SampleModels.
      Parameters:
        `src` - The source of the data
        `dst` - The destination for the data.

    - #### copyRaster

          public static java.awt.image.WritableRaster copyRaster(java.awt.image.Raster ras)

      Creates a new raster that has a copy of the data in `ras`. This is highly optimized for speed. There is no provision for changing any aspect of the SampleModel. This method should be used when you need to change the contents of a Raster that you do not "own" (ie the result of a `getData` call).
      Parameters:
        `ras` - The Raster to copy.
      Returns:
        A writable copy of `ras`

    - #### copyRaster

          public static java.awt.image.WritableRaster copyRaster(java.awt.image.Raster ras,
                                                                 int minX,
                                                                 int minY)

      Creates a new raster that has a copy of the data in `ras`. This is highly optimized for speed. There is no provision for changing any aspect of the SampleModel. However you can specify a new location for the returned raster. This method should be used when you need to change the contents of a Raster that you do not "own" (ie the result of a `getData` call).
      Parameters:
        `ras` - The Raster to copy.
        `minX` - The x location for the upper left corner of the returned WritableRaster.
        `minY` - The y location for the upper left corner of the returned WritableRaster.
      Returns:
        A writable copy of `ras`

    - #### makeRasterWritable

          public static java.awt.image.WritableRaster makeRasterWritable(java.awt.image.Raster ras)

      Coerces `ras` to be writable. The returned Raster continues to reference the DataBuffer from ras, so modifications to the returned WritableRaster will be seen in ras.

      This method should only be used if you need a WritableRaster due to an interface (such as to construct a BufferedImage), but have no intention of modifying the contents of the returned Raster. If you have any doubt about other users of the data in `ras`, use copyRaster (above).

      Parameters:
        `ras` - The raster to make writable.
      Returns:
        A Writable version of ras (shares DataBuffer with `ras`).

    - #### makeRasterWritable

          public static java.awt.image.WritableRaster makeRasterWritable(java.awt.image.Raster ras,
                                                                         int minX,
                                                                         int minY)

      Coerces `ras` to be writable. The returned Raster continues to reference the DataBuffer from ras, so modifications to the returned WritableRaster will be seen in ras.

      You can specify a new location for the returned WritableRaster, this is especially useful for constructing BufferedImages which require the Raster to be at (0,0). This method should only be used if you need a WritableRaster due to an interface (such as to construct a BufferedImage), but have no intention of modifying the contents of the returned Raster. If you have any doubt about other users of the data in `ras`, use copyRaster (above).

      Parameters:
        `ras` - The raster to make writable.
        `minX` - The x location for the upper left corner of the returned WritableRaster.
        `minY` - The y location for the upper left corner of the returned WritableRaster.
      Returns:
        A Writable version of `ras` with it's upper left hand coordinate set to minX, minY (shares it's DataBuffer with `ras`).

    - #### coerceColorModel

          public static java.awt.image.ColorModel coerceColorModel(java.awt.image.ColorModel cm,
                                                                   boolean newAlphaPreMult)

      Create a new ColorModel with it's alpha premultiplied state matching newAlphaPreMult.
      Parameters:
        `cm` - The ColorModel to change the alpha premult state of.
        `newAlphaPreMult` - The new state of alpha premult.
      Returns:
        A new colorModel that has isAlphaPremultiplied() equal to newAlphaPreMult.

    - #### coerceData

          public static java.awt.image.ColorModel coerceData(java.awt.image.WritableRaster wr,
                                                             java.awt.image.ColorModel cm,
                                                             boolean newAlphaPreMult)

      Coerces data within a bufferedImage to match newAlphaPreMult, Note that this can not change the colormodel of bi so you
      Parameters:
        `wr` - The raster to change the state of.
        `cm` - The colormodel currently associated with data in wr.
        `newAlphaPreMult` - The desired state of alpha Premult for raster.
      Returns:
        A new colormodel that matches newAlphaPreMult.

    - #### multiplyAlpha

          public static void multiplyAlpha(java.awt.image.WritableRaster wr)

    - #### divideAlpha

          public static void divideAlpha(java.awt.image.WritableRaster wr)

    - #### copyData

          public static void copyData(java.awt.image.BufferedImage src,
                                      java.awt.image.BufferedImage dst)

      Copies data from one bufferedImage to another paying attention to the state of AlphaPreMultiplied.
      Parameters:
        `src` - The source
        `dst` - The destination

    - #### copyData

          public static void copyData(java.awt.image.BufferedImage src,
                                      java.awt.Rectangle srcRect,
                                      java.awt.image.BufferedImage dst,
                                      java.awt.Point destP)

      Copies data from one bufferedImage to another paying attention to the state of AlphaPreMultiplied.
      Parameters:
        `src` - The source
        `srcRect` - The Rectangle of source data to be copied
        `dst` - The destination
        `destP` - The Place for the upper left corner of srcRect in dst.

    - #### copyBand

          public static void copyBand(java.awt.image.Raster src,
                                      int srcBand,
                                      java.awt.image.WritableRaster dst,
                                      int dstBand)

    - #### copyBand

          public static void copyBand(java.awt.image.Raster src,
                                      java.awt.Rectangle sR,
                                      int sBand,
                                      java.awt.image.WritableRaster dst,
                                      java.awt.Rectangle dR,
                                      int dBand)

    - #### is_INT_PACK_Data

          public static boolean is_INT_PACK_Data(java.awt.image.SampleModel sm,
                                                 boolean requireAlpha)

    - #### is_BYTE_COMP_Data

          public static boolean is_BYTE_COMP_Data(java.awt.image.SampleModel sm)

    - #### divide_INT_PACK_Data

          protected static void divide_INT_PACK_Data(java.awt.image.WritableRaster wr)

    - #### mult_INT_PACK_Data

          protected static void mult_INT_PACK_Data(java.awt.image.WritableRaster wr)

    - #### divide_BYTE_COMP_Data

          protected static void divide_BYTE_COMP_Data(java.awt.image.WritableRaster wr)

    - #### mult_BYTE_COMP_Data

          protected static void mult_BYTE_COMP_Data(java.awt.image.WritableRaster wr)

    - #### getAlphaRaster

          public static java.awt.image.Raster getAlphaRaster(java.awt.image.RenderedImage image)

      Extracts an alpha raster from a RenderedImage. The method tries to avoid copying data unnecessarily by checking if the RenderedImage is a BufferedImage which offers suitable direct methods.
      Parameters:
        `image` - the image
      Returns:
        the alpha raster

Copyright 1999-2025 The Apache Software Foundation. All Rights Reserved.