## PgmImage

PgmImage — An image drawable supporting various media.

## Synopsis

    #include <pgm/pgm.h>

    enum                PgmImageAlignment;
    enum                PgmImageLayoutType;
    enum                PgmImageInterpType;
    enum                PgmImageWrapping;
    enum                PgmImagePixelFormat;
                        PgmImageFile;
                        PgmImageBuffer;
                        PgmImageGstBuffer;
                        PgmImageSystemBuffer;
                        PgmImagePixbuf;
    enum                PgmImageStorageType;
    union               PgmImageData;
                        PgmImage;
    PgmDrawable *       pgm_image_new                       (void);
    PgmDrawable *       pgm_image_new_from_file             (const gchar *filename,
                                                             guint max_size);
    PgmDrawable *       pgm_image_new_from_pixbuf           (GdkPixbuf *pixbuf);
    PgmDrawable *       pgm_image_new_from_buffer           (PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             guint size,
                                                             gconstpointer data);
    PgmDrawable *       pgm_image_new_from_image            (PgmImage *src_image);
    PgmError            pgm_image_set_from_file             (PgmImage *image,
                                                             const gchar *filename,
                                                             guint max_size);
    PgmError            pgm_image_set_from_pixbuf           (PgmImage *image,
                                                             GdkPixbuf *pixbuf);
    PgmError            pgm_image_set_from_buffer           (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             guint size,
                                                             gconstpointer data);
    PgmError            pgm_image_set_from_gst_buffer       (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             GstBuffer *buffer);
    PgmError            pgm_image_set_from_system_buffer    (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             gconstpointer system_buffer);
    PgmError            pgm_image_set_from_image            (PgmImage *image,
                                                             PgmImage *src_image);
    PgmError            pgm_image_to_pixbuf                 (PgmImage *image,
                                                             GdkPixbuf **pixbuf);
    PgmError            pgm_image_clear                     (PgmImage *image);
    PgmError            pgm_image_get_storage_type          (PgmImage *image,
                                                             PgmImageStorageType *storage);
    PgmError            pgm_image_system_buffer_lock        (PgmImage *image);
    PgmError            pgm_image_system_buffer_unlock      (PgmImage *image);
    PgmError            pgm_image_set_mapping_matrix        (PgmImage *image,
                                                             PgmMat4x4 *mapping_matrix);
    PgmError            pgm_image_get_mapping_matrix        (PgmImage *image,
                                                             PgmMat4x4 **mapping_matrix);
    PgmError            pgm_image_set_alignment             (PgmImage *image,
                                                             PgmImageAlignment align);
    PgmError            pgm_image_get_alignment             (PgmImage *image,
                                                             PgmImageAlignment *align);
    PgmError            pgm_image_set_layout                (PgmImage *image,
                                                             PgmImageLayoutType layout);
    PgmError            pgm_image_get_layout                (PgmImage *image,
                                                             PgmImageLayoutType *layout);
    PgmError            pgm_image_set_interp                (PgmImage *image,
                                                             PgmImageInterpType interp);
    PgmError            pgm_image_get_interp                (PgmImage *image,
                                                             PgmImageInterpType *interp);
    PgmError            pgm_image_set_wrapping              (PgmImage *image,
                                                             PgmImageWrapping wrap_s,
                                                             PgmImageWrapping wrap_t);
    PgmError            pgm_image_get_wrapping              (PgmImage *image,
                                                             PgmImageWrapping *wrap_s,
                                                             PgmImageWrapping *wrap_t);
    PgmError            pgm_image_set_aspect_ratio          (PgmImage *image,
                                                             guint numerator,
                                                             guint denominator);
    PgmError            pgm_image_get_aspect_ratio          (PgmImage *image,
                                                             guint *numerator,
                                                             guint *denominator);
    PgmError            pgm_image_set_border_width          (PgmImage *image,
                                                             gfloat width);
    PgmError            pgm_image_get_border_width          (PgmImage *image,
                                                             gfloat *width);
    PgmError            pgm_image_set_border_inner_color    (PgmImage *image,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);
    PgmError            pgm_image_get_border_inner_color    (PgmImage *image,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);
    PgmError            pgm_image_set_border_outer_color    (PgmImage *image,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);
    PgmError            pgm_image_get_border_outer_color    (PgmImage *image,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);
    PgmError            pgm_image_from_drawable             (PgmImage *image,
                                                             gint *x_image,
                                                             gint *y_image,
                                                             gfloat x_drawable,
                                                             gfloat y_drawable);
    PgmError            pgm_image_to_drawable               (PgmImage *image,
                                                             gfloat *x_drawable,
                                                             gfloat *y_drawable,
                                                             gint x_image,
                                                             gint y_image);

