RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Printing


Introduction

The printing system has been extended under RISC OS 3.5, mainly to support the vastly greater number of colours available. A new version of !Printers (1.22) has also been released for use under RISC OS 3, incorporating all changes relevant to the older hardware and operating system. Further changes have been made in RISC OS 3.6, largely to support printing JPEGs.

This chapter describes the few resultant changes the above have made in the programmer's interface. It does not describe in detail the rather more considerable internal changes made to the printing system.

Overview

Trapping of output calls

The printing system still works in the same way as before, intercepting the same calls. Support has been added to track extensions made in RISC OS, such as the use of mode specifiers, new sprite formats and wide translation tables. Because of this, the information in Trapping of output calls is still correct; calls documented there as being processed by the printer drivers are still correctly handled.

There are some new calls handled by the printer drivers; these are documented below.

SpriteV

Treatment of SpriteOp reason codes

The table on Treatment of SpriteOp reason codes shows the printer driver's treatment of each SpriteOp reason code in RISC OS 3. The table below shows the same information for the new reason code added in RISC OS 3.6:

Reason code Meaning Printer driver's treatment
17 Check the validity of a sprite area Passed on

JPEG SWIs

RISC OS 3.6 provides calls to output JPEG images. The printer driver interacts with these calls using a mechanism broadly similar to that used for font output. When printing starts, the printer driver issues the SWI JPEG_PDriverIntercept. The JPEG code then alters its SWI handling so that:

  • It processes certain SWIs itself, as normal.
  • It passes certain SWIs to the printer driver using the SWI PDriver_JPEGSWI. The printer driver may then:
    1. process the call
    2. fault the call.

    The JPEG code does not process such SWIs itself.

The table below shows how each SWI is handled:

JPEG SWI Meaning Processing
Info Gives information on a JPEG image held in a buffer Processed by JPEG code as usual
File Info Gives information on a JPEG image held in a file Processed by JPEG code as usual
Plot Scaled Decompresses, scales, and plots on the screen a JPEG image held in a buffer Passed to printer driver and processed by it
Plot File Scaled Decompresses, scales, and plots on the screen a JPEG image held in a file Passed to printer driver and faulted by it: file operations are not allowed when printing
Plot Transformed Decompresses, transforms, and plots on the screen a JPEG image held in a buffer Passed to printer driver and processed by it
Plot File Transformed Decompresses, transforms, and plots on the screen a JPEG image held in a file Passed to printer driver and faulted by it: file operations are not allowed when printing
PDriver Intercept Requests that SpriteExtend passes on all calls to JPEG plotting SWIs Processed by JPEG code as usual

Technical details

The structure of the printing system

Front and back ends merged

In RISC OS 3.6, the front and back ends of the Printers application have been merged. It is important for future compatibility that any software you write does not assume the internal structure of the Printers application, as it may change again in subsequent releases of RISC OS.

New printer dumper

In RISC OS 3.6, a new printer dumper has been added for printers using Epson's Esc/P2 control language. The dumper's name is PDumperE2; its number is 6.

Colour input

The range of colour documents 'understood' as inputs remains unchanged on RISC OS 3 systems, save that PDriverDP has been extended to take in 8bpp, full palette sprites.

Support for new types of colour document has been added to the printing system as it has been added to other parts of RISC OS. So from RISC OS 3.5 onwards, 16/32 bpp true colour sprites are handled. From RISC OS 3.6 onwards, new type sprites of up to 8bpp with a palette and JPEG images - both files, and inserts in Draw files - are also handled.

New strip types

In order to support the improved colour output facilities some extra strip types have been defined from RISC OS 3.5 onwards, and all calls that use strip types have been extended to support them. The table below should replace that on Strip types:

Value Meaning
0 monochrome
1 grey scale
2 256 colour
3 Multiple pass 24 bit colour (RISC OS 3 only)
4 Single pass 16 bit colour (RISC OS 3.5 or later)
5 Single pass 24 bit colour (RISC OS 3.5 or later)

Multiple pass 24 bit colour allows true colour output under RISC OS 3. Colour output is limited to 24bpp, and caches some very small colour conversion tables for optimum performance.

Single pass 16 and 24 bit colour strips only work under RISC OS 3.5 or later. Using a single pass gives faster output than using multiple passes. 16 bit colour renders internally using 16 bits of information; this is slightly faster than 24 bits, and requires less memory - but the images produced may contain slightly less colour information, depending on how the printer output palette has been defined. Attempting to use these strip types under RISC OS 3 will cause error messages from modules such as ColourTrans and from OS_SpriteOp calls; however, !Printers does not allow this, and so this is not a problem in normal use.

Pre-scanning of rectangles

From RISC OS 3.6 onwards the printer driver may choose to make a pre-scanning pass of the print rectangles that the application wants printed, provided the application is aware this may happen. Under RISC OS 3.6, when the bit image drivers are plotting a JPEG image they must do a pre-scan pass to ascertain memory requirements. In future, pre-scanning may be used for other purposes.

Whether or not the printer driver chooses to perform a pre-scan pass should be transparent to your application, which need only respond to all returned plotting rectangles as normal. A pre-scan pass should not increase printing times significantly provided that the majority of work your application does for each rectangle is to make plotting calls, which are simply 'swallowed' during the pre-scan.

