******************************************************************
*Document type: Library reference
*Readme file name: MANPCM.DOC
*Library prefix: pcm
*Library name: PCM-ADPCM Playback Library
*Version: 1.16
*Creator: Y.T
*Created: 3/31/95
*Comments: None
******************************************************************

1. Overview

This library supports PCM stream playback on the Saturn.

Playback modes include the Memory Playback mode, File Playback 
mode, and Stream Playback mode. The Memory Playback mode can be 
performed by memory-resident data playback or sequential ring 
buffer playback.

AIFF format, APCM format (SEGA ADPCM Encoder output file format), 
and CD-ROM XA audio format files can be played.

This library was created based on the audio processing functions 
developed for the Cinepak library. Because of this, the method of 
using function interfaces and other aspects of the library is 
similar to that used by the Cinepak library. However, note that 
there are minor differences between the two libraries in how the 
work and pause processing work buffers are set up.

2. Provided Software Materials

* PCM-ADPCM Playback Library
* ADPCM Decompression Library
* Sample program (with source) & VCD script (VCD V1.72 compatible)

3. Description of Compatible Software/Hardware Versions

Target:

	Programming Box (Model S) SCU2.4 or higher

File System:

	Version 1.20 or higher

Stream System:

	Version 1.20 or higher

DMA Library:
	
	Version 1.05 or higher

Sound Interface Library:

	Version 1.05 or higher

Sound Driver:

	Version 1.28 or higher

ADPCM Decompression Library:

	Version 1.01 or higher

Virtual CD System (required for CD-based playback):

	VCDPRE:   Version 3.06 or higher
	VCDBUILD: Version 3.06 or higher
	VCDEMU:   Version 1.72 or higher

4. Application Notes

4.1 Recommended Buffer Sizes

Work buffer:

	Size of work structure size

Ring buffer:

	Minimum (sector size*) *10 [byte]

PCM buffer:

	4096*2 to 4096*4 [sample/ch]

Pause processing work:

	Same size as PCM buffer is optimal. Minimum 4096 [sample]

4.2 SCU-DMA Restrictions

When the SCU DMA is used to transfer data from the CD Block to the 
ring buffer, peripheral data may not be read correctly.

It is possible to solve this problem by setting the maximum 
transfer sector count (default value 20) to a lower value.  
However, when this value is set low, it is necessary to call a 
task function (STM_ExecServer or STM_ExecTrans for stream 
playback) at appropriate intervals.

Example:

PCM_SetTrModeCd(pcm, PCM_TRMODE_SCU); /* SCU-DMA transfer */
PCM_SetLoadNum(pcm, 5); /* Max value for 1 transfer [sector] */

During a SCU DMA, the SCU owns the bus completely. Because of 
this, the SH2 goes into a wait state whenever it attempts to 
access the CPU bus. Avoid using SCU DMAs whenever possible.

4.3 Other Cautions

* This library uses the CPU timer. Do not use the CPU timer when
  this library is running.

* Always call the PCM_Init function at the beginning of the
  program.

* Always call the PCM_VblIn function at each V blank.

* Call the PCM_Task function regularly, at least at each V blank
  (once per 16 ms) or more.

When the same sound plays twice, the frequency at PCM_Task is 
called may be inadequate.

* PCM_Start can only be executed once for the handle created.

To play back the same file repeatedly, create a handle each time 
the file is played.

* Call PCM_SetLoadNum and PCM_SetPcmStreamNo before starting
  playback.

* Call PCM_SetTrModeCd before calling PCM_Task.

* Always use PCM_NotifyWriteSize to notify the ring buffer of the
  supplied data size for handles created by PCM_CreateMemHandle.

* When using ADPCM, (i.e. playing back SEGA ADPCM Encoder APCM or
  CD-ROM XA audio format data), declare the use of ADPCM with
  PCM_DeclareUseAdpcm.

* When playing back CD-ROM XA audio, always set playback
  information using PCM_SetInfo.

Only the Stream Playback mode can be used with CD-ROM XA audio 
playback. Refer to sample program smppcm5.c.

5. How to Use Sample Programs

See \SATURN\SEGASMP\MAN\MANPCM.DOC for information on how to use 
the sample demo programs.

6. Revision History

[Changes from Ver.1.00 to Ver.1.10]

1) Change in Library Name

	Old name: PCM Playback Library
	New name: PCM-ADPCM Playback Library

2) Implemented ADPCM Support

3) Task Function Spec Change

- Old specs:

Call task once every 4 V blanks or more.

The amount of data which can be processed with each task execution 
is half the volume of the maximum PCM buffer size.

- New specs:

