RISCOS.com

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

 

PDumperSupport


Introduction and Overview

This chapter describes the PDumperSupport module, introduced in RISC OS 3 (version 3.10). This module's SWI interface provides colour matching, error diffusion and halftoning facilities for the use of printer dumpers. This avoids unnecessary duplication of code in each module, and provides a service for third party printer dumpers.

The way in which this module fits in with the rest of the printing system is explained in the earlier chapter on printer drivers, in The structure of the printing system.

SWI calls


PDumper_Info
(SWI &41B00)

Returns information about the PDumper support module

On entry

--

On exit

R0 = version number ×100 (eg version 1.23 stored as 123)
R1 = bit field of optional features implemented by support module:

bit 0 set => supports halftone grey
bit 1 set => supports error diffuse grey
bit 2 set => supports halftone colour
bit 3 set => supports error diffuse colour
bits 4 - 31 reserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call simply returns information about the PDumper support module, giving its version number and which optional features it supports.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

None

Related vectors

None


PDumper_Claim
(SWI &41B01)

Allocates a block of memory and links it into the chain

On entry

R0 = pointer to anchor word
R3 = size of block to be claimed
R4 = tag for block

On exit

R0 preserved
R2 = pointer to block allocated (on a word boundary)
R3, R4 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call allocates a block of memory and links it into the printer dumper's chain. The chain is specified by the anchor word, which is typically the printer dumper's private word. The size specified need not be a word multiple. The tag is a four byte value stored after the link point. Although you may claim multiple blocks with the same tag, you must be aware that if you subsequently call PDumper_Find it is uncertain which of these blocks it will find; see PDumper_Find.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_Free, PDumper_Find

Related vectors

None


PDumper_Free
(SWI &41B02)

Attempts to release a block of memory from the printer dumper's chain

On entry

R0 = pointer to anchor word
R2 = pointer to block to be released

On exit

R0, R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call attempts to release a block of memory from the printer dumper's chain. The chain is specified by the anchor word. If the block is not part of the specified chain then it is not released, and an error is generated.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_Claim, PDumper_Find

Related vectors

None


PDumper_Find
(SWI &41B03)

Scans the printer dumper's chain for a block of memory with the given tag

On entry

R0 = pointer to anchor word
R2 = tag for block

On exit

R2 = pointer to block found

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call scans the printer dumper's chain for a block of memory with the given tag, returning the first match it finds. The chain is specified by the anchor word.

If you have claimed several blocks with the same tag, you cannot be certain which one this call will return. If there is no match, this call generates an error.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_Claim, PDumper_Free

Related vectors

None


PDumper_StartJob
(SWI &41B04)

Sets up any workspace that is required for a job

On entry

R0 = pointer to anchor word
R1 = flags word: all bits reserved (must be zero)
R2 = pointer to filename of palette to load, or 0 if none to be loaded

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets up any workspace required for a job. The support module links this into the chain specified by the anchor word, which is typically the printer dumper's private word. You should call it at the start of a job (ie when your dumper is called with the reason code PDumperReason_StartJob).

The flags word in R1 is reserved for future expansion, and for the time being you must set it to zero. If non-null, R2 contains a pointer to the filename of a palette file to use for the job, which is loaded into a block with a tag of 1.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_TidyJob

Related vectors

None


PDumper_TidyJob
(SWI &41B05)

Releases workspace used for a job

On entry

R0 = pointer to anchor word
R1 = pointer to list of tags terminated by a null word, or 0
R2 = reason code: 0 => end of page, else end of document

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This routine releases workspace used for a job, as specified by R1 and R2. The support module releases this from the chain specified by the anchor word.

R1 points to a list of tags; any block having a matching tag will be released. Furthermore, any blocks allocated by the support module that are specific to the page or document (as given in R2) will be released.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_StartJob

Related vectors

None


PDumper_SetColour
(SWI &41B06)

Processes the colour setting required by the printer dumper

On entry

R0 = pointer to anchor word
R1 = physical colour (&BBGGRR00)
R2 = strip information:

bits 0 - 7 = strip type (see Strip types)
bits 24 - 31 = pass number
R4 = halftoning information:
bits 0 - 7 = horizontal resolution in pixels
bits 8 - 15 = vertical resolution in pixels
bits 16 - 31 reserved (must be zero)

On exit

R0 - R2 preserved
R3 = strip type dependant colour number
R4 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call processes the colour setting required by the printer dumper. In doing so, it scans the chain specified by the anchor word for any palette block to use, decodes the strip type, and then returns a suitable colour number.

If this call generates an error, R3 may be corrupted on return.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

PDumper_Claim, PDumper_Find

Related vectors

None


PDumper_PrepareStrip
(SWI &41B07)

Processes a bitmap into a format suitable for printing

On entry

R0 = pointer to anchor word
R1 = pointer to bit image data
R2 = resulting format of the strip

bits 0 - 7 = format:
0 => grey level (halftoned)
1 => grey level (diffused)
2 => colour (halftoned)
3 => colour (diffused)
all other bits reserved (must be zero)
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 R1 to go down one line)
R6 = halftoning information:
bits 0 - 7 = horizontal resolution in pixels
bits 8 - 15 = vertical resolution in pixels
bits 16 - 31 reserved (must be zero)

On exit

R0 - R6 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call processes the specified 8 bit-per-pixel bitmap generated by the PDriverDP module into a format suitable for printing by the relevant output routine.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

None

Related vectors

None


PDumper_LookupError
(SWI &41B08)

Accesses the internal error handling routines within the support module

On entry

R0 = pointer to error block, including message token
R1 = pointer to string to substitute for '%0', or zero if no string

On exit

R0 = pointer to resolved error block
V flag set

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call accesses the internal error handling routines within the support module. On entry R0 is a pointer to an error block, the error message in which is a token for one of the messages in the file Resources:$.Resources.PDrivers.Messages. The support module extracts the corresponding message from the file; it then scans it for the string '%0', for which (if found) it substitutes the string pointed to by R1.

Using this call removes any need to have MessageTrans routines within a printer dumper, as most printer dumpers simply resolve errors.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

None

Related vectors

None


PDumper_CopyFilename
(SWI &41B09)

Copies a specified filename into a buffer

On entry

R0 = pointer to buffer into which to copy string
R1 = size of buffer
R2 = pointer to string to be copied (control-character terminated)

On exit

R0 = pointer to character in buffer after terminating null
R2= pointer to last character copied from string

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call copies the specified filename into a buffer. The routine terminates on any character <=32 and converts it to a null. An error is generated if an overflow occurs (ie more than R1 characters need to be copied).

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).

Related SWIs

None

Related vectors

None

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