Alt+152

 Lord of the earwigs

 Michael Pohle
 Bahnhofstrae 20
 04626 Nbdenitz
 Germany

							     
 blackICe						    
							       
 Marko Lukat						       
 Venise-Gosnat-Strae 48				       
 14770 Brandenburg an der Havel				       
 Germany						        matrix



 specification

 matrixTRK v0.8502 (03 Apr 1996)

 copyright  1993-95 F.L. DESIGN
 copyright  1993-96 Lord of the earwigs
 portion copyright  1993-96 blackICe

 matrixLink is  1994-96 blackICe
 matrixSQSH is  1996 blackICe
 Dynamite is  1994 Straylight

      claimed Dynamite block ID's (if in use)
       &49445054 "IDPT"
       &49445143 "IDQC"
       &494453-- "IDS(&--)"

      (if there are clashes with other applications please let me know)




  ******



 file format [18021996.1904]
-
 chunk	MTRX	sign MTRX	start of track
		llllllll	total file length
-
 chunk	CTRL	sign CTRL
		ccvvpppp	cc   compression type for NAME, AUTH, SEQC
				     &00 none	(SEQC cccc field must be 0)
				     &01 Squash  Acorn Computers Ltd, 1991
				     &02 -
				     &04 -
				     &08 -
				     &10 -
				     &20 -
				     &40 -
				     &80 -
				vv   number of pattern voices

				     version  1 2 3 4 5 6 7 8 .. 31 32
				      0.8403	    x	    x
				      0.8426  x x x x x x x x .. x  x

				pppp number of patterns		(1..256)
		sssseeee	ssss number of samples		(1..255)
				eeee number of sequence entries (1..65535)
		cpgvisit	cp compatibility 0-S3M, 1-MOD
				gv global volume (0..64)
				is initial speed (1..255)
				it initial tempo (1..255)
		stereo 1	32 bit each
		   ..
		stereo <vv>
-
 chunk	NAME	sign NAME
		ccccrrrr	cccc compressed size | 0
				rrrr real length (ie uncompressed size)
		data		if cccc=0 then
				  length:=real length
				else
				  length:=cccc
				endif
				size:=(length+3)AND-4
-
 chunk	AUTH	sign AUTH
		ccccrrrr	see NAME
		data
-
 chunk	SEQC	sign SEQC
		ccccrrrr	see NAME
		data
-
 chunk	PATT	sign PATT	(pattern order is fixed, according 2 SEQC)
		ccvvpppp	see CTRL
		cccccccc	32 bit compressed size
		rrrrrrrr	32 bit real length
		data		size see NAME
-
 chunk	SAMP	sign SAMP	(for each sample, means <ssss> SAMP chunks)
		32 bytes name	(without trailing zero when fully used)
		repeat start	32 bit
		repeat end	32 bit
		volume		32 bit
		nnnnffff	sample recording note and frequency
				nnnn record note      (default C-4, 428<<2)
				ffff sample frequency (default 8363Hz)
		ccdd??ff	cc compression type
				dd depth (bits/sixel)
				?? reserved (should be 0)
				ff format bit0=0 logarithm
					      =1 linear
					  bit1=0 signed
					      =1 unsigned

				   version  %00 %10 %01 %11
				    0.8403   x
				    0.8420   x	     x	 x

		cccccccc	32 bit compressed size
		rrrrrrrr	32 bit real length
		data		size see NAME
-
 chunk	ETRK	sign ETRK	end of track



  ******



 SWI interface

 chunk base : &4BD40 (registered)
 prefix	    : matrix (access through matrixLink interface)
-
 name	       usage
-
 TRKVersion    on entry  -
 &4BD50	       on exit	 R0 version number (&12345678 > 1234.5678)

	       registers preserved except R0
-
 TRKLoad       on entry  R0 pointer to file name/aligned memory location
 &4BD51			 R1  =0 load from file
			    <>0 load from memory (R1=length)
	       on exit	 R0 preserved
			 R1  =0 load succeeded
			    <>0 load failed
			 R2 specific error code if R1<>0
			    else preserved

	       registers preserved except R1[,R2]
-
 TRKLink       on entry  R0  =0 for internal use only (C.K.T.C.)
 &4BD52			    <>0 link channel handler
	       on exit	 R2 return code
			    0 link succeeded
			    1 track already linked
			    2 no track available (load status 0)
			    3 track not complete
			    4 number of voices out of range

	       track overall volume is set to current system volume

	       registers preserved except R2
-
 TRKUnlink     on entry  -
 &4BD53	       on exit	 R2 return code
			    0 unlink succeeded
			    1 no track linked

	       registers preserved except R2
-
 TRKRelease    on entry  -
 &4BD54	       on exit	 R2 return code
			    0	 release succeeded or nothing to release
			    &YX1 release failed

			     %xxxx
			     %---1 release of patterns failed
			     %--1- release of sequence failed
			     %-1-- release of at least one sample failed
			     %1--- release of sample attribute space failed

			     %yyyy external flags
			     %---1 pattern data
			     %--1- sequence table
			     %-1-- at least one sample
			     %1--- sample attribute space (incl. link code 2)

			    2	 track still linked

	       registers preserved except R2
