|
www.riscos.com Technical Support: |
This chapter describes printer dumper modules, used in conjunction with the PDriverDP module to provide support for bit image printing.
The way in which these modules fit in with the rest of the printing system is explained in the previous chapter on printer drivers, in the The structure of the printing system.
The relationship of printer dumpers to the PDriverDP module is very similar to that between printer drivers and the printer sharer module. In both cases the 'parent' module issues a service call when it starts, and it is the duty of the 'child' to register at this time. When registering the child passes to the parent module an entry point. The parent module calls this entry point to pass on those calls that it cannot handle because they are device dependent.
For printer dumper modules, the service call they should respond to is Service_PDumperStarting (see Service_PDumperStarting (Service Call &66)). They should register themselves by calling PDriver_MiscOpForDriver &80000000 (see PDriver_MiscOp &80000000 and PDriver_MiscOpForDriver), either on receiving this service call or on starting up. They should ignore any errors from this call.
When a printer dumper module dies it must deregister itself by calling PDriver_MiscOpForDriver &80000001 (see PDriver_MiscOp &80000001 and PDriver_MiscOpForDriver), this time refusing to die if an error is returned.
A printer dumper's reason code handler is called in SVC mode. R11 always contains the reason code for the call. The following reason codes are assumed to be supported by all PDumper modules:
Other reason codes are reserved for future use. If a dumper receives an unknown reason code, it should return the call with all registers preserved.
R12 is always a pointer to the printer dumper's private word, as passed in R3 when it first registered itself using PDriver_MiscOp &80000000 (see PDriver_MiscOp &80000000). The remaining register usage is reason code dependent, and detailed below.
All calls can return an error, which is done in the normal way by returning with the V flag set and R0 pointing to an error block.
Escape will be enabled during most calls, especially for reason code 1 (PDumperReason_OutputDump) as this can often take quite a long time. If a dumper is going to spend a long time processing a request, it should check the escape state regularly and return an escape error if necessary.
If you are writing a dumper, you should preserve all registers, save for those explicitly used to return a value.
These are the current printer dumper numbers in use, and the names of the corresponding PDumper modules:
| Value | Meaning | PDumper module |
|---|---|---|
| 0 | Sprite device | PDumperSP |
| 1 | Dot-matrix generic | PDumperDM |
| 2 | LaserJet compatible device | PDumperLJ |
| 3 | Apple ImageWriter device | PDumperIW |
| 4 | Dot reducing 24 pin device | PDumper24 |
| 5 | Colour Deskjet compatible device | PDumperDJ |
You must register any new printer dumper numbers with Acorn; see the chapter entitled Printer driver and printer dumper numbers.
Most calls to the printer dumper reason code handler specify the type of strip being printed. The values used are:
| Value | Meaning |
|---|---|
| 0 | monochrome |
| 1 | grey scale |
| 2 | 256 colour |
This is a 'code fragment' description of printing:
Use Printers message protocol if running under the Wimp
This is done by !Printers
PDriver_SetDriver
This is done by applications
PDriver_Info
REM check what features are available (eg PDriver_DeclareFont)
OPEN printer:
PDriver_SelectJob
IF driver supports PDriver_DeclareFont THEN
WHILE fonts to be declared
PDriver_DeclareFont font
ENDWHILE
PDriver_DeclareFont end of font list
ENDIF
FOR each page to print
REPEAT
PDriver_GiveRectangle
UNTIL all rectangles declared
REM typically only one rectangle given, specifying whole page
PDriver_DrawPage
WHILE more rectangles to print
plot returned rectangle using supported output calls
PDriver_GetRectangle
ENDWHILE
ENDFOR
PDriver_EndJob
CLOSE printer:
Here is the same 'code fragment' description of printing showing where the various reason codes are used in calls to a dumper's reason code handler:
Use Printers message protocol if running under the Wimp
This is done by !Printers
PDriver_SetDriver
PDumperReason_SetDriver the printer gets configured
This is done by applications
PDriver_Info
REM check what features are available (eg PDriver_DeclareFont)
OPEN printer:
PDriver_SelectJob
PDumperReason_StartJob
IF driver supports PDriver_DeclareFont THEN
WHILE fonts to be declared
PDriver_DeclareFont font
ENDWHILE
PDriver_DeclareFont end of font list
ENDIF
FOR each page to print
REPEAT
PDriver_GiveRectangle
UNTIL all rectangles declared
REM typically only one rectangle given, specifying whole page
PDriver_DrawPage
PDumperReason_StartPage
WHILE more rectangles to print
plot returned rectangle using supported output calls
PDumperReason_ColourSet
PDriver_GetRectangle
PDumperReason_OutputDump
ENDWHILE
PDumperReason_EndPage
PDumperReason_AbortJob (R3=0) to tidy workspace for page end
PDumperReason_StartPage for the next copy
ENDFOR
PDriver_EndJob
PDumperReason_AbortJob (R3![[NOT EQUAL]](../symbols/entities/8800.png)
0) to tidy up job workspace
CLOSE printer:
R1 = printer dumper number
R2 = pointer to command to ensure printer dumper present
R3 = pointer to 256 byte data block giving dumper configuration data
R4 = pointer to 272 byte block giving PDriverDP and dumper configuration data
R5 = configuration word for dumper
R11 = 0 (printer dumper reason code)
R12 = pointer to dumper's private word
--
This is called when the printer dumper is being selected by PDriver_SetDriver (see PDriver_SetDriver (SWI 8015C)).
R1 is unlikely to be useful to the printer dumper, which probably knows its own number.
The command pointed to by R2 is again unlikely to be useful to the printer dumper. The command may not have been used, as the dumper may already have been loaded when PDriver_SetDriver was called.
This call sets the current printer dumper to that specified by the number held in R1. It does so by calling the dumper's reason code handler with reason code 0.
R3 and R4 are both pointers to data blocks containing configuration data for the dumper. Both blocks are transient, and so you must copy any data you need before returning to the caller. When this reason code is called by the Printers application in RISC OS 3 (version 3.10) via PDriver_SetDriver, the contents of the data blocks are as follows:
italicised words below show the names used by PrintEdit for the passed information. All bytes, whether offsets or values, are unsigned quantities; all words are signed:
R5 is a configuration word, the meaning of which is dumper-specific. The top byte will always be the version number of PDriverDP. This is 3 for RISC OS 3 (version 3.10); if you receive a lower value you should fault it.
Other bits of the configuration word currently defined are:
| Bit | Meaning when set |
|---|---|
| 0 | Horizontal output (PDumperDM) |
| Supports multiple copies (PDumperLJ) | |
| 1 | Roll paper feed (PDumperDM) |
| Supports compression (PDumperLJ) | |
| 2 | Do not send form feeds (PDumperLJ) |
| 3 | Use PaintJet paper movement commands (PDumperLJ) |
R0 = pointer to start of strip data giving bitmap for strip
R1 = file handle for output
R2 = strip type (see Value Name on page)
R3 = width output dump should be, in pixels
R4 = height of strip in pixels
R5 = width of strip in bytes (ie amount to add to R0 to go down one line)
R6 = halftoning information:
--
This routine is called by PDriverDP when it has generated a strip for output at the dumper's required depth. The strip is passed as a bitmap stored in sprite format. R0 points to the bitmap data, not to a sprite header; there may be a header preceding the data, but the dumper must not rely on this.
This routine should then render the data to the file handle passed in R1. Interlacing will already have been catered for by PDriverDP.
The strip can be at either 1 or 8 bits-per-pixel. The values stored relate to the byte values returned from PDumperReason_ColourSet.
R0 = physical colour (&BBGGRR00)
R2 = strip type (see Value Name on page)
R3 = pointer to private word for job (see PDumperReason_StartJob on PDumperReason_StartJob (reason code 5))
R4 = halftoning information:
R3 = strip type dependent colour number
This call is made when ever the PDriver needs to convert a physical colour to a colour number. The colour number is specific to the printer dumper and strip type.
The printer dumper can use PDumperSupport to do this by calling PDumper_SetColour.
R0 = copies requested
R1 = file handle for output
R2 = strip type (see Value Name on page)
R3 = number of blank pixel rows to skip before start of data
R4 = pointer to private word for job (see PDumperReason_StartJob on PDumperReason_StartJob (reason code 5))
R5 = pointer to copy of PDriverDP and dumper configuration data (see PDumperReason_SetDriver (reason code 0))
R6 = left margin in pixels
R7 = horizontal and vertical resolution:
R0 = number of copies to be performed
R3 = number of blank pixel rows remaining to skip before start of data
This routine is called at the start of the page. This routine should set up the printer and skip to the correct print position.
If the printer can be requested to perform multiple copies itself then this routine should return the number of copies passed in adjusted appropriately - the returned number of copies being how many times PDriverDP will print a given page.
However much line skipping is performed at the page start should be subtracted from R3 before returning; PDriverDP will perform the rest. Note that R3 on return must not be negative.
The routine is also passed the horizontal margin. This cannot be modified, and it is assumed that the dumping routine will process it appropriately, for example by padding each line start with null bytes, or by moving the graphics origin to the right.
If the printer is a generic dot matrix (ie the printer dumper number is 1) and it has roll paper (ie bit 1 of R5!256 is set), then R3 should be ignored and instead R5!32 pixel rows should be skipped (ie the short advance used for roll paper). As above, you can return any remainder of this in R3.
R1 = file handle for output
R2 = strip type (see Value Name on page)
R3 = pointer to private word for job (see PDumperReason_StartJob on PDumperReason_StartJob (reason code 5))
R4 = pointer to copy of PDriverDP and dumper configuration data (see PDumperReason_SetDriver (reason code 0))
R11 = 4 (reason code)
R12 = pointer to dumper's private word
--
When called the PDumper should output the end of page sequence to the file and then return.
R0 = pointer to private word for job (see below)
R1 = file handle for output
R2 = strip type (see Value Name on page)
R5 = pointer to copy of PDriverDP and dumper configuration data (see PDumperReason_SetDriver (reason code 0))
R11 = 5 (reason code)
R12 = pointer to dumper's private word
--
When this is called the printer dumper should handle setting up the required workspace for the job. The private word for the job should be treated the same way as the private word for a dumper, that is, the meaning is defined by the dumper. Typically workspace is allocated and attached to the private word.
The printer dumper can use PDumperSupport to do this by calling PDumper_StartJob.
R0 = pointer to private word for job (see PDumperReason_StartJob on PDumperReason_StartJob (reason code 5))
R1 = file handle for output
R2 = strip type (see Value Name on page)
R3 = subreason code: 0 
end of a page, else end of document
R11 = 6 (reason code)
R12 = pointer to dumper's private word
--
When this is called the PDumper should release any workspace specified, ie all document specific workspace at the end of document, or all page specific workspace at the end of a page. The PDumper should not output anything to the file.
If an error occurs during a print sequence this call will be made with an 'end of document' subreason code; other calls will not be used.
The printer dumper can use PDumperSupport to do this by calling PDumper_TidyJob.
R0 = PDriver_MiscOp reason code
R11 = 7 (reason code)
R12 = pointer to dumper's private word
Other register usage as for PDriver_MiscOp SWI - see PDriver_MiscOp onwards
--
This call is provided so that dumpers can provide specific features that require an interface other than the control block. The current Acorn printer system does not use this call; if this reason code is used, current printer drivers merely return the call with all registers preserved.
R1 = &66 (reason code)
All registers preserved
This service call is issued when the PDriverDP module starts up. Any printer dumpers resident at that time should declare themselves to PDriverDP by calling PDriver_MiscOpForDriver &80000000 (see PDriver_MiscOp &80000000 and PDriver_MiscOpForDriver).
R1 = &67 (reason code)
All registers preserved
This service call is issued as a broadcast to inform printer dumpers that they have been deregistered and that the PDriverDP module is about to die.