home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / waveedit / !WaveEdit / Dox / WESound < prev   
Text File  |  1993-11-14  |  14KB  |  394 lines
  1.                             WESound 1.20 docs.
  2.                             ==================
  3.  
  4.   WESound has no commands, but a lot of SWI's. It is designed to keep a
  5. sample in memory for modifying or playing.
  6.  
  7.  
  8.  
  9.                              Short SWI list
  10.                              ==============
  11.  
  12.  &C0080 WE_Load         Load a sample into memory
  13.  &C0081 WE_LoadAt       Load a sample at a specified position
  14.  &C0082 WE_Save         Save (part of) the sample in memory
  15.  &C0083 WE_Free         Forget the sample and free the memory
  16.  &C0084 WE_Peek         Read a value from the sample
  17.  &C0085 WE_LinPeek      Read a linear value from the sample
  18.  &C0086 WE_Poke         Store a value in the sample
  19.  &C0087 WE_LinPoke      Store a linear value in the sample
  20.  &C0088 WE_Play         Prepare to play (part of) the sample
  21.  &C0089 WE_Amplify      Amplify one value
  22.  &C008A WE_AmplifyPart  Amplify part of the sample
  23.  &C008B WE_Convert      Convert (part of) the sample from lin to log
  24.  &C008C WE_LinToLog     Convert a linear value to log
  25.  &C008D WE_LogToLin     Convert a logarithmic value to lin
  26.  &C008E WE_Redraw       Plot the sample to the vdu
  27.  &C008F WE_Reverse      Reverse (part of) the sample
  28.  &C0090 WE_Extend       Extend the sample while possibly moving it
  29.  &C0091 WE_Reduce       Reduce the length of the sample
  30.  &C0092 WE_Copy         Copy part of the sample
  31.  &C0093 WE_Create       Create an empty sample
  32.  &C0094 WE_Maximum      Return maximum in (part of) the sample
  33.  &C0095 WE_Sample       Read data from the ADC into the sample
  34.  &C0096 WE_Length       Return length of sample using a given threshold
  35.  &C0097 WE_AppendData   Append (part of) the sample to an open file
  36.  &C0098 WE_UpdatePars   Adjust the parametres while playing the sample
  37.  &C0099 WE_SetVars      Set modes for redrawing
  38.  &C009A WE_Update       Update a part of the sample to the vdu.
  39.  &C009B WE_Mix          Mix one part of the sample with another.
  40.  
  41.  
  42.                                SWIs in detail
  43.                                ==============
  44.  
  45. General note: When few or no errors are listed under 'Possible errors', care
  46. should be taken about the parametres passed to the routine. There are no
  47. bounds checking in these routines.
  48.  
  49.  
  50.   &C0080 'WE_Load' Load a sample into memory
  51.   ------------------------------------------
  52.   On entry: R0 = Pointer to zero-terminated filename
  53.   On exit:  R0 = Length of file
  54.  
  55.   This call will claim sufficient memory from the RMA and load a file into
  56. it. This cannot be done if a sample has already been loaded, you must call
  57. WE_Free (&C0083) first to release the memory.
  58.  
  59. Possible errors:
  60.  'Sample memory occupied',
  61.  'Can't claim enough RMA space'
  62.  
  63.  
  64.   &C0081 'WE_LoadAt' Load a sample at a specified position
  65.   --------------------------------------------------------
  66.   On entry: R0 = Pointer to zero-terminated filename
  67.             R1 = Destination offset
  68.  
  69.   A file is loaded starting from the given position in an existing sample.
  70. Care must be taken to ensure that there is sufficient room for the resulting
  71. sample, i.e. if the loading of the file would make the sample longer, you
  72. must use 'WE_Extend' first. 
  73.  
  74.  
  75.   &C0082 'WE_Save' Save (part of) the sample in memory
  76.   ----------------------------------------------------
  77.   On entry: R0 = Pointer to zero-terminated filename
  78.             R1 = Filetype to give the file
  79.             R2 = Start offset into sample
  80.             R3 = End offset into sample +1
  81.   
  82.   This SWI will save part of the sample as a file.
  83.  
  84.  
  85.   &C0083 'WE_Free' Forget the sample and free the memory
  86.   ------------------------------------------------------
  87.   This SWI takes no parametres and will simply release the memory previously
  88. occupied by the sample. Don't Free a sample while it's sounding!
  89.  
  90.  
  91.  
  92.   &C0084 'WE_Peek' Read a value from the sample
  93.   ---------------------------------------------
  94.   On entry: R0 = Offset into sample
  95.   On exit:  R0 = Value at offset
  96.  
  97.   Returns the value at the given offset as a logarithmic value.
  98.  
  99. Possible errors:
  100.  'Read operation beyond end of sample'
  101.  
  102.  
  103.   &C0085 'WE_LinPeek' Read a linear value from the sample
  104.   -------------------------------------------------------
  105.   On entry: R0 = Offset into sample
  106.   On exit:  R0 = Value at offset converted to linear
  107.  
  108.   Returns the value at the given offset as a 13-bit signed linear value.
  109.  
  110. Possible errors:
  111.  'Read operation beyond end of sample'
  112.  
  113.  
  114.   &C0086 'WE_Poke' Store a value in the sample
  115.   --------------------------------------------
  116.   On entry: R0 = Offset into sample
  117.             R1 = Value to store at offset
  118.  
  119.   Stores the given 8-bit logarithmic value at the specified offset into the
  120. sample.
  121.  
  122. Possible errors:
  123.  'Write operation beyond end of sample'
  124.  
  125.  
  126.   &C0087 'WE_LinPoke' Store a linear value in the sample
  127.   ------------------------------------------------------
  128.   On entry: R0 = Offset into sample
  129.             R1 = Linear value to store at offset
  130.  
  131.   Stores the given 13-bit signed linear value at the specified offset after
  132. converting it to log.
  133.  
  134. Possible errors:
  135.  'Write operation beyond end of sample'
  136.  
  137.  
  138.   &C0088 'WE_Play' Prepare to play (part of) the sample
  139.   -----------------------------------------------------
  140.   On entry: R0 = Start offset
  141.             R1 = End offset
  142.             R2 = Loop flag
  143.             R3 = Loop start offset (*)
  144.             R4 = Loop end offset (*)
  145.  
  146.   This SWI prepares the voice routine for playing the specified part of the
  147. sample at the next Sound command. The Loop flag is either -1 or 0 to use the
  148. loop data or not. Note, that the loop offsets are offsets from the start
  149. point rather than from the start of the sample. The sound is then controlled
  150. as follows:
  151.  
  152.  SOUND 1,&17F,<pitch>,255  to play the sample. (GateOn)
  153.  SOUND 1,&180,<pitch>,255  to stop the sample. (GateOff)
  154.  
  155. The pitch is needed in the gate-off command because the sound is not
  156. immediately cut off but scaled lineary to 0-amplitude in approx. 0.1 sec.
  157. Without looping, the playing routine just plays the sample to the end unless
  158. stopped by you. When looping, it will play as follows:
  159.  
  160. Sample offset
  161.    ^
  162.  SE+
  163.    |                               /
  164.    |                              /
  165.    |                             /
  166.  LE+                            /
  167.    |            /    /    /    /
  168.    |           /    /    /    /
  169.    |          /    /    /    /
  170.    |         /    /    /    /
  171.  LS+        /    /    /    /
  172.    |       /     
  173.    |      /                 |
  174.    |     /                  |
  175.    |    /                   |
  176.    |  |/                    |
  177.  SS+--+---------------------+-------> Time
  178.       |                     |
  179.     GateOn               GateOff
  180.  
  181.  SS = Sample start,   LS = Loop start,   LE = Loop end,   SE = Sample end
  182.  
  183.   Once the GateOff is triggered, the looping is cancelled, and the sample is
  184. played to the end. That's why it's vital always to have some form of fading
  185. at the end of the sample. If, however, the GateOff is received before the
  186. looping has begun, the sound is faded at once, like when no looping is being
  187. used.
  188.  
  189. Possible errors:
  190.  'No sample to play',
  191.  'Can't start beyond end of sample',
  192.  'Can't play beyond end of sample'
  193.  
  194.  
  195.   &C0089 'WE_Amplify' Amplify one value
  196.   -------------------------------------
  197.   On entry: R0 = Offset into sample
  198.             R1 = Gain
  199.  
  200.   This SWI will amplify a single value in the sample by the gain specified.
  201. The gain is given as a fixed point value with the point at bit 17. I.e. to
  202. convert a Basic floating point variable 'Gain' into a suitable value, use:
  203.  
  204.   SYS "WE_Amplify",Offset%,Gain*&20000
  205.  
  206.  
  207.   &C008A 'WE_AmplifyPart' Amplify part of the sample
  208.   --------------------------------------------------
  209.   On entry: R0 = Start offset into sample
  210.             R1 = End offset into sample
  211.             R2 = Gain
  212.  
  213.   This call will amplify a given part of the sample by the given gain. The
  214. gain is of the same type as in 'WE_Amplify'.
  215.  
  216.  
  217.   &C008B 'WE_Convert' Convert (part of) the sample from lin to log
  218.   ----------------------------------------------------------------
  219.   On entry: R0 = Start offset
  220.             R1 = End offset
  221.  
  222.   This SWI expects the values at the positions specified to be signed 8-bit
  223. linear values. It will then convert them to logarithmic values.
  224.  
  225.  
  226.   &C008C 'WE_LinToLog' Convert a