home *** CD-ROM | disk | FTP | other *** search
/ The Best of Windows 95.com 1996 September / WIN95_09964.iso / program / dwstkw.zip / READ.ME < prev   
Text File  |  1996-05-14  |  10KB  |  233 lines
  1. This is the READ.ME file for DiamondWare's Sound ToolKit for Windows.  It
  2. was finalized for version 1.10 on 5/13/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. ******************************************************************************
  16. Guide to the Distribution
  17. ******************************************************************************
  18.  
  19. Demo version users: you must use the -d option with PKUNZIP to generate the
  20. subdirectories in this distribution.  If you did not do this, then delete
  21. everything and run PKUNZIP -D DWSTKW.ZIP again.
  22.  
  23. The PACKING.LST file tells you what all these files and subdirectories are.
  24.  
  25.  
  26. BINARIES
  27.  
  28. The WIN-STK includes 16- and 32-bit DLLs, plus special support for Win32s
  29. under Windows 3.1x (new for v1.1).  The 16-bit DLL will run under Windows
  30. 3.1, 95, and NT.  The 32-bit DLL runs only under 95 and NT.  There are
  31. 32-bit and 16-bit thunk DLLs for Win32s.
  32.  
  33. A utility called WAV2DWD converts WAVE files to the DWD format, which is
  34. what the DLL can play.    Use W2D16.EXE or W2D32.EXE, as appropriate to your
  35. operating system (although W2D16.EXE will also run under 95 or NT).
  36.  
  37. 16- and 32-bit versions of the sample program, PLAYSTK, are provided.
  38.  
  39. The DLLs, utilities, and sample executables are in the BIN directory.
  40.  
  41.  
  42. DEF FILES
  43.  
  44. In case you need them, the .DEF files with which the DLLs were built are
  45. in the DEF directory.  There is one for 16-bit, one for 32-bit, and two
  46. for Win32s.
  47.  
  48.  
  49. DOCUMENTATION
  50.  
  51. The complete documentation is provided online in both ASCII and Microsoft
  52. Word format.  The commercial version also comes with a printed book.  The
  53. documentation files are in the DOC directory.
  54.  
  55.  
  56. ******************************************************************************
  57. Language Notes
  58. ******************************************************************************
  59.  
  60. C/C++ NOTES
  61.  
  62. If you're using Visual BASIC or Pascal (including Delphi) then skip this
  63. section.
  64.  
  65. The WIN-STK includes all the files you will need if you're using a compiler
  66. from Microsoft, Borland, Watcom, or Symantec.  It provides a 16- and 32-bit
  67. version of a .LIB file for each compiler.  The MSC, BORC, WATC, and SYMC
  68. subdirectories each contain the compiler-specific files: DWSW16.LIB and
  69. DWSW32.LIB.  Use the file appropriate to your compiler vendor, and 16- or
  70. 32-bit environment.
  71.  
  72. Note: The code in DWSW32.LIB autodetects whether it's running under Win32s
  73. or a real Win32 environment (Windows 95 or NT).  It will call into the
  74. correct DLL: DWSW32.DLL or DWSW32S.DLL.  DWSW32S.DLL thunks to DWSW16S.DLL
  75. which calls into DWSW16.DLL.  In other words, you will need to install
  76. three DLLs to work in a Win32s environment, but you need only one
  77. executable for Windows 95/NT and Win32s--at least as far as the WIN-STK
  78. goes.  There are many substantial differences between different
  79. implementations of Win32, and especially so with Win32s.
  80.  
  81. Symantec users: You must copy the contents of PARTIAL.DEF (or PARTIALS.DEF
  82. if you you're using the Win32s DLL directly) into your program's .DEF file.
  83. This tells your compiler what the names in our DLL look like.
  84.  
  85. The header file for the WIN-STK is called DWS.H, and it's in the C
  86. directory.  The source code to the PLAYSTK sample program is also there.
  87. It should compile and run in 16- or 32-bits, using any of the supported
  88. compilers.
  89.  
  90. To keep the number of files in the distribution down, there are no
  91. makefiles for PLAYSTK.    Building it should be straightforward.    Some
  92. compilers may require you to specify the common dialog library as an
  93. additional file in the link.
  94.  
  95. If you compile PLAYSTK for 16-bit, make sure that you specify the large
  96. memory model.  The default is usually medium memory model.
  97.  
  98.  
  99. VISUAL BASIC NOTES
  100.  
  101. If you're using C/C++ or Pascal (including Delphi) then skip this section.
  102.  
  103. There are major differences between version 3 and version 4.  For this
  104. reason, there are VB3 and VB4 subdirectories under the VB directory.
  105.  
  106. For VB3, there is DWS.BAS.  This is the WIN-STK module which will allow
  107. you to access the DLL.    Include it in your project.
  108.  
  109. There is also the complete source code to PLAYSTK, including the icon,
  110. form, and make file.
  111.  
  112. Note: Due to the way VB3 handles strings, and the fact that our MIDI
  113. playback function requires the filename of a MIDI song, you will not
  114. be able to play music using the WIN-STK.  However, you can work around
  115. this by specifying no music support when you call dws_Init.  You are
  116. then free to call the Windows MCI functions for music.    This limitation
  117. will be corrected in a future release.
  118.  
  119. For VB4, we provide a single DWS.BAS, which you should include in your
  120. 16- or 32-bit project.    But there are many differences between the
  121. versions of PLAYSTK, so there are further subdirectories for PLAY16 and
  122. PLAY32.
  123.  
  124. Note: For 32-bit VB4, if you want to make an executable which runs under
  125. Win32s, you will need to change DWS.BAS.  In each WIN-STK function
  126. declaration, change "DWSW32.DLL" to "DWSW32S.DLL".  This DLL is the correct
  127. one for Win32s.
  128.  
  129. Note: For VB3, and 16-bit VB4, there is a size limitation on digitized
  130. sounds (or any other buffer type, for that matter) imposed on you by
  131. Visual BASIC.  VB3 will only allow up to 32K.  VB4 (16-bit) will only
  132. allow up to 64K.
  133.  
  134.  
  135. PASCAL (INCLUDING DELPHI) NOTES
  136.  
  137. If you're using C/C++ or Visual BASIC then skip this section.
  138.  
  139. We provide DWS.PAS, which is the unit file for the WIN-STK.  It's been
  140. compiled and tested with Delphi 1, Delphi 2, and Borland Pascal.
  141.  
  142. There is also the complete source code to PLAYSTK.
  143.  
  144. Note: For 32-bit Delphi 2, if you want to make an executable which runs
  145. under Win32s, you will need to change DWS.PAS.    Change the line which
  146. contains DWSDLL = 'DWSW32'; to DWSDLL = 'DWSW32S'; instead.  This DLL is
  147. the correct one for Win32s.
  148.  
  149.  
  150. ******************************************************************************
  151. What's New for v1.10
  152. ******************************************************************************
  153.  
  154. ADDITIONAL DOCUMENTATION NOTES
  155.  
  156. When you install your program on the user's machine, please put the WIN-STK
  157. DLLs in the same directory as your executable(s).  This will ensure that
  158. other programs using different versions of the WIN-STK will coexist with
  159. yours.    In fact, this is a good practice for all DLLs in Windows.
  160.  
  161.  
  162. The flags field in the dws_DPLAY struct was designed to allow you to use as
  163. many or as few of the features available through the dws_DPlay function as
  164. you want.  At a minimum, you must set dws_dplay_SND.  This indicates that
  165. you have specified a pointer to a sound buffer.  All other fields (e.g.
  166. pitch, loop count, etc.) are optional.    The flags mechanism also protects
  167. your program from breaking when you upgrade to new WIN-STK releases.  If
  168. there are new features, your program won't inadvertantly use them.
  169.  
  170.  
  171. WIN32S SUPPORT
  172.  
  173. The WIN-STK now supports Win32s on Windows 3.1x systems.  DWSW32S.DLL is
  174. the primary DLL for Win32s.  It provides the entire documented WIN-STK
  175. API.  It then thunks down to DWSW16S.DLL which then makes calls into
  176. DWSW16.DLL.  The primary difference between the 16- and the main 32-bit
  177. DLL is multithreading.    Under Win32s, therefore, the WIN-STK uses the
  178. 16-bit kernel to actually perform the work.
  179.  
  180. If you're using C/C++, the code in DWSW32.LIB will automatically determine
  181. whether it's running under Win32s or a real Win32 environment (Windows 95
  182. or NT).  It will call into the correct DLL.  This library file is
  183. equivalent to a standard import library, though it was written in C.  Its
  184. other advantage is that it will not terminate your program if it can't find
  185. the DLL (it will instead report no sound capabilities present--true enough
  186. without the WIN-STK DLLs).
  187.  
  188. In Win32s systems, you must install DWSW32S.DLL, DWSW16S.DLL, and
  189. DWSW16.DLL.  But, you will only need to deliver only one executable--at
  190. least as far as the WIN-STK goes.  However, there are many substantial
  191. differences between different implementations of Win32s, especially so with
  192. Win32s.  Caveat programmer!
  193.  
  194. Note: Visual BASIC and Pascal/Delphi users do not have access to this C/C++
  195. mechanism and must provide a separate executable file for Win32s and
  196. Windows 95/NT.
  197.  
  198. For 32-bit VB4, if you want to make an executable which runs under Win32s,
  199. you will need to change DWS.BAS.  In each WIN-STK function declaration,
  200. change "DWSW32.DLL" to "DWSW32S.DLL".  This DLL is the correct one for
  201. Win32s.
  202.  
  203. For 32-bit Delphi 2, if you want to make an executable which runs under
  204. Win32s, you will need to change DWS.PAS.  Change the line which contains
  205. DWSDLL = 'DWSW32'; to DWSDLL = 'DWSW32S'; instead.  This DLL is the correct
  206. one for Win32s.
  207.  
  208.  
  209. BUG FIXES
  210.  
  211.   o Glitch causing the system to pause when a MIDI song looped eliminated
  212.  
  213.   o System volume settings no longer lost
  214.  
  215.  
  216. NEW FEATURES
  217.  
  218.   o dws_dplay_SYNCHRONOUS flag causes dws_DPlay to wait until sound done
  219.  
  220.   o New event messages: dws_EVENT_SOUNDSTARTED and dws_EVENT_SOUNDABORTED
  221.  
  222. If you set the dws_dplay_CALLBACK flag in the dws_DPLAY struct, WIN-STK
  223. v1.0 would send you a window message when the sound completed.    V1.1 will
  224. also send messages when the sound actually starts playing, and if it's
  225. aborted (i.e. displaced by another sound with a higher priority).
  226.  
  227.  
  228. OTHER ADDITIONS
  229.  
  230.   o Added new error: dws_M_BADMPLAY, indicating bad dws_MPLAY struct
  231.  
  232. This error would occur if the MIDI file specified was not found.
  233.