PgmImage

PgmImage — An image drawable supporting various media.

Synopsis


#include <pgm/pgm.h>


enum                PgmImageAlignment;
enum                PgmImageLayoutType;
enum                PgmImageInterpType;
enum                PgmImagePixelFormat;
                    PgmImageBuffer;
                    PgmImageGstBuffer;
                    PgmImageFd;
enum                PgmImageStorageType;
union               PgmImageData;
                    PgmImage;
PgmDrawable*        pgm_image_new                       (void);
PgmDrawable*        pgm_image_new_from_buffer           (PgmImagePixelFormat format,
                                                         guint width,
                                                         guint height,
                                                         guint stride,
                                                         guint size,
                                                         gconstpointer data);
PgmDrawable*        pgm_image_new_from_fd               (guint fd,
                                                         guint max_size);
PgmDrawable*        pgm_image_new_from_image            (PgmImage *src_image);
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_fd               (PgmImage *image,
                                                         guint fd,
                                                         guint max_size);
PgmError            pgm_image_set_from_image            (PgmImage *image,
                                                         PgmImage *src_image);
PgmError            pgm_image_clear                     (PgmImage *image);
PgmError            pgm_image_get_storage_type          (PgmImage *image,
                                                         PgmImageStorageType *storage);
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_aspect_ratio          (PgmImage *image,
                                                         guint numerator,
                                                         guint denominator);
PgmError            pgm_image_get_aspect_ratio          (PgmImage *image,
                                                         guint *numerator,
                                                         guint *denominator);
PgmError            pgm_image_alloc_gst_buffer          (PgmImage *image,
                                                         GstBuffer **buffer,
                                                         PgmImagePixelFormat format,
                                                         guint width,
                                                         guint height,
                                                         guint size);


Object Hierarchy


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

Signals


  "fd-loaded"                                      : Run First

Description

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

Loading image data

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_fd() takes a pre-opened file descriptor to an image file delegating image loading to Pigment. Thus the loading is asynchronous and won't block the Pigment main loop.

Sharing image data between PgmImage objects

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.

Note that an image that has been set as a master to an other image gets its reference count increased for each slave it has, which means it won't get freed until all the references are gone. This can happen either because the slave drawable is removed from the canvas or if pgm_image_clear() is called on the slave drawable.

Image data aspect ratio

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.

Benefitting from hardware acceleration

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().

Rendering video frames directly in video memory

On small machines, memory copies are very expensive for the hardware and they should be avoided at all cost. GStreamer supports a nice system to render video frames directly in hardware allocated memory buffers through the gst_pad_alloc_buffer() function calls. This is why we have a method called pgm_image_alloc_gst_buffer() which returns a pre-allocated GstBuffer with requested pixel format and size, and preferably allocated in video memory. This GstBuffer will come back through pgm_image_set_from_gst_buffer() and it will be rendered directly without any copy of the raw video frame to system memory. Some rendering plugins might not support that feature and will return a system allocated memory buffer instead.

Last reviewed on 2007-04-12 (0.1.5)

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.
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. This is the fastest and lowest quality mode.
PGM_IMAGE_BILINEAR The bilinear sampling. This is the slowest and highest quality mode.

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

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.

PgmImageFd

typedef struct {
  GdkPixbuf *pixbuf;
} PgmImageFd;

The PgmImageFd structure.

GdkPixbuf *pixbuf; the GdkPixbuf object.

enum PgmImageStorageType

typedef enum {
  PGM_IMAGE_EMPTY,
  PGM_IMAGE_BUFFER,
  PGM_IMAGE_GST_BUFFER,
  PGM_IMAGE_FD,
  PGM_IMAGE_IMAGE,
} PgmImageStorageType;

The different storage type.

PGM_IMAGE_EMPTY no image stored.
PGM_IMAGE_BUFFER a PgmImageBuffer is stored.
PGM_IMAGE_GST_BUFFER a PgmImageGstBuffer is stored.
PGM_IMAGE_FD a PgmImageFd is stored.
PGM_IMAGE_IMAGE a PgmImage is stored (slaved).

union PgmImageData

union PgmImageData {
  PgmImageBuffer    buffer;
  PgmImageGstBuffer gst_buffer;
  PgmImageFd        fd;
};

The stored data depending on the storage type.


PgmImage

typedef struct {
  /* Image storage */
  PgmImageStorageType storage_type;
  PgmImageData data;

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

  /* Slavery handling */
  PgmImage *master;
  GList    *slaves;
} PgmImage;

The PgmImage structure.

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.
guint par_n; the image pixel-aspect-ratio numerator.
guint par_d; the image pixel-aspect-ratio denominator.
PgmImage *master; the image PgmImage master.
GList *slaves; the image list of PgmImage slaves.

pgm_image_new ()

PgmDrawable*        pgm_image_new                       (void);

Creates a new PgmImage instance.

MT safe.

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_fd ()

PgmDrawable*        pgm_image_new_from_fd               (guint fd,
                                                         guint max_size);

Creates a new PgmImage instance loading progressively an image from the pre-opened file descriptor fd. The file descriptor is then closed by Pigment. It optionally pre-scales the image so that it has a maximum width and height of max_size.

MT safe.

fd : the file descriptor from which data will be read to load image.
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_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_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_fd ()

PgmError            pgm_image_set_from_fd               (PgmImage *image,
                                                         guint fd,
                                                         guint max_size);

Progressively loads an image from the pre-opened file descriptor fd. The file descriptor is then closed by Pigment. It optionally pre-scales the image so it has a maximum width and height of max_size.

This function is meant to be asynchronous, it loads the image by small chunks of 1024 bytes using an idle source in the Pigment mainloop. The consequence being that the storage type of image doesn't change immediately, but only once the whole image is loaded. You can connect a callback to the fd-loaded signal to know when the loading is done.

MT safe.

image : a PgmImage object.
fd : the file descriptor from which data will be read to load image.
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_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. src_image and image see their reference count increased by 1 during that method as they need each other.

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_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_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_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_alloc_gst_buffer ()

PgmError            pgm_image_alloc_gst_buffer          (PgmImage *image,
                                                         GstBuffer **buffer,
                                                         PgmImagePixelFormat format,
                                                         guint width,
                                                         guint height,
                                                         guint size);

Gets image to allocate a video memory buffer of width x height with size bytes for GStreamer.

MT safe.

image : a PgmImage object.
buffer : a pointer to a GstBuffer which will contain the newly allocated buffer.
format : the format of the image that will be written in the buffer.
width : the image width in pixels.
height : the image height in pixels.
size : the required buffer size.
Returns : a PgmError indicating success/failure.

Signal Details

The "fd-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 descriptor given in methods like pgm_image_set_from_fd() or pgm_image_new_from_fd().

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

See Also

PgmDrawable, PgmText, PgmCanvas.