Call task at every V blank or more.

The amount of data which can be processed with each task execution 
is a maximum of 4096 samples.

4) Addition of PCM_DeclareUseAdpcm

PCM_DeclareUseAdpcm, a function for declaring the use of ADPCM was 
added.

When this function is not declared, the ADPCM Decompression 
Library is not linked.

[Changes from Ver.1.10 to Ver.1.11]

1) ADPCM Decompression Library upgrade from Ver1.00 to Ver1.01.

The upgrade addresses the link errors that occurred with Ver1.00.

* The PCM-ADPCM Playback Library itself was not affected by this 
upgrade.

[Changes from Ver.1.11 to Ver.1.12]

1) Addition of Error Checks

PCM_ERR_TOO_SMALL_PCMBUF: PCM buffer size is too small
PCM_ERR_ILL_SIZE_PCMBUF: PCM buffer size is invalid

2) Section-Related Fixes

The initialization data area (D section) is no longer used.

3) Bug Fix

When the Stream System was used for playback, there were cases 
when a return did not occur after STM_SetExecGrp was called. This 
problem has now been fixed.

The library now supports temporary switching between stream groups 
for data reads whenever there is a processing bandwidth available 
in the stream consumption rate or stock.

[Changes from Ver.1.12 to Ver.1.13]

1) Task Function Spec Change

In Stream Playback mode, STM_ExecServer was called in PCM_Task. 
The specification was changed so that STM_ExecServer can be called 
by the application side.

To perform the equivalent operation found in the previous version, 
call STM_ExecServer immediately before PCM_Task. STM_ExecServer 
only needs to be called once even when PCM_Task is called 
repeatedly due to multiple PCM handles.

In some cases, it is possible to call STM_ExecTrans (which 
performs transfers from the CD block only) instead of 
STM_ExecServer.

- Old specs:

The amount of data that can be processed with each task execution 
is a maximum of 4096 [sample/ch].

During stream playback, the library calls STM_ExecServer.

- New specs:

The amount of data that can be processed with each task execution 
is adjustable. The default value is 1024 [sample/ch].

During stream playback, the application calls STM_ExecServer or 
STM_ExecTrans.

2) Adjustable Task Function Data Processing Amount

PCM_Set1TaskSample can be used to set an upper limit for the 
amount of data processed by each task. This enables a reduction in 
the overhead placed on the task function.

3) Setting PCM Playback Start and Stop Conditions

If playback start conditions are set conservatively with 
PCM_SetStartTrgSize or PCM_SetStartTrgSample, playback reliability 
will be higher even if the data supply becomes unstable after 
playback commences.

[Changes from Ver.1.13 to Ver.1.14]

1) Bug Fix

A bug that caused a popping/clicking noise to occur during stereo 
AIFF playback was fixed.

[Changes from Ver.1.14 to Ver.1.15]

1) Improvement in File Playback Mode Data Transfer Performance

CPU DMA-based data transfer performance was improved in File 
Playback mode.

Previously, the maximum transfer sector amount was transferred 
with 3 task calls.  This has now been improved so that the maximum 
transfer amount is now transferred with 2 task calls.

2) Addition of a Loop Playback Function

The number of loops is set with PCM_SetLoop.  The default is 1.

This feature may be used with Memory Playback mode or File 
Playback mode. In Memory Playback mode, the loop playback function 
can only be used with memory-resident data playback.

Loop playback is not supported for Stream Playback mode.

Note that PCM_EntryNext and PCM_Change take priority over this 
feature. In other words, regardless of the specified loop amount, 
a switch will occur to the next handle that has been set.

Code examples are contained in the sample programs smppcm4 and 
smppcm13.

3) Corrections to Sample Programs

Corrected so that the sound driver initialization settings are 
done by the program.

[Changes from Ver.1.15 to Ver.1.16]

1) Bug Fix

- Preread Processing for File Playback

When the File System was used for playback, an error occurred in 
GFS whenever PCM_Task was called before PCM_Start and then 
PCM_Start was called after that to start playback.

This has now been corrected so that if PCM_Task is called before 
playback start, file preread processing can be performed properly.

2) Using the Sound Interface Library

Old Processing:

Each command issued to the sound driver was sent by the 
application. The command block used a unique number that was 
specified.

New Processing:

Each command issued to the sound driver is done via the Sound 
Interface Library.  The command block is not specified.

The Sound Interface Library is now used to enable the application 
to support specification changes in the sound driver. It is 
necessary to link sega_snd.lib to the application from hereon.

3) Elimination of a Function

PCM_SetPcmCmdBlockNo: Set PCM command block number

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