## Object Hierarchy

      GObject
       +----GstObject
             +----PgmDrawable
                   +----PgmImage

## Signals

      "cloned"                                         : Run First
      "file-loaded"                                    : Run First
      "un-cloned"                                      : Run First

## Description

### Loading image data

PgmImage is a drawable displaying media. It supports various ways of loading images through buffers, file paths or videos through GStreamer.

Image data loading can happen with three different functions:

- `pgm_image_set_from_buffer()` takes a pre-loaded data buffer and sets it as the currently displayed image. This is useful when you want to use an image loading library (GdkPixbuf, FreeImage, etc) in your application and just provide the pixels to PgmImage for display. The data buffer containing the pixels is copied internally, you can free the data buffer from the application side as soon as the function returns.

- `pgm_image_set_from_gst_buffer()` takes a GStreamer GstBuffer and sets it as the currently displayed image. This is mostly used to do video rendering. There's no copying of the buffer data to optimize performances, indeed the reference count of the buffer is going to be increased to keep the buffer around while it's needed for rendering. When you call `pgm_image_clear()` the reference to the buffer will be decreased and the buffer can get freed. Note that this method is used by PgmSink to render video frames directly in a PgmImage when the pipeline is playing.

- `pgm_image_set_from_file()` takes a path to an image file delegating image loading to Pigment. Thus the loading is asynchronous and won't block the Pigment main loop.

`pgm_image_set_from_image()` is a convenient system to slave an image to another one. Indeed you might want to load an image data once and then use it in multiple image objects. In that case this image becomes a slave to the one that has the image data loaded internally and each time it needs to draw it will use that data.

Layout settings of the drawable are independent from one image to another. That means that even if two image objects are using the same image, they can have different colors, different PgmDrawableLayoutType or different PgmDrawableAlignment.

Each time a new image data buffer is loaded in the master image object, all the slave image objects are automatically updated. That means you can render a video clip in ten different drawables without doing anything else than slaving nine image objects to the one that's receiving the image data.

This rarely happens with normal images but video rendering often has non square pixels video frames coming out of the video decoders (DVD, DV cameras, etc). In that case a calculation has to be done when projecting to the viewport so that we put in adequation both the pixel aspect ratio and the source video aspect ratio. You can set the image aspect ratio using `pgm_image_set_aspect_ratio()` and be assured that Pigment is going to render that image correctly on the viewport.

Depending on the viewport implementation, some PgmImagePixelFormat (color space) can be supported or not. When it comes to video rendering, hardware acceleration is very important and you need to know what kind of pixel formats are convenient for the rendering backend. you can get a list of supported (accelerated) pixel formats using `pgm_viewport_get_pixel_formats()`.

Last reviewed on 2007-11-08 (0.3.2)

## Details

### enum PgmImageAlignment

    typedef enum {
      PGM_IMAGE_LEFT          = (1 << 0),
      PGM_IMAGE_CENTER        = (1 << 1),
      PGM_IMAGE_RIGHT         = (1 << 2),
      PGM_IMAGE_TOP           = (1 << 3),
      PGM_IMAGE_BOTTOM        = (1 << 4),
      PGM_IMAGE_TOP_LEFT      = (PGM_IMAGE_TOP | PGM_IMAGE_LEFT),
      PGM_IMAGE_TOP_CENTER    = (PGM_IMAGE_TOP | PGM_IMAGE_CENTER),
      PGM_IMAGE_TOP_RIGHT     = (PGM_IMAGE_TOP | PGM_IMAGE_RIGHT),
      PGM_IMAGE_BOTTOM_LEFT   = (PGM_IMAGE_BOTTOM | PGM_IMAGE_LEFT),
      PGM_IMAGE_BOTTOM_CENTER = (PGM_IMAGE_BOTTOM | PGM_IMAGE_CENTER),
      PGM_IMAGE_BOTTOM_RIGHT  = (PGM_IMAGE_BOTTOM | PGM_IMAGE_RIGHT)
    } PgmImageAlignment;

The possible alignments you can combine.

`PGM_IMAGE_LEFT` | Align to the left.
`PGM_IMAGE_CENTER` | Align to the center (both vertically and horizontally).
`PGM_IMAGE_RIGHT` | Align to the right.
`PGM_IMAGE_TOP` | Align to the top.
`PGM_IMAGE_BOTTOM` | Align to the bottom.
`PGM_IMAGE_TOP_LEFT` | Align to the top left.
`PGM_IMAGE_TOP_CENTER` | Align to the top center.
`PGM_IMAGE_TOP_RIGHT` | Align to the top right.
`PGM_IMAGE_BOTTOM_LEFT` | Align to the bottom left.
`PGM_IMAGE_BOTTOM_CENTER` | Align to the bottom center.
`PGM_IMAGE_BOTTOM_RIGHT` | Align to the bottom right.

