home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsc / computils / !CompUtils / Resources / ExpCode / Docs next >
Encoding:
Text File  |  1995-08-03  |  11.8 KB  |  279 lines
  1. ############################################################################
  2. #                                                                          #
  3. #                              ExpCode utility                             #
  4. #                                                                          #
  5. #==========================================================================#
  6. #                                                                          #
  7. #                              by David Radford                            #
  8. #                                                                          #
  9. #==========================================================================#
  10. #                                                                          #
  11. #     These files are a part of !CompUtils and may not be distributed      #
  12. #         separately other than as laid down in the !ReadMe file.          #
  13. #                                                                          #
  14. ############################################################################
  15.  
  16. Overview
  17. ========
  18.  
  19. This directory contains a short piece of code called ExpCode (in several
  20. 'flavours'), which will expand compressed samples produced using the
  21. !Compress application or one of the Compress utilities. It is intended for
  22. use by programmers who wish to use squashed samples in their own programs.
  23. ExpCode is basically just Expand with some additional code added to tailor
  24. it for main use of Expand: decompressing a sample straight from a file to
  25. memory. It reduces the flexibility of Expand but is much easier to use.
  26.  
  27.  
  28. The ExpCode utility
  29. ===================
  30.  
  31. ExpCode provides an interface with the Expand utility, designed to reduce
  32. the amount of programming YOU have to do to a minimum when you just require
  33. the simplest function of Expand.
  34.  
  35. There is a version of ExpCode for each version of Expand ie. one for each
  36. group of sample types (Type0-2, Type6) together with a Universal version
  37. which will decompress anything. Naturally, the Universal version is much
  38. larger than the others.
  39.  
  40. ExpCode, like Expand, has a general header at the start used for passing
  41. parameters. Where possible this has been designed to conform as closely as
  42. possible to the one used by Expand. The layout is as follows:
  43.  
  44.     +0  branch instruction to ExpCode_InitCode
  45.     +4  branch instruction to ExpCode_ProcessCode
  46.     +8  filetype for compressed samples
  47.    +12  pointer to the source buffer (user provided)
  48.    +16  length of source buffer (user provided)
  49.    +20  pointer to the destination buffer (user provided)
  50.    +24  length of destination buffer (user provided)
  51.    +28  ptr to source filename (user provided)
  52.    +32  sample period of output sample
  53.    +36  output flags (user provided)
  54.    +40  length of final sample
  55.    +44  offset into file of actual data (user provided)
  56.  
  57. Your program can decompress a sample in a series of simple steps:
  58.  
  59.  1) Reserve space for a source buffer (no minimum, but less than 256 bytes
  60.     would probably cripple performance).
  61.  2) Set +12 to point to this buffer.
  62.  3) Set +16 to the length of this buffer.
  63.  4) Set +28 to point to the filename of the sample to decompress.
  64.  5) Set +36 (flags) as for Expand. Refer to the documentation in Expand's
  65.     directory for details.
  66.  6) Set +44 to the offset into the file of the actual data (usually zero).
  67.     Non-zero values are useful for sample libraries, or for adding some
  68.     extra information of your own to the start of the file.
  69.  7) Call +0 to initialise the code. This sets up the values at +32 and +40.
  70.     After the call, R0 is zero and the V flag is clear if no error occurred,
  71.     otherwise the V flag is set and R0 points to a standard error block. If
  72.     an error has occurred you should abort the operation.
  73.  8) Use the value at +40 to create space to store the final sample.
  74.  9) Set +20 to point to this area of memory.
  75. 10) Set +24 to the length of the area, which must be greater than or equal
  76.     to the value at +40.
  77. 11) Call +4 to decompress the sample in your chosen format. After the call,
  78.     R0 and the V flag have been set up in the same manner as in step 6.
  79.  
  80. All samples are decompressed without the sample period byte that Armadeus
  81. files provide at the start, but since the value is returned in the header
  82. you can add this to the output yourself if you want to produce Armadeus
  83. files.
  84.  
  85. The data offset at +44 may need some explaining. Normally you will just
  86. leave this value as zero. However, it is a fact that the amount of space
  87. taken up by several small files on a floppy disc is greater than the sum of
  88. their lengths. This is because a file always takes up a whole number of
  89. sectors on a disc. If each sector is 1024 bytes long, a file of size 4123
  90. would actually occupy 5120 bytes of disc space (5*1024). This obviously
  91. means that some space is wasted.
  92.  
  93. A way of getting round this problem is to add the files together into one
  94. large file (a sample library). This makes more efficient use of the
  95. available disc space. As you do this, make a list of the positions of each
  96. of the small files in the library. These file offsets can then be supplied
  97. at +44, with a pointer to the file name of the library at +28, and the
  98. sample will be decompressed exactly as if it were a separate file.
  99.  
  100. Details of a standard file format for library files can be found in the
  101. documentation in the LoadSample directory. The LoadSample module fully
  102. supports this format, as does SamplePlayer (from !Player) after version
  103. 1.23.
  104.  
  105.  
  106. Technical details
  107. =================
  108.  
  109. (Basic and C programmers can ignore all this information.)
  110.  
  111. Both machine code routines require R14 to give a return address. All
  112. registers are preserved (except R14 and R0), and a temporary stack is set up
  113. inside ExpCode for use by Expand, so you needn't worry about R13 containing
  114. a stack pointer.
  115.  
  116. The exception to this is if you want to call ExpCode from a non-user mode
  117. such as SVC mode (eg. for *commands, SWI handlers, module initialisation
  118. code, etc.), since the internal stack used by ExpCode in USR mode is not
  119. large enough to cope with the demands of RISC OS interrupt-driven routines
  120. as well. If ExpCode is entered in a non-user mode it will automatically
  121. detect this and NOT use it's own stack, but instead use the stack pointer
  122. passed in R13.
  123.  
  124. There is a potential problem when ExpCode is being used in IRQ mode (or FIQ
  125. mode for that matter) with interrupts enabled, since r14_irq can suddenly
  126. become corrupt. To avoid this change the ARM to either SVC or USR mode
  127. before calling ExpCode. This problem doesn't apply when using ExpCode from
  128. Basic of course.
  129.  
  130.  
  131. Output flags
  132. ============
  133.  
  134. See the documentation with Expand for a description of the output flags. Any
  135. flags modified by Expand (eg. the status flags in the top few bits of the
  136. word) will be returned correctly to your program through ExpCode's header.
  137.  
  138.  
  139. Filetypes
  140. =========
  141.  
  142. The filetype for compressed samples is not Acorn-allocated and could have to
  143. change in the future. To make upgrading easier, the filetype should not be
  144. assumed to be &350 but should be read from ExpCode's header.
  145.  
  146.  
  147. Using ExpCode with your own programs
  148. ====================================
  149.  
  150. Basic
  151. -----
  152.  
  153. Choose an appropriate ExpCode file and copy it into your application's
  154. directory. You can load it using something like this:
  155.  
  156.     SYS "OS_File",5,"<App$Dir>.ExpCode" TO a%,,,,l%
  157.     IF a%<>1 THEN l%=16
  158.     DIM expcode% l%
  159.     SYS "OS_File",255,"<App$Dir>.ExpCode",expcode%,0
  160.  
  161. and the code can be called with:
  162.  
  163.     CALL expcode%+0
  164. or
  165.     CALL expcode%+4
  166.  
  167.  
  168. Assembler
  169. ---------
  170.  
  171. When including ExpCode in your own programs there is no reason why it has to
  172. be kept as a separate file in your application's directory. It is actually
  173. designed to be embedded somewhere in the middle of your own code. Refer to
  174. the Technical Details section for more information on calling ExpCode from
  175. machine code programs.
  176.  
  177.  
  178. ObjAsm
  179. ------
  180.  
  181. Users of Acorn's Desktop Assembler will find an AOF version of ExpCode in
  182. the 'asm' sub-directory. A header file is provided to IMPORT all the symbols
  183. you'll need. All you have to do is include the line:
  184.  
  185.         GET     CompUtils:ExpCode.asm.h.Universal
  186.  
  187. at the start of your source code, then add the appropriate object file to
  188. the list of objects and libraries to be linked. There is one object file
  189. for each group of sample types supported (eg. Type0-2, Type6, etc) plus a
  190. 'Universal' version incorporating all of these. Only one header file
  191. is provided (Universal) because the header would be the same for each object
  192. file anyway. By the way, only one ExpCode object can be linked to your code,
  193. unlike Compress. If you need two or more then use the Universal version.
  194.  
  195. The header file imports symbols for the start of the ExpCode header
  196. (ExpCode) and each of the two entry points (ExpCode_InitCode and
  197. ExpCode_ProcessCode). It also defines symbols for offsets from the start of
  198. the header to various entries in the header (eg. ExpCode_SrcBufferPtr,
  199. ExpCode_SamplePeriod, etc). So, to read the sample period you would use
  200. something like this:
  201.  
  202.         LDR     R0,=ExpCode
  203.         LDR     R1,[R0,#ExpCode_SamplePeriod]
  204.  
  205. The first instruction transfers the address of ExpCode's header into R0,
  206. then the second instruction transfers the contents of the sample period
  207. entry into R1. To call ExpCode use:
  208.  
  209.         BL      ExpCode_InitCode
  210. or
  211.         BL      ExpCode_ProcessCode
  212.  
  213. Apart from these symbols, the header file also defines a series of symbols
  214. for various bits in the output flags eg. OUTPUT_LINEAR, FILE_IS_16BIT, etc.
  215. These should be used in preference to actual values (eg. 1<<2 or 4+2+1)
  216. where possible to allow these to be changed in the future, should the need
  217. arrise. It can also be used to highlight trouble spots, if a bit's meaning
  218. changes.
  219.  
  220.  
  221. C/APCS
  222. ------
  223.  
  224. For C users, a header file and a series of object files can be been found
  225. in the 'cc' sub-directory. Only one header file is provided (Universal)
  226. because all the decompressors have an identical user interface, so the
  227. Universal version can be used for any of them. An object file is provided
  228. for each group of sample types (eg. Type0-2, Type6, etc) plus a Universal
  229. version combining all of these. Only one of these object files can be linked
  230. with your code; if you want more than one then use the Universal version
  231. instead.
  232.  
  233. The object code is APCS-compliant (obviously) so can be used from any APCS
  234. language, such as Pascal, C++, etc. You would have to write your own header
  235. file though - the one provided is for C, and should be included in your
  236. source with:
  237.  
  238. #include "CompUtils:ExpCode.cc.h.Universal"
  239.  
  240. It defines the entries in ExpCode's header as global variables that can be
  241. accessed just like normal variables eg.
  242.  
  243.         int     filetype;
  244.         int     count;
  245.         char    *buffer;
  246.         char    bytes[16];
  247.         
  248.         filetype = ExpCode_SampleType;
  249.         buffer = ExpCode_SrcBufferPtr;
  250.         for (count = 0; count < 16; count++)
  251.             bytes[count] = buffer[count];
  252.         
  253. Apart from these variables, the header file also defines a series of symbols
  254. for various bits in the output flags eg. OUTPUT_LINEAR, FILE_IS_16BIT, etc.
  255. These should be used in preference to actual values (eg. 1<<2 or 4+2+1)
  256. where possible to allow these to be changed in the future, should the need
  257. arrise. It can also be used to highlight trouble spots: if a bit's meaning
  258. changes then so would the name attached to it, and the compiler would spot
  259. the fact that the symbol no longer exists.
  260.  
  261. The two entry points are defined as functions with no arguments and
  262. returning a pointer to a structure of type 'os_error' (a null pointer if no
  263. error occured). This is just like most of the RISC OS library functions.
  264.  
  265.  
  266. Bugs
  267. ====
  268.  
  269. There may well be some bugs lurking around, particularly in the ObjAsm and C
  270. versions of ExpCode (I never use these myself). They have been tested with
  271. the example programs so they should work, but you never know. Please report
  272. any bugs, omissions or suggestions for improvement to one of the addresses
  273. in the main !ReadMe file.
  274.  
  275.  
  276.                            (c) David Radford
  277.  
  278.  
  279.