home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / NETWORK / netpbm_src.lzh / NETPBM / PNM / libpnm.3 < prev    next >
Text File  |  1996-11-18  |  5KB  |  177 lines
  1. .TH libpnm 3
  2. .SH NAME
  3. libpnm - functions to support portable anymap programs
  4. .SH SYNOPSIS
  5. .de Ss
  6. .sp
  7. .ft CW
  8. .nf
  9. ..
  10. .de Se
  11. .fi
  12. .ft P
  13. .sp
  14. ..
  15. .Ss
  16. #include <pnm.h>
  17. cc ... libpnm.a libppm.a libpgm.a libpbm.a
  18. .Se
  19. .SH DESCRIPTION
  20. .SS TYPES AND CONSTANTS
  21. .Ss
  22. typedef ... xel;
  23. typedef ... xelval;
  24. #define PNM_MAXMAXVAL ...
  25. extern xelval pnm_pbmmaxval;
  26. .Se
  27. Each
  28. .BR xel
  29. contains three
  30. .BR xelval s,
  31. each of which should contain only the values between
  32. .BR 0
  33. and
  34. .BR PNM_MAXMAXVAL .
  35. .BR pnm_pbmmaxval
  36. is the maxval used when a PNM program reads a PBM file.
  37. Normally it is 1; however, for some programs, a larger value gives better
  38. results.
  39. .SS XEL MANIPULATIONS
  40. .Ss
  41. xelval PNM_GET1( xel x )
  42. .Se
  43. This macro extracts a single value from an xel, when you know it's
  44. from a PBM or PGM file.
  45. When it's from a PPM file, use
  46. .BR PPM_GETR() ,
  47. .BR PPM_GETG() ,
  48. and
  49. .BR PPM_GETB() .
  50. .Ss
  51. void PNM_ASSIGN1( xel x, xelval v )
  52. .Se
  53. This macro assigns a single value to an xel, when you know it's
  54. from a PBM or PGM file.
  55. When it's from a PPM file, use
  56. .BR PPM_ASSIGN() .
  57. .Ss
  58. int PNM_EQUAL( xel x, xel y )
  59. .Se
  60. This macro checks two xels for equality.
  61. .Ss
  62. int PNM_FORMAT_TYPE( int format )
  63. .Se
  64. For distinguishing different file types.
  65. .SS INITIALIZATION
  66. .Ss
  67. void pnm_init( int* argcP, char* argv[] )
  68. .Se
  69. All PNM programs must call this routine.
  70. .SS MEMORY MANAGEMENT
  71. .Ss
  72. xel** pnm_allocarray( int cols, int rows )
  73. .Se
  74. Allocate an array of xels.
  75. .Ss
  76. xel* pnm_allocrow( int cols )
  77. .Se
  78. Allocate a row of the given number of xels.
  79. .Ss
  80. void pnm_freearray( xel** xels, int rows )
  81. .Se
  82. Free the array allocated with
  83. .BR pnm_allocarray()
  84. containing the given number
  85. of rows.
  86. .Ss
  87. void pnm_freerow( xel* xelrow )
  88. .Se
  89. Free a row of xels.
  90. .SS READING FILES
  91. .Ss
  92. void pnm_readpnminit( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )
  93. .Se
  94. Read the header from a PNM file, filling in the rows, cols, maxval and format
  95. variables.
  96. .Ss
  97. void pnm_readpnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format )
  98. .Se
  99. Read a row of xels into the xelrow array.
  100. Format, cols, and maxval were filled in by
  101. .BR pnm_readpnminit() .
  102. .Ss
  103. xel** pnm_readpnm( FILE* fp, int* colsP, int* rowsP, xelval* maxvalP, int* formatP )
  104. .Se
  105. Read an entire anymap file into memory, returning the allocated array and
  106. filling in the rows, cols, maxval, and format variables.
  107. This function combines
  108. .BR pnm_readpnminit() ,
  109. .BR pnm_allocarray()
  110. and
  111. .BR pnm_readpnmrow() .
  112. Unlike the equivalent functions in PBM, PGM, and PPM, it returns the format
  113. so you can tell what type the file is.
  114. .SS WRITING FILES
  115. .Ss
  116. void pnm_writepnminit( FILE* fp, int cols, int rows, xelval maxval, int format, int forceplain )
  117. .Se
  118. Write the header for a portable anymap file.
  119. Unlike the equivalent functions in PBM, PGM, and PPM, you have to specify
  120. the output type.
  121. The forceplain flag forces a plain-format file to be written, as opposed
  122. to a raw-format one.
  123. .Ss
  124. void pnm_writepnmrow( FILE* fp, xel* xelrow, int cols, xelval maxval, int format, int forceplain )
  125. .Se
  126. Write a row from a portable anymap.
  127. .Ss
  128. void pnm_writepnm( FILE* fp, xel** xels, int cols, int rows, xelval maxval, int format, int forceplain )
  129. .Se
  130. Write the header and all data for a portable anymap.
  131. This function combines
  132. .BR pnm_writepnminit()
  133. and
  134. .BR pnm_writepnmrow() .
  135. .SS FORMAT PROMOTION
  136. .Ss
  137. void pnm_promoteformatrow( xel* xelrow, int cols, xelval maxval, int format, xelval newmaxval, int newformat )
  138. .Se
  139. Promote a row of xels from one maxval and format to a new set.
  140. Used when combining multiple anymaps of different types - just
  141. take the max of the maxvals and the max of the formats, and
  142. promote them all to that.
  143. .Ss
  144. void pnm_promoteformat( xel** xels, int cols, int rows, xelval maxval, int format, xelval newmaxval, int newformat )
  145. .Se
  146. Promote an entire anymap.
  147. .SS XEL MANIPULATION
  148. .Ss
  149. xel pnm_whitexel( xelval maxval, int format )
  150. xel pnm_blackxel( xelval maxval, int format )
  151. .Se
  152. Return a white or black xel for the given maxval and format.
  153. .Ss
  154. void pnm_invertxel( xel* x, xelval maxval, int format )
  155. .Se
  156. Invert an xel.
  157. .Ss
  158. xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format )
  159. .Se
  160. Figure out an appropriate background xel based on this row.
  161. .Ss
  162. xel pnm_backgroundxel( xel** xels, int cols, int rows, xelval maxval, int format )
  163. .Se
  164. Figure out a background xel based on an entire anymap.
  165. This can do a slightly better job than
  166. .BR pnm_backgroundxelrow() .
  167. .SH "SEE ALSO"
  168. pbm(3), pgm(3), ppm(3)
  169. .SH AUTHOR
  170. Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer.
  171. .\" Permission to use, copy, modify, and distribute this software and its
  172. .\" documentation for any purpose and without fee is hereby granted, provided
  173. .\" that the above copyright notice appear in all copies and that both that
  174. .\" copyright notice and this permission notice appear in supporting
  175. .\" documentation.  This software is provided "as is" without express or
  176. .\" implied warranty.
  177.