home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / cprog / sefx1c.zip / SEFX.DOC < prev    next >
Text File  |  1993-04-09  |  36KB  |  1,528 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                Sefx
  13.  
  14.  
  15.                C Language Sound Effects Library
  16.  
  17.                Version 1.0
  18.  
  19.                20 Feb 92
  20.  
  21.                Copyright (c) 1992  Bri Productions
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                    1
  62.        Table of Contents
  63.  
  64.  
  65.  
  66.        Introduction
  67.  
  68.                Acknowledgments.........................4
  69.  
  70.                General Description.....................4
  71.  
  72.                Disclaimer..............................4
  73.  
  74.                Registration............................4
  75.  
  76.                Contacting the Author...................5
  77.  
  78.                Terminology.............................5
  79.  
  80.                A typedef...............................5
  81.  
  82.  
  83.        Control Functions
  84.  
  85.                Description.............................6
  86.  
  87.                SndOpen.................................7
  88.  
  89.                SndClose................................8
  90.  
  91.                SndLen..................................9
  92.  
  93.                SndTbase...............................10
  94.  
  95.                SndFlush...............................11
  96.  
  97.                SndHold................................12
  98.  
  99.                SndTerm................................13
  100.  
  101.  
  102.        Sound Generation Functions
  103.  
  104.                Description............................14
  105.  
  106.                SndTone................................15
  107.  
  108.                SndPause...............................16
  109.  
  110.                SndString..............................17
  111.  
  112.                SndTrill...............................18
  113.  
  114.                SndSlide...............................19
  115.  
  116.                SndPulse...............................20
  117.  
  118.  
  119.  
  120.  
  121.  
  122.                                    2
  123.        Miscellaneous
  124.  
  125.                SndMs..................................21
  126.  
  127.  
  128.  
  129.  
  130.        Appendix A - Things to look out for............22
  131.  
  132.  
  133.        Appendix B - Musical notes.....................23
  134.  
  135.  
  136.        Appendix C - Sound queue usage.................24
  137.  
  138.  
  139.        Appendix D - Registration form.................25
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                    3
  184.        Acknowledgments.
  185.  
  186.        I would like to thank Earl Jensen for technical review and
  187.        advice, James Garcia for musical information and Margaret
  188.        Carlsen for proof reading this documentation.
  189.  
  190.  
  191.  
  192.        General Description.
  193.  
  194.        Sefx is a C language timer-driven sound effects library for IBM
  195.        and compatible computers. Sefx is compatible with most if not
  196.        all DOS based C compilers.
  197.  
  198.        All the sound generated by Sefx is generated in the background.
  199.        This fact allows the program to continue with other operations
  200.        while the sound is generated.
  201.  
  202.  
  203.        Some of Sefx's features are:
  204.  
  205.        ∙ Generates sound simultaneously to other operations
  206.        ∙ Produces frequencies from 19 to 20,000+ hertz
  207.        ∙ Time bases of 54.9, 27.5, 13.7 and 6.9 milliseconds
  208.        ∙ Changes frequency up to 145 time per second
  209.        ∙ Adjustable sound queue as large as 65532 bytes
  210.        ∙ Sound queue is handled internally
  211.        ∙ Written in assembly language for optimum speed and efficiency.
  212.  
  213.  
  214.  
  215.        DISCLAIMER.
  216.  
  217.        Sefx is provided AS IS. Bri Productions specifically disclaims
  218.        any and all warranties, expressed or implied, including fitness
  219.        for a particular purpose. Use this product at your own risk.
  220.  
  221.  
  222.  
  223.        Registration.
  224.  
  225.        Sefx is a user supported software product. Distribution of
  226.        this product, unaltered and without charge, is encouraged. If
  227.        you find this product useful, you are encouraged to register
  228.        your copy. This allows Bri Productions to continue to provide
  229.        support low cost, high quality shareware.
  230.  
  231.        The registration fee is $25.00 US dollars and includes libraries
  232.        for small, medium, compact and large memory models and complete
  233.        source code. A registration form is provided in Appendix D.
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.                                    4
  245.        Contacting the author.
  246.  
  247.        Bri Productions may be contacted by any of the following means:
  248.  
  249.        U.S. mail       -       Bri Productions
  250.                                P.O.Box 7121
  251.                                Fremont, CA 94537-7121
  252.        Phone           -       (510) 794-0616
  253.        CompuServe      -       76635,2246
  254.  
  255.        CompuServe is a trademark of CompuServe Inc.
  256.  
  257.  
  258.        Terminology
  259.  
  260.        This section is intended to define the terminology used in this
  261.        documentation and clarify any ambiguities thereof.
  262.  
  263.        A 'tone' consists of a single frequency and a 'duration'. A
  264.        'pause' is the same in all respects as a 'tone' except for the
  265.        absents of a frequency. It can also be defined as a 'tone' with
  266.        a frequency of zero.
  267.  
  268.        A 'sound' is one or more 'tones' and/or 'pauses' put together
  269.        to produce the desired results. ie. trill, slide, string, etc.
  270.        A 'sound' may consist of only one 'tone' or 'pause'. Each Sefx
  271.        sound generation function generates exactly one sound.
  272.  
  273.        The 'time base' refers to the length of time of one 'tic' which
  274.        is the basic unit of time used by the Sefx sound generating
  275.        functions. A new 'tone' or 'pause' may be loaded as often as
  276.        once per 'tic'. Hence the frequency may be changed as often
  277.        as the value of the 'time base'.
  278.  
  279.        The 'duration' of a 'tone' is the number of 'tics' (and hence
  280.        the length of time) it will last.
  281.  
  282.           Examples:
  283.  
  284.              A 'tone' with a 'duration' of two 'tics', when the
  285.              'time base' is set to MEDium (27.5ms), will last 55
  286.              milliseconds.
  287.  
  288.              A 'sound' consisting of a 'tone' with a 'duration' of of
  289.              two 'tics', a 'pause' with a 'duration' of one 'tic'
  290.              followed by another tone with a 'duration' of three 'tics'
  291.              when the 'time base' is set to HIGH (13.7ms), will last
  292.              82.2 milliseconds.
  293.  
  294.  
  295.        A typedef
  296.  
  297.        You will see the data type 'TONE' throughout the Sefx library.
  298.        TONE is a structure, defined in sefx.h, used for storing
  299.        frequency/duration pairs. This type is used mainly by the
  300.        function SndString. The fields are defined as follows:
  301.  
  302.                    typedef struct{
  303.                       int freq;         /* frequency */
  304.                       int durtn;        /* duration  */
  305.                       }TONE;
  306.                                    5
  307.         Control Functions
  308.  
  309.        Before sound can be generated, a call to SndOpen must be made
  310.        to initialize Sefx. SndOpen will also allocate memory for a sound
  311.        queue. Sounds are then loaded into the sound queue and played in
  312.        sequence
  313.  
  314.        Prior to program's termination, a call to SndClose must be made
  315.        to undo SndOpen. Failing to call SndClose prior to a program's
  316.        termination will cause the computer to lock up requiring a
  317.        reboot.
  318.  
  319.        Other control functions are available for manipulating and
  320.        procuring the status of the sound queue. The sound queue can
  321.        be flushed at any time with SndFlush. SndTerm terminates the
  322.        current sound while SndHold will put all sound on hold. The
  323.        number of bytes currently residing in the sound queue is available
  324.        through SndLen.
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.                                    6
  368.        ----------------------------------------------------------------
  369.        SndOpen
  370.        ----------------------------------------------------------------
  371.  
  372.        Function
  373.  
  374.              Initializes the timer and interrupt handler and allocates
  375.              memory for the sound queue.
  376.  
  377.  
  378.        Syntax
  379.  
  380.              #include "sefx.h"
  381.              int SndOpen(unsigned Qsize, int tbase);
  382.  
  383.  
  384.        Parameters
  385.  
  386.              Qsize - Size of the sound queue in bytes. The number
  387.                      of bytes required for a sound varies depending
  388.                      on the sound. This value will be rounded down
  389.                      so that it is even multiple of 4 bytes.
  390.  
  391.              tbase - Time base. This value determines the length of
  392.                      time of one tic and subsequently how often the
  393.                      frequency can be changed. Possibilities are:
  394.  
  395.                         LOW    (3) - 54.9 milliseconds
  396.                         MED    (2) - 27.5 milliseconds
  397.                         HIGH   (1) - 13.7 milliseconds
  398.                         ULTRA  (0) -  6.9 milliseconds
  399.  
  400.  
  401.        Remarks
  402.  
  403.              SndOpen initializes the timer chip, installs the
  404.              timer interrupt handler, allocates memory for the
  405.              sound queue and sets the time base.
  406.  
  407.              The time base determines how long one tic will be. Since
  408.              a new tone can be loaded as often as once per tic, this
  409.              value also determines how often the frequency can be
  410.              changed.
  411.  
  412.              After a call to SndOpen, a subsequent call to SndClose
  413.              must be made prior to the program's termination.
  414.  
  415.  
  416.        Return value
  417.  
  418.              SndOpen returns a zero if no errors occur, or non
  419.              zero on an error. Constants are defined in sefx.h
  420.              as follows:
  421.  
  422.                      NOERR       (0) - no errors
  423.                      OPENED      (1) - Sefx already opened
  424.                      MALLOC_ERR  (4) - queue allocation error
  425.  
  426.  
  427.  
  428.                                    7
  429.        See also
  430.  
  431.              SndClose SndTbase
  432.  
  433.  
  434.        Example
  435.  
  436.              Initialize Sefx, allocate a 1023 byte sound queue and
  437.              set the time base to MEDium resolution.
  438.  
  439.              #define  QSIZE     1024
  440.              {
  441.              int rv;
  442.  
  443.                 rv = SndOpen(QSIZE, MED);
  444.                 if(rv)
  445.                 {
  446.  
  447.                    ... error handler
  448.  
  449.                 }
  450.  
  451.  
  452.  
  453.        ----------------------------------------------------------------
  454.        SndClose
  455.        ----------------------------------------------------------------
  456.  
  457.        Function
  458.  
  459.              Restores the timer and timer interrupt, and releases the
  460.              sound queue from memory.
  461.  
  462.  
  463.        Syntax
  464.  
  465.              #include "sefx.h"
  466.              void SndClose(void);
  467.  
  468.  
  469.        Remarks
  470.  
  471.              SndClose restores the timer interrupt vector and the
  472.              timer chip to normal, and releases the memory allocated
  473.              for the sound queue.
  474.  
  475.              A call to SndClose is required prior to the program's
  476.              termination.
  477.  
  478.  
  479.        See also
  480.  
  481.              SndOpen
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.                                    8
  490.        Example
  491.  
  492.              Restore the interrupt vector and free the sound queue
  493.              prior to termination
  494.  
  495.              {
  496.  
  497.                 ... closing code
  498.  
  499.                 SndClose();
  500.              }
  501.  
  502.  
  503.  
  504.        ----------------------------------------------------------------
  505.        SndLen
  506.        ----------------------------------------------------------------
  507.  
  508.        Function
  509.  
  510.              Determines how many bytes are currently occupying the
  511.              sound queue.
  512.  
  513.  
  514.        Syntax
  515.  
  516.              #include "sefx.h"
  517.              unsigned SndLen(void);
  518.  
  519.  
  520.        Remarks
  521.  
  522.              SndLen determines how many bytes are currently occupying
  523.              the sound queue. The value is a direct representation
  524.              of how full the sound queue actually is and does not
  525.              necessarily represent how much time is left in the queue.
  526.  
  527.  
  528.        Return value
  529.  
  530.              SndLen returns the number of bytes currently residing in
  531.              the sound queue.
  532.  
  533.  
  534.        See also
  535.  
  536.              SndFlush SndHold SndTerm
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.                                    9
  551.        Example
  552.  
  553.              Check if there is room for 10 more bytes in the sound
  554.              queue.
  555.  
  556.              #define THRESH        512
  557.              #define SndThresh()   (SndLen() < THRESH)
  558.              {
  559.                 if(SndThresh())
  560.                 {
  561.  
  562.                    ...load more sound
  563.  
  564.                 }
  565.              }
  566.  
  567.  
  568.  
  569.        ----------------------------------------------------------------
  570.        SndTbase
  571.        ----------------------------------------------------------------
  572.  
  573.        Function
  574.  
  575.              Sets the time base.
  576.  
  577.  
  578.        Syntax
  579.  
  580.              #include "sefx.h"
  581.              int SndTbase(int tbase);
  582.  
  583.  
  584.        Parameters
  585.  
  586.              tbase - Time base. This value determines the length of
  587.                      time of one tic and subsequently how often the
  588.                      frequency can be changed. Possibilities are:
  589.  
  590.                         LOW    (3) - 54.9 milliseconds
  591.                         MED    (2) - 27.5 milliseconds
  592.                         HIGH   (1) - 13.7 milliseconds
  593.                         ULTRA  (0) -  6.9 milliseconds
  594.  
  595.  
  596.        Remarks
  597.  
  598.              SndRes sets the time base. This value determines the
  599.              length of time of one tic, the basic unit of time used
  600.              by Sefx. Since a new tone can be loaded as often as once
  601.              per tic, the time base determines how often the frequency
  602.              can be changed.
  603.  
  604.  
  605.  
  606.        Return value
  607.  
  608.              SndTbase returns the previous time base.
  609.  
  610.  
  611.                                    10
  612.        See also
  613.  
  614.              SndOpen
  615.  
  616.  
  617.        Example
  618.  
  619.              Set the time base to 6.9 milliseconds per tic, later
  620.              restoring the original time base.
  621.  
  622.              {
  623.              int org_tb;
  624.  
  625.                 org_tb = SndTbase(ULTRA);
  626.  
  627.                    ... short tones
  628.              }
  629.  
  630.  
  631.              {
  632.  
  633.                    ... later
  634.  
  635.                 SndTbase(org_tb);
  636.  
  637.              }
  638.  
  639.  
  640.  
  641.        ----------------------------------------------------------------
  642.        SndFlush
  643.        ----------------------------------------------------------------
  644.  
  645.        Function
  646.  
  647.              Flushes all sound.
  648.  
  649.  
  650.        Syntax
  651.  
  652.              #include "sefx.h"
  653.              void SndFlush(void);
  654.  
  655.  
  656.        Remarks
  657.  
  658.              SndFlush flushes the sound queue, deleting all pending
  659.              and current sounds. It also terminates the current tone.
  660.  
  661.        See also
  662.  
  663.              SndLen SndTerm SndHold
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.                                    11
  673.        Example
  674.  
  675.              Play a song after displaying the opening screen until
  676.              the user hits a key.
  677.  
  678.              {
  679.  
  680.                 ...display opening screen
  681.  
  682.                 SndString(song, 100, 0);
  683.  
  684.                 getch();
  685.  
  686.                 SndFlush();
  687.  
  688.                 ...continue
  689.  
  690.              }
  691.  
  692.  
  693.  
  694.        ----------------------------------------------------------------
  695.        SndHold
  696.        ----------------------------------------------------------------
  697.  
  698.        Function
  699.  
  700.              Puts all sound on hold or releases from hold.
  701.  
  702.  
  703.        Syntax
  704.  
  705.              #include "sefx.h"
  706.              int SndHold(int on_off);
  707.  
  708.  
  709.        Parameters
  710.  
  711.              on_off - hold on/off switch. Possibilities are
  712.  
  713.                          ON  (1) - put on hold
  714.                          OFF (0) - release from hold
  715.  
  716.        Remarks
  717.  
  718.              SndHold puts all sound on hold or releases it from a
  719.              previous hold condition. When a hold is set, the
  720.              current tone as well as the sound queue is immediately
  721.              frozen until it is subsequently released from hold.
  722.              When a hold condition is released, the sounds will
  723.              resume where it left off.
  724.  
  725.  
  726.        Return value
  727.  
  728.              SndHold returns the previous hold condition
  729.  
  730.  
  731.  
  732.  
  733.                                    12
  734.        See also
  735.  
  736.              SndFlush SndTerm
  737.  
  738.  
  739.        Example
  740.  
  741.              Make sure the sound is on hold temporarily and then
  742.              restore it to it's previous condition
  743.  
  744.              {
  745.              int prev_hold;
  746.  
  747.                 prev_hold = SndHold(ON);
  748.  
  749.                    ... guaranteed quiet time
  750.  
  751.                 SndHold(prev_hold);
  752.              }
  753.  
  754.  
  755.  
  756.        ----------------------------------------------------------------
  757.        SndTerm
  758.        ----------------------------------------------------------------
  759.  
  760.        Function
  761.  
  762.              Terminates the current sound.
  763.  
  764.  
  765.        Syntax
  766.  
  767.              #include "sefx.h"
  768.              void SndTerm(void);
  769.  
  770.  
  771.        Remarks
  772.  
  773.              SndTerm terminates the current sound. The sound may be a
  774.              single tone or many tones. In either case all the tones
  775.              that make up the sound are terminated.
  776.  
  777.  
  778.        See also
  779.  
  780.              SndFlush SndHold
  781.  
  782.  
  783.        Example
  784.  
  785.              Terminate the alarm when the user responds
  786.  
  787.              #define CONTINUOUS   0
  788.              #define Alarm()   SndTrill(1400, 600, 8, 8, CONTINUOUS)
  789.              {
  790.                 Alarm();
  791.                    ... wait for response
  792.                 SndTerm();
  793.              }
  794.                                    13
  795.        Sound Generation
  796.  
  797.        Sound generation functions load sounds into the sound queue to be
  798.        played in sequence. Most of the sound generation functions allow
  799.        the sound to be repeated a specified number of times or
  800.        continuously.
  801.  
  802.        A sounds consisting of a single tone is loaded with SndTone while
  803.        a sound consisting of a string of tones can be loaded with
  804.        SndString.
  805.  
  806.        Sefx provides sound generation functions for the more common types
  807.        of sounds. This includes trills, pulses and slides created by
  808.        the functions SndTrill, SndPulse and SndSlide respectively.
  809.        These basic sounds can create a multitude of sounds themselves and
  810.        in addition can be used with other sound generation functions to
  811.        create more complex combinations.
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.                                    14
  856.        ----------------------------------------------------------------
  857.        SndTone
  858.        ----------------------------------------------------------------
  859.  
  860.        Function
  861.  
  862.              Loads a single tone  into the sound queue.
  863.  
  864.  
  865.        Syntax
  866.  
  867.              #include "sefx.h"
  868.              void SndTone(int freq, int durtn);
  869.  
  870.  
  871.        Parameters
  872.  
  873.              freq  - frequency of the tone in hertz.
  874.  
  875.              durtn - number of tic the tone will last.
  876.  
  877.  
  878.        Remarks
  879.  
  880.              SndTone loads single tone of the specified frequency and
  881.              duration into the sound queue. Specifying a duration of 0
  882.              causes the tone to be played continuously. Specifying a
  883.              frequency of 0 will generate a pause. The single tone is
  884.              considered to be one sound.
  885.  
  886.        See also
  887.  
  888.              SndString SndPause SndTbase SndMs
  889.  
  890.  
  891.        Example
  892.  
  893.              Make a two second beep at 2000 hertz.
  894.  
  895.              {
  896.              int second;
  897.  
  898.                  ... made an error
  899.  
  900.                 second = SndMs(1000);
  901.                 SndTone(2000, 2*second);
  902.              }
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.                                    15
  917.        ----------------------------------------------------------------
  918.        SndPause
  919.        ----------------------------------------------------------------
  920.  
  921.        Function
  922.  
  923.              Loads a pause into the sound queue.
  924.  
  925.  
  926.        Syntax
  927.  
  928.              #include "sefx.h"
  929.              void SndPause(int durtn);
  930.  
  931.  
  932.        Parameters
  933.  
  934.              durtn - number of tics the tone will last
  935.  
  936.  
  937.        Remarks
  938.  
  939.              SndPause loads a pause (no sound) of the specified
  940.              duration into the sound queue. The pause is considered to
  941.              be one sound.
  942.  
  943.              SndPause is a function macro defined as SndTone(0, durtn).
  944.  
  945.  
  946.        See also
  947.  
  948.              SndTone SndTbase SndMs
  949.  
  950.  
  951.        Example
  952.  
  953.              Insert a three beat pause between two notes
  954.  
  955.              #define  A     440
  956.              #define  B     494
  957.              {
  958.              int beat;
  959.  
  960.                 beat = SndMs(500);
  961.  
  962.                 SndTone(A, 3*beat);
  963.                 SndPause(3*beat);
  964.                 SndTone(B, 3*beat);
  965.  
  966.              }
  967.  
  968.  
  969.  
  970.  
  971.  
  972.  
  973.  
  974.  
  975.  
  976.  
  977.                                    16
  978.        ----------------------------------------------------------------
  979.        SndString
  980.        ----------------------------------------------------------------
  981.  
  982.        Function
  983.  
  984.              Loads a string of tones into the sound queue.
  985.  
  986.  
  987.        Syntax
  988.  
  989.              #include "sefx.h"
  990.              void SndString(const TONE *str, int count, unsigned reps);
  991.  
  992.  
  993.        Parameters
  994.  
  995.              str    - pointer to an array of type TONE were the
  996.                       string of tones are stored.
  997.  
  998.              count  - number of tones in the array.
  999.  
  1000.              reps   - number of times to repeat the string of
  1001.                       tones.
  1002.  
  1003.  
  1004.        Remarks
  1005.  
  1006.              SndString loads an string of tones, stored in an array
  1007.              of type TONE, into the sound queue. The string of tone
  1008.              will be repeated as specified. Specifying a repetition of
  1009.              0 will cause the string to be repeated continuously.
  1010.  
  1011.              The string of tones is considered to be one sound.
  1012.  
  1013.        See also
  1014.  
  1015.              SndTone SndTbase SndMs SndPause
  1016.  
  1017.  
  1018.        Example
  1019.  
  1020.              Play the scale of notes one time.
  1021.  
  1022.              #define  C     262
  1023.              #define  D     294
  1024.              #define  E     330
  1025.              #define  F     349
  1026.              #define  G     392
  1027.              #define  A     440
  1028.              #define  B     494
  1029.  
  1030.              {
  1031.              TONE scale[7] = { {C,3},{D,3},{E,3},{F,3},
  1032.                                {G,3},{A,3},{B,3}
  1033.                              };
  1034.  
  1035.                 SndString(scale, 7, 1);
  1036.              }
  1037.  
  1038.                                    17
  1039.        ----------------------------------------------------------------
  1040.        SndTrill
  1041.        ----------------------------------------------------------------
  1042.  
  1043.        Function
  1044.  
  1045.              Loads a trill sound into the sound queue.
  1046.  
  1047.  
  1048.        Syntax
  1049.  
  1050.              #include "sefx.h"
  1051.              void SndTrill(int freq1, int freq2,
  1052.                                       int durtn1, int durtn2, int reps);
  1053.  
  1054.  
  1055.        Parameters
  1056.  
  1057.              freq1  - frequency of the first tone in hertz.
  1058.  
  1059.              freq2  - frequency of the second tone in hertz.
  1060.  
  1061.              durtn1 - number of tics the first tone will last.
  1062.  
  1063.              durtn2 - number of tics the second tone will last.
  1064.  
  1065.              reps   - number of times to repeat the trill sound.
  1066.        Remarks
  1067.  
  1068.              SndTrill loads a trill sound into the sound queue. The
  1069.              trill is repeated as specified. Specifying a repetition
  1070.              of 0 will cause the trill to be repeated continuously.
  1071.  
  1072.              A trill sound is sometimes referred to as a flip-flop sound.
  1073.  
  1074.  
  1075.        See also
  1076.  
  1077.              SndSlide SndPulse SndMs SndTbase
  1078.  
  1079.  
  1080.        Example
  1081.  
  1082.              Make a telephone ring five times.
  1083.  
  1084.              {
  1085.              int i = 5;
  1086.  
  1087.                 while(i--)
  1088.                 {
  1089.                    SndTrill(1400, 600, 1, 1, 10);
  1090.                    SndPause(22);
  1091.                 }
  1092.              }
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.                                    18
  1100.        ----------------------------------------------------------------
  1101.        SndSlide
  1102.        ----------------------------------------------------------------
  1103.  
  1104.        Function
  1105.  
  1106.              Loads sliding tones into the sound queue.
  1107.  
  1108.  
  1109.        Syntax
  1110.  
  1111.              #include "sefx.h"
  1112.              void SndSlide(int start, signed dfreq,
  1113.                                                int durtn, int reps);
  1114.  
  1115.        Parameters
  1116.  
  1117.              start - frequency of the starting tone in hertz.
  1118.  
  1119.              dfreq - change (delta) in frequency per tic.
  1120.  
  1121.              durtn - number of tic the slide will last.
  1122.  
  1123.              reps  - number of times to repeat the slide.
  1124.  
  1125.  
  1126.        Remarks
  1127.  
  1128.              SndSlide loads sliding tones into the sound queue. The
  1129.              frequency is increased (positive 'dfreq') or decreased
  1130.              (negative 'dfreq') on each tic by the specified delta
  1131.              frequency. The sliding tone will last the specified
  1132.              duration and will be repeated as specified.
  1133.  
  1134.              To calculate the frequency of the ending tone in the slide
  1135.              use: end = start + (durtn - 1) * dfreq.
  1136.  
  1137.              Hint: shorter (faster) time bases generate a smoother
  1138.              sounding slide while longer (slower) time bases generate
  1139.              a more course sounding slide. Both cases can be useful
  1140.              for creating the desired effect.
  1141.  
  1142.        See also
  1143.  
  1144.              SndTrill SndPulse SndMs SndTbase
  1145.  
  1146.  
  1147.        Example
  1148.  
  1149.              Play a sliding tone from 2000 hertz to 992 hertz
  1150.  
  1151.  
  1152.              {
  1153.  
  1154.                 SndSlide(2000, -28, 37);
  1155.  
  1156.              }
  1157.  
  1158.  
  1159.  
  1160.                                    19
  1161.        ----------------------------------------------------------------
  1162.        SndPulse
  1163.        ----------------------------------------------------------------
  1164.  
  1165.        Function
  1166.  
  1167.              Loads a pulsing sound into the sound queue.
  1168.  
  1169.        Syntax
  1170.  
  1171.              #include "sefx.h"
  1172.              void SndPulse(int freq, int durtn,
  1173.                                              int pdurtn, int reps);
  1174.  
  1175.        Parameters
  1176.  
  1177.              freq   - frequency of the tone in hertz.
  1178.  
  1179.              durtn  - number of tics the tone will last.
  1180.  
  1181.              pdurtn - number of tics the pause will last.
  1182.  
  1183.              reps   - number of times to repeat the pulse.
  1184.  
  1185.  
  1186.        Remarks
  1187.  
  1188.              SndPulse loads a tone of the specified frequency and
  1189.              duration, followed by a pause of the specified duration
  1190.              The sound is repeated as specified. Specifying a repetition
  1191.              of 0 will cause the pulse to repeat continuously.
  1192.  
  1193.              SndPulse is a function macro defined as:
  1194.              SndTrill(freq, 0, durtn, pdurtn, reps);
  1195.  
  1196.  
  1197.        See also
  1198.  
  1199.              SndTrill SndSlide SndMs SndTbase
  1200.  
  1201.  
  1202.        Example
  1203.  
  1204.              Make a wrist watch alarm. (Time base = LOW/54.9)
  1205.  
  1206.              {
  1207.              int i = 3;
  1208.  
  1209.                 while(i--)
  1210.                 {
  1211.                    SndPulse(4250, 2, 1, 3);
  1212.                    SndPause(9);
  1213.                 }
  1214.  
  1215.              }
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.                                    20
  1222.        ----------------------------------------------------------------
  1223.        SndMs
  1224.        ----------------------------------------------------------------
  1225.  
  1226.        Function
  1227.  
  1228.              Converts milliseconds to tics.
  1229.  
  1230.  
  1231.        Syntax
  1232.  
  1233.              #include "sefx.h"
  1234.              int SndMs(unsigned ms);
  1235.  
  1236.  
  1237.        Parameters
  1238.  
  1239.              ms - number of milliseconds to convert to tics
  1240.  
  1241.  
  1242.        Remarks
  1243.  
  1244.              SndMs converts a value in milliseconds to the equivalent
  1245.              number of tics, rounding off to the nearest tic. SndMs
  1246.              takes into account the current time base and adjusts
  1247.              the resulting number of tics accordingly. The number of
  1248.              tics will always be at least one unless 0 milliseconds is
  1249.              specified.
  1250.  
  1251.              Shorter (faster) time bases result in a more precise
  1252.              conversion than longer (slower) time bases. In most
  1253.              applications this is an insignificant limitation. In
  1254.              any case the value will never be off more that the length
  1255.              of time of one tic.
  1256.  
  1257.  
  1258.        Return value
  1259.  
  1260.              SndMs returns the number of tics that is approximately
  1261.              equal to the specified number of milliseconds.
  1262.  
  1263.  
  1264.        See also
  1265.  
  1266.              SndTbase
  1267.  
  1268.  
  1269.        Example
  1270.  
  1271.              Make a one second tone at 100 hertz
  1272.  
  1273.              {
  1274.              int second;
  1275.  
  1276.                 second = SndMs(1000);
  1277.  
  1278.                 SndTone(100, second);
  1279.  
  1280.              }
  1281.  
  1282.                                    21
  1283.         Appendix A
  1284.  
  1285.  
  1286.        Things to look out for.
  1287.  
  1288.        ∙ Sefx takes over interrupt 8 and may change the system clock
  1289.          rate. If the clock rate is changed, Sefx arbitrates the
  1290.          timer chain in order that it's rate remains the same. If
  1291.          a program written with Sefx needs to chain into interrupt 8
  1292.          it should do so prior to the calling SndOpen.
  1293.  
  1294.        ∙ The functions SndOpen and SndClose make calls to the C
  1295.          functions malloc and free respectively.
  1296.  
  1297.        ∙ In the small and medium memory models, the near heap where
  1298.          the sound queue is allocated, is limited. The data segment
  1299.          (globals etc.) + the stack + allocated memory (sound queue)
  1300.          must not exceed 64K bytes. If an extremely large sound queue
  1301.          is required the compact or large model, where the sound queue
  1302.          can be as large as 65532 bytes, should be used.
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.                                    22
  1344.        Appendix B
  1345.  
  1346.        Musical notes.
  1347.  
  1348.        This appendix provides information about frequencies of musical
  1349.        notes and octave shifting.
  1350.  
  1351.  
  1352.        The Equal Tempered Chromatic Scale (rounded to integer)
  1353.  
  1354.           note|freq  |  note|freq  |  note|freq  |  note|freq
  1355.         -------------|-------------|-------------|-------------
  1356.           C0     16  |  C2     65  |  C4    262  |  C6   1047
  1357.           C#0    17  |  C#2    69  |  C#4   277  |  C#6  1109
  1358.           D0     18  |  D2     73  |  D4    294  |  D6   1175
  1359.           D#0    19  |  D#2    78  |  D#4   311  |  D#6  1245
  1360.           E0     21  |  E2     82  |  E4    330  |  E6   1319
  1361.           F0     22  |  F2     87  |  F4    349  |  F6   1397
  1362.           F#0    23  |  F#2    93  |  F#4   370  |  F#6  1480
  1363.           G0     25  |  G2     98  |  G4    392  |  G6   1568
  1364.           G#0    26  |  G#2   104  |  G#4   415  |  G#6  1661
  1365.           A0     28  |  A2    110  |  A4    440  |  A6   1760
  1366.           A#0    29  |  A#2   117  |  A#4   466  |  A#6  1865
  1367.           B0     31  |  B2    123  |  B4    494  |  B6   1976
  1368.                      |             |             |
  1369.           C1     33  |  C3    131  |  C5    523  |  C7   2093
  1370.           C#1    35  |  C#3   139  |  C#5   554  |  C#7  2217
  1371.           D1     37  |  D3    147  |  D5    587  |  D7   2349
  1372.           D#1    39  |  D#3   156  |  D#5   622  |  D#7  2489
  1373.           E1     41  |  E3    165  |  E5    659  |  E7   2637
  1374.           F1     44  |  F3    175  |  F5    698  |  F7   2794
  1375.           F#1    46  |  F#3   185  |  F#5   740  |  F#7  2960
  1376.           G1     49  |  G3    196  |  G5    784  |  G7   3136
  1377.           G#1    52  |  G#3   208  |  G#5   831  |  G#7  3322
  1378.           A1     55  |  A3    220  |  A5    880  |  A7   3520
  1379.           A#1    58  |  A#3   233  |  A#5   932  |  A#7  3729
  1380.           B1     62  |  B3    247  |  B5    988  |  B7   3951
  1381.                                                  |  C8   4186
  1382.  
  1383.        Since the frequencies of the octaves increase as a factor of
  1384.        two, musical notes of the other octaves are easily accomplished
  1385.        by multiplying or dividing by factors of two, or more
  1386.        efficiently by shifting left or right. For example to obtain
  1387.        the frequency of A5, the value of A4 (440) is shifted left
  1388.        once (multiplied by two). To obtain the frequency of A2,
  1389.        shift A4 right twice (divide by four).
  1390.  
  1391.        Examples:   A5 = A4 << 1
  1392.  
  1393.                    A2 = A4 >> 2
  1394.  
  1395.        Note: It is better to shift from a higher octave to a lower
  1396.        octave since the percent of rounding error, when rounding to an
  1397.        integer, is smaller with the larger values.
  1398.        Appendix C
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.                                    23
  1405.        Appendix C
  1406.  
  1407.        Sound queue usage
  1408.  
  1409.        Some of the sound generation functions load instructional
  1410.        information as well as frequency and duration information. This
  1411.        added information allows Sefx to conserve memory. When the sound
  1412.        is initially loaded by the sound generation function, it will
  1413.        occupy an 'initial' number of bytes in the sound queue. When the
  1414.        next sound is fetched from the sound queue, the instructional
  1415.        information is evaluated and then discarded. The remaining bytes
  1416.        will continue to occupy the sound queue until the sound is
  1417.        terminated. This is referred to in the table below as 'residual'.
  1418.  
  1419.  
  1420.                               Initial           Residual
  1421.                              ---------         ----------
  1422.  
  1423.           SndTone                4                 4
  1424.  
  1425.           SndPause               4                 4
  1426.  
  1427.           SndString         8 + 4 * len         4 * len
  1428.  
  1429.           SndTrill              16                 8
  1430.  
  1431.           SndSlide         8 + 4 * durtn       4 * durtn
  1432.  
  1433.           SndPulse              16                 8
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.                                    24
  1466.        Appendix D
  1467.  
  1468.        Sefx v1.0 Registration Form
  1469.  
  1470.        Name: ______________________________________________________
  1471.  
  1472.        Company: ___________________________________________________
  1473.  
  1474.        Address: ___________________________________________________
  1475.  
  1476.        City: ____________________________  State: _________________
  1477.  
  1478.        Zip code: _________________  Phone # : _____________________
  1479.  
  1480.        CompuServe # : _____________________________________________
  1481.  
  1482.        How did you acquire Sefx ? _________________________________
  1483.  
  1484.        ____________________________________________________________
  1485.  
  1486.        What functions do you find most useful ?____________________
  1487.  
  1488.        ____________________________________________________________
  1489.  
  1490.        What functions do you find least useful ?___________________
  1491.  
  1492.        ____________________________________________________________
  1493.  
  1494.        What functions, not in Sefx, would you like to see ?________
  1495.  
  1496.        ____________________________________________________________
  1497.  
  1498.        What other types of libraries would you find useful ?_______
  1499.  
  1500.        __ Serial Communications  __ Expanded Memory  __ IEEE/GPIB
  1501.  
  1502.        __ Game Port  Others: ______________________________________
  1503.  
  1504.        registration                                      $ 25.00
  1505.  
  1506.        California residents add sales tax (  8.25% )     $________
  1507.  
  1508.        shipping inside continental U.S.   ( $ 2.00 )
  1509.        shipping outside continental U.S.  ( $ 5.00 )     $________
  1510.  
  1511.  
  1512.                                                 Total:   $________
  1513.  
  1514.        All Payments Must be in U.S. Dollars
  1515.  
  1516.        Make check or money order payable to:    Bri Productions
  1517.                                                 P.O. Box 7121
  1518.                                                 Fremont, CA 94537-7121
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.                                    25
  1527. 
  1528.