Module javafx.graphics
Package javafx.scene.image

# Class PixelBuffer<T extends Buffer>

java.lang.Object
javafx.scene.image.PixelBuffer<T>

Type Parameters:
  `T` - the type of `Buffer` that stores the pixel data. Only `ByteBuffer` and `IntBuffer` are supported.

public class PixelBuffer<T extends Buffer> extends Object
The `PixelBuffer` class represents pixel data that is constructed from a `java.nio.Buffer` supplied by the application. A `WritableImage` can use this `PixelBuffer` directly without copying the pixel data. This `PixelBuffer` can be shared among multiple `WritableImage`s. Pixel data should be stored either in an `IntBuffer` using a `PixelFormat` of type `INT_ARGB_PRE` or in a `ByteBuffer` using a `PixelFormat` of type `BYTE_BGRA_PRE`. When the `Buffer` is updated using the `PixelBuffer.updateBuffer` method, all `WritableImage`s that were created using this `PixelBuffer` are redrawn.

Example code that shows how to create a `PixelBuffer`:

     // Creating a PixelBuffer using BYTE_BGRA_PRE pixel format.
     ByteBuffer byteBuffer = ByteBuffer.allocateDirect(width * height * 4);
     PixelFormat<ByteBuffer> pixelFormat = PixelFormat.getByteBgraPreInstance();
     PixelBuffer<ByteBuffer> pixelBuffer = new PixelBuffer<>(width, height, byteBuffer, pixelFormat);
     Image img = new WritableImage(pixelBuffer);

     // Creating a PixelBuffer using INT_ARGB_PRE pixel format.
     IntBuffer intBuffer = IntBuffer.allocate(width * height);
     PixelFormat<IntBuffer> pixelFormat = PixelFormat.getIntArgbPreInstance();
     PixelBuffer<IntBuffer> pixelBuffer = new PixelBuffer<>(width, height, intBuffer, pixelFormat);
     Image img = new WritableImage(pixelBuffer);

Since:
  13
See Also:
  - `WritableImage(PixelBuffer)`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PixelBuffer(int width, int height, T buffer, PixelFormat<T> pixelFormat)`
  Constructs a `PixelBuffer` using the specified `Buffer` and `PixelFormat`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `T`
  `getBuffer()`
  Returns the `buffer` of this `PixelBuffer`.
  `int`
  `getHeight()`
  Returns the `height` of this `PixelBuffer`.
  `PixelFormat<T>`
  `getPixelFormat()`
  Returns the `PixelFormat` of this `PixelBuffer`.
  `int`
  `getWidth()`
  Returns the `width` of this `PixelBuffer`.
  `void`
  `updateBuffer(Callback<PixelBuffer<T>,Rectangle2D> callback)`
  Invokes the specified `Callback` method and updates the dirty region of all `WritableImage`s that were created using this `PixelBuffer`.

  ### Methods declared in class java.lang.Object

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

- ## Constructor Details

  - ### PixelBuffer

    public PixelBuffer(int width, int height, T buffer, PixelFormat<T> pixelFormat)
    Constructs a `PixelBuffer` using the specified `Buffer` and `PixelFormat`. The type of the specified `PixelFormat` must be either `PixelFormat.Type.INT_ARGB_PRE` or `PixelFormat.Type.BYTE_BGRA_PRE`.

    The constructor does not allocate memory to store the pixel data. The application must provide a buffer with sufficient memory for the combination of dimensions `(width, height)` and the type of `PixelFormat`. The `PixelFormat.Type.INT_ARGB_PRE` requires an `IntBuffer` with minimum capacity of `width * height`, and the `PixelFormat.Type.BYTE_BGRA_PRE` requires a `ByteBuffer` with minimum capacity of `width * height * 4`.

    Parameters:
      `width` - width in pixels of this `PixelBuffer`
      `height` - height in pixels of this `PixelBuffer`
      `buffer` - the buffer that stores the pixel data
      `pixelFormat` - the format of pixels in the `buffer`
    Throws:
      `IllegalArgumentException` - if either `width` or `height` is negative or zero, or if the type of `pixelFormat` is unsupported, or if `buffer` does not have sufficient memory, or if the type of `buffer` and `pixelFormat` do not match
      `NullPointerException` - if `buffer` or `pixelFormat` is `null`

- ## Method Details

  - ### getBuffer

    public T getBuffer()
    Returns the `buffer` of this `PixelBuffer`.
    Returns:
      the `buffer` of this `PixelBuffer`

  - ### getWidth

    public int getWidth()
    Returns the `width` of this `PixelBuffer`.
    Returns:
      the `width` of this `PixelBuffer`

  - ### getHeight

    public int getHeight()
    Returns the `height` of this `PixelBuffer`.
    Returns:
      the `height` of this `PixelBuffer`

  - ### getPixelFormat

    public PixelFormat<T> getPixelFormat()
    Returns the `PixelFormat` of this `PixelBuffer`.
    Returns:
      the `PixelFormat` of this `PixelBuffer`

  - ### updateBuffer

    public void updateBuffer(Callback<PixelBuffer<T>,Rectangle2D> callback)
    Invokes the specified `Callback` method and updates the dirty region of all `WritableImage`s that were created using this `PixelBuffer`. The `Callback` method is expected to update the buffer and return a `Rectangle2D` that encloses the dirty region, or return `null` to indicate that the entire buffer is dirty.

    This method must be called on the JavaFX Application Thread.

    Example code that shows how to use this method:

         Callback<PixelBuffer<ByteBuffer>, Rectangle2D> callback = pixelBuffer -> {
             ByteBuffer buffer = pixelBuffer.getBuffer();
             // Update the buffer.
             return new Rectangle2D(x, y, dirtyWidth, dirtyHeight);
         };
         pixelBuffer.updateBuffer(callback);

    Parameters:
      `callback` - the `Callback` method that updates the buffer
    Throws:
      `IllegalStateException` - if this method is called on a thread other than the JavaFX Application Thread.
      `NullPointerException` - if `callback` is `null`