WritableImage (JavaFX 17)

Module javafx.graphics
Package javafx.scene.image

## Class WritableImage

- java.lang.Object
- - javafx.scene.image.Image
  - - javafx.scene.image.WritableImage

-     public class WritableImage
      extends Image

  The `WritableImage` class represents a custom graphical image that is constructed from pixels supplied by the application, and possibly from `PixelReader` objects from any number of sources, including images read from a file or URL.
  Since:
    JavaFX 2.2

- - ### Property Summary

    - ### Properties declared in class javafx.scene.image.Image

      `error, exception, height, progress, width`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `WritableImage​(int width, int height)` | Constructs an empty image of the specified dimensions.
    `WritableImage​(PixelBuffer<? extends Buffer> pixelBuffer)` | Constructs a `WritableImage` using the specified `PixelBuffer`.
    `WritableImage​(PixelReader reader, int width, int height)` | Constructs an image of the specified dimensions, initialized from the indicated `PixelReader`.
    `WritableImage​(PixelReader reader, int x, int y, int width, int height)` | Constructs an image of the specified dimensions, initialized from the indicated region of the `PixelReader`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PixelWriter` | `getPixelWriter()` | This method returns a `PixelWriter` that provides access to write the pixels of the image.

    - ### Methods declared in class javafx.scene.image.Image

      `cancel, errorProperty, exceptionProperty, getException, getHeight, getPixelReader, getProgress, getRequestedHeight, getRequestedWidth, getUrl, getWidth, heightProperty, isBackgroundLoading, isError, isPreserveRatio, isSmooth, progressProperty, widthProperty`

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

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

- - ### Constructor Detail

    - #### WritableImage

          public WritableImage​(int width,
                               int height)

      Constructs an empty image of the specified dimensions. The image will initially be filled with transparent pixels. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers `(> 0)`.
      Parameters:
        `width` - the desired width of the writable image
        `height` - the desired height of the desired image
      Throws:
        `IllegalArgumentException` - if either dimension is negative or zero.

    - #### WritableImage

          public WritableImage​(PixelBuffer<? extends Buffer> pixelBuffer)

      Constructs a `WritableImage` using the specified `PixelBuffer`. The `Buffer` provided by the `PixelBuffer` will be used directly as the pixel data for this image. The `PixelBuffer` can be shared by multiple `WritableImage`s. Images constructed this way are readable using `Image.getPixelReader()`, but are not writable using `WritableImage.getPixelWriter()`.
      Parameters:
        `pixelBuffer` - the `PixelBuffer` used to construct this image
      Throws:
        `NullPointerException` - if `pixelBuffer` is `null`
      Since:
        13

    - #### WritableImage

          public WritableImage​(PixelReader reader,
                               int width,
                               int height)

      Constructs an image of the specified dimensions, initialized from the indicated `PixelReader`. The image will initially be filled with data returned from the `PixelReader`. If the `PixelReader` accesses a surface that does not contain the necessary number of pixel rows and columns then an `ArrayIndexOutOfBoundsException` will be thrown. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers `(> 0)`.
      Parameters:
        `reader` - the `PixelReader` to construct from
        `width` - the desired width of the writable image and the width of the region to be read from the `reader`
        `height` - the desired height of the desired image and the width of the region to be read from the `reader`
      Throws:
        `ArrayIndexOutOfBoundsException` - if the `reader` does not access a surface of at least the requested dimensions
        `IllegalArgumentException` - if either dimension is negative or zero.

    - #### WritableImage

          public WritableImage​(PixelReader reader,
                               int x,
                               int y,
                               int width,
                               int height)

      Constructs an image of the specified dimensions, initialized from the indicated region of the `PixelReader`. The image will initially be filled with data returned from the `PixelReader` for the specified region. If the `PixelReader` accesses a surface that does not contain the necessary number of pixel rows and columns then an `ArrayIndexOutOfBoundsException` will be thrown. Images constructed this way will always be readable and writable so the corresponding getPixelReader() and getPixelWriter() will always return valid objects. The dimensions must both be positive numbers `(> 0)`.
      Parameters:
        `reader` - the `PixelReader` to construct from
        `x` - the X coordinate of the upper left corner of the region to read from the `reader`
        `y` - the Y coordinate of the upper left corner of the region to read from the `reader`
        `width` - the desired width of the writable image and the width of the region to be read from the `reader`
        `height` - the desired height of the desired image and the width of the region to be read from the `reader`
      Throws:
        `ArrayIndexOutOfBoundsException` - if the `reader` does not access a surface containing at least the indicated region
        `IllegalArgumentException` - if either dimension is negative or zero.

  - ### Method Detail

    - #### getPixelWriter

          public final PixelWriter getPixelWriter()

      This method returns a `PixelWriter` that provides access to write the pixels of the image. This method is not supported for images constructed using a `PixelBuffer`.
      Returns:
        the `PixelWriter` for writing pixels to the image
      Throws:
        `UnsupportedOperationException` - if this image was created using a `PixelBuffer`