home *** CD-ROM | disk | FTP | other *** search
/ Sound Sensations! / sound_sensations.iso / miscprog / soundkit / soundkit.doc < prev    next >
Text File  |  1990-08-17  |  12KB  |  295 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                             SOUNDKIT 1.0
  14.  
  15.                            August 14, 1990
  16.  
  17.  
  18.  
  19.  
  20.                            Copyright 1990,
  21.                          All rights reserved,
  22.  
  23.                          Russell B. Hildreth
  24.  
  25.  
  26.  
  27.  
  28.                  Documentation and Programmer's Notes
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.         Soundkit 1.0  Documentation and Programmer's Notes:
  36.  
  37.  
  38.  
  39.  
  40.  
  41.         INTRODUCTION:
  42.  
  43.         Soundkit 1.0 is a collection of functions designed
  44.         especially for users of Microsoft C compilers (MSC and
  45.         QuickC).  The functions are provided as shareware in
  46.         library format (SOUNDKIT.LIB).  All source code is
  47.         available to programmers who register Soundkit with
  48.         the author.
  49.  
  50.         Microsoft does not provide any ready to use sound
  51.         functions with its languages as Borland does with
  52.         the Turbo series.  Soundkit remedies this situation
  53.         by providing sound support similar to that of Borlands.
  54.  
  55.         Soundkit, however, goes one step further by additionally
  56.         providing a collection of ready to use sound routines.
  57.         There are close to forty sound functions in the first
  58.         Soundkit release, and there will be even more in the
  59.         future.  These routines include musical selections,
  60.         utility beeps, buzzes, and alarms, and generally silly
  61.         sounds.  An attempt has been made to provide a wide
  62.         variety of routines to satisfy programmers.
  63.  
  64.         Programmers can also, of course, use the core Soundkit
  65.         functions [ tone(), soundon(), and soundoff() ] to
  66.         create their own sound routines.
  67.  
  68.         All the currently available Soundkit routines can be
  69.         tried out with the DEMO program included in the shareware
  70.         release.  To illustrate using Soundkit functions, the
  71.         source code to the DEMO program has been included.
  72.  
  73.         Soundkit is shareware.  If you use the routines provided
  74.         in the SOUNDKIT.LIB file, you are obligated to register
  75.         with the author.  Please see the section on registering
  76.         in this document, and the SOUNDKIT.REG file.
  77.  
  78.  
  79.         USING SOUNDKIT
  80.  
  81.         Using the Soundkit routines is very straightforward.  A
  82.         programmer can run the DEMO program to assist in selecting
  83.         desired sound routines.  Once the desired routines have
  84.         been identified, the programmer needs only to #include the
  85.         SOUNDKIT.H file and call the desired routines by name
  86.         in a program.  For example,
  87.  
  88.         #include "SOUNDKIT.H"
  89.         .
  90.         .
  91.         .
  92.  
  93.         void main(void)
  94.         {
  95.                 .
  96.                 .
  97.                 .
  98.                 bach1();
  99.                 .
  100.                 .
  101.                 .
  102.         }
  103.  
  104.         When a programmer compiles a program containing Soundkit
  105.         routines, the SOUNDKIT.LIB file should be linked from the
  106.         command line, or specified within a development environment.
  107.  
  108.         For example, to compile the SAMPLE.C file from the command
  109.         line with Quick C, use the following line:
  110.  
  111.                 QCL SAMPLE.C SOUNDKIT.LIB
  112.  
  113.         Failure to link the SOUNDKIT.LIB file will result in a
  114.         program that will not properly execute any Soundkit functions
  115.         (they simply won't be available to the program).
  116.  
  117.  
  118.         INCLUDED FUNCTIONS:
  119.  
  120.         Core functions:
  121.  
  122.                 delay()         This function provides the necessary
  123.                                 delays to make notes sound the same
  124.                                 length of time on any speed CPU.
  125.                                 Call delay() with an unsigned int
  126.                                 value, i.e., delay(5);  Experimentation
  127.                                 is usually necessary to obtain the
  128.                                 optimum delay time.  The delay()
  129.                                 function is written in assembly
  130.                                 language to increase delay length
  131.                                 accuracy (the delay routine suggested
  132.                                 by Microsoft in the QuickC sample
  133.                                 programs in an example of terrible
  134.                                 programming!).  Calling delay() with a
  135.                                 value of 0 is not advised, as it is
  136.                                 liable to lock up your machine.
  137.  
  138.                 flushkb()       Flushes the keyboard.  This routine
  139.                                 is used by many of the Soundkit
  140.                                 which can be stopped by pressing a
  141.                                 key, to make sure that the user does
  142.                                 not stop a sound routine before it
  143.                                 has a chance to begin.
  144.  
  145.                 soundon()       Takes an integer value and sounds the
  146.                                 PC speaker with that value.  This
  147.                                 sound will continue until the
  148.                                 soundoff() function is called.
  149.  
  150.                 soundoff()      Turns off the PC speaker.  Use this to
  151.                                 shut the computer up at the end of
  152.                                 your sound functions.
  153.  
  154.                 tone()          For many programmers this will be the
  155.                                 primary sound function.  It takes two
  156.                                 values, both unsigned integers.  The
  157.                                 first is a hz note value (musical note),
  158.                                 and the second is a delay length.  The
  159.                                 note is played for the delay length.
  160.                                 For example  tone(440,6)  would play an
  161.                                 A note for a short time.  The file
  162.                                 NOTE.CHT provides a complete list of
  163.                                 notes and their corresponding hz values.
  164.  
  165.         Sound routines:
  166.  
  167.         The DEMO program provides a complete list of all currently
  168.         available sound routines.  These include musical routines
  169.         from Bach and other favorites, alarms, buzzes, beeps,
  170.         sirens, and other noises that programmers might find handy
  171.         at one point or another.
  172.  
  173.         Many of the longer sound routines can be stopped by a
  174.         keypress.  These include all of the music routines, the alarms,
  175.         and several others.  Each of these calls the flushkb()
  176.         function first to make sure that the routine will get a chance
  177.         to play.  The shorter routines simply play themselves out,
  178.         ignoring keypresses.
  179.  
  180.  
  181.         GENERAL NOTES:
  182.  
  183.         A prewritten OFF.EXE program has been included to shut
  184.         the speaker up from the command line.  The author
  185.         experienced several instances in which he left the speaker
  186.         on at the end of a routine by accident, and found the
  187.         OFF program convenient for turning it back off while
  188.         editing and recompiling.
  189.  
  190.         One important thing for novice programmers to realize is
  191.         that just because there are many routines in the SOUNDKIT.LIB
  192.         file, only those routines you call in your program will be
  193.         actually used.  If your program only uses one beep routine,
  194.         then its size will only grow in proportion to the one beep
  195.         routine, NOT the full size of the SOUNDKIT.LIB file!
  196.  
  197.         Every effort has been made to keep these routines as small
  198.         as possible.  They add very little overhead to the size
  199.         of finished programs.  Further, the author is committed to
  200.         making these routines even smaller in future releases of
  201.         Soundkit.  Register now to get the next release as soon as
  202.         it becomes available.
  203.  
  204.         Turbo C:  The author has absolutely no idea whether any of
  205.         the Soundkit functions will work with Turbo C or Turbo C++.
  206.         Probably they will not.  The author will, however, make a
  207.         Borland compatible version of Soundkit available if demand
  208.         warrants doing so.
  209.  
  210.  
  211.  
  212.         CPU DEPENDENT ROUTINES:
  213.  
  214.         There are several routines included which are CPU dependent.
  215.         This means that they will not sound the same on all machines,
  216.         primarily because faster machines will process the loops more
  217.         quickly, distorting the sound.  These routines have been
  218.         optimized to sound best on an 8mhz AT.  For consistency
  219.         programmers should only use these routines in programs which
  220.         will not be distributed to the world at large.  The CPU
  221.         dependent routines are noted in the DEMO program as being such.
  222.         All other Soundkit routines will perform identically on all
  223.         machines--they are processor independent.  They have been
  224.         tested on machines ranging from 4.77mhz to 20mhz with identical
  225.         results in every instance.  Programmers should rely more heavily
  226.         on these routines.
  227.  
  228.         Programmers constructing their own routines should be aware
  229.         of the way different speed CPUs handle loops.  To create a
  230.         routine that is CPU independent, always nest a minimal delay
  231.         (i.e., delay(1);).  The delay() function performs identically
  232.         on every CPU.  A routine which lacks a delay function will
  233.         not be consistent among different processors (though such a
  234.         routine might very well be used to create a desired sound
  235.         effect).
  236.  
  237.         Programmers who possess the registered version of the Soundkit
  238.         have access to the source code for each routine and can compare
  239.         a CPU dependent routine such as siren2() with a processor
  240.         independent routine such as siren1().
  241.  
  242.  
  243.         REGISTRATION:
  244.  
  245.         There are three very good reasons for registering with the
  246.         author.  One is that the programmer receives all of the
  247.         source code used to create the SOUNDKIT.LIB.  This includes
  248.         the core functions and all of the sound routines.  The
  249.         programmer can then use these as examples for his or her
  250.         own routines, or modify them to make new routines.  Also, the
  251.         programmer can see how the core routines work and perhaps
  252.         modify these also.
  253.  
  254.         Another reason is that the author will continually update
  255.         Soundkit with a) additional sound routines and b) improved
  256.         core routines.  The author is committed to producing the
  257.         best possible sounds through the limited PC speaker, and is
  258.         always searching for new ways to do more.
  259.  
  260.         The third reason deals with copyright laws.  Soundkit is
  261.         copyright by the author, Russell B. Hildreth, 1990, who
  262.         retains all rights to the routines.  If a programmer uses
  263.         any of the Soundkit routines in a program that is to be
  264.         distributed to the public, be it shareware, freeware, or
  265.         retail software, the programmer (or distributor, as the
  266.         case may be) is legally bound to register Soundkit with the
  267.         author.  Most programmers, however, will probably want to
  268.         register anyway, in order to obtain the source code.
  269.  
  270.         And finally, it is nice to support the work of others.  The
  271.         author of Soundkit actively supports the shareware community.
  272.         Further, all income derived from Soundkit is used by the
  273.         author to assist in offsetting the ever increasing costs of
  274.         obtaining a higher education.
  275.  
  276.         Please use the SOUNDKIT.REG form for registering.  Send
  277.         $25.00 to
  278.                         Russell B. Hildreth
  279.                         P.O. Box 72431
  280.                         Davis, CA  95617-2431
  281.  
  282.  
  283.         CONTACTING THE AUTHOR:
  284.  
  285.         The author can be contacted on Compuserve at 71041,2132, or
  286.         by U.S. Mail at the registration address.
  287.  
  288.         The author welcomes your suggestions for improvements to the
  289.         Soundkit routines, as well as criticims and bug reports.
  290.  
  291.  
  292.  
  293.  
  294.  
  295.