Navigation C API Pages Python bindings Applications

Context loaders

This part of GFXprim library aims to create API to load and save images from/to common image file formats.

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

Have a look at the supported formats.

Image Loaders and Savers

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

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

In case of a failure errno is set, possible errno values are:

  • anything returned by open(), close(), lseek(), read(), write(), …

    • ENOENT if file doesn’t exist

    • EACCES if process doesn’t have rights

    • etc.

  • ENOSYS if GFXprim wasn’t compiled with particular library 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.

#include <loaders/GP_Loader.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback);

Loads an image from a file.

The image format is first guessed by the file extension. If loader for the file extension is found it’s called and if it succedes the image data is returned.

If file extension based guess fails either because the extension wasn’t matched or if the loader for the extension failed; the 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 found image loader it is called and the result is returned.

If file extension disagrees with file signature on the file format a warning is printed into the stderr.

#include <loaders/GP_Loader.h>
/* or */
#include <GP.h>

int GP_SaveImage(GP_Context *src, const char *dst_path,
                 GP_ProgressCallback *callback);

Saves a context 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 context pixel type is not supported by the format errno is set to EINVAL.

Advanced Loaders usage

typedef struct GP_Loader {
        /*
         *  Loads an image.
         *
         *  Returns allocated and initialized bitmap on success, NULL on failure
         *  and errno must be set.
         */
        GP_Context *(*Load)(const char *src_path, GP_ProgressCallback *callback);

        /*
         * Save an image.
         *
         * Returns zero on succes, non-zero on failure and errno must be set.
         */
        int (*Save)(const GP_Context *src, const char *dst_path,
                    GP_ProgressCallback *callback);

        /*
         * 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;

        /* don't touch */
        struct GP_Loader *next;

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

/*
 * List loaders into the stdout.
 */
void GP_ListLoaders(void);

/*
 * Register a loader.
 */
void GP_LoaderRegister(GP_Loader *self);

/*
 * Unregister loader.
 */
void GP_LoaderUnregister(GP_Loader *self);

The GP_Loader structure describes an image loader.

The Load, 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.

All internal loaders are all described in list of this structures which is used to implement functions such as GP_LoadImage().

You can print currently active loaders via the GP_ListLoaders(). Register and unregister your own loaders by GP_LoaderRegister() and GP_LoaderUnregister(). Once image loader is registered the generic loading functions can use it to load and save images.

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

const GP_Loader *GP_MatchSignature(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_Loader.h>
/* or */
#include <GP.h>

const GP_Loader *GP_MatchExtension(const char *path)

Matches loader by the file extension. This function does not check that the file exists or that it could be opened it only looks at the extension (i.e. string after the dot) and matches it agains known extensions.

Warning If you attempt to modify the content of the strucutre the behavior is undefined. Most likely the program will crash.

PNG Loader

The PNG image support is implemented by the libpng library.

#include <loaders/GP_PNG.h>
/* or */
#include <GP.h>

int GP_OpenPNG(const char *src_path, FILE **f);

Opens file and checks for PNG signature. Returns zero on success (file could be opened, signature matches), the opened file is returned and the file position points right after the end of the PNG signature.

This function is semi-internal, you should rather use functions listed below.

#include <loaders/GP_PNG.h>
/* or */
#include <GP.h>

GP_Context *GP_ReadPNG(FILE *f, GP_ProgressCallback *callback);

Loads PNG file into context the file pointer must point to the start of the PNG data stream (i.e. should point right after the signature). The context, to store the image to, is allocated. The loading process could by aborted by a callback, in such case all memory is freed.

#include <loaders/GP_PNG.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadPNG(const char *src_path, GP_ProgressCallback *callback);

Same as above but takes path to the file as a parameter and check for the signature. Basically this combines both of the calls above.

#include <loaders/GP_PNG.h>
/* or */
#include <GP.h>

int GP_SavePNG(const GP_Context *src, const char *dst_path,
               GP_ProgressCallback *callback);

Currently only RGB888 format is supported, you should convert the GP_Context to RGB888 before calling this function otherwise non-zero is returned and errno is set to ENOSYS.

#include <loaders/GP_PNG.h>
/* or */
#include <GP.h>

int GP_MatchPNG(const void *buf);

Matches a PNG signature.

JPEG Loader

The JPEG image support is implemented by the jpeg library.

#include <loaders/GP_JPG.h>
/* or */
#include <GP.h>

int GP_OpenJPG(const char *src_path, FILE **f);

Opens file and checks for JPG signature upon successful return (file could be opened, signature matches), the opened file is returned and the file position points right after the end of the JPG signature.

This function is semi-internal, you should rather use functions listed below.

TODO: This is not finished yet, currently this just opens and returns the file and the GP_ReadJPG() reads the signature instead.

#include <loaders/GP_JPG.h>
/* or */
#include <GP.h>

GP_Context *GP_ReadJPG(FILE *f, GP_ProgressCallback *callback);

Loads JPG file into context the file pointer must point to the start of the JPG data stream (i.e. should point right after the signature). The context, to store the image to, is allocated. The loading process could by aborted by a callback, in such case all memory is freed and the call returns NULL and errno is set to ECANCELED.

#include <loaders/GP_JPG.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadJPG(const char *src_path, GP_ProgressCallback *callback);

Same as above but takes path to the file as a parameter and check for the signature. Basically this combines both of the calls above.

#include <loaders/GP_JPG.h>
/* or */
#include <GP.h>

int GP_SaveJPG(const GP_Context *src, const char *dst_path,
               GP_ProgressCallback *callback);

Writes a Context into a JPG image. If aborted by a callback, the opened file is closed and removed before the call returns non-zero and errno is set to ECANCELED.

The JPG format could store either G8 or RGB888 pixeltypes and you must convert the context into one of them before this functions is called.

#include <loaders/GP_JPG.h>
/* or */
#include <GP.h>

int GP_MatchJPG(const void *buf);

Matches a JPG signature.

JPEG 2000 Loader

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

#include <loaders/GP_JP2.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadJP2(const char *src_path, GP_ProgressCallback *callback);

Loads JPEG 2000 image.

Due to limitations of the openjpeg library progress callback does not work.

GIF Loader

The GIF image support is implemented by the giflib library.

#include <loaders/GP_GIF.h>
/* or */
#include <GP.h>

int GP_OpenGIF(const char *src_path, void **f);

Opens file and checks for GIF signature upon successful return (file could be opened, signature matches) zero is returned and gif handle f is set otherwise non-zero is returned and errno is set.

This function is semi-internal, you should rather use functions listed below.

#include <loaders/GP_GIF.h>
/* or */
#include <GP.h>

GP_Context *GP_ReadGIF(void *f, GP_ProgressCallback *callback);

Loads GIF file into context. The pointer must point to the GIF handle as returned by GP_OpenGIF() function. The context, to store the image to, is allocated. The loading process could by aborted by a callback, in such case all memory is freed and the call returns NULL and errno is set to ECANCELED.

Currently this function loads only first image from the gif container.

#include <loaders/GP_GIF.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadGIF(const char *src_path, GP_ProgressCallback *callback);

Same as above but takes path to the file as a parameter and check for the signature. Basically this combines both of the calls above.

#include <loaders/GP_GIF.h>
/* or */
#include <GP.h>

int GP_MatchGIF(const void *buf);

Matches a GIF signature.

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_BMP.h>
/* or */
#include <GP.h>

int GP_OpenBMP(const char *src_path, FILE **f,
               GP_Size *w, GP_Size *h, GP_PixelType *pixel_type);

Opens file and checks for BMP signature upon successful return (file could be opened, signature matches) zero is returned and the parameters, if non-NULL, are initialized. Upon failure non-zero is returned and errno is set.

This function is semi-internal, you should rather use functions listed below.

#include <loaders/GP_BMP.h>
/* or */
#include <GP.h>

GP_Context *GP_ReadBMP(FILE *f, GP_ProgressCallback *callback);

Loads BMP file into context. The FILE pointer must point to opened BMP file. The context, to store the image to, is allocated. The loading process could by aborted by a callback, in such case all memory is freed and the call returns NULL and errno is set to ECANCELED.

#include <loaders/GP_BMP.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadBMP(const char *src_path, GP_ProgressCallback *callback);

Same as above but takes path to the file as a parameter and check for the signature. Basically this combines both of the calls above.

#include <loaders/GP_BMP.h>
/* or */
#include <GP.h>

int GP_SaveBMP(const GP_Context *src, const char *dst_path,
               GP_ProgressCallback *callback);

Saves RGB888 (24 bit RGB) image into BMP bitmap.

#include <loaders/GP_BMP.h>
/* or */
#include <GP.h>

int GP_MatchBMP(const void *buf);

Matches a BMP signature.

PSP Loader

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

#include <loaders/GP_PSP.h>
/* or */
#include <GP.h>

int GP_OpenPSP(const char *src_path, FILE **f);

Opens file and checks for PSP signature. Upon successful return (file could be opened, signature matches) zero is returned. Upon failure non-zero is returned and errno is set.

#include <loaders/GP_PSP.h>
/* or */
#include <GP.h>

GP_Context *GP_ReadPSP(FILE *f, GP_ProgressCallback *callback);

Reads PSP image into a context.

#include <loaders/GP_PSP.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadPSP(const char *src_path, GP_ProgressCallback *callback);

Same as above but takes path to the file as a parameter and checks for the signature. Basically this combines both of the calls above.

#include <loaders/GP_PSP.h>
/* or */
#include <GP.h>

int GP_MatchPSP(const void *buf);

Matches a PSP signature.

PNM

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

GP_Context *GP_LoadPBM(const char *src_path, GP_ProgressCallback *callback);

GP_Context *GP_LoadPGM(const char *src_path, GP_ProgressCallback *callback);

GP_Context *GP_LoadPPM(const char *src_path, GP_ProgressCallback *callback);

GP_Context *GP_LoadPNM(const char *src_path, GP_ProgressCallback *callback);

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

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

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

GP_Context *GP_SavePBM(const GP_Context *src, const char *dst_path,
                       GP_ProgressCallback *callback);

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

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

GP_Context *GP_SavePGM(const GP_Context *src, const char *dst_path,
                       GP_ProgressCallback *callback);

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

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

GP_Context *GP_SavePPM(const GP_Context *src, const char *dst_path,
                       GP_ProgressCallback *callback);

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

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

GP_Context *GP_SavePNM(const GP_Context *src, const char *dst_path,
                       GP_ProgressCallback *callback);

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

#include <loaders/GP_PNM.h>
/* or */
#include <GP.h>

int GP_MatchPBM(const void *buf);

int GP_MatchPGM(const void *buf);

int GP_MatchPPM(const void *buf);

int GP_MatchPNM(const void *buf);

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

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