Your application should not rely on information such as ColourTrans tables remaining valid between the pre-scan pass and the real pass.

New SWIs

From RISC OS 3.5 onwards you can enumerate the available strip types by calling PDriver_MiscOp with the new reason code of &80000002; for details see PDriver_MiscOp.

From RISC OS 3.6 onwards, there is a new SWI PDriver_JPEGSWI used to pass on JPEG SWIs to the printer drivers. For details, see PDriver_JPEGSWI.

Changes to existing SWIs

PDriver_Info

A new bit has been added in RISC OS 3.6 to the features word returned in R3 that describes the printer driver:

Bit(s) Value Meaning
13 0 it does not expect a flag byte to be passed in R0 for PDriver_DrawPage (see below for details).
1 it expects a flag byte to be passed in R0 for PDriver_DrawPage (see below for details).
PDriver_DrawPage

The meaning of R0 has been altered in RISC OS 3.6; the top byte now holds flags. Currently only a single bit is used, to support pre-scanning. On entry:

R0 = number of copies to print, and flags:
bits 0 - 23 = number of copies to print
bit 24 set => application knows about pre-scan of rectangles by printer driver
bits 25 - 31 reserved (must be zero)

and on exit:

R0 = zero if finished; else more rectangles to be printed, and:
bit 24 set => this rectangle is for pre-scan only

We recommend that before calling this SWI you should first call PDriver_Info (see above) to check if the printer driver expects to receive the flag byte:

  • If it does, you should set any relevant flags when calling this SWI (ie set bit 24), even if you believe you don't need to for the particular document you are printing. This ensures future compatibility.
  • If it does not, you must not set any of the flags when calling this SWI, otherwise you will get a very large number of copies output!
PDriver_GetRectangle

The meaning of R0 on exit has been extended in RISC OS 3.6 in the same way as for PDriver_DrawPage:

R0 = zero if finished; else more rectangles to be printed, and:
bit 24 set => THIS RECTANGLE IS FOR PRE-SCAN ONLY
PDumperReason_SetDriver

Extra bits have been added to the configuration word:

Bit Meaning when set
4 Printer does black removal (PDumperLJ) - RISC OS 3.5 onwards
5 Printer supports colour (PDumperLJ) - RISC OS 3.6 onwards
PDumperReason_AbortJob

This call has been extended from RISC OS 3.5 onwards so that the printer dumper can reset the printer should a print job be terminated (eg by Escape). R3 on entry has an extra bit flag from RISC OS 3.5 onwards, which if set also causes R4 to be used:

R3 bit 24 set => reset printer
R4 = pointer to copy of PDriverDP and dumper configuration data (see PDumperReason_SetDriver (reason code 0)) - only if bit 24 of R3 is set

If a printer dumper is called with this bit set it must output to file the appropriate graphics termination and reset sequences to ensure the printer is in a sensible state.

This avoids problems where a job cancelled in the middle of a graphics sequence might leave the printer awaiting the rest of the sequence: the printer then hangs, and possibly even wrecks the next print job by treating its start as the end of the missing sequence.

PostScript restriction on 16 or 32bpp sprites with a mask

When the PostScript printer driver plots a 16 or 32bpp sprite with a mask to a colour printer, the masked pixels are white (not transparent), and so overwrite any graphics underneath the sprite. This is because the PostScript imaging model does not directly support a bitmap mask; the method used to emulate it for sprites with up to 8 bits per pixel does not generalise to sprites with a large number of colours.

This limitation only applies when output is to a colour printer; on black-and-white printers the sprite is reduced to 256 shades of grey, and the mask is transparent.

New palette file format in PDumperSupport

PDumperSupport has been enhanced in RISC OS 3.5 to allow better control over the quality of the printed image. To do so it uses a new format of palette file. In order to minimise prompting for the disc, these palette files are loaded into RMA and made available through ResourceFS. You can modify a palette file using the !RePRO tool, available from Oak Solutions.

SWI Calls


PDriver_MiscOp
(SWI &8015A)

Returns a bit mask showing which strip types a printer dumper supports

On entry

R0 = &80000002 (reason code)
R1 = number of printer dumper for which to obtain strip types bitmask

On exit

R0 = supported strip types bit mask (if dumper loaded), otherwise preserved

Use

This call returns a bit mask showing which strip types a printer dumper supports (see New strip types). If bit n of the mask is set, then it shows that the printer dumper can output strip type n.

The new RISC OS 3 dumpers described in this chapter return 2_1111, and the RISC OS 3.5 dumpers return 2_110111. Older dumpers return 2_111.


PDriver_JPEGSWI
(SWI &8015D)

Passes JPEG SWIs to the printer driver

On entry

R8 = JPEG SWI number modulo 64
All other registers as for original JPEG_... call

On exit

R8 corrupted (JPEG SWI's original R8 preserved by SpriteExtend)
All other registers preserved

Interrupts

Interrupt state is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call passes JPEG SWIs to the printer driver, once the printer driver has called JPEG_PDriverIntercept to enable interception. See JPEG SWIs.

This call is for internal use only; you must not use it in your own code.

Related SWIs

JPEG_PDriverIntercept

Related vectors

None

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015