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.