home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / bluebook.zip / SOUND.DOC < prev    next >
Text File  |  1986-05-08  |  12KB  |  290 lines
  1. SOUND.DOC -- Description of the Sound Generation Routines in SOUND.ASM
  2. ======================================================================
  3.  
  4.   From `BLUEBOOK of ASSEMBLY ROUTINES for the IBM PC & XT'
  5.         by Christopher L. Morgan
  6.         Copyright (C) 1984 by The Waite Group, Inc.
  7.  
  8.   Purpose:
  9.   -------- 
  10.          The routines in SOUND.ASM are useful for producing sound on the
  11.     PC via the speaker and associated timer chip. The routines named 
  12.     TONExxxx are primitives that directly access the speaker and timer.
  13.     All other routines call these routines to produce any sound.
  14.  
  15.    Contents:
  16.    ---------
  17.    DELAY    --  Delay for a specified time interval    
  18.    FREQ        --  Convert from frequency to period
  19.    GLISSNDO    --  Make a glissando (sliding tone)
  20.    LINSCALE    --  Provide linear scaling
  21.    PITCH    --  Convert from pitch number    
  22.    PLAY        --  Play music from a table
  23.    TONE        --  Make a tone
  24.    TONE_INIT    --  Initialize speaker timer
  25.    TONE_OFF    --  Turn off tone
  26.    TONE_ON    --  Turn on tone
  27.    TONE_SET    --  Set the tone on the speaker
  28.  
  29.   Overview:
  30.   ---------
  31.     The speaker is connected to the output of timer 2, which produces a 
  32.   square wave whose frequency can be set using the TONE_SET routine.  TONE_SET
  33.   assumes the timer has been properly initialized, as is done during normal
  34.   boot-up.  TONE_INIT can also be used to initialize the timer.
  35.     The frequency of the square wave from the timer is determined by the
  36.   formula, f=F/n, where f is the frequency of the square wave, F is 1,193,182
  37.   and n is a 16-bit integer that is input to the routine.  The constant, F, is
  38.   exactly 1/3 the frequency of the NTSC subcarrier used for color encoding by
  39.   the Color/Graphics Adapter.  F is derived by hardware from a main clock
  40.   signal that runs at 14,317,800 Hertz and supplies the timing for most of the
  41.   computer.
  42.     TONE_ON and TONE_OFF provide control over whether the square wave
  43.   reaches the speaker, thus turning the sound on or off.  There are actually
  44.   two bits involved, one to control the connection between the clock signal
  45.   and the timer, and one to control the connection between the timer and the
  46.   speaker.  Both routines switch both connections simultaneously.  There is
  47.   no provision to control the bits independently.
  48.     The routine, DELAY, provides timing for the duration of musical notes
  49.   in milliseconds.  The routine, FREQ, uses the formula, n=F/f, to compute
  50.   the input parameter for TONE_SET from a given frequency.  Using this just
  51.   before TONE_SET permits working directly with frequencies rather than clock
  52.   cycles of the 1,193,182 Hertz clock.
  53.     The routine, TONE, uses the other routines to produce tones of a
  54.   given frequency and duration.  The frequency is input as a 16-bit integer
  55.   and the duration is in milliseconds using the DELAY routine.
  56.     The rest of the routines provide special sound effects.  SCALE converts
  57.   numbers between 0 and 1 into numbers within the range of X1 and X2, which
  58.   are any specified 16-bit integers.  This is used with RANDOM to produce
  59.   pseudo-random numbers between 0 and 1.  The routine, WHITE, uses these 
  60.   pseudo-random numbers along with SCALE to generate white noise.  The routine,
  61.   GUN shows how to shape white noise into a machine gun sound.
  62.     The routine, GLISSANDO, makes a tone that slides smoothly from one
  63.   frequency, X1, to another, X2.  RED shows how to shape glissandos into red
  64.   alert sirens.
  65.     PITCH and PLAY are music routines.  PITCH converts the pitch number
  66.   to a value useable by TONE_SET to set the frequency.  PLAY plays music from
  67.   a "playlist" of notes.
  68.  
  69. __________________________ Descriptions of Routines __________________________
  70.  
  71. DELAY -- Delay for a specified number of milliseconds
  72. -----------------------------------------------------
  73.   Function: This routine provides a time delay for specifying the 
  74.     duration of a sound, a wait, etc.  
  75.  
  76.   Input: Upon input, CX contains the no. of milliseconds to delay.
  77.  
  78.   Output: None
  79.  
  80.   Register used: CX is first saved and then restored.
  81. _______________________________________________________________________________
  82.  
  83. FREQ -- Convert from Frequency to Period
  84. ----------------------------------------
  85.   Function: This routine  converts from frequency to the number required
  86.     by TONE_SET to set the frequency.  The routine evaluates the formula,
  87.     N = F/f, where f is the frequency input to this routine, n is the number 
  88.     output by this routine, and F is 1,193,182. In other words, this routine
  89.     divides the specified frequency, f, into the 1,193,182 hertz clock
  90.     frequency that drives the timer.  Use this routine just before TONE_SET.
  91.  
  92.   Input: Upon entry, the frequency is in CX.
  93.  
  94.   Output: Upon exit, F/f is in CX.
  95.  
  96.   Registers used: CX is modified, AX & DX are first saved and then restored.
  97. _______________________________________________________________________________
  98.  
  99. GLISSNDO -- Make a Glissando
  100. ----------------------------
  101.   Function: This routine makes a glissando; i.e., a sound that slides from
  102.     one frequency to another.  The rate of change can be controlled.
  103.  
  104.   Input: Upon entry, the starting frequency is in BX, the ending frequency
  105.     is in CX, and the control parameter for the rate increase is in DX.
  106.     Increasing the value in DX slows down the rate of change.
  107.  
  108.   Output: To the speaker and timer only.
  109.  
  110.   Registers used: All registers are saved and then restored.
  111.  
  112.   Segments referenced: The data segment must contain the variables,
  113.     F_START & F_END.
  114.  
  115.   Routines called: TONE_SET, TONE_ON, TONE_OFF, DELAY
  116.  
  117.   Special note: The speaker timer must already have been initialized.  If
  118.     necessary, use TONE_INIT to initialize before calling this routine.
  119. _______________________________________________________________________________
  120.  
  121. PITCH -- Convert from Pitch Number
  122. ----------------------------------
  123.   Function: This routine converts from pitch number to the value required
  124.     by TONE_SET to set the frequency. The pitch numbers refer to an 
  125.     extended chromatic scale. The notes of this scale are numbered from
  126.     0 to 95 with 12 notes/octave. 0 corresponds to a C at 16.35 hertz.
  127.  
  128.   Input: Upon entry the pitch number of the note is in AL.
  129.  
  130.   Output: Upon exit, the DX register has the proper value for TONE_SET.
  131.  
  132.   Registers used: DX has value; AX, BX, & CX are saved and then restored.
  133.  
  134.   Segments Referenced: The data segment must contain the
  135.                         following pitch table:
  136.  
  137.     NOTES    DW    4186            ;C
  138.         DW    4435            ;C#/D-
  139.         DW    4699            ;D
  140.         DW    4978            ;D#/E-
  141.         DW    5274            ;E
  142.         DW    5588            ;F
  143.         DW    5920            ;F#/G-
  144.         DW    6272            ;G
  145.         DW    6645            ;G#/A-
  146.         DW    7040            ;A
  147.         DW    7459            ;A#/B-
  148.         DW    7902            ;B
  149.  
  150.   Routines called: FREQ
  151. _______________________________________________________________________________
  152.  
  153. LINSCALE -- Do Linear Scaling
  154. -----------------------------
  155.   Function: This routine performs a linear scaling, converting a fixed
  156.     point number between 0 and 1 into an integer between X1 and X2, 
  157.     where X1 and X2 are 16-bit integers.
  158.  
  159.   Input: Upon entry, CX has a binary fixed point number between 0 and 1.
  160.     The binary point is to the left of the leftmost bit. X1 and X2 are
  161.     variables stored in memory.
  162.  
  163.   Output: Upon exit, CX contains the 16-bit integer result.
  164.  
  165.   Registers used: CX is modified, AX & DX are first saved and then restored.
  166.  
  167.   Segments referenced: The data segment must contain the variables, X1 & X2.
  168. _______________________________________________________________________________
  169.  
  170. PLAY -- Play Music
  171. ------------------
  172.   Function: This program plays music.  It reads a binary "play" list
  173.     that contains instructions to make the tune.  This list consists
  174.     of a series of music instructions: Tempo, Note, Rest, and End.
  175.  
  176.     The syntax for the instructions are:
  177.  
  178.       Tempo Command
  179.         first byte  = ASCII "T"
  180.         second byte = tempo in whole notes/minute
  181.  
  182.       Note Command
  183.         first byte  = ASCII "N"
  184.         second byte = pitch number (integer 0-95)
  185.         third byte  = length (8-bit binary fixed point - scale 1)
  186.         fourth byte = style (8-bit binary fixed point - scale 0)
  187.  
  188.       Rest Command
  189.         first byte  = ASCII "R"
  190.         second byte = length (8-bit binary fixed point - scale 1)
  191.  
  192.       End Command
  193.         first byte  = ASCII "X"
  194.  
  195.     The scaling is:
  196.       scale 0 has the binary point to the left of the leftmost digit
  197.       scale 1 has the binary point to the right of the leftmost bit
  198.  
  199.   Input: Upon entry, the address of the "play" list is in DS:SI
  200.  
  201.   Output: To the speaker and timer only
  202.  
  203.   Registers Used: Entry registers are saved and restored
  204.  
  205.   Segments Referenced: The data segment contains the "play" list and
  206.                          the variables WHOLE, ACCOUNT, and RCOUNT
  207.  
  208.   Routines Called: PITCH, TONE_OFF, DELAY
  209. _______________________________________________________________________________
  210.  
  211. TONE -- Make a Tone
  212. -------------------
  213.   Function: This routine makes a tone of a given frequency and given length.
  214.  
  215.   Input: Upon entry, the frequency is in CX and the length in no. of
  216.     milliseconds is in DX.
  217.  
  218.   Output: To the speaker and timer only.
  219.  
  220.   Registers used: AX, CX, & DX are first saved and then restored.
  221.  
  222.   Segments referenced: The data segment must contain the variable, COUNT.
  223.  
  224.   Routines called: TONE_SET, TONE_ON, TONE_OFF, DELAY
  225.  
  226.   Special note: The speaker timer must already have been properly initialized.
  227.     This should normally occur during boot-up.
  228. _______________________________________________________________________________
  229.  
  230. TONE_INIT -- Initialize Speaker Timer
  231. -------------------------------------
  232.   Function: This routine initializes the part of the 8253 timer chip used
  233.     by the speaker system.  Particularly, it sets up channel 2 of this 
  234.     timer as a square wave generator. This routine does not select the 
  235.     frequency, nor does it turn on the tone.  Use TONE_SET to select the
  236.     frequency, TONE_ON to turn the tone on, and TONE_OFF to turn it off.
  237.  
  238.   Input: None
  239.  
  240.   Output: Only to the timer 2 of the speaker circuit.
  241.  
  242.   Registers used: AX is first saved and then restored.
  243. _______________________________________________________________________________
  244.  
  245. TONE_OFF -- Turn off Tone
  246. -------------------------
  247.   Function: This routine turns of the timer and speaker.
  248.  
  249.   Input: None
  250.  
  251.   Output: To the timer and speaker only.
  252.  
  253.   Registers Used: AX register is first saved and then restored.
  254. _______________________________________________________________________________
  255.  
  256. TONE_ON -- Turn on Tone
  257. -----------------------
  258.   Function: This routine turns on the timer and speaker to produce a tone.
  259.     The frequency of the tone must have already been selected on the timer.
  260.     you can use TONE_SET to set the frequency of the tone.
  261.  
  262.   Input: None
  263.  
  264.   Output: To the timer and speaker only.
  265.  
  266.   Register used: AX is first saved and then restored.
  267. _______________________________________________________________________________
  268.  
  269. TONE_SET -- Set the Tone on the Speaker
  270. ---------------------------------------
  271.   Function: This routine selects the frequency of the square wave tone to 
  272.     the speaker.  The input to this routine is a 16-bit integer n which 
  273.     determines the frequency, f, according to the following formula:
  274.       f = F/n
  275.     where F is 1,193,182, the frequency of a clock signal which feeds the
  276.     timer.  The value, n, is the number of cycles of the clock signal per
  277.     cycle of the resulting square wave.  This routine does not actually 
  278.     turn on the tone.  Use TONE_ON to turn on the tone, and TONE_OFF to turn
  279.     it off. This routine assumes the speaker timer has already been properly
  280.     initialized.  This happens during normal boot-up, or you can use 
  281.     TONE_INIT to initialize the timer.
  282.  
  283.   Input: Upon entry, the 16-bit integer, n, is in the CX register.
  284.  
  285.   Output: Only to the timer 2.
  286.  
  287.   Register used: AX is first saved and then restored.
  288. _______________________________________________________________________________
  289.  >>>Physical EOF SOUND.DOC<<<
  290.