### enum PgmImageLayoutType

    typedef enum {
      PGM_IMAGE_FILLED   = 0,
      PGM_IMAGE_SCALED   = 1,
      PGM_IMAGE_ZOOMED   = 2,
      PGM_IMAGE_CENTERED = 3,
      PGM_IMAGE_TILED    = 4
    } PgmImageLayoutType;

The different layout types.

`PGM_IMAGE_FILLED` | Scales the stored image to the whole drawable size ignoring the pixel-aspect-ratio.
`PGM_IMAGE_SCALED` | Scales the stored image to adapt its size to the drawable one keeping the pixel-aspect-ratio.
`PGM_IMAGE_ZOOMED` | Scales the stored image to the whole drawable size keeping the pixel-aspect-ratio. It crops the border of the stored image.
`PGM_IMAGE_CENTERED` | Centers the stored image in the middle of the drawable keeping the pixel-aspect-ratio. It crops the image if its size is bigger than the drawable size.
`PGM_IMAGE_TILED` | Repeats the stored image along the drawable.

### enum PgmImageInterpType

    typedef enum {
      PGM_IMAGE_NEAREST,
      PGM_IMAGE_BILINEAR
    } PgmImageInterpType;

The different image interpolation types.

`PGM_IMAGE_NEAREST` | The nearest neighbour sampling is the fastest and lowest quality mode.
`PGM_IMAGE_BILINEAR` | The bilinear sampling is the slowest and highest quality mode.

### enum PgmImageWrapping

    typedef enum {
      PGM_IMAGE_CLAMP,
      PGM_IMAGE_TRANSPARENT,
      PGM_IMAGE_REPEAT
    } PgmImageWrapping;

The different image wrapping types.

`PGM_IMAGE_CLAMP` | The image content is displayed in the mapping range [0.0, 1.0] and clamped to the last pixel outside it.
`PGM_IMAGE_TRANSPARENT` | The image content is displayed in the mapping range [0.0, 1.0] and discarded outside it. Can be used in combination with the PGM_IMAGE_BILINEAR filtering to antialias the edges of images.
`PGM_IMAGE_REPEAT` | The image content is displayed in the mapping range [0.0, 1.0] and repeated infinitely outside it.

### enum PgmImagePixelFormat

    typedef enum {
      PGM_IMAGE_RGB  = (1 << 0),
      PGM_IMAGE_BGR  = (1 << 1),
      PGM_IMAGE_RGBA = (1 << 2),
      PGM_IMAGE_BGRA = (1 << 3),
      PGM_IMAGE_I420 = (1 << 4),
      PGM_IMAGE_YV12 = (1 << 5),
      PGM_IMAGE_UYVY = (1 << 6),
      PGM_IMAGE_YUYV = (1 << 7)
    } PgmImagePixelFormat;

The different image pixel formats.

`PGM_IMAGE_RGB` | 24 bits RGB (3 bytes, red 8 @ 16, green 8 @ 8, blue 8 @ 0).
`PGM_IMAGE_BGR` | 24 bits BGR (3 bytes, blue 8 @ 16, green 8 @ 8, red 8 @ 0).
`PGM_IMAGE_RGBA` | 32 bits RGBA (4 bytes, red 8 @ 24, green 8 @ 16, blue 8 @ 8, alpha 8 @ 0).
`PGM_IMAGE_BGRA` | 32 bits BGRA (4 bytes, blue 8 @ 24, green 8 @ 16, red 8 @ 8, alpha 8 @ 0).
`PGM_IMAGE_I420` | 12 bits YUV (8 bits Y plane followed by 8 bits quarter size U/V planes).
`PGM_IMAGE_YV12` | 12 bits YUV (8 bits Y plane followed by 8 bits quarter size V/U planes).
`PGM_IMAGE_UYVY` | 16 bits YUV (4 bytes / 2 pixels, macropixel contains YCbYCr [31:0]).
`PGM_IMAGE_YUYV` | 16 bits YUV (4 bytes / 2 pixels, macropixel contains CbYCrY [31:0], duplicate of YUY2).

### PgmImageFile

    typedef struct {
      GdkPixbuf *pixbuf;
      gchar     *filename;
      guint      width;
      guint      height;
    } PgmImageFile;

The PgmImageFile structure.

GdkPixbuf *`pixbuf`; | the GdkPixbuf object.
gchar *`filename`; | the file name.
guint `width`; | the cached pixbuf width.
guint `height`; | the cached pixbuf height.

