Navigation C API Pages Python bindings Applications

Pixmap loaders

This part of GFXprim library implements API to load and save images for common image file formats.

Currently we support JPEG, PNG, BMP, TIFF and PNM images for loading and saving and GIF, WEBP, JPEG2000, PCX, CBZ, PSD and PSP for loading.

Have a look at the supported formats for more detailed information.

Image Loaders and Savers

Loading functions exists in at least two flavors. One that works with a path to a file and one that reads data from an IO stream.

All loading functions returns a pointer to newly allocated and loaded image or upon a failure NULL and errno is set.

The pixmap returned by the loaders should be later freed with gp_pixmap_free().

All saving functions returns zero on success and non-zero on failure. If image saving is aborted by a callback, the opened file is closed and removed from a file-system before the call returns.

The signature matching functions takes a 32 bytes long buffer and looks for a valid image signature. If signature is found non-zero is returned.

Table 1. Possible errno values

Any errno returned by underlying open(), close(), lseek(), read(), write(), …

ENOENT if file doesn’t exist

EACCES if process doesn’t have rights to open the file

ENOSYS if GFXprim wasn’t compiled with particular format support

ENOMEM if returned by malloc()

EIO, EINVAL invalid image data (wrong signature, wrong or too short header or image data)

ECANCELED action canceled by returning non-zero from within a callback.

You can get more information about the error condition by turning on GFXprim debug messages.

General interface

#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_image(const char *src_path, gp_progress_cb *callback);

Loads an image from a file.

The image format is first guessed by the file extension. If loader is found and if it succeeds to load the image the newly loaded image is returned.

If file extension based guess fails either because the extension wasn’t matched or if the loader for the extension failed; the file signature based method is used. The loader loads several bytes (currently 32) from the file and calls signature matching functions for each format that implements signature matching. If image signature is recognized, image loader it is called and the result is returned.

If file extension disagrees with file signature (which is quite common on the internet) a warning is printed into the stderr.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

int gp_save_image(gp_pixmap *src, const char *dst_path,
                  gp_progress_cb *callback);

Saves a pixmap into a file.

The file format is matched accordingly to the file extension.

If extension is not found non-zero is returned and errno is set to EINVAL.

If extension was found but support for saving the image format is not implemented errno is set to ENOSYS (this may happen in case that GFXprim wasn’t compiled with support for this image type).

If pixmap pixel type is not supported by the format errno is set to EINVAL.

Advanced Interface

typedef struct gp_loader {
        /*
         * Reads an image from an IO stream.
         *
         * Returns newly allocated pixmap cotaining the loaded image or in
         * case of failure NULL and errno is set.
         */
        gp_pixmap *(*read)(gp_io *io, gp_progress_cb *callback);

        /*
         * Save an image.
         *
         * Returns zero on success, non-zero on failure and errno must be set.
         */
        int (*save)(const gp_pixmap *src, const char *dst_path,
                    gp_progress_cb *callback);

        /*
         * GP_PIXEL_UNKNOWN terminated array of formats loader supports for save.
         *
         * This is _NOT_ a complete list loaders is able to save, due to automatic
         * conversions (i.e. RGB888 vs BRG888).
         */
        const gp_pixel_type *save_ptypes;

        /*
         * The buffer is filled with 32 bytes from an image start, returns 1 if
         * image signature was found zero otherwise.
         */
        int (*match)(const void *buf);

        /*
         * Short format name.
         */
        const char *fmt_name;

        /*
         * NULL terminated array of file extensions.
         */
        const char *extensions[];
} gp_load_er;

The gp_loader structure describes an image loader.

The read, save and match functions could be NULL if the particular functionality is not implemented.

The fmt_name is a short string that describes the format. For example: Netbpm portable pixmap.

The extensions is NULL-terminated array of strings that holds all possible extensions that are commonly used for this image format.

#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

void gp_loaders_list(void);

int gp_loader_register(const gp_loader *self);

void gp_loader_unregister(const gp_loader *self);

The gp_loaders_list() function prints all currently registered loaders and their capabilities into the stdout.

You can register and unregister your own loader by gp_loader_register() and gp_loader_unregister(). Once image loader is registered it’s automatically used by all loaders functions.

The gp_loader_register() can fail (return non-zero) if you try to register loader that is allready registered or if the loaders table is full (the table size is compile time constant and there should be space for at least fifty user defined loaders). I this cases the errno would be set to EEXIST or ENOSPC respectively.