-
 TRKSamplePeriod
 &4BD55	       on entry  R0 sample period in micro seconds (3..255)
			    0 inspect current value
	       on exit	 R0 previous sample period

	       registers preserved except R0
-
 TRKVolume     on entry  R0 new volume (0..64)
 &4BD56			    ]0..64[ to inspect current value
	       on exit	 R0 previous volume

	       mapping 0..64 linear 2 0..127 logarithm

	       registers preserved except R0
-
 TRKValidity   on entry  R0 pointer to file name/aligned memory location
 &4BD57			 R1  =0 check file
			    <>0 check memory (R1=length)
	       on exit	 R0 preserved
			 R1  =0 track valid
			    <>0 check failed
			 R2 specific error code if R1<>0
			    else required memory size
			 R3 decompression requirements (if R1=0)
			    bit 31-24 : compression for NAME/AUTH/SEQC
			    bit 23-16 : compression for PATT and/or SAMP
			    bit 15-00 : unused (zero)
			    else preserved

	       registers preserved except R1,R2[,R3]



  ******



 CLI interface
-

 ==> Help on keyword LinkTRK
     *LinkTRK links given track with sound system
     Syntax: *LinkTRK <filename>

 ==> Help on keyword UnlinkTRK
     *UnlinkTRK unlinks current track from sound system
     Syntax: *UnlinkTRK

 ==> Help on keyword TRKVolume
     *TRKVolume sets internal tracker volume (0..64 linear)
     Passing no parameter or values outside 0..64 results
     in providing current volume.
     Syntax: *TRKVolume [0..64]




  ******



 Service call interface (to install different/new decompressors)

 Service call base : &80400 (registered)
 Names aren't registered

 As long as matrix_TRKValidity detects compressed data matrix_TRKLoad
 performs the following installation sequence:

  1.  issue Service_ModulityIdentify
      - cancel SWI if OS_ServiceCall fails
  2.  if claimed then next type (decompressor already installed)
  3.  try loading decompressor via OS_Module,1,"<matrix$dcmpr?>"
      where ? is in [1..8] (i.e. lb(type)+1)
      example: Squash -> type &01 -> <matrix$dcmpr1>
			 type &80 -> <matrix$dcmpr8>
      - cancel SWI if OS_Module fails
  4.  issue Service_ModulityIdentify again
      - cancel SWI if OS_ServiceCall fails
      - cancel SWI if service is still not claimed
  5.  install next type

 The transfer itself is initiated with Service_ModulityTransfer. The Modulity
 must be able to decompress data of a given size from memory to memory or
 from file (handle is given) to memory (see Service_ModulityTransfer).
-
 Service_ModulityIdentify
 &80401

 on entry  R0 type &00 none (internal, i.e. plain copy)
		   &01 Squash  Acorn Computers Ltd, 1991
		   &02 -
		   &04 -
		   &08 -
		   &10 -
		   &20 -
		   &40 -
		   &80 -
	   R1 &80401

 on exit   R0 type
	   R1 0
	   R2 version number (format see matrix_TRKVersion)
-
 Service_ModulityTransfer
 &80402

 on entry  R0 type &00 none (internal, plain copy)
		   &01 Squash  Acorn Computers Ltd, 1991
		   &02 -
		   &04 -
		   &08 -
		   &10 -
		   &20 -
		   &40 -
		   &80 -
	   R1 &80402
	   R2 destination address
	   R3 number of bytes to read
	   R4 Fkt 3: offset
	      Fkt 4: -1 (use current/virtual filepointer)
	   R5 available output space
	   R6 flag (file/memory = 0/blocklength to check for EOM)
	      R6=0 (file)
	       R7 don't care
	       R8 file handle
	      R6<>0 (memory)
	       R7 virtual filepointer
		   Fkt 3: set R7=R4, read from [R8,R7]
		   Fkt 4:	     read from [R8,R7]
	       R8 source address

	   EOM end of memory (R8+R6)

 on exit   R0 rrrrrrtt
		rrrrrr - result code
			  0   transfer successful
			  <>0 error (type specific, EOF/EOM/..)
			      (if you are unable to pass this service on)
		    tt - type (for reference)
	   R1 0
	   R2 destination address + number of bytes transfered
	   R3 number of bytes not transfered
	   R5 amount of unused output space
	   R6 preserved
	      R6=0 (file)
	       R4 initial filepointer + number of bytes transfered
		  (if ascertainable, OS_GBPB may fail with VS)
		  else -1
	       R7 can be corrupted
	      R6<>0 (memory)
	       R4 virtual filepointer + number of bytes transfered
	       R7 virtual filepointer + number of bytes transfered
	   R8 preserved

 If you can't cope with this service you must not claim it. All registers
 must be preserved in this case (real filepointer too, R6=0).


 edited by blackICe 03 Apr 1996