home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 3 / 3593 / NOTES < prev    next >
Text File  |  1991-07-07  |  3KB  |  85 lines
  1. The internals of AUX are a little odd: there are separate
  2. read/write modules for each sample format, and their coding
  3. is quasi object-oriented.  
  4.  
  5. AUX includes skeleton handler files to assist you in supporting 
  6. new formats.  The full skeleton driver, skel.c, helps you write drivers 
  7. for a new format which has data structures.  The simple skeleton drivers
  8. help you write a new driver for raw (headerless) formats, or
  9. for formats which just have a simple header followed by raw data.
  10.  
  11. Most sound sample formats are fairly simple: they are just a string
  12. of bytes or words and are presumed to be sampled at a known data rate.
  13. The Sparcstation is an example of this: .AU files are headerless,
  14. logarithmically encoded (u-law) bytes, sampled at 8192 hertz.
  15. The file au.c implements this by setting the input or output parameters
  16. to these specifications and invokes the raw handler.
  17.  
  18. The 'tests' file shows how to specify the .AU parameters from the 
  19. command line.
  20.  
  21. Handler spec:
  22.  
  23. A handler is responsible for translating between sound sample files
  24. and an internal buffer.  The internal buffer is store in signed longs
  25. with a fixed sampling rate.  The handler operates from two data structures:
  26. a format structure, and a private structure.
  27.  
  28. The format structure contains a list of control parameters for
  29. the sample: sampling rate, data size (bytes, words, floats, etc.),
  30. style (unsigned, signed, logarithmic), number of sound channels.
  31. It also contains other state information: whether the sample file
  32. needs to be byte-swapped, whether fseek() will work, its suffix,
  33. its file stream pointer, its handler pointer, and the private
  34. structure for the handler.
  35.  
  36. The private handler is just a preallocated data array for the handler
  37. to use however it wishes.  It should have a defined data structure
  38. and cast the array to that structure.  See voc.c for the use of
  39. a private data area.  Voc.c has to track the number of samples it 
  40. writes and when finishing, seek back to the beginning of the file
  41. and write it out.
  42.  
  43. A handler has 6 routines:
  44.     startread
  45.         Set up the format parameters, or read in
  46.         a data header, or do what needs to be done.
  47.     read
  48.         Given a buffer and a length: 
  49.         read up to that many samples, 
  50.         transform them into signed long integers,
  51.         and copy them into the buffer.
  52.         Return the number of samples actually read.
  53.     stopread
  54.         Do what needs to be done.
  55.  
  56.     startwrite
  57.         Set up the format parameters, or write out 
  58.         a data header, or do what needs to be done.
  59.     write
  60.         Given a buffer and a length: 
  61.         copy that many samples out of the buffer,
  62.         convert them from signed longs to the appropriate
  63.         data, and write them to the file.
  64.         If it can't write out all the samples,
  65.         fail.
  66.     stopwrite
  67.         Fix up any file header, or do what needs to be done.
  68.  
  69. Comments:
  70. Theoretically, handlers can be used to manipulate several files 
  71. inside one program.  Multi-sample files, for example the download
  72. for a sampling keyboard, can be handled cleanly with this feature.
  73.  
  74. Portability problems:
  75. Many computers don't supply arithmetic shifting, so do multiplies
  76. instead of << and >> .
  77.  
  78. Do all arithmetic bit-shifting conversions one stage at a time.
  79. I've had too many problems with "obviously clean" combinations.
  80.  
  81. In general, don't worry about "efficiency".  The aux.c base translator
  82. is disk-bound on any machine (other than a 8088 PC with an SMD disk 
  83. controller).  Just comment your code and make sure it's clean
  84. and simple.
  85.