home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsc / computils / !CompUtils / Resources / LoadSample / Docs < prev    next >
Encoding:
Text File  |  1995-07-30  |  6.7 KB  |  159 lines
  1. ############################################################################
  2. #                                                                          #
  3. #                            SampleLoader module                           #
  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 module which allows you to decompress samples
  20. using simple *commands. The module is not really a very practical way of
  21. adding support of compressed samples to a multitasking application, since it
  22. would be yet ANOTHER module loaded into the RMA. However, for games and
  23. other single-tasking applications it would be perfectly okay providing you
  24. remember to kill it off after you have finished with it.
  25.  
  26.  
  27. The *commands
  28. =============
  29.  
  30. There are three *commands:
  31.  
  32.  
  33. *LoadSampleBufferSize <size>
  34. ----------------------------
  35.  
  36. This command attempts to claim a block of memory from the RMA to use as a
  37. source buffer during decompression. <size> is given as a number of bytes,
  38. and the default base is base 10. The minimum value is 16 bytes (but it
  39. isn't really sensible to go below 256 bytes), and the maximum is 40960 (40K).
  40. The module automatically claims a 2048-byte buffer (2K) when first loaded,
  41. and this may well be sufficient for most needs. Increasing the buffer size
  42. *should* speed up loading from floppy discs.
  43.  
  44.  
  45. *LoadSampleType 0|1
  46. -------------------
  47.  
  48. This command allows you to choose the output format of all subsequent
  49. samples. 0 is logarithmic (VIDC format), and 1 is linear signed. The default
  50. value is 0.
  51.  
  52.  
  53. *LoadSample <filename> <load address> [<sample ID> [<header address>]]
  54. ----------------------------------------------------------------------
  55.  
  56. This is the main command. In its most simple form, it takes the file given
  57. and decompresses to the specified address. (The default base for the address
  58. is base 16, ie. hexadecimal.) Be sure that you have enough memory spare to
  59. load the sample. Remember that the file size of a compressed sample is far
  60. smaller than the size of the actual decompressed sample! On a normal file,
  61. the <sample ID> parameter is ignored if given.
  62.  
  63. As well as standard compressed files, the module also supports library
  64. files. These consist of several compressed samples all lumped together into
  65. one file. The format of these files is given in a later section of this
  66. document.
  67.  
  68. Since library files can hold many samples, each sample is given a unique
  69. sample ID. When a library file is accessed by the module, it attempts to
  70. load the sample referenced by <sample ID>. If the parameter is omitted, the
  71. first sample in the library is used instead. An error is generated if the ID
  72. didn't match any of the samples (the test is case-insensitive).
  73.  
  74. The header and table of entries in a library can be separated from the main
  75. library and stored somewhere in a separate file. This has the advantage that
  76. it may be more readily accessable from another program, and it also stops
  77. people pinching samples from your library, since only the first sample can
  78. be recovered without the list of file offsets. If you do this, the header
  79. must have been loaded into some area of memory before using the *command.
  80. The address can then be passed in hexadecimal as <header address>.
  81.  
  82. Note that the decompressed sample is stored as raw 8-bit data. The sample
  83. period information is omitted.
  84.  
  85.  
  86. Libraries
  87. =========
  88.  
  89. The filetype for a library is &FFD (Data) though this may change in the
  90. future. The basic layout of a standard library is:
  91.  
  92.         1) Header
  93.         2) Table of entries
  94.         3) Compressed sample data
  95.  
  96. The first two of these can be held in a separate file from the third, should
  97. you so desire.
  98.  
  99. The header is 12 bytes long:
  100.  
  101.         +0  Four byte text string ("LIBR") identifying this as a library.
  102.         +4  Number of entries in table
  103.         +8  Length of each entry
  104.  
  105. This is immediately followed by the table. Each entry is currently 24 bytes
  106. long, but this could increase in the future, so make sure you use the value
  107. in the header when reading the file.
  108.  
  109.         +0  Sample ID. Up to ten characters, followed by a <CR>.
  110.        +12  Offset into library file of the associated sample data.
  111.        +16  The length of the compressed sample data.
  112.        +20  The length of the original sample.
  113.  
  114. Libraries are supported by the SamplePlayer module (part of !Player) from
  115. version 1.23 onwards.
  116.  
  117.  
  118. Producing libraries
  119. ===================
  120.  
  121. At the moment there is no fancy multitasking program to construct library
  122. files. There is, however, a simple basic program which performs the task
  123. called 'BuildLib'. You'll find it in the same directory as this !Help file.
  124. Details of the library to be created are passed to BuildLib in a text file,
  125. the name of which is held at the start of the program (currently
  126. RAM:$.TextFile). You can change this if you wish. If you want your library
  127. to hold more than 100 samples, you should also increase the value of
  128. maxentries% in the following line.
  129.  
  130. Each piece of information in the text file contains a single piece of
  131. information. Spaces at the start and ends of lines are ignored, so this can
  132. be used to increase readability. The format of the text file is as follows:
  133.  
  134.         1) Prefix for list of samples
  135.         2) Output filename of main library
  136.         3) Output filename of library header
  137.         4) List of samples for inclusion, one per line.
  138.  
  139. If the filename for the library header is a blank line, the header will be
  140. included in the main library as normal. Each sample in the list has the
  141. prefix added to the start before use. The ID used for the sample is the
  142. leafname of the sample.
  143.  
  144.  
  145. Using the module with your own programs
  146. =======================================
  147.  
  148. The module uses ExpCode to do all its dirty work, so the same conditions of
  149. use that apply to Expand and ExpCode also apply to the module. Basically,
  150. don't tamper with it, don't pretend you wrote it, and if you use it, you
  151. must mention the author somewhere in the credits. See the !ReadMe file in
  152. the main directory for more information on copyright details and contact
  153. addresses.
  154.  
  155.  
  156.                            (c) David Radford
  157.  
  158.  
  159.