|
www.riscos.com Technical Support: |
This module provides general compression and decompression facilities of a lossless nature through a SWI interface. The algorithm is 12-bit LZW, however, this may change in future releases.
The interface is designed to be restartable, so that compression or decompression can occur from a variety of locations. Operations involving file I/O can easily be constructed from the operations provided.
This module is not available in RISC OS 2.
The module is used by the Squash application to generate files of type Squash (&FCA). The format of these files is documented in the chapter entitled Squash files.
The following errors can be returned by the Squash module:
| Error number | Error text |
|---|---|
| &921 | Bad address for module Squash |
| &922 | Bad input for module Squash |
| &923 | Bad workspace for module Squash |
| &924 | Bad parameters for module Squash |
R0 = flags:
| bit 0: | 0  START NEW OPERATION_ 1 continue existing operation (using existing workspace contents)
|
| bit 1: | 0 END OF THE INPUT_ 1 more input after this
|
| bit 2: | reserved (must be zero) |
| bit 3: | 0 NO EFFECT_ 1 return the work space size required and the maximum output size in bytes (all other bits must be 0)
|
| bits 4 - 31 reserved (must be zero) | |
do not return maximum output size) - if bit 3 of R0 is set; or workspace pointer - if bit 3 of R0 is clearR0 = required work space size - if bit 3 of R0 set on input; else output status - if bit 3 of R0 clear on input:
operation completed operation ran out of input data (R3 = 0) operation ran out of output space (R5 < 12)
don't know or wasn't asked) - if bit 3 of R0 set on input; else preserved - if bit 3 of R0 clear on inputInterrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This call provides general compression of a lossless nature. It acts as a filter on a stream of data. The call returns if either the input or the output is exhausted.
It is recommended that you use the following facility to determine the maximum output size rather than attempting to calculate it yourself:
Call the SWI first with bit 3 of R0 set and the input size placed in R1. The maximum output size is then calculated and returned on exit in R1. You can use this value to allocate the required amount of space and call the SWI again setting the registers as appropriate.
The algorithm used by this module is 12-bit LZW, as used by the UNIX 'compress' command (with -b 12 specified). If future versions of the module use different algorithms, they will still be able to decompress existing compressed data.
If bits 0 and 1 of R0 are clear, and the output is definitely big enough, a fast algorithm will be used.
The performance of compression on an 8Mhz A420 with ARM2 is approximately as follows:
| Store to store | Fast case |
|---|---|
| 24 Kbytes per second | 68 Kbytes per second |
where Fast case is store to store, with all input present, and with an output buffer large enough to hold all output.
R0 = flags:
| bit 0: | 0 START NEW OPERATION_ 1 continue existing operation (using existing workspace contents)
|
| bit 1: | 0 END OF THE INPUT_ 1 more input after this
|
| bit 2: | 0 NORMAL_ 1 you may assume that the output will all fit in this buffer (allows a faster algorithm to be used, if bits 0 and 1 are both 0)
|
| bit 3: | 0 NO EFFECT_ 1 return the work space size required and the maximum output size in bytes (all other bits must be 0)
|
| bits 4 - 31 reserved (must be zero) | |
do not return maximum output size) - if bit 3 of R0 is set; or workspace pointer - if bit 3 of R0 is clearR0 = required work space size - if bit 3 of R0 set on input; else output status - if bit 3 of R0 clear on input:
operation completed operation ran out of input data (R3 < 12) operation ran out of output space (R5 = 0)
don't know or wasn't asked) - if bit 3 of R0 set on input; else preserved - if bit 3 of R0 clear on inputInterrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant
This SWI provides general decompression of a lossless nature.
Note: The current algorithm cannot predict what the size of the decompressed output will be. This means that, currently, -1 is always returned on exit in R1. In future releases this may change; it is therefore recommended that you call the SWI first with bit 3 of R0 set and the input size placed in R1.
In the case where R3 < 12, the unused input must be resupplied.
The performance of decompression on an 8Mhz A420 with ARM2 is approximately as follows:
| Store to store | Fast case |
|---|---|
| 48 Kbytes per second | 280 Kbytes per second |
where Fast case is store to store, with all input present, and with an output buffer large enough to hold all output.