home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PSION / MISC / PSTUNER / TSMP10FO / README.TXT next >
Encoding:
Text File  |  1994-04-06  |  8.5 KB  |  241 lines
  1. Using SMP: (SYS$SAMP.LDD), the sound sampling device driver
  2. ===========================================================
  3.  
  4. Files in this zip (TSMP10.ZIP)
  5. ------------------------------
  6. README.TXT      This documentation
  7. SYS$SAMP.LDD    The device driver itself
  8. SAMPLER.H       Header file (for C programming)
  9. TSMP.IMG        Example code ready build
  10. TSMP.C          Source of example code (C)
  11. TSMP.OPL        Example code (OPL)
  12. TSMP2.OPL       A second Opl example program
  13.  
  14. The basic idea of sound samples
  15. -------------------------------
  16. When the microphone is enabled, a "sound value" is provided, by the
  17. hardware, once every 8000th of a second.  This sound value is
  18. actually provided as an ALAW encoded byte (8 bit value).
  19.  
  20. The PLIB function p_recordsoundw (and related functions) write series
  21. of these sound values (or "sound samples") direct to a nominated
  22. file.  However, using SMP:, you can have these values placed into a
  23. buffer in your dataspace, that you can analyse directly.
  24.  
  25. You can either analyse these ALAW encoded values directly, or you can
  26. have SMP: return a buffer of decoded values - where the decoded
  27. values are 13 bit numbers in the range -4096 to +4096.
  28.  
  29. Once you have opened a channel to SMP:, you can use code as simple as
  30.     p_read(pcb,&buf[0],len);
  31. to read 'len' consecutive samples into a buffer.  The largest allowed
  32. value of 'len' is 4000, in which case the data in buf[] represents
  33. half a second of sound.
  34.  
  35. The supplied test program TSMP
  36. ------------------------------
  37. Copy TSMP.IMG into an \IMG\ directory.
  38. Copy SYS$SAMP.LDD into the root directory on the same device.
  39. Go to the RunImg icon, highlight "Tsmp", and press Enter.
  40. Press Enter again to accept the initial suggestion.
  41. You will see a continually refreshed graph of the sound going into
  42. the microphone at that very moment.
  43. Try whistling, talking, or making other noises.
  44. Exit the application from the Shell when you are bored with it.
  45.  
  46. Note that after you exit TSMP, by default the SMP: device driver is
  47. left loaded in memory (using up around 6k of RAM).  To clean this up,
  48. run the program again, but choose Esc at the initial query alert.
  49.  
  50. If you make a very short sound, TSMP may fail to pick this up - this
  51. is because TSMP *doesn't* monitor SMP: continuously - it spends a lot
  52. of time drawing its graph instead.  But you could rewrite TSMP in
  53. order to be more responsive.  Ie it could avoid making any display
  54. until the sound reached a higher threshold.  It could improve its
  55. performance even further by reading and analysing the ALAW encoded
  56. values directly, which is a faster service that reading the decoded
  57. values.
  58.  
  59. Warning: TSMP will keep your S3a switched on!  Be sure to exit it!
  60. Also, while it's running, it will prevent any other access to the
  61. sound system on the S3a - so no alarms will sound, etc.
  62.  
  63. The C source code and the Opl source code
  64. -----------------------------------------
  65. The code in TSMP.C and TSMP.OPL corresponds in all essential details.
  66. (Except that the C code runs in "compatibility mode".)
  67. For simplicity, I shall just describe the services of SMP: in terms
  68. of the C interface.
  69. (Though I have provided TWO Opl example programs, and only one in C.)
  70.  
  71. Basic pattern of use of SMP:
  72. ----------------------------
  73. Before you can use any of the services of SMP:, you have to open a
  74. channel to it, using p_open.  Eg
  75.  
  76.     LOCAL_C VOID OpenChannel(VOID)
  77.         {
  78.         INT ret;
  79.     
  80.         ret=p_open(&pcb,"SMP:",-1);
  81.         if (ret)
  82.             Panic(ret,"Failed to open channel to SMP");
  83.         }
  84.  
  85. This writes back into pcb the "handle" (the "Pointer to the Control
  86. Block") that you use in all subsequent p_read, p_iow, p_close (etc)
  87. calls to SMP:.
  88.  
  89. Before you can open a channel to SMP:, however, you have to ensure
  90. that the device driver SYS$SAMP.LDD has been loaded into memory.   Eg
  91.  
  92.     LOCAL_C VOID LoadDriver(VOID)
  93.         {
  94.         INT ret;
  95.         TEXT buf[P_FNAMESIZE];
  96.     
  97.         p_fparse("\\sys$samp.LDD",DatCommandPtr,&buf[0],NULL);
  98.         ret=p_loadldd(&buf[0]);
  99.         if (ret && ret!=E_FILE_EXIST)
  100.             Panic(ret,"Failed to load SYS$SAMP.LDD");
  101.         }
  102.  
  103. SMP: keeps recording samples internally all the time
  104. ----------------------------------------------------
  105. SMP: can have up to four open channels, from four different
  106. applications at the same time.
  107.  
  108. Whenever there is at least one open channel to SMP:, it keeps
  109. recording sample values internally.  These values then get written
  110. into applications' buffers when requested.
  111.  
  112. SMP: only keeps half a second's worth of samples, however.
  113.  
  114. Three modes of using SMP:
  115. -------------------------
  116. In the default mode ("P_SAMPLES_SINCE_LAST"), you ask for a fixed
  117. number of samples, and you at once get given either this number of
  118. samples, or as many as have been collected since the last time you
  119. requested samples (if this is less).
  120.  
  121. In the mode P_SAMPLES_FROM_LAST, you definitely get given the number
  122. of samples you ask for, starting from the last time you requested
  123. samples, and the call only completes when the required number of
  124. samples is ready.
  125.  
  126. In the mode P_SAMPLES_FROM_NOW, the same applies, but the samples
  127. only start from "now".
  128.  
  129. How to change the mode
  130. ----------------------
  131. You use the P_FSET function.  Thus
  132.     p_iow3(pcb,P_FSET,mode);
  133.  
  134. You can also sense the mode, using
  135.     WORD mode;
  136.     p_iow3(pcb,P_FSENSE,&mode);
  137.  
  138. Reading and "super-reading"
  139. ---------------------------
  140. The call
  141.     p_read(pcb,&buf[0],len);
  142. is just equivalent, as always, to
  143.     p_iow4(pcb,P_FREAD,&buf[0],&len);
  144.  
  145. Here, len is the number of WORDs of data in buf[].
  146.  
  147. If you prefer, you can use P_FRSUPER instead of P_FREAD, to read a
  148. number of BYTEs of ALAW encoded data - as discussed earlier.  In this
  149. case, there is no utility function p_read - you have to use the p_iow
  150. (or p_ioc etc) call.
  151.  
  152. In either P_FREAD or P_FRSUPER, the number of samples actually
  153. delivered is written back to the 'len' variable.
  154.  
  155. Note that only a single P_FREAD or P_FRSUPER per open channel should
  156. be pending at any one time.
  157.  
  158. Technical note
  159. --------------
  160. The "ALAW encoded data" provided by P_FRSUPER isn't exactly the same
  161. as provided by the raw CODEC hardware.  The value is inverted and
  162. then "magic xor-red" (to XOR all the even bits), before being
  163. returned to the application.  This means that a louder sound will
  164. give rise to a larger value.
  165.  
  166. (In contrast, the bytes written to file by services such as
  167. p_recordsoundw are *exactly* as provided by the CODEC.)
  168.  
  169. Synchronous and asynchronous calls
  170. ----------------------------------
  171. Like all device drivers, SMP: supports asynchronous versions of its
  172. services as well as synchronous ones.  And you can P_FCANCEL an
  173. outstanding asynchronous request.
  174.  
  175. Special utility conversion services
  176. -----------------------------------
  177. SMP: also provides a couple of conversion services, to convert a
  178. buffer of WORDs of decoded data into another buffer of BYTEs of ALAW
  179. encoded data, and vice versa.  These services both use the P_CONVERT
  180. struct, defined in the header file SAMPLER.H:
  181.  
  182.     typedef struct /* Conversion structure */
  183.         {
  184.         VOID *Source;
  185.         VOID *Destination;
  186.         } P_CONVERT;
  187.  
  188. For example,
  189.  
  190.     BYTE aLaw[4];
  191.     WORD Data[4];
  192.     P_CONVERT Conversion;
  193.  
  194.     Len=4;
  195.     Conversion.Source=&Data[0];
  196.     Conversion.Destination=&aLaw[0];
  197.     p_iow4(pcb,P_FCONVERT_TO,&Conversion,&Len);
  198.     Conversion.Source=&aLaw[0];
  199.     Conversion.Destination=&Data[0];
  200.     p_iow4(pcb,P_FCONVERT_FROM,&Conversion,&Len);
  201.  
  202. Values of some #define's (for Opl programmers)
  203. ----------------------------------------------
  204. #define P_FREAD   1
  205. #define P_FCANCEL 4
  206. #define P_FSET    7
  207. #define P_FSENSE  8
  208. #define P_FRSUPER 13
  209.  
  210. An example program using "super-reading"
  211. ----------------------------------------
  212. Have a look at TSMP2.OPL.  Try to figure out what happens when you
  213. run it, and then run it and see if you were right.
  214.  
  215. Some of the limitations in the performance in TSMP2.OPL are due to
  216. time wasted scanning the buffer for large values.  This time could be
  217. cut down by programming in C, or by creating some machine code and
  218. accessing that using USR.
  219.  
  220. Disclaimer
  221. ----------
  222. Psion will not be held responsible for any loss of data as a result
  223. of use of SYS$SAMP.LDD, which is still to an extent in an experimental
  224. phase.
  225.  
  226. SYS$SAMP.LDD is not an official Psion product.
  227.  
  228. It has not yet been exhaustively tested, and cannot be relied upon eg
  229. not to reset your S3a occasionally.
  230.  
  231. Distribution
  232. ------------
  233. You can freely distribute the file TSMP10.ZIP, but all the files in
  234. it should be kept together.
  235.  
  236. These notes prepared
  237. --------------------
  238. By David Wood, Psion Product Development, 24th March 1994.
  239. Revised, 6th April 1994 (TSMP2.OPL added.)
  240. All comments, bug reports etc welcome by EMAIL (eg CiX) ONLY.
  241.