
 Compression
 -----------
 Although ProSound always uses 16 bits linear signed, little endian for samples,
the actual data on the disc may be stored in other formats; typically compressed
or in another format.
 Whenever ProSound accesses the file, the calls are redirected to the
compression type code which handles the actual fileoperations and the conversion
to 16 bit lin sign.

 In this doc, the terms 'track' and 'file' both refer to the same.


 Installation
 ------------
 The module providing the compression type must be loaded after the ProSound
module has been loaded. The Obey file <ProSound$Dir>.!Modules RMLoads the
ProSound module; the compression modules should be RMLoad'ed in this file too.


 Workspace
 ---------
 The compression code owns 256 bytes of each track (bytes 768-1023); you should
not use any other workspace - when loading a project, ProSound assumes that it
can reconstruct a track from the track file and the contents of these 256 bytes.


 IDs
 ---
 A compression type is identified by its compression type id. This id is a
5 bit number which is allocated by Oregan.

 The currently allocated compression type ids are:
 #0     16 bit          (16 bit linear signed)
 #1     8 bit log       (8 bit VIDC1a log)


 SWI ProSound_TrackCompression  (SWI &83F0C)
 -------------------------------------------
 This SWI manages compression/decompression of tracks.

 On entry
        R0  =   Reason code
                0 : Install compression type
                1 : Remove compression type
                2 : Read compression types list
                3 : Read compression type details
        R1-R8   Depends on R0

 On exit
        Depends on the reason code


 Install compression type (reason code 0)
 On entry
        R0  =   0
        R1  =>  List of entry points
                0       ReadSamples_Code (**)
                4       WriteSamples_Code (**)
                8       CreateTrack_Code (**)
                12      RemoveTrack_Code
                16      InsertSamples_Code or 0 (*) (**)
                20      RemoveSamples_Code or 0 (*) (**)
                24      ExtendFile_Code (**)
                28      OpenFile_Code
                32      0
                36      0
                40      0
                44      0
                48      0
                52      0
                56      Decompress_Code
                60      Compress_Code
        R2  =>  Compression type name (max 23 chars, 0-terminated)
        R3  =   Compression info flags
                bits 0  - 15    samples per chunk (SPC)
                bits 16 - 31    chunksize in bytes (CS)
                The data MUST be organised in chunks of <CS> bytes, each
                of which must be decompressable to <SPC> 16 bits samples
                by the Decompress_Code
                If possible, <SPC> should be equal to 512 or a multiple
                of 256.
        R4  =   Compression type id, allocated by Oregan.
        R5  =   Feature flags
                Bit 0 set => always temporary tracks (eg. in RAM)

 (*)     If either of these entries are 0, then ProSound will do
         the inserting or removing using ReadSamples_Code and
         WriteSamples_Code.

 (**)    OpenFile_Code is always called before these entries, to
         ensure that the file is open.


 On exit
        All registers preserved



 Remove compression type (reason code 1)
 On entry
        R0  =   1
        R1  =   Compression type id

 On exit
        All registers preserved



 Read compression type list (reason code 2)
 On entry
        R0  =   2
        R1  =>  Buffer for namelist (64 words)
                Each available compression type is stored in the buffer
                as two words:
                word 0  =>  name
                word 1      bits 0-4   compression type id

 On exit
        R2  =   Number of available compression types (max. 32)
        All other registers preserved



 Read compression details (reason code 3)
 On entry
        R0  =   3
        R1  =   Compression type id

 On exit
        R0  =>  Entry point list
        R1  =>  Compression type name
        R2  =   Compression info flags




 ReadSamples_Code
 ----------------
 This is called to read a number of samples from the track. The code should
return with the buffer filled with 16 bit samples.

 On entry
        R0  =>  Track
        R1  =>  Buffer
        R2  =   Number of samples to read
        R3  =   Index of first sample to read

 On exit
        R2  =   Number of samples read
        All other registers must be preserved


 WriteSamples_Code
 -----------------
 This is called to write a number of (16 bit) samples to the track.

 On entry
        R0  =>  Track
        R1  =>  Buffer
        R2  =   Number of samples to write
        R3  =   Index of first sample to write

 On exit
        R2  =   Number of samples written
        All other registers preserved


 CreateTrack_Code
 ----------------
 This is called to create a new VM file.

 On entry
        R0  =>  Track
        R1  =   Flags (was R5 on entry to SWI ProSound_InitTrack) 
                If bit 2 set, the file already exists and have been
                copied from an already existing track and the compression
                workspace is preserved from that track

 On exit
        All registers must be preserved
        V flag set if the code was unable to create the file

 When SWI ProSound_InitTrack is called, it calls CreateTrack_Code before
allocating workspace for the track (cache, memory map, envelope etc.).


 RemoveTrack_Code
 ----------------
 This is called to remove a track. OpenFile_Code is always called before this
entry is called, to ensure that the file is closed.

 On entry
        R0  =>  Track

 On exit
        All registers must be preserved


 InsertSamples_Code
 ------------------
 This is called to insert a number of samples at any position in the file.
 The length of the file should not be altered.

 On entry
        R0  =>  Track
        R1  =   Sample index of sample to insert AFTER
        R2  =   Number of samples to insert

 On exit
        R2  =   Number of samples inserted
        All other registers preserved


 RemoveSamples_Code
 ------------------
 This is called to remove a number of samples from a track.
 The length of the file should not be altered.

 On entry
        R0  =>  Track
        R1  =   Sample index of first sample to remove
        R2  =   Number of samples to remove

 On exit
        All registers preserved


 ExtendFile_Code
 ---------------
 This is called to extend or shrink the length of a track.
 The code should update the length of the file (stored at R0+244).

 On entry
        R0  =>  Track
        R1  =   New duration (in samples)

 On exit
        R1  =   Actual new duration (in samples)
        All other registers preserved


 OpenFile_Code
 -------------
 This is called to open/close a track file.

 On entry
        R0  =>  Track
        R1  =   0 (open) or 1 (close)

 On exit
        All registers preserved


 Decompress_Code
 ---------------
 This call decompresses a chunk (CS bytes) to <SPC> 16 bits samples.

 On entry
        R0  =>  Track
        R1  =>  Chunk buffer (CS bytes)
        R2  =>  Output buffer (SPC * 2 bytes)

 On exit
        All registers preserved


 Compress_Code
 -------------
 This call compresses <SPC> samples to a chunk.

 On entry
        R0  =>  Track
        R1  =>  Chunk buffer (CS bytes)
        R2  =>  Input buffer (SPC * 2 bytes)

 On exit
        All registers preserved
