.TH libpnm 3
.SH NAME
libpnm - functions to support portable anymap programs
.SH SYNOPSIS
.de Ss
.sp
.ft CW
.nf
..
.de Se
.fi
.ft P
.sp
..
.Ss
#include <pnm.h>
cc ... libpnm.a libppm.a libpgm.a libpbm.a
.Se
.SH DESCRIPTION
.SS TYPES AND CONSTANTS
.Ss
typedef ... xel;
typedef ... xelval;
#define PNM_MAXMAXVAL ...
extern xelval pnm_pbmmaxval;
.Se
Each
.BR xel
contains three
.BR xelval s,
each of which should contain only the values between
.BR 0
and
.BR PNM_MAXMAXVAL .
.BR pnm_pbmmaxval
is the maxval used when a PNM program reads a PBM file.
Normally it is 1; however, for some programs, a larger value gives better
results.
.SS XEL MANIPULATIONS
.Ss
xelval PNM_GET1( xel x )
.Se
This macro extracts a single value from an xel, when you know it's
from a PBM or PGM file.
When it's from a PPM file, use
.BR PPM_GETR() ,
.BR PPM_GETG() ,
and
.BR PPM_GETB() .
.Ss
void PNM_ASSIGN1( xel x, xelval v )
.Se
This macro assigns a single value to an xel, when you know it's
from a PBM or PGM file.
When it's from a PPM file, use
.BR PPM_ASSIGN() .
.Ss
int PNM_EQUAL( xel x, xel y )
.Se
This macro checks two xels for equality.
.Ss
int PNM_FORMAT_TYPE( int format )
.Se
For distinguishing different file types.
.SS INITIALIZATION
.Ss
void pnm_init( int* argcP, char* argv[] )
.Se
All PNM programs must call this routine.
.SS MEMORY MANAGEMENT
.Ss
xel** pnm_allocarray( int cols, int rows )
.Se
Allocate an array of xels.
.Ss
xel* pnm_allocrow( int cols )
.Se
Allocate a row of the given number of xels.
.Ss
void pnm_freearray( xel** xels, int rows )
.Se
Free the array allocated with
.BR pnm_allocarray()
containing the given number
of rows.
.Ss
void pnm_freerow( xel* xelrow )
.Se
Free a row of xels.
.SS READING FILES
.Ss
void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )
.Se
Read the header from a PNM file, filling in the rows, cols, maxval and format
variables.
.Ss
void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format )
.Se
Read a row of xels into the xelrow array.
Format, cols, and maxval were filled in by
.BR pnm_readpnminit() .
.Ss
xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )
.Se
Read an entire anymap file into memory, returning the allocated array and
filling in the rows, cols, maxval, and format variables.
This function combines
.BR pnm_readpnminit() ,
.BR pnm_allocarray()
and
.BR pnm_readpnmrow() .
Unlike the equivalent functions in PBM, PGM, and PPM, it returns the format
so you can tell what type the file is.
.SS WRITING FILES
.Ss
void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxval, int format, int forceplain )
.Se
Write the header for a portable anymap file.
Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify
the output type.
The forceplain flag forces a plain-format file to be written, as opposed
to a raw-format one.
.Ss
void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, int forceplain )
.Se
Write a row from a portable anymap.
.Ss
void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, int forceplain )
.Se
Write the header and all data for a portable anymap.
This function combines
.BR pnm_writepnminit()
and
.BR pnm_writepnmrow() .
.SS FORMAT PROMOTION
.Ss
void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval newmaxval, int newformat )
.Se
Promote a row of xels from one maxval and format to a new set.
Used when combining multiple anymaps of different types - just
take the max of the maxvals and the max of the formats, and
promote them all to that.
.Ss
void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, int format, xelval newmaxval, int newformat )
.Se
Promote an entire anymap.
.SS XEL MANIPULATION
.Ss
xel pnm_whitexel( xelval maxval, int format )
xel pnm_blackxel( xelval maxval, int format )
.Se
Return a white or black xel for the given maxval and format.
.Ss
void pnm_invertxel( xel* x, xelval maxval, int format )
.Se
Invert an xel.
.Ss
xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format )
.Se
Figure out an appropriate background xel based on this row.
.Ss
xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, int format )
.Se
Figure out a background xel based on an entire anymap.
This can do a slightly better job than
.BR pnm_backgroundxelrow() .
.SH "SEE ALSO"
pbm(3), pgm(3), ppm(3)
.SH AUTHOR
Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
.\" Permission to use, copy, modify, and distribute this software and its
.\" documentation for any purpose and without fee is hereby granted, provided
.\" that the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.  This software is provided "as is" without express or
.\" implied warranty.