Tip For example usage see image loader registration example.
#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

const gp_loader *gp_loader_by_signature(const void *buf)

Returns pointer to image loader accordingly to image signature or NULL if no suitable loader was found. The buf pointer must point to a buffer at least 32 bytes long.

#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

const gp_loader *gp_loader_by_filename(const char *path)

Matches loader by the file extension. This function does not check that the file exists or that it could be opened etc. It only looks at the file extension (i.e. string at the end of the path after a dot) and matches it against extensions defined by loaders.

#include <loaders/gp_load_er.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_loader_load_image(const gp_loader *self, const char *src_path,
                                gp_progress_cb *callback);

Loads an image given a loader structure.

Returns NULL and sets errno to ENOSYS loader Read() callback is NULL.

Otherwise prepares a gp_io from the src_path file, calls the read() callbacks and closes the IO before the call returns.

PNG Loader

The PNG image support is implemented by the libpng library.

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_png(gp_io *io, gp_progress_cb *callback);

Reads a PNG image from readable gp_io. The IO stream is expected to start exactly at the PNG file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_png(const char *src_path, gp_progress_cb *callback);

Loads a PNG image from a file.

Returns a pointer to newly allocated loaded image, or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_save_png(const gp_pixmap *src, const char *dst_path,
                gp_progress_cb *callback);

Saves a pixmap as a PNG image, in case particular pixel type is not supported non-zero is returned and errno is set to ENOSYS.

Supports G1, G2, G4, G8, G16, and 8-bit RGB and RGBA pixel types.

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_match_png(const void *buf);

Matches a PNG file signature. Returns non-zero if found.

JPEG Loader

The JPEG image support is implemented by the jpeg library.

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_jpg(gp_io *io, gp_progress_cb *callback);

Reads a JPEG image from readable gp_io. The IO stream is expected to start exactly at the JPEG file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_jpg(const char *src_path, gp_progress_cb *callback);

Loads a JPEG image from a file.

Returns a pointer to newly allocated loaded image, or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_save_jpg(const gp_pixmap *src, const char *dst_path,
                gp_progress_cb *callback);

Saves a pixmap as a JPEG image.

The JPEG format could store either G8 or 8-bit RGB pixel-types.

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_match_jpg(const void *buf);

Matches a JPEG file signature. Returns non-zero if found.

JPEG 2000 Loader

The JPEG 2000 image support is implemented using the openjpeg library.

#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_jp2(gp_io *io, gp_progress_cb *callback);

Reads a JPEG2000 image from readable gp_io. The IO stream is expected to start exactly at the JPEG2000 file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

Note Due to limitations of the openjpeg library progress callback does not work.
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_jp2(const char *src_path, gp_progress_cb *callback);

Loads a JPEG2000 image from a file.

The resulting pixmap should be later freed with gp_pixmap_free().

Note Due to limitations of the openjpeg library progress callback does not work.
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_jp2(const void *buf);

Matches a JPEG2000 file signature. Returns non-zero if found.

GIF Loader

The GIF image support is implemented using the giflib library.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_gif(gp_io *io, gp_progress_cb *callback);

Reads a GIF image from readable gp_io. The IO stream is expected to start exactly at the GIF file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

Note Currently this function loads only first image from the GIF container.
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_gif(const char *src_path, gp_progress_cb *callback);

Loads a GIF image from a file.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_gif(const void *buf);

Matches a GIF file signature. Returns non-zero if found.

BMP Loader

The BMP loading support is nearly complete the only missing features should be exotic RGB compressions (RGB101010 for example) and RLE4 support.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_bmp(gp_io *io, gp_progress_cb *callback);

Reads a BMP image from readable gp_io. The IO stream is expected to start exactly at the BMP file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_bmp(const char *src_path, gp_progress_cb *callback);

Loads a BMP image from a file.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_save_bmp(const gp_pixmap *src, const char *dst_path,
                gp_progress_cb *callback);

Saves a pixmap as a BMP image.

Currently only 8-bit RGB pixel types are supported.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_bmp(const void *buf);

Matches a BMP file signature. Returns non-zero if found.

TIFF Loader

The TIFF loader support is done using the tiff library.

Currently only subset of tiff images could be loaded, tiles does not work yet.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_tiff(gp_io *io, gp_progress_cb *callback);

Reads a TIFF image from readable gp_io. The IO stream is expected to start exactly at the TIFF file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_tiff(const char *src_path, gp_progress_cb *callback);

