\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Libnetpbm manual" 3 "December 2003" "netpbm documentation"

.SH NAME
libnetpbm - general introduction to the netpbm library
.SH DESCRIPTION
.PP
\fBlibnetpbm\fP is a C programming library for reading, writing, and
manipulating Netpbm images.  It also contains a few general graphics
manipulation tools, but it is not intended to be a graphics tools
library.  For graphics tools, Netpbm expects you to run the Netpbm
programs.  From a C program, the \fBlibnetpbm\fP function
\fBpm_system()\fP makes this easy.  However, since it creates a
process and execs a program, this may be too heavyweight for some
applications.
.PP
To use \fBlibnetpbm\fP services in your C program, #include the
\fBpam.h\fP interface header file.  For historical reasons, you can
also get by in some cases with \fBpbm.h\fP, \fBpgm.h\fP,
\fBppm.h\fP, or \fBpnm.h\fP, but there's really no point to that
anymore.
.PP
The \fBlibnetpbm\fP functions are divided into these categories:

.IP \(bu
PBM functions.  These have names that start with \fBpbm\fP and work
only on PBM images.
.IP \(bu
PGM functions.  These have names that start with \fBpgm\fP and work
only on PGM images.
.IP \(bu
PPM functions.  These have names that start with \fBppm\fP and work
only on PPM images.
.IP \(bu
PNM functions.  These have names that start with \fBpnm\fP and work on
PBM, PGM, and PPM images.
.IP \(bu
PAM functions.  These also have names that start with \fBpnm\fP and 
work on all the Netpbm image types.
.IP \(bu
PM functions.  These are utility functions that aren't specific to any
particular image format.

.PP
For new programming, you rarely need to concern yourself with the
PBM, PGM, PPM, and PNM functions, because the newer PAM functions do
the same thing and are easier to use.  For certain processing of
bi-level images, the PBM functions are significantly more efficient,
though.
.PP
\fBlibnetpbm\fP has a backward compatibility feature that means a
function designed to read one format can read some others too,
converting on the fly.  In particular, a function that reads a PGM
image will also read a PBM image, but converts it as it reads it so
that for programming purposes, it is a PGM image.  Similarly, a
function that reads PPM can read PBM and PGM as well.  And a function
that reads PBM, PGM, or PPM can read a PAM that has an equivalent
tuple type.
.PP
For each of the five classes of \fBlibnetpbm\fP image processing
functions, \fBlibnetpbm\fP has in in-memory representation for a
pixel, a row, and a whole image.  Do not confuse this format with the
actual image format, as you would see in a file.  The \fBlibnetpbm\fP
in-memory format is designed to make programming very easy.  It is
sometimes extremely inefficient, even more than the actual image
format.  For example, a pixel that a PPM image represents with 3
bytes, \fBlibnetpbm\fP's PAM functions represent with 16 bytes.  A
pixel in a PBM image is represented by a single bit, but the PNM
functions represent that pixel in memory with 96 bits.
.PP
See
.BR Libnetpbm User's Manual (3)
 for the
basics on using \fBlibnetpbm\fP in a program.
.PP
You can look up the reference information for a particular function
in
.BR The libnetpbm Directory (1)
.
.PP
Before Netpbm release 10 (June 2002), this library was split into
four: libpbm, libpgm, libppm, and libpnm.  That's largely the reason
for the multiple sets of functions and scattered documentation.