BandCombineOp (Java SE 26 & JDK 26)
Description: declaration: module: java.desktop, package: java.awt.image, class: BandCombineOp
Keywords: java.awt.image.BandCombineOp class

# Class BandCombineOp

java.lang.Object
java.awt.image.BandCombineOp

All Implemented Interfaces:
  `RasterOp`

public class BandCombineOp extends Object implements RasterOp
This class performs an arbitrary linear combination of the bands in a `Raster`, using a specified matrix.

The width of the matrix must be equal to the number of bands in the source `Raster`, optionally plus one. If there is one more column in the matrix than the number of bands, there is an implied 1 at the end of the vector of band samples representing a pixel. The height of the matrix must be equal to the number of bands in the destination.

For example, a 3-banded `Raster` might have the following transformation applied to each pixel in order to invert the second band of the `Raster`.

      [ 1.0   0.0   0.0    0.0  ]     [ b1 ]
      [ 0.0  -1.0   0.0  255.0  ]  x  [ b2 ]
      [ 0.0   0.0   1.0    0.0  ]     [ b3 ]
                                      [ 1 ]

Note that the source and destination can be the same object.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BandCombineOp(float[][] matrix, RenderingHints hints)`
  Constructs a `BandCombineOp` with the specified matrix.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `WritableRaster`
  `createCompatibleDestRaster(Raster src)`
  Creates a zeroed destination `Raster` with the correct size and number of bands.
  `WritableRaster`
  `filter(Raster src, WritableRaster dst)`
  Transforms the `Raster` using the matrix specified in the constructor.
  `final Rectangle2D`
  `getBounds2D(Raster src)`
  Returns the bounding box of the transformed destination.
  `final float[][]`
  `getMatrix()`
  Returns a copy of the linear combination matrix.
  `final Point2D`
  `getPoint2D(Point2D srcPt, Point2D dstPt)`
  Returns the location of the corresponding destination point given a point in the source `Raster`.
  `final RenderingHints`
  `getRenderingHints()`
  Returns the rendering hints for this operation.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### BandCombineOp

    public BandCombineOp(float[][] matrix, RenderingHints hints)
    Constructs a `BandCombineOp` with the specified matrix. The width of the matrix must be equal to the number of bands in the source `Raster`, optionally plus one. If there is one more column in the matrix than the number of bands, there is an implied 1 at the end of the vector of band samples representing a pixel. The height of the matrix must be equal to the number of bands in the destination.

    The first subscript is the row index and the second is the column index. This operation uses none of the currently defined rendering hints; the `RenderingHints` argument can be null.

    Parameters:
      `matrix` - The matrix to use for the band combine operation.
      `hints` - The `RenderingHints` object for this operation. Not currently used so it can be null.

- ## Method Details

  - ### getMatrix

    public final float[][] getMatrix()
    Returns a copy of the linear combination matrix.
    Returns:
      The matrix associated with this band combine operation.

  - ### filter

    public WritableRaster filter(Raster src, WritableRaster dst)
    Transforms the `Raster` using the matrix specified in the constructor. An `IllegalArgumentException` may be thrown if the number of bands in the source or destination is incompatible with the matrix. See the class comments for more details.

    If the destination is null, it will be created with a number of bands equalling the number of rows in the matrix. No exception is thrown if the operation causes a data overflow.

    Specified by:
      `filter` in interface `RasterOp`
    Parameters:
      `src` - The `Raster` to be filtered.
      `dst` - The `Raster` in which to store the results of the filter operation.
    Returns:
      The filtered `Raster`.
    Throws:
      `IllegalArgumentException` - If the number of bands in the source or destination is incompatible with the matrix.

  - ### getBounds2D

    public final Rectangle2D getBounds2D(Raster src)
    Returns the bounding box of the transformed destination. Since this is not a geometric operation, the bounding box is the same for the source and destination. An `IllegalArgumentException` may be thrown if the number of bands in the source is incompatible with the matrix. See the class comments for more details.
    Specified by:
      `getBounds2D` in interface `RasterOp`
    Parameters:
      `src` - The `Raster` to be filtered.
    Returns:
      The `Rectangle2D` representing the destination image's bounding box.
    Throws:
      `IllegalArgumentException` - If the number of bands in the source is incompatible with the matrix.

  - ### createCompatibleDestRaster

    public WritableRaster createCompatibleDestRaster(Raster src)
    Creates a zeroed destination `Raster` with the correct size and number of bands. An `IllegalArgumentException` may be thrown if the number of bands in the source is incompatible with the matrix. See the class comments for more details.
    Specified by:
      `createCompatibleDestRaster` in interface `RasterOp`
    Parameters:
      `src` - The `Raster` to be filtered.
    Returns:
      The zeroed destination `Raster`.

  - ### getPoint2D

    public final Point2D getPoint2D(Point2D srcPt, Point2D dstPt)
    Returns the location of the corresponding destination point given a point in the source `Raster`. If `dstPt` is specified, it is used to hold the return value. Since this is not a geometric operation, the point returned is the same as the specified `srcPt`.
    Specified by:
      `getPoint2D` in interface `RasterOp`
    Parameters:
      `srcPt` - The `Point2D` that represents the point in the source `Raster`
      `dstPt` - The `Point2D` in which to store the result.
    Returns:
      The `Point2D` in the destination image that corresponds to the specified point in the source image.

  - ### getRenderingHints

    public final RenderingHints getRenderingHints()
    Returns the rendering hints for this operation.
    Specified by:
      `getRenderingHints` in interface `RasterOp`
    Returns:
      The `RenderingHints` object associated with this operation. Returns null if no hints have been set.