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 link:about.html#Loaders[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 link:loaders_io.html[IO stream].

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

The link:pixmap.html[pixmap] returned by the loaders should be later freed
with link:pixmap.html#pixmap_free[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 link:signatures.html[image signature]. If signature is found non-zero is
returned.

.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
  link:progress_callback.html[callback].
|===============================================================================

You can get more information about the error condition by turning on GFXprim
link:environment_variables.html#GP_DEBUG[debug messages].

General interface
^^^^^^^^^^^^^^^^^

[[Load_Image]]
[source,c]
-------------------------------------------------------------------------------
#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
link:signatures.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[[Save_Image]]
[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[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'.

[[Register_Loader]]
Advanced Interface
^^^^^^^^^^^^^^^^^^

[source,c]
-------------------------------------------------------------------------------
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.

[source,c]
-------------------------------------------------------------------------------
#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
link:example_loader_registration.html[example].

[source,c]
-------------------------------------------------------------------------------
#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.

[source,c]
-------------------------------------------------------------------------------
#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.

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[gp_io] from the 'src_path' file,
calls the 'read()' callbacks and closes the 'IO' before the call returns.

[[PNG]]
PNG Loader
~~~~~~~~~~
The 'PNG' image support is implemented by the
link:http://www.libpng.org/[libpng library].

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[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.

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_match_png(const void *buf);
-------------------------------------------------------------------------------

Matches a 'PNG' link:signatures.html[file signature]. Returns non-zero if found.

[[JPEG]]
JPEG Loader
~~~~~~~~~~~
The 'JPEG' image support is implemented by the jpeg library.

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] as a 'JPEG' image.

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

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_load_ers.h>
/* or */
#include <gfxprim.h>

int gp_match_jpg(const void *buf);
-------------------------------------------------------------------------------

Matches a 'JPEG' link:signatures.html[file signature]. Returns non-zero if
found.

[[JPEG2000]]
JPEG 2000 Loader
~~~~~~~~~~~~~~~~
The 'JPEG 2000' image support is implemented using the openjpeg library.

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

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

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

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

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_jp2(const void *buf);
-------------------------------------------------------------------------------

Matches a 'JPEG2000' link:signatures.html[file signature]. Returns non-zero if
found.

[[GIF]]
GIF Loader
~~~~~~~~~~

The 'GIF' image support is implemented using the
link:http://sourceforge.net/projects/giflib/[giflib library].

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

NOTE: Currently this function loads only first image from the 'GIF' container.

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_gif(const void *buf);
-------------------------------------------------------------------------------

Matches a 'GIF' link:signatures.html[file signature]. Returns non-zero if
found.

[[BMP]]
BMP Loader
~~~~~~~~~~

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

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] as a 'BMP' image.

Currently only 8-bit 'RGB' pixel types are supported.

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_bmp(const void *buf);
-------------------------------------------------------------------------------

Matches a 'BMP' link:signatures.html[file signature]. Returns non-zero if
found.

[[TIFF]]
TIFF Loader
~~~~~~~~~~~

The 'TIFF' loader support is done using the
link:http://www.remotesensing.org/libtiff/[tiff library].

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

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] as a 'TIFF' image.

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

The image is saved in stripes.

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_tiff(const void *buf);
-------------------------------------------------------------------------------

Matches a 'TIFF' link:signatures.html[file signature]. Returns non-zero if
found.

[[PSP]]
PSP Loader
~~~~~~~~~~

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

[source,c]
-------------------------------------------------------------------------------
#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
link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_psp(const void *buf);
-------------------------------------------------------------------------------

Matches a 'PSP' link:signatures.html[file signature]. Returns non-zero if
found.

[[PSD]]
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).

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_psd(const void *buf);
-------------------------------------------------------------------------------

Matches a 'PSD' link:signatures.html[file signature]. Returns non-zero if
found.

[[PNM]]
PNM Loaders
~~~~~~~~~~~

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[IO stream] is expected to start exactly at
the file signature.

The resulting link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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'.

[source,c]
-------------------------------------------------------------------------------
#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'.

[source,c]
-------------------------------------------------------------------------------
#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'.

[source,c]
-------------------------------------------------------------------------------
#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'.

[source,c]
-------------------------------------------------------------------------------
#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'
link:signatures.html[file signatures].

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

All functions return non-zero if found.

[[PCX]]
PCX Loader
~~~~~~~~~~

The 'PCX' loader can load ZSoft PCX images.

[source,c]
-------------------------------------------------------------------------------
#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 link:loaders_io.html[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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#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 link:pixmap.html[pixmap] should be later freed with
link:pixmap.html#pixmap_free[gp_pixmap_free()].

[source,c]
-------------------------------------------------------------------------------
#include <loaders/gp_loaders.h>
/* or */
#include <gfxprim.h>

int gp_match_pcx(const void *buf);
-------------------------------------------------------------------------------

Matches a 'PCX' link:signatures.html[file signature]. Returns non-zero if
found.