Loads a TIFF image from a file.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_save_tiff(const gp_pixmap *src, const char *dst_path,
                 gp_progress_cb *callback);

Saves a pixmap as a TIFF image.

Supports G1, G2, G4 and G8 grayscale and 8-bit RGB pixel types.

The image is saved in stripes.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_tiff(const void *buf);

Matches a TIFF file signature. Returns non-zero if found.

PSP Loader

The PSP loader can load a composite image from a Paint Shop Pro Image Files.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_psp(gp_io *io, gp_progress_cb *callback);

Reads a PSP composite image from readable gp_io. The IO stream is expected to start exactly at the PSP file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_psp(const char *src_path, gp_progress_cb *callback);

Loads a composite image from a PSP file.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_psp(const void *buf);

Matches a PSP file signature. Returns non-zero if found.

PSD Loader

The PSD loader can load a merged image (if present) or a thumbnail from an Adobe Photoshop Image. Currently 16bit RGB and 16bit CMYK is not supported and the loader will fallback to the thumbnail in this case (which is always 8bit RGB).

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_psd(gp_io *io, gp_progress_cb *callback);

Reads a PSD image from readable gp_io. The IO stream is expected to start exactly at the PSD file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_psd(const char *src_path, gp_progress_cb *callback);

Loads a merged image (if present) from a PSD file.

Fallbacks to thumbnail if merged image is not present or has unsupported pixel type.

Returns NULL (TODO ERRNO) if merged image is not present/supported and thumbnail is not present either.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_psd(const void *buf);

Matches a PSD file signature. Returns non-zero if found.

PNM Loaders

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_pbm(gp_io *io, gp_progress_cb *callback);

gp_pixmap *gp_read_pgm(gp_io *io, gp_progress_cb *callback);

gp_pixmap *gp_read_ppm(gp_io *io, gp_progress_cb *callback);

gp_pixmap *gp_read_pnm(gp_io *io, gp_progress_cb *callback);

Reads a ASCII or Rawbits (binary) PBM, PGM and PPM image from readable gp_io. The IO stream is expected to start exactly at the file signature.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_pbm(const char *src_path, gp_progress_cb *callback);

gp_pixmap *gp_load_pgm(const char *src_path, gp_progress_cb *callback);

gp_pixmap *gp_load_ppm(const char *src_path, gp_progress_cb *callback);

gp_pixmap *gp_load_pnm(const char *src_path, gp_progress_cb *callback);

Loads either ASCII or Rawbits (binary) PBM, PGM and PPM.

The PNM loader can load all of them i.e. PBM, PGM and PPM.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_save_pbm(const GP_pixmap *src, const char *dst_path,
                       gp_progress_cb *callback);

Saves G1 (1 bit grayscale) image as ASCII PBM.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_save_pgm(const GP_pixmap *src, const char *dst_path,
                       gp_progress_cb *callback);

Saves G1, G2, G4 and G8 (1, 2, 4 and 8 bit grayscale) image as ASCII PGM.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_save_ppm(const GP_pixmap *src, const char *dst_path,
                       gp_progress_cb *callback);

Saves RGB888 (24 bit RGB) image as ASCII PPM.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_save_pnm(const GP_pixmap *src, const char *dst_path,
                       gp_progress_cb *callback);

Saves G1, G2, G4 and G8 (1, 2, 4, 8 bit grayscale) or RGB888 (24 bit RGB) image as ASCII PNM.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_pbm(const void *buf);

int gp_match_pgm(const void *buf);

int gp_match_ppm(const void *buf);

int gp_match_pnm(const void *buf);

Matches either ASCII or Rawbits (binary) PBM, PGM and PPM file signatures.

The PNM matches all of the formats. i.e. PBM, PGM and PPM.

All functions return non-zero if found.

PCX Loader

The PCX loader can load ZSoft PCX images.

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_read_pcx(gp_io *io, gp_progress_cb *callback);

Reads a PCX image from readable gp_io. The IO stream is expected to start exactly at the PCX file signature.

Returns newly allocated pixmap (containing decompressed image) or in case of failure NULL and errno is set.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

gp_pixmap *gp_load_pcx(const char *src_path, gp_progress_cb *callback);

Loads a PCX image from a file.

The resulting pixmap should be later freed with gp_pixmap_free().

#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_pcx(const void *buf);

Matches a PCX file signature. Returns non-zero if found.