PixelBuffer (JavaFX 17)

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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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`