### PgmImageBuffer

    typedef struct {
      guint8              *buffer;
      PgmImagePixelFormat  format;
      guint                width;
      guint                height;
      guint                stride;
      guint                size;
    } PgmImageBuffer;

The PgmImageBuffer structure.

guint8 *`buffer`; | the buffer pointer.
PgmImagePixelFormat `format`; | the buffer format.
guint `width`; | the buffer width.
guint `height`; | the buffer height.
guint `stride`; | the buffer stride.
guint `size`; | the buffer size.

### PgmImageGstBuffer

    typedef struct {
      GstBuffer           *gst_buffer;
      PgmImagePixelFormat  format;
      guint                width;
      guint                height;
      guint                stride;
    } PgmImageGstBuffer;

The PgmImageGstBuffer structure.

GstBuffer *`gst_buffer`; | the GstBuffer object.
PgmImagePixelFormat `format`; | the GstBuffer format.
guint `width`; | the GstBuffer width.
guint `height`; | the GstBuffer height.
guint `stride`; | the GstBuffer stride.

### PgmImageSystemBuffer

    typedef struct {
      gconstpointer       system_buffer;
      PgmImagePixelFormat format;
      guint               width;
      guint               height;
    } PgmImageSystemBuffer;

The PgmImageSystemBuffer structure.

gconstpointer `system_buffer`; | the system buffer pointer.
PgmImagePixelFormat `format`; | the system buffer format.
guint `width`; | the system buffer width.
guint `height`; | the system buffer height.

### PgmImagePixbuf

    typedef struct {
      GdkPixbuf *pixbuf;
    } PgmImagePixbuf;

The PgmImagePixbuf structure.

GdkPixbuf *`pixbuf`; | the GdkPixbuf object.

### enum PgmImageStorageType

    typedef enum {
      PGM_IMAGE_EMPTY,
      PGM_IMAGE_FILE,
      PGM_IMAGE_BUFFER,
      PGM_IMAGE_GST_BUFFER,
      PGM_IMAGE_PIXBUF,
      PGM_IMAGE_IMAGE,
      PGM_IMAGE_SYSTEM_BUFFER
    } PgmImageStorageType;

The different storage type.

`PGM_IMAGE_EMPTY` | no image stored.
`PGM_IMAGE_FILE` | a PgmImageFile is stored.
`PGM_IMAGE_BUFFER` | a PgmImageBuffer is stored.
`PGM_IMAGE_GST_BUFFER` | a PgmImageGstBuffer is stored.
`PGM_IMAGE_PIXBUF` | a PgmImagePixbuf is stored.
`PGM_IMAGE_IMAGE` | a PgmImage is stored.
`PGM_IMAGE_SYSTEM_BUFFER` | a PgmImageSystemBuffer is stored.

### union PgmImageData

    union PgmImageData {
      PgmImageFile         file;
      PgmImageBuffer       buffer;
      PgmImageGstBuffer    gst_buffer;
      PgmImagePixbuf       pixbuf;
      PgmImageSystemBuffer system_buffer;
    };

The stored data depending on the storage type.

### PgmImage

    typedef struct {
      /* Slavery handling */
      PgmImage *master;
      GList    *slaves;

      PgmMat4x4 *mapping_matrix;

      /* Image storage */
      PgmImageStorageType storage_type;
      PgmImageData data;

      /* Image displaying properties */
      PgmImageLayoutType  layout;
      PgmImageAlignment   align;
      PgmImageInterpType  interp;
      PgmImageWrapping    wrap_s;
      PgmImageWrapping    wrap_t;
      guint               par_n, par_d;

      /* Image border */
      gfloat border_width;
      guchar border_inner_r;
      guchar border_inner_g;
      guchar border_inner_b;
      guchar border_inner_a;
      guchar border_outer_r;
      guchar border_outer_g;
      guchar border_outer_b;
      guchar border_outer_a;
    } PgmImage;

The PgmImage structure.

PgmImage *`master`; | the image PgmImage master.
GList *`slaves`; | the image list of PgmImage slaves.
PgmMat4x4 *`mapping_matrix`; | the image mapping matrix.
PgmImageStorageType `storage_type`; | the currently stored image type.
PgmImageData `data`; | the image data depending on the type.
PgmImageLayoutType `layout`; | the image layout.
PgmImageAlignment `align`; | the image alignment.
PgmImageInterpType `interp`; | the image interpolation.
PgmImageWrapping `wrap_s`; | the image s wrapping.
PgmImageWrapping `wrap_t`; | the image t wrapping.
guint `par_n`; | the image pixel-aspect-ratio numerator.
guint `par_d`; | the image pixel-aspect-ratio denominator.
gfloat `border_width`; | the image border width.
guchar `border_inner_r`; | the image border outer red color.
guchar `border_inner_g`; | the image border outer green color.
guchar `border_inner_b`; | the image border outer blue color.
guchar `border_inner_a`; | the image border outer alpha color.
guchar `border_outer_r`; | the image border outer red color.
guchar `border_outer_g`; | the image border outer green color.
guchar `border_outer_b`; | the image border outer blue color.
guchar `border_outer_a`; | the image border outer alpha color.

