home *** CD-ROM | disk | FTP | other *** search
/ C/C++ User's Journal & Wi…eveloper's Journal Tools / C-C__Users_Journal_and_Windows_Developers_Journal_Tools_1997.iso / diamond / read.me < prev   
Encoding:
Text File  |  1996-11-06  |  12.3 KB  |  316 lines
  1. This is the READ.ME file for DiamondWare's Sound ToolKit for Windows.  It
  2. was finalized for version 1.22 on 11/06/96.
  3.  
  4. It's organized into several sections.  Following this introduction is a
  5. quick guide to the distribution, language notes for each supported language
  6. (C/C++, Visual BASIC, and Pascal/Delphi), and additional notes for each
  7. version past 1.0.  If you're already familiar with the product, you may
  8. skip the guide and language notes.  Otherwise, we recommend that you read
  9. this file in its entirety (skipping uninteresting language notes).
  10.  
  11. You will always be able to find the latest announcements and demos of
  12. DiamondWare products on http://www.dw.com.
  13.  
  14.  
  15. ANNOUNCEMENTS
  16.  
  17.   o CoolEdit, GoldWave, and AWave can now read/write DWD files
  18.  
  19.   o Smacker for Windows will support the WIN-STK in its next version
  20.  
  21. CoolEdit allows the storage of author, description, copyright, and other
  22. information in audio files.  The DWD filters fully support this feature.
  23.  
  24. You can download the CoolEdit filters from our website.  Smacker is the
  25. leading video playback engine for games.  It will utilize the WIN-STK
  26. for sound playback.
  27.  
  28.  
  29. ******************************************************************************
  30. Guide to the Distribution
  31. ******************************************************************************
  32.  
  33. The PACKING.LST file tells you what all these files and subdirectories are.
  34.  
  35.  
  36. BINARIES
  37.  
  38. The WIN-STK includes 16- and 32-bit DLLs, plus special support for Win32s
  39. under Windows 3.1x (new for v1.1).  The 16-bit DLL will run under Windows
  40. 3.1, 95, and NT.  The 32-bit DLL runs only under 95 and NT.  There are
  41. 32-bit and 16-bit thunk DLLs for Win32s.
  42.  
  43. A utility called WAV2DWD converts WAVE files to the DWD format, which is
  44. what the DLL can play.    Use W2D16.EXE or W2D32.EXE, as appropriate to your
  45. operating system (although W2D16.EXE will also run under 95 or NT).
  46.  
  47. 16- and 32-bit versions of the sample program, PLAYSTK, are provided.
  48.  
  49. The DLLs, utilities, and sample executables are in the BIN directory.
  50.  
  51.  
  52. DEF FILES
  53.  
  54. In case you need them, the .DEF files with which the DLLs were built are
  55. in the DEF directory.  There is one for 16-bit, one for 32-bit, and two
  56. for Win32s.
  57.  
  58.  
  59. DOCUMENTATION
  60.  
  61. The complete documentation is provided online in both ASCII and Microsoft
  62. Word format.  The commercial version also comes with a printed book.  The
  63. documentation files are in the DOC directory.
  64.  
  65.  
  66. ******************************************************************************
  67. Language Notes
  68. ******************************************************************************
  69.  
  70. C/C++ NOTES
  71.  
  72. If you're using Visual BASIC or Pascal (including Delphi) then skip this
  73. section.
  74.  
  75. The WIN-STK includes all the files you will need if you're using a compiler
  76. from Microsoft, Borland, Watcom, Symantec, or IBM.  It provides a 16- and
  77. 32-bit version of a .LIB file for each compiler (except IBM Visual Age for
  78. C++ which is 32-bit only).  The MSC, BORC, WATC, SYMC, and IBMC subdirectories
  79. each contain the compiler-specific files: DWSW16.LIB and DWSW32.LIB.  Use the
  80. file appropriate to your compiler vendor, and 16- or 32-bit environment.
  81.  
  82. Note: The code in DWSW32.LIB autodetects whether it's running under Win32s
  83. or a real Win32 environment (Windows 95 or NT).  It will call into the
  84. correct DLL: DWSW32.DLL or DWSW32S.DLL.  DWSW32S.DLL thunks to DWSW16S.DLL
  85. which calls into DWSW16.DLL.  In other words, you will need to install
  86. three DLLs to work in a Win32s environment, but you need only one
  87. executable for Windows 95/NT and Win32s--at least as far as the WIN-STK
  88. goes.  There are many substantive differences between the various
  89. implementations of Win32, and especially so with Win32s.
  90.  
  91. Symantec users: You must copy the contents of PARTIAL.DEF (or PARTIALS.DEF
  92. if you you're using the Win32s DLL directly) into your program's .DEF file.
  93. This tells your compiler what the names in our DLL look like.
  94.  
  95. The header file for the WIN-STK is called DWS.H, and it's in the C
  96. directory.  The source code to the PLAYSTK sample program is also there.
  97. It should compile and run in 16- or 32-bits, using any of the supported
  98. compilers.
  99.  
  100. To keep the number of files in the distribution down, there are no
  101. makefiles for PLAYSTK.    Building it should be straightforward.    Some
  102. compilers may require you to specify the common dialog library as an
  103. additional file in the link.
  104.  
  105. If you compile PLAYSTK for 16-bit, make sure that you specify the large
  106. memory model.  The default is usually medium memory model.
  107.  
  108.  
  109. VISUAL BASIC NOTES
  110.  
  111. If you're using C/C++ or Pascal (including Delphi) then skip this section.
  112.  
  113. There are major differences between version 3 and version 4.  For this
  114. reason, there are VB3 and VB4 subdirectories under the VB directory.
  115.  
  116. For VB3, there is DWS.BAS.  This is the WIN-STK module which will allow
  117. you to access the DLL.    Include it in your project.
  118.  
  119. There is also the complete source code to PLAYSTK, including the icon,
  120. form, and make file.
  121.  
  122. Note: Due to the way VB3 handles strings, and the fact that our MIDI
  123. playback function requires the filename of a MIDI song, you will not
  124. be able to play music using the WIN-STK.  However, you can work around
  125. this by specifying no music support when you call dws_Init.  You are
  126. then free to call the Windows MCI functions for music.    This limitation
  127. will be corrected in a future release.
  128.  
  129. For VB4, we provide a single DWS.BAS, which you should include in your
  130. 16- or 32-bit project.    But there are many differences between the
  131. versions of PLAYSTK, so there are further subdirectories for PLAY16 and
  132. PLAY32.
  133.  
  134. Note: For 32-bit VB4, if you want to make an executable which runs under
  135. Win32s, you will need to change DWS.BAS.  In each WIN-STK function
  136. declaration, change "DWSW32.DLL" to "DWSW32S.DLL".  This DLL is the correct
  137. one for Win32s.
  138.  
  139. Note: For VB3, and 16-bit VB4, there is a size limitation on digitized
  140. sounds (or any other buffer type, for that matter) imposed on you by
  141. Visual BASIC.  VB3 will only allow up to 32K.  VB4 (16-bit) will only
  142. allow up to 64K.
  143.  
  144.  
  145. PASCAL (INCLUDING DELPHI) NOTES
  146.  
  147. If you're using C/C++ or Visual BASIC then skip this section.
  148.  
  149. We provide DWS.PAS, which is the unit file for the WIN-STK.  It's been
  150. compiled and tested with Delphi 1, Delphi 2, and Borland Pascal.
  151.  
  152. There is also the complete source code to PLAYSTK.
  153.  
  154. Note: For 32-bit Delphi 2, if you want to make an executable which runs
  155. under Win32s, you will need to change DWS.PAS.    Change the line which
  156. contains DWSDLL = 'DWSW32'; to DWSDLL = 'DWSW32S'; instead.  This DLL is
  157. the correct one for Win32s.
  158.  
  159.  
  160. ******************************************************************************
  161. What's New for v1.10
  162. ******************************************************************************
  163.  
  164. ADDITIONAL DOCUMENTATION NOTES
  165.  
  166. When you install your program on the user's machine, please put the WIN-STK
  167. DLLs in the same directory as your executable(s).  This will ensure that
  168. other programs using different versions of the WIN-STK will coexist with
  169. yours.    In fact, this is a good practice for all DLLs in Windows.
  170.  
  171.  
  172. The flags field in the dws_DPLAY struct was designed to allow you to use as
  173. many or as few of the features available through the dws_DPlay function as
  174. you want.  At a minimum, you must set dws_dplay_SND.  This indicates that
  175. you have specified a pointer to a sound buffer.  All other fields (e.g.
  176. pitch, loop count, etc.) are optional.    The flags mechanism also protects
  177. your program from breaking when you upgrade to new WIN-STK releases.  If
  178. there are new features, your program won't inadvertantly use them.
  179.  
  180.  
  181. WIN32S SUPPORT
  182.  
  183. The WIN-STK now supports Win32s on Windows 3.1x systems.  DWSW32S.DLL is
  184. the primary DLL for Win32s.  It provides the entire documented WIN-STK
  185. API.  It then thunks down to DWSW16S.DLL which then makes calls into
  186. DWSW16.DLL.  The primary difference between the 16- and the main 32-bit
  187. DLL is multithreading.    Under Win32s, therefore, the WIN-STK uses the
  188. 16-bit kernel to actually perform the work.
  189.  
  190. If you're using C/C++, the code in DWSW32.LIB will automatically determine
  191. whether it's running under Win32s or a real Win32 environment (Windows 95
  192. or NT).  It will call into the correct DLL.  This library file is
  193. equivalent to a standard import library, though it was written in C.  Its
  194. other advantage is that it will not terminate your program if it can't find
  195. the DLL (it will instead report no sound capabilities present--true enough
  196. without the WIN-STK DLLs).
  197.  
  198. In Win32s systems, you must install DWSW32S.DLL, DWSW16S.DLL, and
  199. DWSW16.DLL.  But, you will only need to deliver only one executable--at
  200. least as far as the WIN-STK goes.  However, there are many substantial
  201. differences between different implementations of Win32s, especially so with
  202. Win32s.  Caveat programmer!
  203.  
  204. Note: Visual BASIC and Pascal/Delphi users do not have access to this C/C++
  205. mechanism and must provide a separate executable file for Win32s and
  206. Windows 95/NT.
  207.  
  208. For 32-bit VB4, if you want to make an executable which runs under Win32s,
  209. you will need to change DWS.BAS.  In each WIN-STK function declaration,
  210. change "DWSW32.DLL" to "DWSW32S.DLL".  This DLL is the correct one for
  211. Win32s.
  212.  
  213. For 32-bit Delphi 2, if you want to make an executable which runs under
  214. Win32s, you will need to change DWS.PAS.  Change the line which contains
  215. DWSDLL = 'DWSW32'; to DWSDLL = 'DWSW32S'; instead.  This DLL is the correct
  216. one for Win32s.
  217.  
  218.  
  219. BUG FIXES
  220.  
  221.   o Glitch causing the system to pause when a MIDI song looped eliminated
  222.  
  223.   o System volume settings no longer lost
  224.  
  225.  
  226. NEW FEATURES
  227.  
  228.   o dws_dplay_SYNCHRONOUS flag causes dws_DPlay to wait until sound done
  229.  
  230.   o New event messages: dws_EVENT_SOUNDSTARTED and dws_EVENT_SOUNDABORTED
  231.  
  232. If you set the dws_dplay_CALLBACK flag in the dws_DPLAY struct, WIN-STK
  233. v1.0 would send you a window message when the sound completed.    V1.1 will
  234. also send messages when the sound actually starts playing, and if it's
  235. aborted (i.e. displaced by another sound with a higher priority).
  236.  
  237.  
  238. OTHER ADDITIONS
  239.  
  240.   o Added new error: dws_M_BADMPLAY, indicating bad dws_MPLAY struct
  241.  
  242. This error would occur if the MIDI file specified was not found.
  243.  
  244.  
  245. ******************************************************************************
  246. What's New for v1.20
  247. ******************************************************************************
  248.  
  249. BUG FIXES
  250.   o Fixed set-volume bug in dws_SetInfo
  251.  
  252.   o Fixed rare bug in dws_DDiscardAO
  253.  
  254.   o Fixed dws_DGetInfo and dws_DSetInfo bug (mishandling second DPLAY struct)
  255.  
  256.   o Fixed sequencing bug
  257.  
  258.   o Robust reentrancy protection (although no bugs had been reported)
  259.  
  260.   o In Win32s, compensation for the 16-bit HWND and UINT in the DPLAY struct
  261.  
  262.   o Calls return dws_NOTINITTED rather than dws_NOTSUPPORTED when appropriate
  263.  
  264.   o dws_MClear no longer unpauses the music
  265.  
  266.   o Calling dws_Init, requesting no sound services, now returns success
  267.  
  268.   o Fixed rare bug which played past end of sound
  269.  
  270.   o Fixed bug in pitch changer (to detect end-of-sound in all cases)
  271.  
  272.   o Fixed timer problem, now timing is much more consistent
  273.  
  274.  
  275. NEW FEATURES
  276.  
  277.   o Getting and Setting start, current, and end playback points
  278.  
  279.   o Uses the most capable sound driver, rather than the last enumerated
  280.  
  281.   o WAV2DWD (32-bit version) now supports long filenames
  282.  
  283.   o Now supports the IBM Visual Age for C++ compiler
  284.  
  285.   o Now works with the Watcom C/C++ compiler's Win386 mode
  286.  
  287.   o Now reports dws_NOTSUPPORTED if DLL is not present (C/C++ only)
  288.  
  289.  
  290. OTHER IMPROVEMENTS
  291.  
  292.   o Added more error checking to dws_MPlay
  293.  
  294.   o Added more error checking to dws_DGetRateFromDWD
  295.  
  296.   o Added invalid pointer detection (32 bit code) for dws_DDiscardAO
  297.  
  298.   o Reduced latency between a sound ending, and its soundnum being set to 0
  299.  
  300.   o Moved all autodetect results from DLL-static to the DETECTRESULTS struct
  301.  
  302.  
  303. ******************************************************************************
  304. What's New for v1.22
  305. ******************************************************************************
  306.  
  307. BUG FIXES
  308.  
  309.  o Fixed distortion in the 16-bit stereo to 8-bit mono conversion code
  310.  
  311.  o dws_Update no longer GPFs when called in the midst of dws_Kill (reentrancy)
  312.  
  313.  o Vastly reduced CPU usage with MWave drivers (lower latency and CPU overall)
  314.  
  315.  o DGetInfo and DSetInfo no longer reject dplay.flags = 0 for (used by Pascal)
  316.