org.gnome.gdk

## Class Pixbuf

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gdk.Pixbuf

-     public class Pixbuf
      extends Object

  An image in memory.

  Pixbuf is just here to be efficient at handling images that are going to placed in your GTK user interfaces. If you want to draw on an image, use Cairo's ImageSurface. If you want to otherwise manipulate the image, use a dedicated image processing library to load the data as it will doubtless provide for more efficient storage anticipating the processing tasks it will facilitate.

  Since:
    4.0.0
  Author:
    Andrew Cowie, Serkan Kaba

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Pixbuf(byte[] data)` Construct a new Pixbuf object from image data already in memory.
    `Pixbuf(byte[] data, int width, int height, boolean preserveAspectRatio)` Construct a new Pixbuf from in-memory data and scale it.
    `Pixbuf(int width, int height)`
    `Pixbuf(String filename)` Construct a new Pixbuf object from the image found in `filename`.
    `Pixbuf(String filename, int width, int height, boolean preserveAspectRatio)` Construct a new Pixbuf object by loading an image from a given filename, but scaling it.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Pixbuf` | `copy()` Create an identical copy of this Pixbuf.
    `static int` | `getFileInfoHeight(String filename)` Query an image on disk for its height.
    `static int` | `getFileInfoWidth(String filename)` Query an image on disk for its width.
    `int` | `getHeight()` Get the height of this Pixbuf, in pixels
    `int` | `getNumChannels()` Get the number of colour channels in this Pixbuf.
    `byte[]` | `getPixels()` Get a the individual pixel values comprising this Pixbuf.
    `int` | `getWidth()` Get the width of this Pixbuf, in pixels
    `void` | `save(String filename, PixbufFormat type)` Write this Pixbuf to a file.
    `Pixbuf` | `scale(int width, int height, InterpType algorithm)` Create a new Pixbuf, applying the scaling factors inherent in the ratios between the size of this Pixbuf and the new image size specified by `width` and `height`.

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Pixbuf

          public Pixbuf(byte[] data)
                 throws IOException

      Construct a new Pixbuf object from image data already in memory. The data needs to be a complete image in a format that will be recognized by one of the gdk-pixbuf library's loaders (PNG, JPEG, etc).
      Throws:
        `IOException`
      Since:
        4.0.10

    - #### Pixbuf

          public Pixbuf(byte[] data,
                int width,
                int height,
                boolean preserveAspectRatio)
                 throws IOException

      Construct a new Pixbuf from in-memory data and scale it.

      See `Pixbuf(byte[])` for info on in-memory data.
      See `Pixbuf(String, int, int, boolean)` for info on scaling.

      Throws:
        `IOException`
      Since:
        4.0.12

    - #### Pixbuf

          public Pixbuf(int width,
                int height)

    - #### Pixbuf

          public Pixbuf(String filename)
                 throws FileNotFoundException

      Construct a new Pixbuf object from the image found in `filename`.
      Throws:
        `FileNotFoundException`
      Since:
        4.0.5

    - #### Pixbuf

          public Pixbuf(String filename,
                int width,
                int height,
                boolean preserveAspectRatio)
                 throws FileNotFoundException

      Construct a new Pixbuf object by loading an image from a given filename, but scaling it. The image will be scaled to fit the supplied width and height, preserving the aspect ratio or not based on the value of the fourth parameter.

      If preserving the aspect ratio,

      - width of `-1` will cause the image to be scaled to the exact given height
      - height of `-1` will cause the image to be scaled to the exact given width.
      When not preserving aspect ratio,
      - a width or height of `-1` means to not scale the image at all in that dimension.
      Throws:
        `FileNotFoundException`
      Since:
        4.0.5

  - ### Method Detail

    - #### copy

          public Pixbuf copy()

      Create an identical copy of this Pixbuf.

      Since you can happily reuse a Pixbuf instance in multiple places, you generally won't need this unless doing mutating operations like rescaling.

      Since:
        4.0.10

    - #### getFileInfoHeight

          public static int getFileInfoHeight(String filename)
                                       throws IOException

      Query an image on disk for its height.

      This function is the compliment of `getFileInfoWidth()`; see there.

      Throws:
        `IOException`
      Since:
        4.0.14

    - #### getFileInfoWidth

          public static int getFileInfoWidth(String filename)
                                      throws IOException

      Query an image on disk for its width.

      This is a utility function where the minimum amount is read in order to determine metadata about the file in question. You'll get an IOException if the gdk-pixbuf library's image loaders can't figure out the format of the file.

      Throws:
        `IOException`
      Since:
        4.0.14

    - #### getHeight

          public int getHeight()

      Get the height of this Pixbuf, in pixels
      Since:
        4.0.8

    - #### getNumChannels

          public int getNumChannels()

      Get the number of colour channels in this Pixbuf. This will be either `3` for RGB or `4` for an RGBA image.

      You don't actually need this; if you're working with the pixel data from `getPixels()` just divide the length of the returned array by (width `*` height).

      Since:
        4.0.8

    - #### getPixels

          public byte[] getPixels()

      Get a the individual pixel values comprising this Pixbuf.

      Image data in a Pixbuf is stored in memory in an uncompressed but packed format. Rows in the image are stored top to bottom, and in each row pixels are stored from left to right. The returned array is, as you would expect, the bytes comprising each single pixel in a sequential series. There will be either three (RGB) or four (RGBA) bytes per pixel, see `getNumChannels()`.

      The return array is of type of is `byte` but you can expect unsigned values in the range `0` to `255`. If you need the actual values you'll have to `&` with `0xFF` to get yourself to the correct unsigned integer.

      You should not need to call this. See the caveats at the top of this class; changing the values of this array will not change the underlying image.

      The underlying library stores Pixbufs in a format which is efficient for internal representation and memory operations, though not necessarily efficient for size and frequently extra bits are added as alignment padding. We do some minor copying so that the array returned is one byte per channel and Cartesian.

      In the current GDK Pixbuf library implementation, the red, green, blue and optional alpha are fixed at 8 bits per channel.

      Since:
        4.0.8

    - #### getWidth

          public int getWidth()

      Get the width of this Pixbuf, in pixels
      Since:
        4.0.8

    - #### save

          public void save(String filename,
                  PixbufFormat type)

      Write this Pixbuf to a file.

      The various file formats that GDK is actually capable of writing to are specified by the constants on PixbufFormat. For example, you can save a screenshot as a PNG using:

           Pixbuf p;
           ...

           p.save("Screenshot.png", PixbufFormat.PNG);

      Since:
        4.0.5

    - #### scale

          public Pixbuf scale(int width,
                     int height,
                     InterpType algorithm)

      Create a new Pixbuf, applying the scaling factors inherent in the ratios between the size of this Pixbuf and the new image size specified by `width` and `height`.

      In general you probably want to use the `BILINEAR` interpolation algorithm.

      Since:
        4.0.10