home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 344a.lha / Post_v.02 / post.doc.pp / post.doc
Encoding:
Text File  |  1990-02-12  |  12.5 KB  |  395 lines
  1. Postscript interpreter - user documentation
  2. ===========================================
  3.  
  4. Post V0.2 Copyright Adrian Aylward 1989, 1990
  5.  
  6. Free use and non-commercial reproduction of the binaries of this prerelease
  7. is permitted, providing that the copyright notices are not removed.
  8. Distribution by disk libraries is permitted provided only a nominal copying
  9. fee is charged.
  10.  
  11. All other rights are reserved.  For queries and bug reports write to the
  12. author:
  13.  
  14.         Adrian Aylward,
  15.         20 Maidstone Road,
  16.         SWINDON,
  17.         Wiltsire.
  18.         UK.
  19.  
  20. No responsibilities accepted for bugs, but please let me know so I can fix
  21. them.
  22.  
  23. Introduction
  24. ============
  25.  
  26. "Post" is a software based PostScript interpreter, presently running on the
  27. Amiga.  The source code is written in C, and should be fairly portable to
  28. other machines.  It supports the full Adobe language, with only minor
  29. variations.
  30.  
  31. Being a prerelease there will likely be bugs.
  32.  
  33. Command line interface
  34. ======================
  35.  
  36. usage:
  37.     post [files...] [IFF file] [SCREEN] [SIZE xydxy..lhi?] [MEM fhlv..?]
  38.  
  39. The input files
  40. ---------------
  41.  
  42. The interpreter reads the input files in turn.  If none are present, the
  43. standard input is read instead.  (The standard input may also be explicity
  44. read as "%stdin".)  If the input appears to be interactive, prompts will
  45. be displayed.  When the end of the last file is reached, the program exits.
  46.  
  47. Printer output
  48. --------------
  49.  
  50. This is the default if neither the IFF nor SCREEN options are used.  The
  51. oputput is sent to the printer device as a graphic dump.
  52.  
  53. The interpreter will obtain default values for the page size, density, and
  54. number of colors from the current preferences.  If you use the default sizes
  55. make sure you have set the page size: run preferences and on the graphic 2
  56. screen set the width and height limits -  either bounded or absolute or in
  57. pixels.  The output defaults to black and white or 3 colour, according to
  58. the preferences.
  59.  
  60. IFF file output
  61. ---------------
  62.  
  63. This option will send the output to an IFF file.  Each IFF file comtains a
  64. single FORM ILBM.  So that multiple pages may be created in a single run of
  65. the interpreter, sequence nubers are automatically generated:
  66.  
  67.     IFF path/fred*.pic   will generate  path/fred1.pic, path/fred2.pic ...
  68. and IFF path/fred??.pic  will generate  path/fred01.pic, path/fred02.pic ...
  69.  
  70. The default page size etc. is the same as for screen output.
  71.  
  72. SCREEN output
  73. -------------
  74.  
  75. This option  will send the output to a screen.  (Use Amiga/N, Amiga/M to
  76. view it.)  You can generate both screen and IFF output at the same time.
  77.  
  78. The default screen size is the same as the workbench screen, but in
  79. interlace mode.  The default density is 75 pixels per inch.  The default
  80. number of colours is 3.
  81.  
  82. The SIZE option
  83. ---------------
  84.  
  85. The SIZE option sets the page size and density etc..
  86.  
  87.     SIZE "x..y..s..[x]d...[y]d..lhibc.?"
  88.  
  89. The page sizes ("x..y..s..") are in pixels, as decimal numbers; "s" sets
  90. the size of the bands, for band rendering to the printer.  Densities
  91. ([x]d..[y]d..) are in pixels per inch; "xd" or "yd" set the x or y density,
  92. and "d" sets both.
  93.  
  94. The screen resolution is: "l" for low resolution no interlace, "h" for high
  95. resolution no interlace, and "i" for high resolution interlaced.
  96.  
  97. The number of colours is: "b" for black and white (1 bit plane), "c" or "c3"
  98. for 3 colour rgb (3 bit planes), and "c4" for 4 colour cmyk (4 bit planes).
  99.  
  100. To verify the sizes, type SIZE "?".
  101.  
  102. The MEM option
  103. --------------
  104.  
  105. The MEM option controls the amount of memory allocated for workspace.
  106.  
  107. The memory defaults are chosen to suit a large machine processing relatively
  108. complex pages.  For simple screen output much lower minimums are possible -
  109. if you don't have enough memory on your machine try the small values
  110. instead.
  111.  
  112.     Default   Small
  113.     -------   -----
  114.     v280000  (40000)     Virtual machine memory
  115.      f60000   (1000)     Font cache
  116.      l60000   (8000)     Line drawing and image workspace
  117.      h20000   (1000)     Halftone buffer
  118.  
  119.      (x + 32) * y / 8    Page buffer
  120.  
  121. At the one extreme it should be possible to generate simple screen output
  122. using the small values on 512K machine, whereas the default values for a
  123. complex A4 page at 300 dpi. should fit on a machine with 2 megabytes.  If
  124. you include "?" the interpreter will tell you the sizes it is using.
  125.  
  126. Compatability
  127. =============
  128.  
  129. The interpreter is based upon the language (version "23.0") as described by
  130. the book:
  131.  
  132.     "PostScript Language Reference Manual"
  133.     Adobe Systems Incorporated,
  134.     Addison-Wesley 1985, ISBN 0-201-10174-2
  135.  
  136. File handling
  137. -------------
  138.  
  139. The files %stdin, %stdout, %stderr are permanently open as far as the
  140. operating system is concerned.  Attempts to close them will invalidate the
  141. file object but not close them to the operating system.  If they are
  142. connected to a terminal they will be unbuffered, so output will be
  143. transmitted immediately, without waiting for a "flush".  The special files
  144. %statementedit and %lineedit are not supported.
  145.  
  146. Error handling
  147. --------------
  148.  
  149. A new error "invalidstop" has been added.
  150.  
  151. The execution stack
  152. -------------------
  153.  
  154. The exact contents of the execution stack are not defined by the language
  155. reference manual, and cannot therefore be guaranteed to be the same as other
  156. implementations.  Dumping the stack is likely to yield useful debugging
  157. information but is not recommended for normal programming.
  158.  
  159. Colour mapping
  160. --------------
  161.  
  162. The interpreter can run with one bit plane (for black and white printers),
  163. 3 bit planes (red, green, blue) or 4 bit planes (cyan, magenta, yellow,
  164. black).  For screen output 3 bit planes are appropiate.  For a colour
  165. printer the 3 or 4 colour model can be used.  The output is always in
  166. binary; gray scale is supported only via the halftone mechanism.
  167.  
  168. For low resolution colour printers the 3 colour model is probably best.
  169. The 4 color model is for high resolution colour printers that can generate
  170. high frequency halftone screens, where a fourth screen is used to improve
  171. the quality of the blacks and grays.
  172.  
  173. (N.B. the preferences printer drivers only handle 3 colour model, so if
  174. you want to use the 4 colour model you will probably need to generate an
  175. IFF file and write your own print dump program.  They will however
  176. automatically use black the ribbon/ink if the printer has one)
  177.  
  178. The transformations between the RGB and the HSB models are based on those in
  179. the book:
  180.  
  181.     "Procedural Elements for Computer Graphics"
  182.     David F. Rogers,
  183.     McGraw-Hill 1985, ISBN 0-E07-053534-5.
  184.  
  185. Band Rendwring
  186. --------------
  187.  
  188. For a high resolution printer the page buffer can be quite large (a megabyte
  189. or so).  If you don't have enough memory to hold the entire page at once you
  190. can render each one in several bands.  Set the "SIZE s..." option to the
  191. largest band size you have space for.  (For matrix printers it will probably
  192. be best to make it a multiple of the number of printer pins times the number
  193. of vertically displaced passes).  Then run the postscript program generating
  194. each page once for each band, using the "setband" operator, which is
  195. described below, to set the base for each band.  Start at a base of zero
  196. and increment the base by the band size until you reach the page height.
  197. Each band is sent to the printer as a separate graphic dump; the last band
  198. generates a form feed to eject the page.  You can use the "currentband"
  199. operator to calculate the number of bands needed:
  200.  
  201.     currentband 1 sub { setband pageproc } for 0 setband
  202.  
  203. will execute "pageproc" once for each band (remaining) on the page.  The
  204. procedure should execute copypage (or showpage) exactly once per iteration.
  205.  
  206. N.B. this technique is only suitable for printer output.
  207.  
  208. Fonts
  209. -----
  210.  
  211. There are no fonts built in to the interpreter; they must all be downloaded.
  212. The findfont operator will execute the error invalidfont if the font you
  213. request is not present in the font dictionary.  You can redefine it, perhaps
  214. to search the Unix/Amiga filing system to automatically download fonts or to
  215. substitute a default font.
  216.  
  217. The font caching will work significantly better if all your fonts have
  218. UniqueID's.  Then repeated makes of the same font with the same matrix will
  219. be cached, and cached character bitmaps can be retained even if the font
  220. is removed by a restore operation.  N.B. if fonts are downloaded after a
  221. save they will be removed by the corresponding restore; in the interests of
  222. efficiency it may therefore be better to preload them.
  223.  
  224. Operators omitted or changed
  225. ----------------------------
  226.  
  227.     banddevice
  228.  
  229. Not appropiate for the Unix/Amiga environment.
  230.  
  231.     bytesavailable
  232.  
  233. Since we can't tell how many bytes are available we always return -1.
  234.  
  235.     copypage
  236.  
  237. For printer output this works like the standard.  For screen output it
  238. does not need to do anything, as the screen is not buffered.  Use Amiga/n
  239. and Amiga/m to view the screen and to return to the workbench screen.  If
  240. you want to add a pause to view the results, redefine the operator to add
  241. one.  For IFF file output it writes the page to the next file.
  242.  
  243.     echo
  244.  
  245. Not appropiate for the Unix/Amiga environment.
  246.  
  247.     executive
  248.  
  249. There is no executive, as the interpreter supports interactive usage
  250. directly.
  251.  
  252.     findfont
  253.  
  254. Looks in the FontDirectory.  If it can't find the supplied key, it exeuctes
  255. the error invalidfont.
  256.  
  257.     flushfile
  258.  
  259. We don't check for errors when flushing an input file, to prevent recursion
  260. in the error handler.
  261.  
  262.     framedevice
  263.  
  264. Not appropiate for the Unix/Amiga environment.
  265.  
  266.     prompt
  267.  
  268. Not called by the interpreter.  See "prompts" instead.
  269.  
  270.     renderbands
  271.  
  272. Not appropiate for the Unix/Amiga environment.
  273.  
  274.     resetfile
  275.  
  276. Does nothing.
  277.  
  278.     showpage
  279.  
  280. See the notes for copypage above.
  281.  
  282.     start
  283.  
  284. Not used.  Write your own startup file if you want one.
  285.  
  286.     usertime
  287.  
  288. Returns the time elapsed since the interpreter started, with a resolution of
  289. one second.
  290.  
  291. Operators added
  292. ---------------
  293.  
  294.     currentband
  295.  
  296.         "currentband" base size height
  297.  
  298. Returns the base of the current band, size of each band, and total height
  299. of the page.
  300.  
  301.     setband
  302.  
  303.         base "setband"
  304.  
  305. Sets the base height of the band being rendered.  The value must be greater
  306. than or equal to zero and less than the total height of the page.
  307.  
  308.     invalidstop
  309.  
  310.         (error)
  311.  
  312. A "stop" has been executed for which there is no dynamically enclosing
  313. "stopped" context.
  314.  
  315.     prompts
  316.  
  317.         string string "prompts"
  318.  
  319. The first string is used as the prompt when the interpreter is scanning
  320. terminal input and executing it immediately; the second string is used when
  321. execution is defered while scanning the contents of a procedure "{ ... }".
  322. No prompt is given when a newline is encountered within a string.
  323.  
  324.     vmhwm
  325.  
  326.         "vmhwm" hwmused maximum
  327.  
  328. Returns two integers: the high water mark of the amount virtual memory used
  329. since the program was first started or the last "vmhwm", and the maximum
  330. available amount of memory.
  331.  
  332. Colour operators not in the red book
  333. ------------------------------------
  334.  
  335. The Adobe 4 colour operators are supported:
  336.  
  337.     colorimage
  338.     currentblackgeneration
  339.     currentcmykcolor
  340.     currentcolorscreen
  341.     currentcolortransfer
  342.     currentundercolorremoval
  343.     setblackgeneration
  344.     setcmykcolor
  345.     setcolorscreen
  346.     setcolortransfer
  347.     setundercolorremoval
  348.  
  349. Miscellaneous
  350. -------------
  351.  
  352. The system dictionary is left writeable so that standard preludes can add
  353. things to it - possibly removing write permission when they have finished.
  354.  
  355. Device space
  356. ------------
  357.  
  358. The largest device that the interpreter can handle is 31767 (sic.) by 32767
  359. pixels.  In practice you will probably run out of memory long before
  360. reaching this limit.
  361.  
  362. Versions
  363. ========
  364.  
  365.     V0.0  14-Nov-89 (prerelease)
  366.  
  367. The original.
  368.  
  369.     V0.1  06-Dec-89 (prerelease)
  370.  
  371. Image routines added.
  372.  
  373. Range checks eased on gray levels and colours etc..
  374.  
  375. Area filling speeded up, matrix manipulation and colour mapping rewritten,
  376. numeric conditioning improved for path fill.
  377.  
  378. Bugs fixed: syntax error, == string escapes, error handling and quit when
  379. recursing, vm error handling, integer overflow in path fill, matrix save,
  380. interrupt after printing page, dictionary second save, name table restore,
  381. boolean type checking, multiple halftone screens memory allocation.
  382.  
  383.     V0.2  07-Jan-90 (prerelease)
  384.  
  385. Font and character routines added.  Null device added.  Band rendering of
  386. printer output added.
  387.  
  388. Matrix manipulation rewritten again.  Interpreter recursion rewritten.
  389. Allocate stacks dynamically.
  390.  
  391. Bugs fixed: missing access checks on strings, scan token negative chars,
  392. depth check in path flattening, pathbbox, strings or null objects as
  393. dictionary keys, shade after grestore(all), fill/image with clip region,
  394. clip unclosed subpath, dictstack/execstack.
  395.