### pgm_image_new ()

    PgmDrawable *       pgm_image_new                       (void);

Creates a new PgmImage instance.

MT safe.

Returns : | a new PgmImage instance.

### pgm_image_new_from_file ()

    PgmDrawable *       pgm_image_new_from_file             (const gchar *filename,
                                                             guint max_size);

Creates a new PgmImage instance loading an image from the given `filename`. It optionally pre-scales the image so that it has a maximum width and height of `max_size`.

The loading is done asynchronously, it means that this function returns right after the image object is created, the loading and decoding of the image being done in another thread. The 'file-loaded' signal is emitted from the Pigment main loop (the thread running `pgm_main()` or the thread running a GMainLoop using the default GMainContext) once the loading finishes successfully.

MT safe.

`filename` : | the filename.
`max_size` : | the maximum size of the image in pixels before loading it in the PgmImage or 0 to not constrain the size.
Returns : | a new PgmImage instance.

### pgm_image_new_from_pixbuf ()

    PgmDrawable *       pgm_image_new_from_pixbuf           (GdkPixbuf *pixbuf);

Creates a new PgmImage instance using `pixbuf` as stored image.

MT safe.

`pixbuf` : | the GdkPixbuf.
Returns : | a new PgmImage instance.

### pgm_image_new_from_buffer ()

    PgmDrawable *       pgm_image_new_from_buffer           (PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             guint size,
                                                             gconstpointer data);

Creates a new PgmImage instance with the image from the given buffer.

MT safe.

`format` : | the pixel format of the buffer.
`width` : | the image width in pixels.
`height` : | the image height in pixels.
`stride` : | the image rowstride in bytes (number of bytes per line).
`size` : | the buffer size in bytes.
`data` : | a pointer to the data buffer.
Returns : | a new PgmImage instance.

### pgm_image_new_from_image ()

    PgmDrawable *       pgm_image_new_from_image            (PgmImage *src_image);

Creates a new PgmImage instance with an image slaved from the image of `src_image`.

MT safe.

`src_image` : | a PgmImage which will be used as the master image.
Returns : | a new PgmImage instance.

### pgm_image_set_from_file ()

    PgmError            pgm_image_set_from_file             (PgmImage *image,
                                                             const gchar *filename,
                                                             guint max_size);

Loads an image from the file `filename`. It optionally pre-scales the image so it has a maximum width and height of `max_size`.

The loading is done asynchronously, it means that this function returns right after the image object is created, the loading and decoding of the image being done in another thread. The 'pixbuf-loaded' signal is emitted from the Pigment main loop (the thread running `pgm_main()` or the thread running a GMainLoop using the default GMainContext) once the loading finishes successfully.

MT safe.

`image` : | a PgmImage object.
`filename` : | a filename.
`max_size` : | the maximum size of the image in pixels before loading it in the PgmImage or 0 to not constrain the size.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_from_pixbuf ()

    PgmError            pgm_image_set_from_pixbuf           (PgmImage *image,
                                                             GdkPixbuf *pixbuf);

Loads an image in `image` from a pixbuf. `pixbuf` will have its reference count increased by 1 and will not get freed until the drawable gets cleaned up or that a new buffer is loaded.

MT safe.

`image` : | a PgmImage object.
`pixbuf` : | the GdkPixbuf.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_from_buffer ()

    PgmError            pgm_image_set_from_buffer           (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             guint size,
                                                             gconstpointer data);

Loads an image in `image` from an existing buffer using pixel format `format`. If you don't know the rowstride of the image you can set stride to 0. `data` is copied internally you can free it right after the function call returns.

MT safe.

`image` : | a PgmImage object.
`format` : | the pixel format of the buffer.
`width` : | the image width in pixels.
`height` : | the image height in pixels.
`stride` : | the rowstride of the image in bytes (number of bytes per line).
`size` : | the buffer size in bytes.
`data` : | a pointer to the data buffer.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_from_gst_buffer ()

    PgmError            pgm_image_set_from_gst_buffer       (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             guint stride,
                                                             GstBuffer *buffer);

Loads an image in `image` from an existing GstBuffer using the pixel format `format`. If you don't know the rowstride of the image you can set stride to 0. `buffer` will have its reference count increased by 1 and will not get freed until the drawable gets cleaned up or that a new buffer is loaded.

