JavaFX 24 · javafx.scene.image.PixelBuffer · APIdia, the JavaDoc alternative

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 WritableImages. 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 WritableImages 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);

Field Summary

Modifier and Type	Field and Description
private final T	buffer
private final int	height
private final List<WeakReference<WritableImage>>	imageRefs
private final PixelFormat<T>	pixelFormat
private final int	width

Constructor Summary

Access	Constructor and Description
public	PixelBuffer(int width in pixels of this `PixelBuffer` width, int height in pixels of this `PixelBuffer` height, T the buffer that stores the pixel data buffer, PixelFormat<T> the format of pixels in the `buffer` pixelFormat) Constructs a `PixelBuffer` using the specified `Buffer` and `PixelFormat`.

Method Summary

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

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

buffer	back to summary
private final T buffer

height	back to summary
private final int height

imageRefs	back to summary
private final List<WeakReference<WritableImage>> imageRefs

pixelFormat	back to summary
private final PixelFormat<T> pixelFormat

width	back to summary
private final int width

Constructor Detail

PixelBuffer back to summary

PixelBuffer	back to summary
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:int width in pixels of this `PixelBuffer` height:int height in pixels of this `PixelBuffer` buffer:T the buffer that stores the pixel data pixelFormat:PixelFormat<T> the format of pixels in the `buffer` Exceptions 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`

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:int: width in pixels of this PixelBuffer
height:int: height in pixels of this PixelBuffer
buffer:T: the buffer that stores the pixel data
pixelFormat:PixelFormat<T>: the format of pixels in the buffer

Exceptions

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

addImage	back to summary
pack-priv void addImage(WritableImage image)

bufferDirty	back to summary
private void bufferDirty(Rectangle rect)

getBuffer back to summary

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

public T getBuffer()

Returns the buffer of this PixelBuffer.

Returns:T: the buffer of this PixelBuffer

getHeight back to summary

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

public int getHeight()

Returns the height of this PixelBuffer.

Returns:int: the height of this PixelBuffer

getPixelFormat back to summary

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

public PixelFormat<T> getPixelFormat()

Returns the PixelFormat of this PixelBuffer.

Returns:PixelFormat<T>: the PixelFormat of this PixelBuffer

getWidth back to summary

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

public int getWidth()

Returns the width of this PixelBuffer.

Returns:int: the width of this PixelBuffer

updateBuffer back to summary

updateBuffer	back to summary
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:Callback<PixelBuffer<T>, Rectangle2D> the `Callback` method that updates the buffer Exceptions IllegalStateException: if this method is called on a thread other than the JavaFX Application Thread. NullPointerException: if `callback` is `null`

public void updateBuffer(Callback<PixelBuffer<T>, Rectangle2D> callback)

Invokes the specified Callback method and updates the dirty region of all WritableImages 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);