******************************************************************
*Document type: Library Reference
*Readme file name: mansnd.txt
*Library prefix: snd
*Library name: Sound Interface
*Version: 1.07
*Creator: K.T / Y.K
*Created: 4/21/95
*Comments: Changes from 3rd Step Library 11/11/94 -> 04/21/95
******************************************************************

******************************************************************
Description of Version 1.05 -> Version 1.05 Changes

* Sample Sequence Data Bug Fixes

Sequence data could not be played back in the smpsnd1 demo 
released on 11/11/94.  This problem was caused because the sound 
data was not converted for use with version 1.27 of the sound 
driver.  Following is an description of the smpsnd1 data files as 
well as a description of the files that were changed.  (See the 
saturn\segadrv\man document for information on sound driver 
specification changes.)

smpsnd1 Data Files    Type            Changed?
----------------------------------------------
boottone.bin          Tone data       No
bootse.bnk            Sequence data   Yes
pitch.bnk             Sequence data   Yes
bootse.exb            DSP program     No
vc_ps.exb             DSP program     No
surround.exb          DSP program     No
3bandana.exb          DSP program     No
bootsnd.mp            Area map        Yes

* bootsnd.mp (area map) was changed because the sequence data size
  changed.  Following are the changes made to the sequence data
  size in bootsnd.mp.

                 11/11/94            12/27/94
---------------------------------------------
Data number 0    2000H       ->      4000H
Data number 1    2000H       ->      4000H

******************************************************************
Manual Addenda

* Specification Changes

[Summary of Changes]

+ Corrections

  1) Procedure changed during SND_ChgMap

+ Additions

  2) Explanation of SND_Init(),SND_MoveData() Execution 
  3) Addition of DSP Stop Command
  4) Addition of All Sound Stop Command
  5) Addition of Sequence PAN Setting Command
  6) Addition of Sound Control Setting
     (stereo/mono mode setting)

* Details of Changes

[Function Specifications]

+ Sound System Startup

+---------------------------+---------------------------+
| Startup sound system      | SND_Init                  |
+---------------------------+---------------------------+

Do not execute SND_Init() during interrupt processing.

+ Performance Setup

+---------------------------+---------------------------+
| Transfer sound data       | SND_MoveData              |
+---------------------------+---------------------------+

When the default interrupt priority is used, do not execute 
SND_MoveData() during interrupt processing.  To use during 
interrupt processing, change the interrupt priority so that the 
DMA completion interrupt can occur within the interrupt processing 
period.  Use the System Library to change interrupt priority. The 
sound demo program SMPSND4 is provided as an example.

+ Common Sound Control

+---------------------------+---------------------------+
| Change sound area map     | SND_ChgMap                |
+---------------------------+---------------------------+

****** NOTE ******

While a sound is being played or the DSP is being, changing the 
sound area map or sound data being used may cause the sound driver 
to crash.  Always observe the following requirement:

When there is no CD-DA audio playback, execute the sound area map 
change function after executing the following two commands.

  * Stop DSP function
  * All sound off function

+---------------------------+---------------------------+
| Stop DSP                  | SND_StopDsp               |
+---------------------------+---------------------------+

Format:         SndRet SND_StopDsp(void)
Input:          None
Output:         None
Function Value: Command execution status
Function:       Halts DSP micro program execution.

+---------------------------+---------------------------+
| All sound off             | SND_OffAllSound           |
+---------------------------+---------------------------+

Format:         SndRet SND_OffAllSound(void)
Input:          None
Output:         None
Function Value: Command execution status
Function:       Stops playback of all sound.

+ Sound Control Sequence

+---------------------------+---------------------------+
| Set sequence pan          | SND_SetSeqPan             |
+---------------------------+---------------------------+

Format:         SndRet SND_SetSeqPan(SndSeqNum seq_no, Uint8
                ctrl_sw, Uint8 md_pan)
Input:  seq_no: Sound control number
       ctrl_sw: Control switch
                  SND_SEQ_PAN_ON  = Control ON
                  SND_SEQ_PAN_OFF = Control OFF
        md_pan: MIDI pan data
                Value range:    0x00 to 0x7f

                Description of values:
                +---------------------------+
                | left <-- Center --> Right |
                +---------------------------+
                | 0x00 <--  0x40  --> 0x7f  |
                +---------------------------+

Output:         None
Function Value: Command execution status
Function:       Sets sequence PAN.  (For detailed information, see
                the Sound Driver System Interface documentation in
                the Sound Development Manual.)

+ Other

+---------------------------+---------------------------+
| Set sound control         | SND_SET_SND_CTRL          |
+---------------------------+---------------------------+

