Copyright © Acorn Computers Ltd. 1992       0396,007/FS Issue 1 ****LIVE****

                   RISC OS Green Support for Printer Dumpers
                   =========================================

                   -----------------------------------------
                   | Drawing No : 0396,007/FS              |
                   |      Issue : 1 ****LIVE****           |
                   |       Date : 30 January 1991          |
                   |     Author : David De Vorchik         |
                   |  Change No : AMR xxxx                 |
                   |     Sheets : x                        |
                   |  Last Issue: x (AMR xxxx of xx.xx.xx) |
                   -----------------------------------------

INTRODUCTION
============

This document outlines how the PDumper system works within RISC OS 3, it
covers the aspects of writing a PDumper and the use of the other modules
PDriverDP and PDumper Suppport.

The PDumper system was introduced to make the implementation of bitmap based
printer drivers a lot easier, in earlier releases of the OS you had to build
a complete printer driver specific to your printer to generate bit map
images, now it is possible just to supply the output routines to output
either a 1BPP or a 8BPP tile.

The system is structured so that there is one generic printer driver,
PDriverDP and sitting below that are the PDumpers, the PDumpers can make use
of facilities provided by the support module PDumperSupport for halftoning
the image and/or setting colours.

NB: All calls can return an error, this is signaled by setting V and 
    setting R0 to point at the error block.

PDriver, PDriverDP and the PDumper
==================================

SWI interface
-------------

PDriverDP does not itself have a SWI dispatcher, instead PDriver switches
SWIs it receives to the relevant PDriver as appropriate which then performs
the action required. A PDumper is well removed from this SWI
interface, only a few of the SWIs are relevant. These SWIs are
described below.

PDriver_MiscOp and PDriver_MiscOpForDriver (which is preferred) should be
used to register and deregister your PDumper with PDriverDP. The PDumper
should attempt to register itself on initialisation and again on
receiving Service_PDumperStarting (&65) - ignoring any errors back from
these. When a PDumper module dies it must deregister itself, this time
refusing to die if an error is returned from the deregistration call. A
PDumper identifies itself to PDriverDP with a unique ID number. The ID
numbers already allocated are:

0       PDumperSP_Number        Sprite device
1       PDumperDM_Number        dot-matrix generic
2       PDumperLJ_Number        LaserJet compatible device
3       PDumperIW_Number        Apple ImageWriter device
4       PDumper24_Number        Dot reducing 24 pin device

NB: Further dumpers must be registered with Acorn via ISV support.

These SWIs all pass through PDriver which switches them to the relevant
PDriverXX. In our case this is PDriverDP.


SWI PDriver_MiscOp (&8015A) or PDriver_MiscOpForDriver (&8015B)
---------------------------------------------------------------
  in    R0 = PDumperMiscOp_AddPDumper (&80000000)
        R1 = PDumper ID
        R2 = version of PDumperDP required
        R3 -> private word
        R4 -> dispatch routine
        R5 = supported calls bit mask
        R6 = supported strip types bit masks
        R8 = PDriverType_DP (7) (PDriver_MiscOpForDriver only)
  out   -

This registers a PDumper with PDriverDP. It is recommended that the
PDriver_MiscOpForDriver form is used as this ensures correct operation
whatever PDriver is currently selected.

R1 contains a unique ID for the PDumper as described above.

R2 contains the minimum version of PDriverDP this PDumper requires.

R3 is passed to the PDumper in R12 whenever PDriverDP calls R4. It is
expected that this will be the PDumper module's private workspace pointer.

R4 should point to the dispatch routine in the PDumper which services
requests made of the PDumper by PDriverDP (eg to dump a strip).

R5 is a mask describing which reason codes the dispatch routine can handle.
Bit N set means dispatch reason code N is supported. These are the reason
codes:

0       PDumperReason_SetDriver
1       PDumperReason_OutputDump
2       PDumperReason_ColourSet
3       PDumperReason_StartPage
4       PDumperReason_EndPage
5       PDumperReason_StartJob
6       PDumperReason_AbortJob
7       PDumperReason_MiscOp
8-31    reserved - these bits in R5 must be clear

A PDumper must support reasons 0-7 - PDriverDP will assume it does.

R6 is a mask describing which strip types the PDumper supports. Bit N set
means strip type N is supported. These are the strip types:

0       StripType_Monochrome
1       StripType_GreyLevel
2       StripType_256Colour
3-31    reserved - these bits in R6 must be clear

A PDumper must support types 0-2 - PDumperDP will assume it does.

The dispatch routine will be called in SVC mode, with R12 set to R3 as
supplied above. R11 will contain the reason code for the request.


PDriver_MiscOp (&8015A) or PDriver_MiscOpForDriver (&8015B)
-----------------------------------------------------------
  in    R0 = PDumperMiscOp_RemovePDumper (&80000001)
        R1 = PDumper ID
        R8 = PDriverType_DP (7) (PDriver_MiscOpForDriver only)
  out   -

This deregisters the specified PDumper from PDriverDP. A PDumper must call
this when it dies. This call may return an error, especially if the PDumper
in question is current being used for a print job, in which case the PDumper
must refuse to die by returning the error. It is recommended that the
PDriver_MiscOpForDriver form is used as this ensures correct operation
whatever PDriver is currently selected.

PDriver_MiscOp (&8015A) or PDriver_MiscOpForDriver (&8015B)
-----------------------------------------------------------
  in    R0 >= &80000100
        R1 = PDumper ID
        R8 = PDriverType_DP (7) (PDriver_MiscOpForDriver only)
  out   -

These calls are passed straight through to the PDumper as
PDumperReason_MiscOp. This mechanism is to provide direct control over a
PDumper.



The PDriverDP module also supports the PDriver_SetDriver SWI to allow the
configuration of the driver to be changed, the parameters are as follows:

PDriver_SetDriver
-----------------
  in    R1 = PDumper ID
        R2 -> Command to ensure PDumper present
        R3 -> 256 byte data block of PDumper specific configuration data
        R4 -> 256 byte block of PDriverDP configuration data
        R5 = configuration word for dumper
  out   -

This SWI is passed through to PDumpers as PDumperReason_SetDriver (0) hence
it is documented here.

R1 is the PDumper's ID.

R2 contains a command line. This command will be used to load the PDumper
if it is not already loaded. The length of this command line should not
exceed 256 bytes including the terminating character.

R3 points to a 256 byte block of data to be used for passing configuration
data to the PDumper. The block passed into PDriver_SetDriver may not be
the same one as that passed to the PDumper in PDumperReason_SetDriver, a
copy being used instead, in other words, on return from PDriver_SetDriver
the caller may discard this configuration block.

R4 contains a pointer to a configuration block which is also 256
bytes in length. It is used by both PDriverDP and the PDumpers. The
PDriverDP specified contents are:

offset  meaning

+0      height in dots of a strip
                This is the pin-height of the print head * number of
                vertical interlace passes.
+1      number of vertical interlace passes-1
+2      number of horizontal interlace passes-1
+3      number of repetition passes over a given line-1
                This is the number of passes over a given line a PDumper
                should perform. This is for multiple-pass printing eg for
                colour.
+4      StripType
                0 - monochrome
                1 - grey level
                2 - 256-colour
+5      output depth (BPP)
+6      number of passes per strip
                This is the number of passes over a given rectangle
                PDriverDP 