home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1996 / ARCHIVE_96.iso / discs / mag_discs / volume_8 / issue_06 / risc_os / OldPDriver < prev    next >
Text File  |  1988-11-29  |  65KB  |  1,463 lines
  1. This document is intended to tell application authors how to write their
  2. applications so as to make use of the standard RISC OS printer driver
  3. interface. It starts with a general explanation of how the printer drivers
  4. are supposed to be used. Then the SWI interface is described and an example
  5. BASIC procedure is given that shows an application might do its printing. The
  6. final section of the document specifies exactly what VDU sequences and other
  7. plotting operations the application may use while printing.
  8.  
  9.  
  10.  
  11. PRINTER DRIVER PHILOSOPHY
  12. =========================
  13.  
  14.  
  15. What the application user sees
  16. ------------------------------
  17.  
  18. RISC OS comes with two printer driver applications, !PSPrinter for PostScript
  19. printers and !DMPrinter for a range of dot matrix printers.
  20.  
  21. If I possess a PostScript printer and I wish to print, I should do the
  22. following:
  23.  
  24. Double-click on !PSPrinter. An icon will appear. Menu on this and check
  25. that the settings are right for where the printer is connected, e.g.
  26. net/parallel/serial etc. This setting will be retained in CMOS RAM, so it
  27. need only be done once.
  28.  
  29. If I wish to print Text files, drag them onto the printer icon. They will get
  30. printed.
  31.  
  32. If I wish to print from ArcDraw, click Print on the Print dialogue box after
  33. running !PSPrinter. The diagram will be printed. Or, drag the icon from the
  34. Save dialogue box onto the printer icon.
  35.  
  36. If I wish to print from ArcPaint, it's exactly the same.
  37.  
  38. If I with to print from any other editor program, it's exactly the same.
  39.  
  40. If I have a dot matrix printer, run !DMPrinter. Click on the printer icon to
  41. produce a dialogue box of the correct type of printer. Click on the
  42. printer-type field to cycle through the various dot matrix printers
  43. supported, until it reflects mine. If I can't find mine, seek help.
  44.  
  45. Drivers for other printers will appear, from Acorn and from others, in an
  46. analogous form. New printer drivers will work with all existing applications,
  47. subject to the limitations of any particular printing device.
  48.  
  49.  
  50. How and Why
  51. -----------
  52.  
  53. I use the term "editor" to mean any sort of interactive program that
  54. prepares, changes and processes data files. This includes word processors,
  55. DTP packages, spreadsheets, draw programs, etc. I use the term "Foo" to refer
  56. to any editor program, which operates on "Foo data files": so, substitute
  57. ArcDraw, ArcPaint, or whatever as you read. I use the term "Poo" to refer to
  58. any printer capable of generating graphics, e.g. FX80, Apple LaserWriter,
  59. etc.
  60.  
  61. In the general case, editors save data in files of their own format, with an
  62. appropriate file type. Only Foo understands Foo data files. Also, different
  63. printers are entirely different from each other, and a pain to drive. If each
  64. editor is to understand each printer, and there are X editors and Y printers
  65. in the world, then:
  66.  
  67.   (a) There is X*Y work to do
  68.   (b) If a new printer type comes along, all applications need updating.
  69.  
  70. Because of this, RISC OS separates printer drivers from editors so that they
  71. are separate programs. This means:
  72.  
  73.   (a) There is X+Y work to do
  74.   (b) If a new printer type comes along, once a printer driver has been
  75.       written for it, it will work with all applications.
  76.  
  77. This is clearly a better situation, and is one of the main reasons why
  78. applications working together is important.
  79.  
  80. How do we achieve this? The main step is to define an interface that all
  81. editors should use when talking to printers, a sort of "virtual printer
  82. interface". All editors then output to this virtual interface, knowing little
  83. of the characteristics of the physical printer itself.
  84.  
  85. The "virtual printer interface" chosen in RISC OS is to say that the printer
  86. supports a specified subset of the screen graphics primitives. This is
  87. because a WYSIWYG editor (where what you see on the screen is what you get on
  88. paper) will already contain code to render the data file using screen
  89. primitives; provided the application restricts itself to the specified
  90. subset, printing is unlikely to require very much extra code.
  91.  
  92. There are several reasons why not all the screen primitives are supported by
  93. the virtual printer interface. The main ones are:
  94.  
  95.   (a) Some screen primitives are screen hardware specific (e.g. flashing
  96.       colours, hardware palette changes, etc.).
  97.   (b) Some screen primitives are very hard or impossible to implement on
  98.       common types of printer (e.g. PostScript printers cannot handle
  99.       non-overwriting GCOL actions).
  100.   (c) Some screen primitives - e.g. flood fill - cannot be split across
  101.       multiple boxes and so do not work with the window system. The printer
  102.       drivers use a similar interface to the window system and have the same
  103.       problems with these calls as it does.
  104.  
  105. Each printer driver is implemented as a RISC OS relocatable module, which
  106. provides extra SWIs (system calls) concerned with starting, stopping and
  107. controlling a print job. The interface allows the printer driver to ask the
  108. application to render specific rectangles of the picture in any order, to
  109. give the printer driver maximum freedom in manipulating buffer space, etc.
  110.  
  111. The interface to printer drivers means that an editor is not able to supply
  112. an acceptable user interface for setting printer-specific options such as
  113. quality/draft mode. For this reason, a separate application exists for each
  114. possible printer driver, to allow any printer-specific options to be set.
  115.  
  116. The printing of plain text is such a basic facility that it is considered
  117. unacceptable to require the loading of ArcEdit. Furthermore, printers tend to
  118. provide a much simpler method for the printing of simple text than the
  119. facilities provided for arbitrary graphics. For this reason, every printer
  120. interface program provides simple facilities for the printing of plain text
  121. files.
  122.  
  123.  
  124.  
  125. THE SWI INTERFACE
  126. =================
  127.  
  128.  
  129. To send output to the printer, an application must engage in a dialogue with
  130. the printer driver. Parts of this dialogue is similar to the dialogue with
  131. the window manager when a window requires redrawing. The dialogue can be
  132. summarised as follows:
  133.  
  134. The application starts by opening a file to receive the printer driver's
  135. output. Typically this file is "printer:", but any file may be used. It
  136. passes this file's handle to SWI PDriver_SelectJob in order to start a print
  137. job.
  138.  
  139. To output a page, the application then uses SWI PDriver_GiveRectangle to give
  140. the printer driver a list of the rectangles it wants to appear on the page
  141. and where it wants them to appear.
  142.  
  143. When it has specified all the rectangles it wants printed, it uses SWI
  144. PDriver_DrawPage to ask the printer driver for the first rectangle to be
  145. printed. It then prints this rectangle and uses SWI PDriver_GetRectangle to
  146. get another rectangle to print, until there are no further rectangles to
  147. print. This is very similar to the way an application uses SWI
  148. Wimp_RedrawWindow and SWI Wimp_GetRectangle when redrawing its window.
  149.  
  150. When all the desired pages have been output in this manner, the application
  151. first uses SWI PDriver_EndJob to end the print job, then closes the output
  152. file.
  153.  
  154. The full set of printer driver SWIs is as follows:
  155.  
  156.  
  157. SWI PDriver_Info (&80140)
  158. -------------------------
  159.  
  160.   Entry: -
  161.  
  162.   Exit:  R0 (top 16 bits) identifies general type of printer driven.
  163.             Current assignments:
  164.               0 = PostScript printers.
  165.               1 = FX80 and similar dot matrix printers.
  166.          R0 (bottom 16 bits) = 100 * version number of printer driver.
  167.          R1 = X pixel resolution of printer driven (pixels/inch).
  168.          R2 = Y pixel resolution of printer driven (pixels/inch).
  169.          R3 = features word:
  170.               Bit 0 set => colour
  171.               If bit 0 set, bit 1 set => full colour range not available.
  172.               Bit 2 set => only a discrete set of colours supported.
  173.               Bit 8 set => cannot handle filled shapes well.
  174.               Bit 9 set => cannot handle thick lines well.
  175.               Bit 10 set => cannot handle overwriting well.
  176.               Bit 24 set => supports the PDriver_ScreenDump call.
  177.               Bit 25 set => supports arbitrary transformations (else only
  178.                             axis-preserving ones).
  179.          R4 -> adjectival description of printers supported (a maximum of 20
  180.               characters, excluding the zero-termination).
  181.          R5 = X halftone resolution (repeats/inch). If no halftoning is done,
  182.               this is equal to the value returned in R1.
  183.          R6 = Y halftone resolution (repeats/inch). If no halftoning is done,
  184.               this is equal to the value returned in R2.
  185.          R7 identifies a specific configured printer. Assignments of these
  186.               numbers are specific to each printer driver.
  187.  
  188. Some of these values can be changed by the configuration application
  189. associated with the printer driver (using SWI PDriver_SetInfo). If SWI
  190. PDriver_Info is called while a print job is selected, the values returned are
  191. those that were in effect when that print job was started (i.e. when it was
  192. first selected using PDriver_SelectJob). If SWI PDriver_Info is called when
  193. no print job is active, the values returned are those that would be used for
  194. a new print job.
  195.  
  196.  
  197. SWI PDriver_SetInfo (&80141)
  198. ----------------------------
  199.  
  200.   Entry: R1 = X pixel resolution of printer driven (pixels/inch).
  201.          R2 = Y pixel resolution of printer driven (pixels/inch).
  202.          R3 (bit 0) is zero to set monochrome, 1 to set colour. The other
  203.               bits of R3 are ignored.
  204.          R5 = X halftone resolution (repeats/inch). If no halftoning is to be
  205.               done, this should be equal to the value in R1.
  206.          R6 = Y halftone resolution (repeats/inch). If no halftoning is to be
  207.               done, this should be equal to the value in R2.
  208.          R7 identifies a specific configured printer.
  209.  
  210.   Exit:  -
  211.  
  212. The configuration application associated with a particular printer driver
  213. uses this SWI to change the information values associated with subsequent
  214. print jobs. No other application should use this SWI.
  215.  
  216.  
  217. SWI PDriver_CheckFeatures (&80142)
  218. ----------------------------------
  219.  
  220.   Entry: R0 = features word mask.
  221.          R1 = features word value.
  222.  
  223.   Exit:  If the features word that PDriver_Info would return in R3 satisfies
  224.          ((features word) AND R0) = (R1 AND R0), return is normal with all
  225.          registers preserved. Otherwise a suitable error is generated, if
  226.          appropriate - e.g. no error will be generated if the printer driver
  227.          has the ability to support arbitrary rotations and your features
  228.          word value merely requests axis-preserving ones.
  229.  
  230. This call may be used by an application to check that the current printer
  231. driver has the features it requires, and to generate a suitable descriptive
  232. error if it doesn't.
  233.  
  234.  
  235. SWI PDriver_PageSize (&80143)
  236. -----------------------------
  237.  
  238.   Entry: -
  239.  
  240.   Exit:  R1 = X size of paper, including margins. (Units 1/72000 inch)
  241.          R2 = Y size of paper, including margins. (Units 1/72000 inch)
  242.          R3 = left edge of printable area of paper, relative to the left edge
  243.               of the paper. (Units 1/72000 inch)
  244.          R4 = bottom edge of printable area of paper, relative to the bottom
  245.               edge of the paper. (Units 1/72000 inch)
  246.          R5 = right edge of printable area of paper, relative to the left
  247.               edge of the paper. (Units 1/72000 inch)
  248.          R6 = top edge of printable area of paper, relative to the bottom
  249.               edge of the paper. (Units 1/72000 inch)
  250.  
  251. An application can use this call to find out how big the paper in use is and
  252. how large the printable area on the paper is. This information can then be
  253. used to decide how to place the data to be printed on the page.
  254.  
  255. These values can be changed by the configuration application associated with
  256. the printer driver (using SWI PDriver_SetPageSize). If SWI PDriver_PageSize
  257. is called while a print job is selected, the values returned are those that
  258. were in effect when that print job was started (i.e. when it was first
  259. selected using PDriver_SelectJob). If SWI PDriver_PageSize is called when no
  260. print job is active, the values returned are those that would be used for a
  261. new print job.
  262.  
  263.  
  264. SWI PDriver_SetPageSize (&80144)
  265. --------------------------------
  266.  
  267.   Entry: R1 = X size of paper, including margins. (Units 1/72000 inch)
  268.          R2 = Y size of paper, including margins. (Units 1/72000 inch)
  269.          R3 = left edge of printable area of paper, relative to the left edge
  270.               of the paper. (Units 1/72000 inch)
  271.          R4 = bottom edge of printable area of paper, relative to the bottom
  272.               edge of the paper. (Units 1/72000 inch)
  273.          R5 = right edge of printable area of paper, relative to the left
  274.               edge of the paper. (Units 1/72000 inch)
  275.          R6 = top edge of printable area of paper, relative to the bottom
  276.               edge of the paper. (Units 1/72000 inch)
  277.  
  278.   Exit:  -
  279.  
  280. The configuration application associated with a particular printer driver
  281. uses this SWI to change the page size values associated with subsequent print
  282. jobs. No other application should use this SWI.
  283.  
  284.  
  285. SWI PDriver_SelectJob (&80145)
  286. ------------------------------
  287.  
  288.   Entry: R0 = file handle for print job to be selected, or zero to cease
  289.               having any print job selected.
  290.          R1 is zero or points to a title string for the job. This title
  291.               string is terminated by any character outside the range ASCII
  292.               32-126.
  293.  
  294.   Exit:  R0 = file handle for print job that was previously active, or zero
  295.               if no print job was active.
  296.  
  297. A print job is identified by a file handle, which must be that of a file that
  298. is open for output. The printer output for the job concerned is sent to this
  299. file.
  300.  
  301. Calling SWI PDriver_SelectJob with R0=0 will cause the current print job (if
  302. any) to be suspended, and the printer driver will cease intercepting plotting
  303. calls.
  304.  
  305. Calling SWI PDriver_SelectJob with R0 containing a file handle will cause the
  306. current print job (if any) to be suspended, and a print job with the given
  307. file handle to be selected. If a print job with this file handle already
  308. exists, it is resumed; otherwise a new print job is started. The printer
  309. driver will start to intercept plotting calls if it is not already doing so.
  310.  
  311. Note that this call never ends a print job - to do so, use one of SWI
  312. PDriver_EndJob and SWI PDriver_AbortJob.
  313.  
  314. The title string pointed to by R1 is treated by different printer drivers in
  315. different ways. It is only ever used if a new print job is being started, not
  316. when an old one is being resumed. Typical uses are:
  317.  
  318.   (a) A simple printer driver might ignore it.
  319.   (b) The PostScript printer driver adds a line "%%Title: " followed by the
  320.       given title string to the PostScript header it generates.
  321.   (c) Printer drivers whose output is destined for an expensive central
  322.       printer in a large organisation might use it when generating a cover
  323.       sheet for the document.
  324.  
  325. An application is always entitled not to supply a title (by setting R1=0),
  326. and a printer driver is entitled to ignore any title supplied.
  327.  
  328. Printer drivers may also use the following OS variables when creating cover
  329. sheets, etc.:
  330.  
  331.   PDriver$For     - indicates who the output is intended to go to.
  332.   PDriver$Address - indicates where to send the output.
  333.  
  334. These variables should not contain characters outside the range ASCII 32-126.
  335.  
  336. If an error occurs during PDriver_SelectJob, the previous job will still be
  337. selected afterwards (though it may have been de-selected and re-selected
  338. during the call).
  339.  
  340.  
  341. SWI PDriver_CurrentJob (&80146)
  342. -------------------------------
  343.  
  344.   Entry: -
  345.  
  346.   Exit:  R0 = file handle for print job that is currently active, or zero if
  347.               no print job is active.
  348.  
  349.  
  350. SWI PDriver_FontSWI (&80147)
  351. ----------------------------
  352.  
  353. This SWI is part of the internal interface between the font system and
  354. printer drivers. Applications should not call it.
  355.  
  356.  
  357. SWI PDriver_EndJob (&80148)
  358. ---------------------------
  359.  
  360.   Entry: R0 = file handle for print job to be ended.
  361.  
  362.   Exit:  -
  363.  
  364. This SWI should be used to end a print job normally. This may result in
  365. further printer output - e.g. the PostScript printer driver will produce the
  366. standard trailer comments.
  367.  
  368. If the print job being ended is the currently active one, there will be no
  369. current print job after this call (so plotting calls will no longer be
  370. intercepted).
  371.  
  372. If the print job being ended is not currently active, it will be ended
  373. without altering which print job is currently active or whether plotting
  374. calls are being intercepted.
  375.  
  376.  
  377. SWI PDriver_AbortJob (&80149)
  378. -----------------------------
  379.  
  380.   Entry: R0 = file handle for print job to be aborted.
  381.  
  382.   Exit:  -
  383.  
  384. This SWI should be used to end a print job abnormally - it should generally
  385. be called after fatal errors while printing. It will not try to produce any
  386. further printer output - this is important if an error occurs while sending
  387. output to the print job's output file.
  388.  
  389. If the print job being aborted is the currently active one, there will be no
  390. current print job after this call (so plotting calls will no longer be
  391. intercepted).
  392.  
  393. If the print job being aborted is not currently active, it will be aborted
  394. without altering which print job is currently active or whether plotting
  395. calls are being intercepted.
  396.  
  397.  
  398. SWI PDriver_Reset (&8014A)
  399. --------------------------
  400.  
  401.   Entry: -
  402.  
  403.   Exit:  -
  404.  
  405. This SWI aborts all print jobs known to the printer driver, leaving the
  406. printer driver with no active or suspended print jobs and ensuring that
  407. plotting calls are not being intercepted.
  408.  
  409. Normal applications shouldn't use this SWI, but it can be useful as an
  410. emergency recovery measure when developing an application.
  411.  
  412. A call to this SWI is generated automatically if the machine is reset or the
  413. printer driver module is killed or RMTIDYed.
  414.  
  415.  
  416. SWI PDriver_GiveRectangle (&8014B)
  417. ----------------------------------
  418.  
  419.   Entry: R0 = rectangle identification word. This word is reported back to
  420.               the application when it is requested to plot all or part of
  421.               this rectangle.
  422.          R1 -> 4 word block, containing rectangle to be plotted. Units are OS
  423.               units.
  424.          R2 -> 4 word block, containing dimensionless transformation to be
  425.               applied to the specified rectangle before printing it. The
  426.               entries are given as fixed point numbers with 16 binary places,
  427.               so the transformation is:
  428.                 x' = (x * R2!0 + y * R2!8)/2^16
  429.                 y' = (x * R2!4 + y * R2!12)/2^16
  430.          R3 -> 2 word block, containing the position where the bottom left
  431.               corner of the rectangle is to be plotted on the printed page.
  432.               Units are 1/72000 inch.
  433.          R4 = background colour for this rectangle, in the form &BBGGRRXX.
  434.  
  435. Exit:  -
  436.  
  437. This SWI allows an application to specify a rectangle from its workspace to
  438. be printed, how it is to be transformed and where it is to appear on the
  439. printed page. An application should make one or more calls to SWI
  440. PDriver_GiveRectangle before a call to SWI PDriver_DrawPage and the
  441. subsequent calls to SWI PDriver_GetRectangle. (Multiple calls allow the
  442. application to print multiple rectangles from its workspace to one printed
  443. page - e.g. for "two up" printing).
  444.  
  445. The printer driver may subsequently ask the application to plot the specified
  446. rectangles or parts thereof in any order it chooses. An application should
  447. not make any assumptions about this order or whether the rectangles it
  448. specifies will be split. (A common reason why a printer driver might split a
  449. rectangle is that it prints the page in strips to avoid using excessively
  450. large page buffers.)
  451.  
  452. Assuming that a non-zero number of copies is requested and that none of the
  453. requested rectangles go outside the area available for printing, it is
  454. certain to ask the application to plot everything requested at least once. It
  455. may ask for some areas to be plotted more than once, even if only one copy is
  456. being printed, and it may ask for areas marginally outside the requested
  457. rectangles to be plotted (this can typically happen if the boundaries of the
  458. requested rectangles are not on exact device pixel boundaries).
  459.  
  460. If SWI PDriver_GiveRectangle is used to specify a set of rectangles that
  461. overlap on the output page, the rectangles will be printed in the order of
  462. the SWI PDriver_GiveRectangle calls. For appropriate printers (i.e. most
  463. printers, but not e.g. XY plotters), this means that rectangles supplied via
  464. later PDriver_GiveRectangle calls will overwrite rectangles supplied via
  465. earlier calls.
  466.  
  467.  
  468. SWI PDriver_DrawPage (&8014C)
  469. -----------------------------
  470.  
  471.   Entry: R0 = number of copies to print.
  472.          R1 -> 4 word block, to receive the rectangle to print.
  473.          R2 is zero or contains the page's sequence number within the
  474.               document being printed (i.e. 1-n for an n-page document).
  475.          R3 is zero or points to a string, terminated by a character in the
  476.               ASCII range 33-126 (note spaces are not allowed), which gives
  477.               the 'real' page number. (Examples: "23", "viii", "A-1")
  478.  
  479.   Exit:  R0 = number of copies still requiring printing. This is zero if and
  480.               only if no more plotting is required.
  481.          If R0 is non-zero, the area pointed to by R1 has been filled in with
  482.               the rectangle that needs to be plotted, and R2 contains the
  483.               rectangle identification word for the user-specified rectangle
  484.               that this is a part of.
  485.          If R0 is zero, the contents of R2 and the area pointed to by R1 are
  486.               undefined.
  487.  
  488. This SWI should be called after all rectangles to be plotted on the current
  489. page have been specified (using SWI PDriver_GiveRectangle). It returns the
  490. first rectangle that the printer driver wants plotted in the area pointed to
  491. by R1. If nothing requires plotting - i.e. if there is no such rectangle - it
  492. returns R0=0.
  493.  
  494. So the application should stop trying to plot the current page if R0=0, and
  495. continue otherwise. If R0<>0, the fact that R0 is the number of copies still
  496. to be printed is only intended to be used for information purposes (e.g.
  497. putting a "Printing page m of n" message on the screen); as long as it is
  498. non-zero, R0's value does not affect what the application should try to plot.
  499.  
  500. The information passed in R2 and R3 is not particularly important, though it
  501. helps to make output produced by the PostScript printer driver conform better
  502. to Adobe's structuring conventions. If non-zero values are supplied, they
  503. should be correct. Note that R2 is NOT the sequence number of the page in the
  504. print job, but in the document.
  505.  
  506. An example: if a document consists of 11 pages, numbered "" (the title page),
  507. "i"-"iii" and "1"-"7", and the application is requested to print the entire
  508. preface part, it should use R2 = 2, 3, 4 and R3 -> "i", "ii", "iii" for the
  509. three pages.
  510.  
  511. When plotting starts in a rectangle supplied by a printer driver, the printer
  512. driver behaves as though the VDU system is in the following state:
  513.  
  514.   * VDU drivers enabled.
  515.   * VDU 5 state has been set up.
  516.   * all graphics cursor positions and the graphics origin have been set to
  517.     (0,0).
  518.   * the current dot pattern for dotted lines plotted via VDU calls is
  519.     &AA,&AA,&AA,&AA,&AA,&AA,&AA,&AA, with a repeat length of 8.
  520.   * a VDU 5 character size and spacing of 16 OS units by 32 OS units.
  521.   * the graphics clipping region has been set to bound the actual area that
  522.     is to be plotted. (But note that an application cannot read what this
  523.     area is: the printer drivers do not - and cannot - intercept
  524.     OS_ReadVduVariables or OS_ReadModeVariable.)
  525.   * the area in which plotting will actually take place has been cleared to
  526.     the background colour supplied in the corresponding PDriver_GiveRectangle
  527.     call, as though a CLG had occurred.
  528.   * the cursor movement control bits (i.e. the ones that would be set by
  529.     VDU 23,16,...) are set to &40 - i.e. cursor movement is normal, except
  530.     that movements beyond the edge of the graphics window in VDU 5 mode do
  531.     not generate special actions.
  532.   * one OS unit on the paper is 1/180 inch.
  533.  
  534. This is designed to be as similar as possible to the state set up by the
  535. window manager when redrawing.
  536.  
  537.  
  538. SWI PDriver_GetRectangle (&8014D)
  539. ---------------------------------
  540.  
  541.   Entry: R1 -> 4 word block, to receive the rectangle to print.
  542.  
  543.   Exit:  R0 = number of copies still requiring printing. This is zero if and
  544.               only if no more plotting is required.
  545.          If R0 is non-zero, the area pointed to by R1 has been filled in with
  546.               the rectangle that needs to be plotted, and R2 contains the
  547.               rectangle identification word for the user-specified rectangle
  548.               that this is a part of.
  549.          If R0 is zero, the contents of R2 and the area pointed to by R1 are
  550.               undefined.
  551.  
  552. This SWI should be used after plotting a rectangle returned by a previous
  553. call to SWI PDriver_DrawPage or SWI PDriver_GetRectangle, to get the next
  554. rectangle the printer driver wants plotted. It returns precisely the same
  555. information as PDriver_DrawPage.
  556.  
  557.  
  558. SWI PDriver_CancelJob (&8014E)
  559. ------------------------------
  560.  
  561.   Entry: R0 = file handle for job to be cancelled.
  562.  
  563.   Exit:  -
  564.  
  565. This SWI causes subsequent attempts to output to the print job associated
  566. with the given file handle to do nothing other than generate the error "Print
  567. job cancelled". An application is expected to respond to this error by
  568. aborting the print job.
  569.  
  570.  
  571. SWI PDriver_ScreenDump (&8014F)
  572. -------------------------------
  573.  
  574.   Entry: R0 = file handle of file to receive the dump.
  575.  
  576.   Exit:  -
  577.  
  578. If this SWI is supported (i.e. if bit 24 is set in the value SWI PDriver_Info
  579. returns in R3), this SWI causes the printer driver to output a screen dump to
  580. the file handle supplied in R0. The file concerned should be open for output.
  581.    If the SWI is not supported, an error is returned.
  582.  
  583.  
  584. SWI PDriver_EnumerateJobs (&80150)
  585. ----------------------------------
  586.  
  587.   Entry: R0 = 0 to get file handle of first print job, or file handle of a
  588.               print job to get the file handle of the next print job.
  589.   Exit:  R0 = file handle of print job requested, or 0 if there are no more
  590.               print jobs.
  591.  
  592. This allows the print jobs that exist to be enumerated. The order in which
  593. they appear is undefined.
  594.  
  595.  
  596. SWI PDriver_SetPrinter (&80151)
  597. -------------------------------
  598.  
  599.   Entry: Printer-driver specific.
  600.   Exit:  Printer-driver specific.
  601.  
  602. This allows the setting of options specific to a particular printer driver.
  603. See the individual printer driver documentation for details.
  604.  
  605.  
  606.  
  607. EXAMPLE BASIC PROCEDURE
  608. =======================
  609.  
  610.  
  611. An example BASIC procedure that does a standard "two up" printing job:
  612.  
  613.   DEFPROCprintout(firstpage%, lastpage%, title$, filename$)
  614.     :
  615.     REM Get SWI numbers used in this procedure.
  616.     LOCAL select%, abort%, pagesize%, giverect%, drawpage%, getrect%, end%
  617.     SYS "OS_SWINumberFromString",,"PDriver_SelectJob" TO select%
  618.     SYS "OS_SWINumberFromString",,"PDriver_AbortJob" TO abort%
  619.     SYS "OS_SWINumberFromString",,"PDriver_PageSize" TO pagesize%
  620.     SYS "OS_SWINumberFromString",,"PDriver_GiveRectangle" TO giverect%
  621.     SYS "OS_SWINumberFromString",,"PDriver_DrawPage" TO drawpage%
  622.     SYS "OS_SWINumberFromString",,"PDriver_GetRectangle" TO getrect%
  623.     SYS "OS_SWINumberFromString",,"PDriver_EndJob" TO end%
  624.     :
  625.     REM Open destination file and set up a local error handler that will
  626.     REM close it again on an error.
  627.     LOCAL H%, O%
  628.     H% = OPENOUT(filename$)
  629.     LOCAL ERROR
  630.     ON ERROR LOCAL:RESTORE ERROR:CLOSE#H%:PROCpasserror
  631.     :
  632.     REM Start up a print job associated with this file, remembering the
  633.     REM handle associated with the previous print job (if any), then set up a
  634.     REM a local error handler for it.
  635.     SYS select%,H%,title$ TO O%
  636.     LOCAL ERROR
  637.     ON ERROR LOCAL:RESTORE ERROR:SYSabort%,H%:SYSselect%,O%:PROCpasserror
  638.     :
  639.     REM Now we decide how two pages are to fit on a piece of paper.
  640.     LOCAL left%, bottom%, right%, top%
  641.     PROCgetdocumentsize(box%)
  642.     SYS pagesize% TO ,,,left%,bottom%,right%,top%
  643.     PROCfittwopages(left%,bottom%,right%,top%,box%,matrix%,origin1%,origin2%)
  644.     :
  645.     REM Start the double page loop
  646.     LOCAL page%, copiesleft%, pagetoprint%, white%
  647.     white%=&FFFFFF00
  648.     FOR page%=firstpage% TO lastpage% STEP 2
  649.       :
  650.       REM Set up to print two pages, or possibly just one last time around.
  651.       SYS giverect%, page%, box%, matrix%, origin1%, white%
  652.       IF page%<lastpage% THEN
  653.         SYS giverect%, page%+1, box%, matrix%, origin2%, white%
  654.       ENDIF
  655.       :
  656.       REM Start printing. As each printed page corresponds to two document
  657.       REM pages, we cannot easily assign any sensible page numbers to printed
  658.       REM pages. So we simply pass zeroes to PDriver_DrawPage.
  659.       SYS drawpage%,1,box2%,0,0 TO copiesleft%,,pagetoprint%
  660.       WHILE copiesleft%<>0
  661.         PROCprintpage(pagetoprint%, box2%)
  662.         SYS getrect%,,box% TO copiesleft%,,pagetoprint%
  663.       ENDWHILE
  664.       :
  665.     REM End of page loop
  666.     NEXT
  667.     :
  668.     REM All pages have now been printed. Terminate this print job.
  669.     SYS end%,H%
  670.     :
  671.     REM Go back to the first of our local error handlers.
  672.     RESTORE ERROR
  673.     :
  674.     REM And go back to whatever print job was active on entry to this
  675.     REM procedure (or to no print job in no print job was active).
  676.     SYS select%,O%
  677.     :
  678.     REM Go back to the caller's error handler.
  679.     RESTORE ERROR
  680.     :
  681.     REM Close the destination file.
  682.     CLOSE#H%
  683.   ENDPROC
  684.   :
  685.   DEFPROCpasserror
  686.     ERROR ERR,REPORT$+" (from line "+STR$(ERL)+")"
  687.   ENDPROC
  688.  
  689. This uses the following global areas of store:
  690.  
  691.   box%:     4 words
  692.   box2%:    4 words
  693.   matrix%:  4 words
  694.   origin1%: 2 words
  695.   origin2%: 2 words 
  696.  
  697. And the following external procedures:
  698.  
  699. DEFPROCgetdocumentsize(box%)
  700.   - fills the area pointed to by 'box%' with the size of a document page in
  701.     OS units.
  702.  
  703. DEFPROCfittwopages(l%, b%, r%, t%, box%, transform%, org1%, org2%)
  704.   - given left, bottom, right and top bounds of a piece of paper in units of
  705.     1/72000 inch, and a bounding box of a document page in OS units, sets up
  706.     a transformation and two origins in the areas pointed to by 'tr%','org1%'
  707.     and 'org2%' to print two of those pages on a piece of paper.
  708.  
  709. DEFPROCdrawpage(page%, box%)
  710.   - draw the parts of document page number 'page%' that lie with the box held
  711.     in the 4 word area pointed to by 'box%'.
  712.  
  713. If printing is likely to take a long time and the application does not want
  714. to hold other applications up while it prints, it should regularly use a
  715. sequence like the following during printing:
  716.  
  717.   SYS select%,O%
  718.   SYS "Wimp_Poll",mask%,area% TO reason%
  719.   <process reason% as appropriate>
  720.   SYS select%,H% TO O%
  721.  
  722.  
  723.  
  724. THE VIRTUAL PRINTER INTERFACE
  725. =============================
  726.  
  727.  
  728. When a print job is active, the printer driver intercepts the following
  729. vectors:
  730.  
  731.   (a) WrchV (= WriteCV): all character output is received and interpreted by
  732.       the printer driver. Many VDU sequences are converted into printer
  733.       output to do similar things on the printed page. Some VDU sequences
  734.       produce errors. A few are passed through to the real VDU drivers. Only
  735.       these last go through the usual output stream selection controlled by
  736.       OS_Byte 3.
  737.         See the section entitled 'VDU SEQUENCES' below for more details.
  738.  
  739.   (b) SpriteV: most sprite operations are passed on unchanged to the
  740.       SpriteExtend module and/or the operating system. Those that do sprite
  741.       plotting are intercepted and generate printer output to do similar
  742.       sprite plotting on the printed page.
  743.         Note that, because of the way vector interception is done, the
  744.       SpriteExtend module must be initialised before the printer driver.
  745.         See the section entitled 'SPRITE OPERATIONS' below for more details.
  746.  
  747.   (c) DrawV: Draw calls that would not normally plot to the screen are passed
  748.       on unchanged to the Draw module. Others are intercepted and, where
  749.       possible, used to generate printer output to do similar things on the
  750.       printed page. However, some of the intercepted calls cannot be so
  751.       treated and instead produce errors.
  752.         Note that, because of the way vector interception is done, the
  753.       Draw module must be initialised before the printer driver.
  754.         See the section entitled 'DRAW MODULE CALLS' below for more details.
  755.  
  756.   (d) ColourV: some ColourTrans calls are intercepted and processed by the
  757.       printer driver, others are left to be dealt with by the ColourTrans
  758.       module itself.
  759.         Note that, because of the way vector interception is done, the
  760.       ColourTrans module must be initialised before the printer driver.
  761.         See the section entitled 'COLOURTRANS MODULE CALLS' below for more
  762.       details.
  763.  
  764.   (e) ByteV: The OS_Byte calls dealing with dot-dash repeat lengths (OS_Byte
  765.       163,242,0-64) are intercepted and processed by the printer driver. The
  766.       same applies to OS_Byte 218 (read/write bytes in VDU queue).
  767.         See the section entitled 'MISCELLANEOUS CALLS' below for more
  768.       details.
  769.  
  770. In addition, the font manager and the printer driver interact to cause many
  771. of the font manager calls to be processed by the printer driver. See the
  772. section entitled 'FONT MANAGER CALLS' below for more details.
  773.  
  774.  
  775.  
  776. VDU SEQUENCES
  777. =============
  778.  
  779.  
  780. General rules
  781. -------------
  782.  
  783. Whenever a print job is active, the printer driver will intercept all
  784. characters sent through WrchV. It will then queue them in the same way as the
  785. VDU drivers do and process complete VDU sequences as they appear. Because the
  786. printer driver will not pick up any data currently in the VDU queue, and may
  787. send sequences of its own to the VDU drivers, a print job should not be
  788. selected with an incomplete sequence in the VDU queue.
  789.  
  790. Also, because the printer driver may send sequences of its own to the VDU
  791. drivers, the output stream specification set by OS_Byte 3 should be in its
  792. standard state (i.e. as though set by OS_Byte 3,0).
  793.  
  794. The printer driver will pass the following VDU sequences through to the
  795. normal VDU drivers, either because they control the screen hardware or
  796. because they affect global resources such as the character and ECF
  797. definitions:
  798.  
  799.   VDU 7                         - Produce bell sound
  800.   VDU 19,l,p,r,g,b              - Change hardware palette
  801.   VDU 20                        - Set default hardware palette
  802.   VDU 23,0,n,m|                 - "Program 6845 registers"
  803.   VDU 23,1,n|                   - Change cursor appearance
  804.   VDU 23,2-5,a,b,c,d,e,f,g,h    - Set ECF pattern
  805.   VDU 23,9-10,n|                - Set flash durations
  806.   VDU 23,11|                    - Set default ECF patterns
  807.   VDU 23,12-15,a,b,c,d,e,f,g,h  - Simple setting of ECF pattern
  808.   VDU 23,17,4,m|                - Set ECF type
  809.   VDU 23,17,6,x;y;|             - Set ECF origin
  810.   VDU 23,32-255,a,b,c,d,e,f,g,h - Define character
  811.  
  812. The printer driver will interpret or fault all other VDU sequences. If the
  813. printer driver currently wants a rectangle printed (i.e. if there has been a
  814. call to SWI PDriver_DrawPage or SWI PDriver_GetRectangle and the last such
  815. call returned R0 <> 0), these will result in it producing appropriate output
  816. or errors. Otherwise, the printer driver will keep track of some state
  817. information (e.g. what the current foreground and background colours are),
  818. but will not produce any printer output.
  819.  
  820. The printer driver will always behave as though it is in VDU 5 state. No text
  821. co-ordinate system is defined, and no scrolling is possible. For these
  822. reasons, the following VDU sequences are faulted:
  823.  
  824.    VDU 4                        - exit VDU 5 state
  825.    VDU 23,7,m,d,z|              - scroll display
  826.    VDU 23,8,t1,t2,x1,y1,x2,y2|  - clear text block
  827.  
  828. It is generally meaningless to try to send or echo characters directly to the
  829. printer while printing. Furthermore, attempts to do so are likely to disrupt
  830. the operation of printer drivers. For these reasons, the following VDU
  831. sequences are faulted:
  832.  
  833.    VDU 1,c                      - send character to printer
  834.    VDU 2                        - start echoing characters to printer
  835.  
  836. It is not possible to change the "mode" of a printed page, so the following
  837. VDU sequence is faulted:
  838.  
  839.    VDU 22,m                     - change display mode
  840.  
  841. A printer driver cannot be written to deal with undefined or reserved calls,
  842. so the following VDU sequences are faulted:
  843.  
  844.    VDU 23,18-24,...             - reserved for Acorn expansion
  845.    VDU 23,28-31,...             - reserved for use by applications
  846.    VDU 25,216-231,...           - reserved for Acorn expansion
  847.    VDU 25,240-255,...           - reserved for use by applications
  848.  
  849. The following VDU sequences are ignored, either because they normally do
  850. nothing (at least when stuck in VDU 5 mode and not echoing characters to the
  851. printer) or because they have no sensible interpretation when applied to
  852. printed output rather than a screen.
  853.  
  854.    VDU 0                        - do nothing
  855.    VDU 3                        - stop echoing characters to printer
  856.    VDU 5                        - enter VDU 5 state
  857.    VDU 14                       - start "paged" display
  858.    VDU 15                       - end "paged" display
  859.    VDU 17,c                     - define text colour
  860.    VDU 23,17,5|                 - exchange text foreground and background
  861.    VDU 27                       - do nothing
  862.    VDU 28,l,b,r,t               - define text window
  863.  
  864.  
  865. Colours
  866. -------
  867.  
  868. Colours are a rather complicated matter. It is strongly recommended that
  869. applications should use SWI ColourTrans_SetGCOL, SWI ColourTrans_SelectTable
  870. and SWI ColourTrans_SetFontColours to set colours, as these will allow the
  871. printer to produce as accurate an approximation as it can to the desired
  872. colour, independently of the screen palette. The GCOL sequence (VDU 18,k,c)
  873. should only be used if absolutely necessary, and the application writer
  874. should be aware of the fact that the printer driver has a simplified
  875. interpretation of the parameters, as follows:
  876.  
  877.   * The fact that the background colour is affected if c >= 128 and the
  878.     foreground colour if c < 128 is unchanged.
  879.   * If k MOD 8 <> 0, subsequent plots and sprite plots will not do anything.
  880.   * If k=0, subsequent plots will cause the colour c MOD 128 (possibly
  881.     modified by the current tint) is looked up in the screen palette (at the
  882.     time of plotting, not the time the VDU 18,k,c command was issued).
  883.     Plotting is done by overwriting with the closest approximation the
  884.     printer can produce to the RGB combination found. Subsequent sprite
  885.     plotting will be done without use of the sprite's mask.
  886.   * If k=8, subsequent plots will be treated the same as k=0 above, except
  887.     that sprite plots will be done using the sprite's mask (if any).
  888.   * If k=16 or k=24, ECF pattern 1 will be read (at the time of plotting).
  889.     Each pixel value in it will be looked up as an RGB combination in the
  890.     screen's palette, and the resulting values will be averaged. Plotting
  891.     will be done with the closest approximation the printer can produce to
  892.     the resulting colour. Sprite plotting is done without using the sprite's
  893.     mask if k=16 and using it if k=24.
  894.   * The cases k=32 and k=40 are treated similarly to k=16 and k=24, except
  895.     that ECF pattern 2 is used.
  896.   * The cases k=48 and k=56 are treated similarly to k=16 and k=24, except
  897.     that ECF pattern 3 is used.
  898.   * The cases k=64 and k=72 are treated similarly to k=16 and k=24, except
  899.     that ECF pattern 4 is used.
  900.   * The cases k=80 and k=88 are treated similarly to k=16 and k=24, except
  901.     that the "giant" ECF pattern is used.
  902.  
  903. The major problems with the use of VDU 18,k,c to set colours are (a) that
  904. it makes the printer driver output dependent on the current screen mode and
  905. palette; (b) that it artificially limits the printer driver to the number
  906. of colours displayed on the screen (which can be very limiting in a two
  907. colour mode!).
  908.  
  909. Other techniques that depend on GCOLs (e.g. SWI Font_SetFontColours,
  910. colour-changing sequences in strings passed to Font_Paint, plotting sprites
  911. without a translation table, etc.) have the same problems and are similarly
  912. not recommended.
  913.  
  914. No operations other than overwriting are permitted, mainly because they
  915. cannot be implemented on many common printers (e.g. PostScript printers).
  916.  
  917. The treatment of ECF patterns is only intended to allow them to be used to
  918. "mix" colours. (Allowing genuine pattern printing is a possible area for
  919. future printer driver development.)
  920.  
  921. Note that the printer driver maintains its own foreground and background
  922. colour information. The screen foreground and background colours are not
  923. affected by VDU 18,k,c sequences encountered while a print job is active.
  924.  
  925. Similarly, VDU 23,17,2-3,t| sequences encountered while a print job is active
  926. do not affect the screen tints, just the printer driver's own tints. VDU
  927. 23,17,0-1,t| sequences would only affect the colours of the text tints, so
  928. the printer driver ignores them.
  929.  
  930.  
  931. Other graphics state operations
  932. -------------------------------
  933.  
  934. The VDU 6 and VDU 21 sequences have their normal effects of enabling and
  935. disabling execution (but not parsing) of subsequent VDU sequences. As usual,
  936. the printer driver keeps track of this independently of the VDU drivers.
  937.  
  938. The cursor movement VDU sequences (i.e. VDU 8-11, VDU 13, VDU 30 and VDU
  939. 31,x,y) all update the current graphics position (without updating the
  940. previous graphics positions used in e.g. triangle plotting), precisely as
  941. they do in VDU 5 mode on the screen.
  942.  
  943. VDU 24,l;b;r;t; will set the printer driver's graphics clipping box. The
  944. rectangle specified should lie completely within the box that was reported on
  945. return from the last call to SWI PDriver_DrawPage or SWI
  946. PDriver_GetRectangle. If this is not the case, it is not defined what will
  947. happen, and different printer drivers may treat it in different ways. This is
  948. analogous to the situation with the window manager: attempts to set a
  949. graphics clipping box outside the rectangle currently being redrawn may be
  950. ignored completely (if they go outside the screen) or may get obeyed (with
  951. consequences that are almost certainly wrong!).
  952.  
  953. VDU 29,x;y; sets the printer driver's graphics origin.
  954.  
  955. VDU 26 will reset the printer driver's graphics clipping box to its maximum
  956. size (this is essentially the box reported on return from the last call to
  957. SWI PDriver_DrawPage or SWI PDriver_GetRectangle, but may be slightly
  958. different due to rounding problems when converting from a box expressed in
  959. printer pixels to one expressed in OS units). It also resets its versions of
  960. the graphics origin, the current graphics position and all the previous
  961. graphics positions to (0,0).
  962.  
  963. VDU 23,6,a,b,c,d,e,f,g,h will set the printer driver's current dot pattern
  964. (for use with lines plotted via VDU 25,16-31,x;y; and VDU 25,48-63,x;y;). The
  965. exact lengths of the dashes and gaps produced may differ between various
  966. printer drivers, and also between the screen and printer drivers, so an
  967. application should not rely on them. However, an application can reasonably
  968. expect each set bit in the pattern to correspond to approximately 2 to 3 OS
  969. units on the printed page.
  970.  
  971. VDU 23,16,x,y| changes the printer driver's version of the cursor control
  972. flags, and thus how the cursor movement control sequences and BBC-style
  973. character plotting affect the current graphics position. As usual, this is
  974. completely independent of the corresponding flags in the VDU drivers.
  975. However, printer drivers pay no attention to the setting of bit 6 (which
  976. controls whether movements beyond the edge of the graphics window cause
  977. carriage return/line feeds and other cursor movements to be generated
  978. automatically) - they always behave as though it is set. Note that the
  979. Wimp normally sets this bit, and that it is not sensible to have it clear
  980. at any time during a Wimp redraw.
  981.  
  982. VDU 23,17,7,flags,x;y;| changes the printer driver's version of the size that
  983. BBC-style characters are to be plotted and the spacing that is required
  984. between them. Setting the VDU 4 character size cannot possibly affect the
  985. printer driver's output and so will be ignored completely. As noted below
  986. under 'Plotting operations', a "pixel" is regarded as the size of a screen
  987. pixel for the screen mode that was in effect when the print job was started.
  988.  
  989.  
  990. Plotting operations
  991. -------------------
  992.  
  993. The printer driver regards a "pixel" as having size 2 OS units square (1/90
  994. inch square). The main effect of this is that all PLOT line, PLOT point and
  995. PLOT outline calls will produce lines that are approximately 2 OS units
  996. wide.
  997.  
  998. However, when translating the character size and spacing information provided
  999. by VDU 23,17,7,... (see above) from pixels to OS units, the screen pixel size
  1000. for the screen mode that was in effect when the print job was started is
  1001. used. This is done in the expectation that the application is basing its
  1002. requested sizes on that screen mode.
  1003.  
  1004. The following VDU sequences perform straightforward plotting operations;
  1005. printer drivers will produce the corresponding printed output:
  1006.  
  1007.    VDU 12                       - clear graphics window (in VDU 5 state)
  1008.    VDU 16                       - clear graphics window
  1009.    VDU 25,0-63,x;y;             - draw line
  1010.    VDU 25,64-71,x;y;            - draw point
  1011.    VDU 25,80-87,x;y;            - fill triangle
  1012.    VDU 25,96-103,x;y;           - fill axis-aligned rectangle
  1013.    VDU 25,112-119,x;y;          - fill parallelogram
  1014.    VDU 25,144-151,x;y;          - draw circle
  1015.    VDU 25,152-159,x;y;          - fill circle
  1016.    VDU 25,160-167,x;y;          - draw circular arc
  1017.    VDU 25,168-175,x;y;          - fill circular segment
  1018.    VDU 25,176-183,x;y;          - fill cicular sector
  1019.    VDU 25,192-199,x;y;          - draw ellipse
  1020.    VDU 25,200-207,x;y;          - fill ellipse
  1021.    VDU 32-126                   - print characters in BBC-style font
  1022.    VDU 127                      - backspace & delete
  1023.    VDU 128-255                  - print characters in BBC-style font
  1024.  
  1025. One difference to note is that most printer drivers will either not do the
  1026. rounding to pixel centres normally done by the VDU drivers, or will round to
  1027. different pixel centres (probably the centres of their device pixels).
  1028.  
  1029. The following VDU sequences are faulted because they cannot be split up
  1030. easily across rectangles, and also because they depend on the current picture
  1031. contents and so cannot be implemented e.g. on PostScript printers:
  1032.  
  1033.    VDU 25,72-79,x;y;            - horizontal line fill (flood fill primitive)
  1034.    VDU 25,88-95,x;y;            - horizontal line fill (flood fill primitive)
  1035.    VDU 25,104-111,x;y;          - horizontal line fill (flood fill primitive)
  1036.    VDU 25,120-127,x;y;          - horizontal line fill (flood fill primitive)
  1037.    VDU 25,128-143,x;y;          - flood fills
  1038.    VDU 25,184-191,x;y;          - copy/move rectangle
  1039.  
  1040. Exception: VDU 25,184,x;y; and VDU 25,188,x;y; are now correctly interpreted
  1041. by printer drivers (as being equivalent to VDU 25,0,x;y; and VDU 25,4,x;y;
  1042. respectively).
  1043.  
  1044. The sprite plotting sequences (VDU 23,27,m,n| and VDU 25,232-239,x;y;) are
  1045. converted to the appropriate calls to SWI OS_SpriteOp. These calls will then
  1046. be intercepted as normal by the printer driver (see under 'SPRITE OPERATIONS'
  1047. below). In addition, the VDU 25,232-239,x;y; sequence causes the printer
  1048. driver's graphics position to be updated. Application writers should use
  1049. direct calls to SWI OS_SpriteOp in preference to these sequences.
  1050.  
  1051. The font manager VDU sequences (VDU 23,25,a,b,c,d,e,f,g,h,
  1052. VDU 23,26,a,b,c,d,e,f,g,h,text and VDU 25,208-215,x;y;text) are trapped by
  1053. the printer driver and converted into the corresponding font manager SWIs.
  1054. These are then handled as normal (see under 'FONT MANAGER CALLS' below). In
  1055. addition, the VDU 25,208-215,x;y;text sequence causes the printer driver's
  1056. current graphics position to be updated. Again, application writers are
  1057. strongly recommended to use the font manager SWIs in preference to these VDU
  1058. sequences.
  1059.  
  1060.  
  1061.  
  1062. SPRITE OPERATIONS
  1063. =================
  1064.  
  1065.  
  1066. Printer drivers intercept OS_SpriteOp via the SpriteV vector. Most calls are
  1067. simply passed through to the operating system or the SpriteExtend module. The
  1068. ones that normally plot to the screen are generally intercepted and used to
  1069. generate printer output by the printer driver.
  1070.  
  1071. The following reason codes normally involve reading or writing the screen
  1072. contents and are not straightforward sprite plotting operations. Because some
  1073. printer drivers redirect output to a sprite internally, it is unknown what
  1074. the "screen" is during these operations. They are therefore faulted.
  1075.  
  1076.    2 - screen save
  1077.    3 - screen load
  1078.   14 - get sprite from current point on screen
  1079.   16 - get sprite from specified point on screen
  1080.  
  1081. Reason codes that are passed through to the operating system or the
  1082. SpriteExtend module are:
  1083.  
  1084.    8 - read sprite area control block
  1085.    9 - initialise sprite area
  1086.   10 - load sprite file
  1087.   11 - merge sprite file
  1088.   12 - save sprite file
  1089.   13 - return name of numbered sprite
  1090.   15 - create sprite
  1091.   25 - delete sprite
  1092.   26 - rename sprite
  1093.   27 - copy sprite
  1094.   29 - create mask
  1095.   30 - remove mask
  1096.   31 - insert row
  1097.   32 - delete row
  1098.   33 - flip about X axis
  1099.   35 - append sprite
  1100.   36 - set pointer shape
  1101.   40 - read sprite size
  1102.   41 - read pixel colour
  1103.   42 - write pixel colour
  1104.   43 - read pixel mask
  1105.   44 - write pixel mask
  1106.   45 - insert column
  1107.   46 - delete column
  1108.   47 - flip about Y axis
  1109.   62 - read save area size
  1110.  
  1111. The following reason code is passed through to the operating system. In
  1112. addition, the printer driver remembers the sprite selected so that VDU
  1113. 25,232-239,x;y; sequences can be correctly converted to SWI OS_SpriteOp
  1114. calls.
  1115.  
  1116.   24 - select sprite
  1117.  
  1118. The following reason codes plot a sprite or its mask, and are converted into
  1119. appropriate printer output:
  1120.  
  1121.   28 - plot sprite at current point on screen
  1122.   34 - plot sprite at specified point on screen
  1123.   48 - plot mask at current point on screen
  1124.   49 - plot mask at specified point on screen
  1125.   50 - plot mask at specified point on screen, scaled
  1126.   51 - plot character, scaled
  1127.   52 - plot sprite at specified point on screen, scaled
  1128.   53 - plot sprite at specified point on screen, grey scaled
  1129.  
  1130. As usual for a printer driver, only some GCOL actions are understood. If the
  1131. GCOL action is not divisible by 8, nothing is plotted. If it is divisible by
  1132. 8, the "overwrite" action is used. If it is divisible by 16, the sprite is
  1133. plotted without using its mask; otherwise the mask is used.
  1134.  
  1135. The colours used to plot sprite pixels are determined as follows:
  1136.  
  1137.   * If the call does not allow a pixel translation table, or if no
  1138.     translation table is supplied, the current screen palette is consulted to
  1139.     find out what RGB combination the sprite pixel's value corresponds to.
  1140.     The printer driver then does its best to produce that RGB combination.
  1141.     Use of this option is not really recommended.
  1142.   * If a translation table is supplied with the call, the printer driver
  1143.     assumes that the table contains code values allocated by one of:
  1144.  
  1145.       SWI ColourTrans_SelectTable with R2 = -1
  1146.       SWI ColourTrans_ReturnColourNumber
  1147.       SWI ColourTrans_ReturnColourNumberForMode with R1 = -1
  1148.       SWI ColourTrans_ReturnOppColourNumber
  1149.       SWI ColourTrans_ReturnOppColourNumberForMode with R1 = -1
  1150.  
  1151.     It can therefore look up precisely which RGB combination is supposed to
  1152.     correspond to each sprite pixel value. Because of the variety of ways in
  1153.     which printer drivers can allocate these values, the translation table
  1154.     should always have been set up in the current print job and using these
  1155.     calls.
  1156.  
  1157. If a sprite is printed unscaled, its size on the printed output is the same
  1158. as its size would be if it were plotted to the screen in the screen mode that
  1159. was in effect at the time that the print job concerned was started. If it is
  1160. printed scaled, the scaling factors are applied to this size. This is one of
  1161. the few ways in which the printed output does depend on this screen mode (the
  1162. main other ones are in interpreting GCOL and TINT values, and in interpreting
  1163. VDU 5 character sizes). It is done this way in the expectation that the
  1164. application is scaling the sprite for what it believes is the current screen
  1165. mode.
  1166.  
  1167. Finally, the following two reason codes are intercepted to keep track of
  1168. whether plotting output is currently supposed to go to a sprite or to the
  1169. screen. If it is supposed to go to a sprite, it really will go to that sprite
  1170. - this allows applications to create sprites normally while printing. If it
  1171. is supposed to go to the screen, it will be processed by the printer driver.
  1172. (Note that printer drivers that redirect output to a sprite internally will
  1173. treat this case specially, regarding output as still being destined for the
  1174. screen!)
  1175.  
  1176.   60 - switch output to sprite
  1177.   61 - switch output to mask
  1178.  
  1179.  
  1180.  
  1181. DRAW MODULE CALLS
  1182. =================
  1183.  
  1184.  
  1185. Printer drivers intercept the DrawV vector and re-interpret those calls whose
  1186. purpose is to plot something on the screen, producing appropriate printer
  1187. output instead. There are a number of restrictions on the calls that can be
  1188. dealt with, mainly due to the limitations of PostScript. Most of the
  1189. operations that are disallowed are not particularly useful, fortunately.
  1190.  
  1191. Note that the Draw module calls normally use the graphics foreground colour
  1192. to plot with and the graphics origin. The printer driver uses its versions of
  1193. these values. In particular, this means that the fill colour is subject to
  1194. all the restrictions noted elsewhere in this document.
  1195.  
  1196. The floating point Draw module calls are not intercepted at present. If and
  1197. when the Draw module is upgraded to deal with them, printer drivers will be
  1198. similarly upgraded.
  1199.  
  1200.  
  1201. SWI Draw_Fill
  1202. -------------
  1203.  
  1204.   Printer drivers can deal with most common calls to this SWI. The
  1205. restrictions are:
  1206.  
  1207.   (a) They cannot deal with fill styles that invoke the positive or negative
  1208.       winding number rules - i.e. those with bit 0 set.
  1209.   (b) They cannot deal with a fill style which asks for non-boundary exterior
  1210.       pixels to be plotted (i.e. which have bit 2 set). Exception: they can
  1211.       deal with the trivial case in which all of bits 2-5 are set - i.e. if
  1212.       all pixels in the plane are to be plotted!
  1213.   (c) They cannot deal with the following values for bits 5-2:
  1214.         0010 - plot exterior boundary pixels only.
  1215.         0100 - plot interior boundary pixels only.
  1216.         1010 - plot exterior boundary and interior non-boundary pixels only.
  1217.   (d) An application should not rely on there being any difference between
  1218.       what is printed for the following three values of bits 5-2:
  1219.         1000 - plot interior non-boundary pixels only.
  1220.         1100 - plot all interior pixels.
  1221.         1110 - plot all interior pixels and exterior boundary pixels.
  1222.       (A printer driver will generally try its best to distinguish these, but
  1223.       it may not be possible.)
  1224.  
  1225.  
  1226. SWI Draw_Stroke
  1227. ---------------
  1228.  
  1229.   Again, most common calls to this SWI can be dealt with. The restrictions
  1230. on the parameters depend on whether the specified thickness is zero or not:
  1231.  
  1232. If the specified thickness is zero, the restrictions are:
  1233.  
  1234.   (a) Printer drivers cannot deal with a fill style with bits 3-2 equal to 01
  1235.       - i.e. one that asks for pixels lying on the stroke to be plotted and
  1236.       those that lie off the stroke not to be.
  1237.   (b) Most printer drivers will not pay any attention to bit 31 of the fill
  1238.       style - the one that distinguishes plotting the stroke subpath by
  1239.       subpath from plotting it all at once.
  1240.  
  1241. If the specified thickness is non-zero, the restrictions are:
  1242.  
  1243.   (a) All the restrictions mentioned under SWI Draw_Fill above.
  1244.   (b) They cannot deal with bits 5-2 being 0110 - i.e. asking for just the
  1245.       boundary pixels of the resulting filled path to be plotted.
  1246.   (c) Most printer drivers will not pay any attention to bit 31 of the fill
  1247.       style - the one that distinguishes plotting the stroke subpath by
  1248.       subpath from plotting it all at once.
  1249.  
  1250.  
  1251. SWI Draw_StrokePath, SWI Draw_FlattenPath and SWI Draw_TransformPath
  1252. --------------------------------------------------------------------
  1253.  
  1254. None of these do any plotting; they are all dealt with in the normal way by
  1255. the Draw module.
  1256.  
  1257.  
  1258. SWI Draw_ProcessPath
  1259. --------------------
  1260.  
  1261. This SWI is faulted if R7=1 (fill path normally) or R7=2 (fill path subpath
  1262. by subpath) on entry. Use the appropriate one of Draw_Fill or Draw_Stroke if
  1263. you want to produce printed output. If the operation you're trying to do is
  1264. too complicated for them, it almost certainly cannot be handled by e.g. the
  1265. PostScript printer driver.
  1266.  
  1267. All other values of R7 correspond to calls that don't do any plotting and are
  1268. dealt with in the normal way by the Draw module. If you're trying to do
  1269. something complicated and you've got enough workspace and RMA, a possible
  1270. useful trick is to use SWI Draw_ProcessPath with R7 pointing to an output
  1271. buffer, followed by SWI Draw_Fill on the result.
  1272.  
  1273.  
  1274.  
  1275. COLOURTRANS MODULE CALLS
  1276. ========================
  1277.  
  1278.  
  1279. The printer driver intercepts calls to the ColourTrans module, via the
  1280. ColourV vector. Most of them are passed straight on to the ColourTrans module
  1281. - the exceptions are:
  1282.  
  1283.  
  1284. SWI ColourTrans_SelectTable with R2 = -1
  1285. ----------------------------------------
  1286.  
  1287. Each RGB combination in the source palette (or implied by it in the case of
  1288. 256 colour modes) is converted into a colour number as though by SWI
  1289. ColourTrans_ReturnColourNumber (see below). The resulting values are placed
  1290. in the table.
  1291.  
  1292.  
  1293. SWI ColourTrans_SetGCOL
  1294. -----------------------
  1295.  
  1296. The printer driver's version of the foreground or background colour (as
  1297. appropriate) is set. The GCOL actions are interpreted precisely as for the
  1298. VDU 18,k,c call (see above). However, rather than looking up a GCOL in the
  1299. screen palette at plot time, the exact RGB combination specified in this call
  1300. is remembered and used (as accurately as the printer will render it) at plot
  1301. time.
  1302.  
  1303. After this has been done, the call is effectively converted into SWI
  1304. ColourTrans_ReturnGCOL and passed down to the ColourTrans module in order to
  1305. set the information returned correctly. Note that this implies that
  1306. subsequently using the GCOL returned in a VDU 18,k,c sequence will not
  1307. produce the same effect on the colour as this call: it will merely produce
  1308. the best approximation the printer can manage to the best approximation the
  1309. current screen palette can manage to the specified RGB combination. It is
  1310. therefore probably a bad idea to use the values returned.
  1311.  
  1312. This call therefore allows the application to make full use of a printer's
  1313. colour resolution without having to switch to another screen mode or mess
  1314. around with the screen's palette, and without worrying about the effects of a
  1315. change in the screen's palette. It is therefore the recommended way to set
  1316. the foreground and background colours.
  1317.  
  1318.  
  1319. SWI ColourTrans_ReturnColourNumber
  1320. ----------------------------------
  1321.  
  1322. This will return a code value (in the range 0-255) that identifies the
  1323. specified RGB combination as accurately as possible to the printer driver.
  1324. How this code value is determined may vary from printer driver to printer
  1325. driver, and indeed even from print job to print job for the same printer
  1326. driver. An application should therefore not make any assumptions about what
  1327. these code values mean.
  1328.  
  1329. (Most printer drivers implement this by pre-allocating some range of code
  1330. values to evenly spaced RGB combinations, then adopting the following
  1331. approach:
  1332.  
  1333.    (a) If the RGB combination is already known about, return the
  1334.        corresponding code value.
  1335.    (b) If the RGB combination is not already known about and some code values
  1336.        are still free, allocate one of the unused code values to the new RGB
  1337.        combination and return that code value.
  1338.    (c) If the RGB combination is not already known about and all code values
  1339.        have been allocated, return the code number whose RGB combination is
  1340.        as close as possible to the desired RGB combination.
  1341.  
  1342. The pre-allocation of evenly spaced RGB combinations will ensure that even
  1343. case (c) does not have really terrible results.)
  1344.  
  1345.  
  1346. SWI ColourTrans_ReturnColourNumberForMode with R1 = -1
  1347. ------------------------------------------------------
  1348.  
  1349. This is treated exactly the same as SWI ColourTrans_ReturnColourNumber above.
  1350.  
  1351.  
  1352. SWI ColourTrans_SetOppGCOL
  1353. --------------------------
  1354.  
  1355. This behaves like ColourTrans_SetGCOL above, except that the RGB combination
  1356. it remembers is the furthest possible RGB combination from the one actually
  1357. specified in R0, and it ends by being converted into a call to
  1358. ColourTrans_ReturnOppGCOL. Note that there is no guarantee that the GCOL
  1359. returned is anywhere near the RGB combination remembered!
  1360.  
  1361.  
  1362. SWI ColourTrans_ReturnOppColourNumber
  1363. -------------------------------------
  1364.  
  1365. This behaves exactly as though ColourTrans_ReturnColourNumber (see above) had
  1366. been called with R0 containing the furthest possible RGB combination from the
  1367. one actually specified.
  1368.  
  1369.  
  1370. SWI ColourTrans_ReturnOppColourNumberForMode with R1 = -1
  1371. ---------------------------------------------------------
  1372.  
  1373. This behaves exactly as though ColourTrans_ReturnColourNumberForMode (see
  1374. above) had been called with R1 = -1 and R0 containing the furthest possible
  1375. RGB combination from the one actually specified.
  1376.  
  1377.  
  1378. SWI ColourTrans_SetFontColours
  1379. ------------------------------
  1380.  
  1381. The printer driver's version of the font colours is set, to as accurate a
  1382. representation of the desired RGB combinations as the printer can manage.
  1383.  
  1384. After this has been done, the call is effectively converted into SWI
  1385. ColourTrans_ReturnFontColours and passed down to the ColourTrans module in
  1386. order to set the information returned correctly. Note that this implies that
  1387. subsequently using the values returned in a SWI Font_SetFontColours call will
  1388. not produce the same effect on the font colours as this call: it will merely
  1389. produce the best approximations the printer can manage to the best
  1390. approximations the current screen palette can manage to the specified RGB
  1391. combinations. It is therefore probably a bad idea to use the values returned.
  1392.  
  1393. This call therefore allows the application to make full use of a printer's
  1394. colour resolution without having to switch to another screen mode or mess
  1395. around with the screen's palette, and without worrying about the effects of a
  1396. change in the screen's palette. It is the recommended way to set the font
  1397. colours.
  1398.  
  1399.  
  1400.  
  1401. FONT MANAGER CALLS
  1402. ==================
  1403.  
  1404.  
  1405. The printer driver interacts with the font manager (via a service call and
  1406. SWI PDriver_FontSWI) in such a way that when it is active, calls to the
  1407. following SWIs are processed by the printer driver:
  1408.  
  1409.   SWI Font_Paint
  1410.   SWI Font_LoseFont
  1411.   SWI Font_SetFontColours
  1412.   SWI Font_SetPalette
  1413.  
  1414. This enables the printer driver to make SWI Font_Paint produce printer output
  1415. rather than affecting the screen.
  1416.  
  1417. The use of SWI Font_SetFontColours is not recommended, as it results in the
  1418. setting of colours that depend on the current screen palette. Instead, use
  1419. SWI ColourTrans_SetFontColours to set font colours to absolute RGB values.
  1420. Similarly, the use of colour-changing control sequences in strings passed to
  1421. SWI Font_Paint is not recommended.
  1422.  
  1423. In addition to the control sequences allowed by current font managers,
  1424. printer drivers will be able to handle the following control sequence if
  1425. the font manager they are working with can:
  1426.  
  1427.   19,background red,green,blue,foreground red,green,blue,maximum offset
  1428.  
  1429. This gives a way of changing colour in the middle of a string without
  1430. sacrificing colour resolution.
  1431.  
  1432. (How exactly it does this varies quite markedly between printer drivers: for
  1433. instance, most dot matrix printer drivers will probably use the font manager
  1434. to write into the sprite they are using to hold the current strip of printed
  1435. output, while the PostScript printer driver uses the PostScript prologue to
  1436. define a translation from font manager font names to printer fonts.)
  1437.  
  1438.  
  1439.  
  1440. MISCELLANEOUS CALLS
  1441. ===================
  1442.  
  1443.  
  1444. OS_Byte 163,242,0-64 are intercepted to set the printer driver version of the
  1445. dot pattern repeat length instead of the VDU drivers' version.
  1446.  
  1447. OS_Byte 218 is intercepted to act on the printer driver's VDU queue instead
  1448. of the VDU drivers' version.
  1449.  
  1450. It should be noted that most of the informational calls associated with the
  1451. VDU drivers (and OS_ReadVduVariables in particular) will produce undefined
  1452. results when a printer driver is active. These results are likely to differ
  1453. between printer drivers (in particular, they will vary according to whether
  1454. the printer driver plots to a sprite internally and if so, how large the
  1455. sprite concerned is).
  1456.  
  1457. The only informational calls that the application may rely upon are:
  1458.  
  1459.    OS_Word 10      - used to read character and ECF definitions.
  1460.    OS_Word 11      - used to read palette definitions.
  1461.    OS_ReadPalette  - used to read palette definitions.
  1462.    OS_Byte 218     - when used to read the number of bytes in the VDU queue.
  1463.