MT safe.

`image` : | a PgmImage object.
`format` : | the pixel format of the buffer.
`width` : | the image width in pixels.
`height` : | the image height in pixels.
`stride` : | the rowstride of the image in bytes (number of bytes per line).
`buffer` : | A GstBuffer reference containing the video frame.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_from_system_buffer ()

    PgmError            pgm_image_set_from_system_buffer    (PgmImage *image,
                                                             PgmImagePixelFormat format,
                                                             guint width,
                                                             guint height,
                                                             gconstpointer system_buffer);

Loads an image in `image` from an existing system buffer.

A system buffer depends on the platform, for instance on UNIX with an X11 server running, `system_buffer` can be set to an X11 Pixmap.

MT safe.

`image` : | a PgmImage object.
`format` : | the pixel format of the buffer.
`width` : | the image width in pixels.
`height` : | the image height in pixels.
`system_buffer` : | a pointer to the system buffer.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_from_image ()

    PgmError            pgm_image_set_from_image            (PgmImage *image,
                                                             PgmImage *src_image);

Slaves `image` to `src_image`. Every change to `src_image` is reflected on `image` until you remove `image` from the canvas or you call `pgm_image_clear()` on `image`.

MT safe.

`image` : | a PgmImage object.
`src_image` : | the source PgmImage object to use as a master.
Returns : | a PgmError indicating success/failure.

### pgm_image_to_pixbuf ()

    PgmError            pgm_image_to_pixbuf                 (PgmImage *image,
                                                             GdkPixbuf **pixbuf);

Retrieves a GdkPixbuf of the image currently stored in `image`.

Only the images stored as pixbuf can be retrieved at the moment, the conversion for the other storage types is not implemented yet.

MT safe.

`image` : | a PgmImage object.
`pixbuf` : | a double pointer to GdkPixbuf. Unref after usage.
Returns : | a PgmError indicating success/failure.

### pgm_image_clear ()

    PgmError            pgm_image_clear                     (PgmImage *image);

Removes any image from `image`. If `image` had some image data loaded, it's cleared, if there was a GstBuffer used, it's unreffed and if the `image` was a slave to another it is not anymore. If `image` has slave images they all get cleared but they still are slaves to `image`. So if you load a new image to `image`, all the slaves will load it too.

MT safe.

`image` : | a PgmImage object.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_storage_type ()

    PgmError            pgm_image_get_storage_type          (PgmImage *image,
                                                             PgmImageStorageType *storage);

Retrieves the type of representation being used by `image` to store image data. If `image` has no image data, the return value will be PGM_IMAGE_EMPTY.

MT safe.

`image` : | a PgmImage object.
`storage` : | a PgmImageStorageType where the storage type is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_system_buffer_lock ()

    PgmError            pgm_image_system_buffer_lock        (PgmImage *image);

Lock the system buffer set as the image content, ensuring the image is not going to be drawn while the system buffer content changes. This function guaranties tear free system buffer updates.

MT safe.

`image` : | a PgmImage object.
Returns : | a PgmError indicating success/failure.

### pgm_image_system_buffer_unlock ()

    PgmError            pgm_image_system_buffer_unlock      (PgmImage *image);

Unlock the system buffer set as the image content.

MT safe.

`image` : | a PgmImage object.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_mapping_matrix ()

    PgmError            pgm_image_set_mapping_matrix        (PgmImage *image,
                                                             PgmMat4x4 *mapping_matrix);

Defines the transformation to apply to the stored image when it is rendered. You can make the stored image slide over the drawable, rotate around it, stretch and shrink, or any combination of the three.

Each point in an image can be defined by an (x, y) vector, which we call the source position, representing the horizontal (x) and vertical (y) positions (with values between 0 for left/top and 1 for right/bottom). When the image is drawn on a surface, each point (x, y) is drawn on the (x', y') coordinate of the surface. We call (x', y') the destination position. The default mapping matrix is the identity, you have (x', y') == (x, y). Once you have called the function, the destination position is calculated by multiplying `mapping_matrix` with the source position vector. To reset the mapping matrix, just set the identity.

`mapping_matrix` is a 4x4 matrix since the source and destination positions can be represented as 4 coordinate vectors (x, y, z, w) and (x', y', z', w'). Unless you know what you are doing, you should not worry about z and w, and arrange for your matrix to leave them unchanged.

MT safe.

`image` : | a PgmImage object.
`mapping_matrix` : | a PgmMat4x4 object.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_mapping_matrix ()

    PgmError            pgm_image_get_mapping_matrix        (PgmImage *image,
                                                             PgmMat4x4 **mapping_matrix);

Retrieves in `matrix` the current mapping matrix applied to `image`.

MT safe.