Format:         void SND_SET_SND_CTRL(Uint8 snd_ctrl)
Input:          Sound control value
                  SND_CTRL_OUTPUT_STEREO = Stereo
                  SND_CTRL_OUTPUT_MONO   = Mono
Output:         None
Function Value: None
Function:       Sets the sound control value. Currently stereo and
                mono modes can be selected.

+---------------------------+---------------------------+
| Get sound control         | SND_GET_SND_CTRL         |
+---------------------------+---------------------------+

Format:         Uint8 SND_GET_SND_CTRL(void)
Input:          None
Output:         Sound control value
                  SND_CTRL_OUTPUT_STEREO  Stereo
                  SND_CTRL_OUTPUT_MONO    Mono
Function Value: None
Function:       Gets the sound control value.

* Additional Information

+ Accessing Sound Memory

Frequent access to sound memory is prohibited.  When sound memory 
is frequently accessed by the host side (SH2), the sound driver 
will lose access to that memory.  The sound driver will stop 
operating as a result.

Example: SND_StartSeq(1,0,0,0);
         while(SND_SEQ_STAT_MODE(status) == SND_MD_STOP){
             SND_GetSeqStat(&status, 0);
         }

In the case above, the sound driver may go into an infinite loop.  
Since the host side accesses the status memory frequently, the 
"stop sequence" status cannot be written to memory even if the 
sequence has stopped playing.

* Warnings

+ 8/22/94 SMPSND3.C Demo

This sample has been removed.  The interrupt status register used 
by this sample cannot be used because of SCU hardware 
restrictions.

+ PCM Data in the Demo Programs

When listening to the PCM sound data used in smpsnd4 and smpsnd5, 
the songs will sound strange.  This is not a hardware or software 
bug.  This strange playback is caused by bad PCM data.

******************************************************************
Description of Version 1.06 Changes

* Changes to Duplicate Command Calling Prevention Fix

The interrupts that occur during sending of commands to the sound 
driver are no longer disabled by masking the interrupt.  
Interrupts are now controlled via flags.

* Changes to Map Change End Check Method

A wait has been added to the map change end check.  As a result, 
no overhead is placed on driver operations.

******************************************************************
Description of Version 1.07 Changes

* Sequence Pan Bug Fix

Corrected problems that prevented sequence pan commands from being 
issued correctly.

* Addition of 3D Audio Parameter Setup Function

A function which sets QSound and Yamaha 3D parameters was added.

******************************************************************
Manual Addenda

* Specification Changes

[Summary of Changes]

+ Corrections

  1) Fixed SND_SetSeqPan Command Send Bug

+ Additions

  2) Explanations of the SND_SetQSound(), SND_Set3D_Stat(),
     SND_Set3D_Init() Functions

* Details of Changes

[Function Specifications]

+ QSound Parameter Setup

+---------------------------+---------------------------+
| Set QSound parameters     | SND_SetQSound             |
+---------------------------+---------------------------+

Format:         SndRet SND_SetQSound(Uint8 QCh, Uint8 QSt)
Input:     QCh: QSound channel to be controlled
           QSt: QSound pan data (0x00 to 0x1e)

                Description of values:
                +---------------------------+
                | left <-- Center --> Right |
                +---------------------------+
                | 0x00 <--  0x0f  --> 0x1e  |
                +---------------------------+

Output:         None
Function Value: Command execution status
Function:       Sets the QSound audio placement.  (For detailed
                information, see the Sound Driver System Interface
                section in the Sound Development Manual.)

+ Yamaha 3D Parameter Setup

+---------------------------+---------------------------+
| Set Yamaha 3D parameters  | SND_Set3D_Stat          |
+---------------------------+---------------------------+

Format:         SndRet SND_Set3D_Stat(Uint8 Y3DDst, Uint8 Y3DAzm,
                Uint8 Y3DElv)
Input:  Y3DDst: Distance (0x00 to 0x7f)
        Y3DAzm: Azimuth (0x00 to 0x7f)
        Y3DElv: Elevation (0x00 to 0x7f)
Output:         None
Function Value: Command execution status
Function:       Sets Yamaha 3D audio placement.  (For detailed
                information, see the Sound Driver System Interface
                section in the Sound Development Manual.)

+ Yamaha 3D Placement Initialization

+---------------------------+---------------------------+
| Yamaha 3D Placement Init  | SND_Set3D_Init            |
+---------------------------+---------------------------+

Format:         SndRet SND_Set3D_Init()
Input:          None
Output:         None
Function Value: Command execution status
Function:       Sets placement for Yamaha 3D audio to front
                center.  (For detailed information, see the Sound
                Driver System Interface section in the Sound
                Development Manual.)

***************************end of file***************************
