![]() |
![]() |
![]() |
Pigment 0.3 Reference Manual | ![]() |
---|---|---|---|---|
#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);
PgmImage is a drawable displaying media. It supports various ways of loading images through buffers, file descriptors 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_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.
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.
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()
.
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)
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.
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.
typedef enum { PGM_IMAGE_NEAREST, PGM_IMAGE_BILINEAR } PgmImageInterpType;
The different image interpolation types.
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.
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. |
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. |
typedef struct { GdkPixbuf *pixbuf; } PgmImageFd;
The PgmImageFd structure.
GdkPixbuf *pixbuf ; |
the GdkPixbuf object. |
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 { PgmImageBuffer buffer; PgmImageGstBuffer gst_buffer; PgmImageFd fd; };
The stored data depending on the storage type.
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. |
PgmDrawable* pgm_image_new (void);
Creates a new PgmImage instance.
MT safe.
Returns : | a new PgmImage instance. |
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. |
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.
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.
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. |
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. |
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.
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.
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.
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. |
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. |
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. |
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. |
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. |
PgmError pgm_image_set_interp (PgmImage *image, PgmImageInterpType interp);
Defines that image
will be rendered using interp
as its interpolation
type.
MT safe.
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. |
PgmError pgm_image_set_aspect_ratio (PgmImage *image, guint numerator, guint denominator);
Customizes the aspect ratio of the stored image.
MT safe.
PgmError pgm_image_get_aspect_ratio (PgmImage *image, guint *numerator, guint *denominator);
Retrieves the aspect ratio of the stored image.
MT safe.
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. |
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. |