`image` : | a PgmImage object.
`mapping_matrix` : | a pointer to a PgmMat4x4 pointer where the mapping matrix is going to be stored. `pgm_mat4x4_free()` after use.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_alignment ()

    PgmError            pgm_image_set_alignment             (PgmImage *image,
                                                             PgmImageAlignment align);

Defines the way `image` aligns the stored image.

MT safe.

`image` : | a PgmImage object.
`align` : | a PgmImageAlignment combination of flags.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_alignment ()

    PgmError            pgm_image_get_alignment             (PgmImage *image,
                                                             PgmImageAlignment *align);

Retrieves in `align` the way `image` aligns the stored image.

MT safe.

`image` : | a PgmImage object.
`align` : | a pointer to a PgmImageAlignment where alignment flags are going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_layout ()

    PgmError            pgm_image_set_layout                (PgmImage *image,
                                                             PgmImageLayoutType layout);

Defines the way `image` layouts its stored image.

MT safe.

`image` : | a PgmImage object.
`layout` : | a PgmImageLayoutType layout type.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_layout ()

    PgmError            pgm_image_get_layout                (PgmImage *image,
                                                             PgmImageLayoutType *layout);

Retrieves in `layout` the way `image` layouts its its stored image.

MT safe.

`image` : | a PgmImage object.
`layout` : | a pointer to a PgmImageLayoutType where the layout type is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_interp ()

    PgmError            pgm_image_set_interp                (PgmImage *image,
                                                             PgmImageInterpType interp);

Defines that `image` will be rendered using `interp` as its interpolation type.

MT safe.

`image` : | a PgmImage object.
`interp` : | the interpolation type.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_interp ()

    PgmError            pgm_image_get_interp                (PgmImage *image,
                                                             PgmImageInterpType *interp);

Retrieves in `interp` the current interpolation type of `image`.

MT safe.

`image` : | a PgmImage object.
`interp` : | a pointer to a PgmImageInterpType where the interpolation type is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_wrapping ()

    PgmError            pgm_image_set_wrapping              (PgmImage *image,
                                                             PgmImageWrapping wrap_s,
                                                             PgmImageWrapping wrap_t);

Sets the horizontal and vertical wrapping modes used for the mapping of `image`. When the mapping matrix is modified, pixels outside the range of the image content are accessed, the wrapping mode defines the behaviour of the mapping in that particular case.

MT safe.

`image` : | a PgmImage object.
`wrap_s` : | the wrapping on the s coordinate. PGM_IMAGE_REPEAT by default.
`wrap_t` : | the wrapping on the t coordinate. PGM_IMAGE_REPEAT by default.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_wrapping ()

    PgmError            pgm_image_get_wrapping              (PgmImage *image,
                                                             PgmImageWrapping *wrap_s,
                                                             PgmImageWrapping *wrap_t);

Retrieves in `wrap_s` and `wrap_t` the current wrapping modes of `image`.

MT safe.

`image` : | a PgmImage object.
`wrap_s` : | a pointer to a PgmImageInterpType where the wrapping mode on the s coordinate is going to be stored.
`wrap_t` : | a pointer to a PgmImageInterpType where the wrapping mode on the t coordinate is going to be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_aspect_ratio ()

    PgmError            pgm_image_set_aspect_ratio          (PgmImage *image,
                                                             guint numerator,
                                                             guint denominator);

Customizes the aspect ratio of the stored image.

MT safe.

`image` : | a PgmImage object.
`numerator` : | the numerator of the aspect ratio fraction.
`denominator` : | the denominator of the aspect ratio fraction.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_aspect_ratio ()

    PgmError            pgm_image_get_aspect_ratio          (PgmImage *image,
                                                             guint *numerator,
                                                             guint *denominator);

Retrieves the aspect ratio of the stored image.

MT safe.

`image` : | a PgmImage object.
`numerator` : | a pointer to a guint where the numerator of the aspect ratio fraction will be stored.
`denominator` : | a pointer to a guint where the denominator of the aspect ratio fraction will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_border_width ()

    PgmError            pgm_image_set_border_width          (PgmImage *image,
                                                             gfloat width);

Defines the border width drawn around `image`.

Note that the border is drawn around the image, inside the drawable. When you change the size of the border, the image will be down-scaled.

MT safe.

`image` : | a PgmImage object.
`width` : | the border with. 0.0 by default.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_border_width ()

    PgmError            pgm_image_get_border_width          (PgmImage *image,
                                                             gfloat *width);

Retrieves the width of the border drawn around image inside the drawable.

MT safe.

`image` : | a PgmImage object.
`width` : | a pointer to a gfloat where the border width will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_border_inner_color ()

    PgmError            pgm_image_set_border_inner_color    (PgmImage *image,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);

