home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / sound / waveedit / !WaveEdit / Dox / WESound < prev   
Encoding:
Text File  |  1993-11-14  |  13.9 KB  |  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 linear value to log
  227.   --------------------------------------------------
  228.   On entry: R0 = Signed 13-bit linear value
  229.   On exit:  R0 = 8-bit logarithmic value
  230.  
  231.   Converts a linear value to the logarithmic approximation.
  232.  
  233.  
  234.   &C008D 'WE_LogToLin' Convert a logarithmic value to lin
  235.   -------------------------------------------------------
  236.   On entry: R0 = 8-bit logarithmic value
  237.   On exit:  R0 = Signed 13-bit linear value
  238.  
  239.   Converts a logarithmic value to the linear approximation.
  240.  
  241.  
  242.   &C008E 'WE_Redraw' Plot the sample to the vdu
  243.   ---------------------------------------------
  244.   On entry: R1 = Pointer to normal Wimp_RedrawWindow block.
  245.  
  246.   This SWI will plot (part of) the sample on the screen using the supplied
  247. values. It's suitable for displaying the sample in a window. Before this SWI
  248. is called, WE_SetVars (&C0099) should be called at least once to specify
  249. various values. It is intended for being called in response to a
  250. RedrawWindow poll action.
  251.  
  252.  
  253.   &C008F 'WE_Reverse' Reverse (part of) the sample
  254.   ------------------------------------------------
  255.   On entry: R0 = Start offset into sample
  256.             R1 = End offset into sample
  257.  
  258.   This SWI will reverse the order of the values in the given part of the
  259. sample.
  260.  
  261.  
  262.   &C0090 'WE_Extend' Extend the sample while possibly moving it
  263.   -------------------------------------------------------------
  264.   On entry: R0 = New length
  265.             R1 = New offset to put old data from
  266.  
  267.   This SWI will attempt to extend the sample to the given length. After
  268. doing this, the data is moved to the given offset into the new sample.
  269. In the current version of the module, space must be available for both the
  270. old and the new sample. This will be changed some day.
  271.  
  272. Possible errors:
  273.  'Can't claim enough RMA space'
  274.  
  275.  
  276.   &C0091 'WE_Reduce' Reduce the length of the sample
  277.   --------------------------------------------------
  278.   On entry: R0 = New length
  279.  
  280.   This SWI will reduce the length of the sample to the new length given. In
  281. the current version of the module, space must be available for both the old
  282. and the new sample. This will be changed the same day.
  283.  
  284. Possible errors:
  285.  'Can't claim enough RMA space'
  286.  
  287.  
  288.   &C0092 'WE_Copy' Copy part of the sample
  289.   ----------------------------------------
  290.   On entry: R0 = Source start offset
  291.             R1 = Source end offset
  292.             R2 = Destination start offset
  293.  
  294.   This SWI will copy the specified part of the sample to the new position
  295. given.
  296.  
  297.              
  298.   &C0093 'WE_Create' Create an empty sample
  299.   -----------------------------------------
  300.   On entry: R0 = Length
  301.  
  302.   This call will claim the specified space as a sample and clear it to 0.
  303.  
  304.  
  305.   &C0094 'WE_Maximum' Return maximum in (part of) the sample
  306.   ----------------------------------------------------------
  307.   On entry: R0 = Start offset
  308.             R1 = End offset
  309.   On exit:  R0 = Maximum (signed 13-bit linear, but always positive)
  310.  
  311.   This SWI will read through the values at the range given, and return the
  312. absolute value of the largest one found.
  313.  
  314.  
  315.   &C0095 'WE_Sample' Read data from the ADC into the sample
  316.   ---------------------------------------------------------
  317.   On entry: R0 = Trigger level (13-bit positive linear value)
  318.             R1 = Sample period in 0.5 µs units
  319.  
  320.   This call will set up the neccesary parametres for an 'ADC_Sample' call
  321. and then call it. See the documentation about 'SampleMod' for a more
  322. detailed description about the sampling itself.
  323.  
  324.  
  325.   &C0096 'WE_Length' Return length of sample using a given threshold
  326.   ------------------------------------------------------------------
  327.   On entry: R0 = Threshold (signed 13-bit linear, should be positive)
  328.   On exit:  R0 = Offset to last value 
  329.  
  330.   This SWI will search through the sample for the last value greater than or
  331. equal to the threshold given. It is not used by WaveEdit, but by a program
  332. called AutoSample to find the audible end of a sample.
  333.  
  334.  
  335.   &C0097 'WE_AppendData' Append (part of) the sample to an open file
  336.   ------------------------------------------------------------------
  337.   On entry: R0 = File handle
  338.             R1 = Start offset
  339.             R2 = End offset
  340.  
  341.   This SWI will simply append the specified part of the sample to an open
  342. file.
  343.  
  344.  
  345.   &C0098 'WE_UpdatePars' Adjust the parametres while playing the sample
  346.   ---------------------------------------------------------------------
  347.   On entry: R0 = Start offset
  348.             R1 = End offset
  349.             R2 = Loop flag
  350.             R3 = Loop start offset
  351.             R4 = Loop end offset
  352.  
  353.   This SWI takes the same parametres as 'WE_Play', but can be called while
  354. the sample is being played. The changes come into effect on the next buffer
  355. fill event.
  356.  
  357. Possible errors:
  358.  'No sample to play',
  359.  'Can't start beyond end of sample',
  360.  'Can't play beyond end of sample'
  361.  
  362.   &C0099 'WE_SetVars' Set WE_Redraw and WE_Update parametres
  363.   ----------------------------------------------------------
  364.   On entry: R0 = Window handle
  365.             R1 = Start mark or -1
  366.             R2 = End mark (if R1<>-1)
  367.             R3 = Zoom
  368.             R4 = Cursor position or -1
  369.             R5 = Line mode
  370.             
  371.   This SWI sets up the way to display the sample. R1, R2 and R4 are all
  372. offsets in bytes from the start of the sample. R1=-1 means that no area is
  373. marked. Zoom is log2 to the zoom factor, 0 being 1:1. Line mode is 0-3 for
  374. Dots, Amp, Line and Full.
  375.         
  376.  
  377.   &C009A 'WE_Update' Update the sample on the vdu
  378.   -----------------------------------------------
  379.   On entry: R0 = Start offset
  380.             R1 = End offset
  381.  
  382.   This SWI will update part of the sample by calling Wimp_UpdateWindow and
  383. then entering the redraw loop as WE_Redraw. WE_SetVars (&C0099) should be
  384. called at least once before this SWI is called.
  385.  
  386.   &C009B 'WE_Mix' Mix part of the sample with another
  387.   ---------------------------------------------------
  388.   On entry: R0 = Destination start offset
  389.             R1 = Destination end offset
  390.             R2 = Mix start offset
  391.  
  392.   This SWI will overlay the specified part of the sample with another part,
  393. starting at R2.
  394.