Defines the border inner color drawn around `image`.

MT safe.

`image` : | a PgmImage object.
`red` : | the border inner red color. 255 by default.
`green` : | the border inner green color. 255 by default.
`blue` : | the border inner blue color. 255 by default.
`alpha` : | the border inner alpha color. 255 by default.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_border_inner_color ()

    PgmError            pgm_image_get_border_inner_color    (PgmImage *image,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

Retrieves the inner color of the border drawn around image inside the drawable.

MT safe.

`image` : | a PgmImage object.
`red` : | a pointer to a guchar where the border inner red color will be stored.
`green` : | a pointer to a guchar where the border inner green color will be stored.
`blue` : | a pointer to a guchar where the border inner blue color will be stored.
`alpha` : | a pointer to a guchar where the border inner alpha color will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_set_border_outer_color ()

    PgmError            pgm_image_set_border_outer_color    (PgmImage *image,
                                                             guchar red,
                                                             guchar green,
                                                             guchar blue,
                                                             guchar alpha);

Defines the border outer color drawn around `image`.

MT safe.

`image` : | a PgmImage object.
`red` : | the border outer red color. 255 by default.
`green` : | the border outer green color. 255 by default.
`blue` : | the border outer blue color. 255 by default.
`alpha` : | the border outer alpha color. 255 by default.
Returns : | a PgmError indicating success/failure.

### pgm_image_get_border_outer_color ()

    PgmError            pgm_image_get_border_outer_color    (PgmImage *image,
                                                             guchar *red,
                                                             guchar *green,
                                                             guchar *blue,
                                                             guchar *alpha);

Retrieves the outer color of the border drawn around image inside the drawable.

MT safe.

`image` : | a PgmImage object.
`red` : | a pointer to a guchar where the border outer red color will be stored.
`green` : | a pointer to a guchar where the border outer green color will be stored.
`blue` : | a pointer to a guchar where the border outer blue color will be stored.
`alpha` : | a pointer to a guchar where the border outer alpha color will be stored.
Returns : | a PgmError indicating success/failure.

### pgm_image_from_drawable ()

    PgmError            pgm_image_from_drawable             (PgmImage *image,
                                                             gint *x_image,
                                                             gint *y_image,
                                                             gfloat x_drawable,
                                                             gfloat y_drawable);

Converts a position in drawable space (canvas units, origin at top left of drawable) into `image` space (image pixel units, origin at top left of image).

`image` : | a PgmImage instance
`x_image` : | where to return the x coordinate in the `image` plane.
`y_image` : | where to return the y coordinate in the `image` plane.
`x_drawable` : | the x coordinate in drawable space.
`y_drawable` : | the y coordinate in drawable space.
Returns : | a PgmError indicating success/failure.

### pgm_image_to_drawable ()

    PgmError            pgm_image_to_drawable               (PgmImage *image,
                                                             gfloat *x_drawable,
                                                             gfloat *y_drawable,
                                                             gint x_image,
                                                             gint y_image);

Converts a position in `image` space (image pixel units, origin at top left of image) into drawable space (canvas units, origin at top left of drawable).

`image` : | a PgmImage instance
`x_drawable` : | where to return the x coordinate in the `drawable` plane.
`y_drawable` : | where to return the y coordinate in the `drawable` plane.
`x_image` : | the x coordinate in image space.
`y_image` : | the y coordinate in image space.
Returns : | a PgmError indicating success/failure.

## Signal Details

### The `"cloned"` signal

    void                user_function                      (PgmImage *image,
                                                            PgmImage *clone,
                                                            guint     n_clones,
                                                            gpointer  user_data)      : Run First

Will be emitted after `image` has been cloned by another PgmImage through the `pgm_image_new_from_image()` or `pgm_image_set_from_image()` functions.

`image` : | the PgmImage
`clone` : | the cloned PgmImage
`n_clones` : | the number of cloned images
`user_data` : | user data set when the signal handler was connected.

### The `"file-loaded"` signal

    void                user_function                      (PgmImage *image,
                                                            gpointer  user_data)      : Run First

Will be emitted after `image` has finished to load its data from the file path given in the `pgm_image_set_from_file()` method.

`image` : | the PgmImage
`user_data` : | user data set when the signal handler was connected.

### The `"un-cloned"` signal

    void                user_function                      (PgmImage *image,
                                                            guint     n_clones,
                                                            gpointer  user_data)      : Run First

Will be emitted after `image` has got a cloned PgmImage removed.

`image` : | the PgmImage
`n_clones` : | the number of cloned images
`user_data` : | user data set when the signal handler was connected.

## See Also

#PgmDrawable, PgmText, PgmCanvas.