< 8/ 8>PCM/ADPCM playback library/6.2 function details

Japanese

★ PROGRAMMER'S GUIDE ★ PCM/ADPCM playback library

▲ Back | ■

PCM/ADPCM playback library

6.2 Function details

Initialization and termination processing

one View table Title function specification Function Initialization Function name PCM_Init No 1.1
Format: Bool PCM_Init(void)
input: none
output: none
function value: If initialization was successful: TRUE
If unable to initialize successfully: FALSE
function: Immediately after starting the program, initialization is performed to use this library.
remarks: When using this library, be sure to call this function at the beginning of the program.

one View table Title function specification Function End processing Function name PCM_Finish No 1.2
Format: void PCM_Finish(void)
input: none
output: none
function value: none
function: Performs termination processing of the PCM library.
remarks: If you do not want to perform PCM playback after that, call this function.

one View table Title function specification Function ADPCM usage declaration Function name PCM_DeclareUseAdpcm No 1.3
Format: void PCM_DeclareUseAdpcm(void)
input: none
output: none
function value: none
function: The functionality will be expanded to allow ADPCM playback.
remarks: Required when playing the specified ADPCM format or CD-ROM XA Audio format. Call it immediately after the initialization function PCM_Init.
When this is called, the ADPCM decompression library module will be linked.
Playback functions other than ADPCM are not restricted by calling.
If you do not call it, the executable file size will be slightly smaller.

one View table Title function specification Function SaturnPCM usage declaration (file system) Function name PCM_DeclareUseSapGfs No 1.4
Format: void PCM_DeclareUseSapGfs(void)
input: none
output: none
function value: none
function: The functionality will be expanded to allow playback of SaturnPCM format.
Called when using SaturnPCM format in file playback mode (file system).
remarks: Required if you want to play SaturnPCM format in file playback mode.
Call it immediately after the initialization function PCM_Init.
By calling this function, all PCM files to be played will be in SaturnPCM format.
Files in SaturnPCM format, AIFF format, specified ADPCM format, and CD-ROM XA Audio format cannot be used at the same time.

one View table Title function specification Function SaturnPCM usage declaration (stream system) Function name PCM_DeclareUseSapStm No 1.5
Format: void PCM_DeclareUseSapStm(void)
input: none
output: none
function value: none
function: The functionality will be expanded to allow playback of SaturnPCM format.
Use the SaturnPCM format in stream playback mode (stream system).
remarks: Required if you want to play SaturnPCM format in stream playback mode.
Call it immediately after the initialization function PCM_Init.
By calling this function, all PCM files to be played will be in SaturnPCM format.
Files in SaturnPCM format, AIFF format, specified ADPCM format, and CD-ROM XA Audio format cannot be used at the same time.

Handle operation

one View table Title function specification Function Creating a handle (memory) Function name PCM_CreateMemHandle No 2.1

Format

PcmHn PCM_CreateMemHandle(PcmCreatePara *para)

input

para: creation parameter

output

none

function value

Handle (NULL if cannot be created)

function

Creates a handle to play a file in memory.

remarks

Up to 32 handles can be created at the same time.
Load the file into memory using an application program.
For handles created with PCM_CreateMemHandle, be sure to notify the file size with PCM_NotifyWriteSize.

one View table Title function specification Function Erasing handles (memory) Function name PCM_DestroyMemHandle No 2.2
Format: void PCM_DestroyMemHandle(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Erase the handle.
remarks: Erasing a handle prevents it from being used again.

one View table Title function specification Function Creating a handle (file system) Function name PCM_CreateGfsHandle No 2.3

Format

PcmHn PCM_CreateGfsHandle(PcmCreatePara *para, GfsHn gfs)

input

para	:Creation parameter
gfs	: file handle

output

none

function value

Handle (NULL if cannot be created)

function

Creates a handle to play a file on the file system.

remarks

Up to 32 handles can be created at the same time.
Obtain the file handle in advance using the application program.

one View table Title function specification Function Clearing a handle (file system) Function name PCM_DestroyGfsHandle No 2.4
Format: void PCM_DestroyGfsHandle(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Erase the handle.
remarks: Erasing a handle prevents it from being used again.

one View table Title function specification Function Creating a handle (stream system) Function name PCM_CreateStmHandle No 2.5

Format

PcmHn PCM_CreateStmHandle(PcmCreatePara *para, StmHn stm)

input

para	:Creation parameter
stm	:Stream handle

output

none

function value

Handle (NULL if cannot be created)

function

Creates a handle for playing a file on a stream system.

remarks

Up to 32 handles can be created at the same time.
Obtain the stream handle in advance using the application program.

one View table Title function specification Function Clearing handles (stream system) Function name PCM_DestroyStmHandle No 2.6
Format: void PCM_DestroyStmHandle(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Erase the handle.
remarks: Erasing a handle prevents it from being used again.

one View table Title function specification Function replay task Function name PCM_Task No 2.7
Format: void PCM_Task(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Reads files from CD and transfers data to sound memory.; If you specify NULL for pcm, the play task will be executed for all the handles that are being played.
remarks: Please call this function periodically during playback.
Please call at a frequency equal to or higher than the V blank interrupt frequency (1 time/16ms).

one View table Title function specification Function V blank IN processing function Function name PCM_VblIn No 2.8
Format: void PCM_VblIn(void)
input: none
output: none
function value: none
function: Manage playback time.
remarks: When using this library, be sure to call this function in V blank IN interrupt processing.

playback control

one View table Title function specification Function Start playing Function name PCM_Start No 3.1
Format: void PCM_Start(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Start playing.
remarks: Regeneration can only be performed once on a generated handle.
If you want to play the same file over and over again, generate a handle each time.

one View table Title function specification Function Stop playing Function name PCM_Stop No 3.2
Format: void PCM_Stop(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Stop playback.

one View table Title function specification Function Pause Function name PCM_Pause No 3.3

Format

void PCM_Pause(PcmHn pcm, PcmPauseCmd cmd)

input

pcm	:handle
cmd	: Pause control command

output

none

function value

none

function

Pause playback. Or unpause.

one View table Title function specification Function Registering the handle to play next Function name PCM_EntryNext No 3.4
Format: void PCM_EntryNext(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Next, register the handle to be played.
remarks: If you register a handle with this function, the next handle will automatically start playing when the currently playing handle ends. Specifying NULL will cancel the registration.
Even when a forced switch is performed using PCM_Change, the handle registered using this function will start playing.
Only one handle can be registered. When you switch to the registered handle, it becomes unregistered and you can register the next handle.

one View table Title function specification Function Forced handle switching Function name PCM_Change No 3.5
Format: void PCM_Change(void)
input: none
output: none
function value: none
function: Interrupts the currently playing handle and starts playing the handle registered with PCM_EntryNext.

one View table Title function specification Function Get handle switching state Function name PCM_CheckChange No 3.6
Format: PcmChangeStatus PCM_CheckChange(void)
input: none
output: none
function value: Forced switch possibility check value
function: Returns the possibility of switching when forced switching with PCM_Change.

one View table Title function specification Function Setting the loop playback count Function name PCM_SetLoop No 3.7

Format

void PCM_SetLoop(PcmHn pcm, Sint32 cnt_loop)

input

pcm	:handle
cnt_loop	:Number of loops

output

none

function value

none

function

Specify the number of loops for loop playback.
The default is once.

remarks

Loop playback can be used in memory playback mode (resident playback method) or file playback mode.
Sequential supply method memory playback mode and stream playback mode are not supported.
The specifications in the function PCM_EntryNext and the function PCM_Change take precedence over the loop playback count specification in this function. In other words, regardless of the number of loops specified, it will switch to the next registered handle.

Information setting function

one View table Title function specification Function Setting the maximum number of transferred sectors Function name PCM_SetLoadNum No 4.1

Format

void PCM_SetLoadNum(PcmHn pcm, Sint32 load_sct)

input

pcm	:handle
load_sct	: Maximum number of transferred sectors

output

none

function value

none

function

Set the maximum number of transfer sectors when transferring from the CD buffer to the library's ring buffer.
Default is 20 sectors.

remarks

Call this function before starting playback.

one View table Title function specification Function Playback PAN settings Function name PCM_SetPan No 4.2

Format

void PCM_SetPan(PcmHn pcm, Sint32 pan)

input

pcm	:handle
bread	: PAN value (0 to 31)

output

none

function value

none

function

Specify the PAN of the sound.
Default is 0.
PAN settings are valid for monaural playback. Ignored for stereo playback.

one View table Title function specification Function Setting playback volume Function name PCM_SetVolume No 4.3

Format

void PCM_SetVolume(PcmHn pcm, Sint32 volume)

input

pcm	:handle
volume	:Volume (0~7)

output

none

function value

none

function

Specify the volume. (0 means no output, 7 means maximum volume) Default is 7.

one View table Title function specification Function Change PCM playback parameters Function name PCM_ChangePcmPara No 4.4
Format: void PCM_ChangePcmPara(PcmHn pcm)
input: pcm: handle
output: none
function value: none
function: Changes the PCM playback parameters during playback for the sound driver.
remarks: After setting the volume and pan, call this function to make the actual changes.

one View table Title function specification Function Setting the PCM stream playback number Function name PCM_SetPcmStreamNo No 4.5

Format

void PCM_SetPcmStreamNo(PcmHn pcm, Sint32 stream_no)

input

pcm	:handle
stream_no	:PCM stream playback number (0 to 7)

output

none

function value

none

function

Set the PCM stream playback number to be set in the sound driver.
Default is 1.

remarks

For more information on PCM stream playback numbers, please refer to the Sega Saturn Sound Driver 2.10 Programmer's Guide .
When playing multiple streams, use different stream playback numbers for each stream. Call this function before starting playback.

one View table Title function specification Function Setting the workpiece for pose processing Function name PCM_SetPauseWork No 4.6

Format

void PCM_SetPauseWork(Sint32 *addr, Sint32 size)

input

addr	:Work address
size	:Work size

output

none

function value

none

function

Set the work area used in pause-on processing.

remarks

When using the pose function, it is necessary to specify the work for pose processing using PCM_SetPauseWork in advance. This work does not need to be prepared for each handle. This work is a work area that is used temporarily during pause-on processing, so you can reserve the area immediately before pause-on processing and release the area immediately after.

Processing example

#defile PAUSE_WORK_SIZE (4096L*2)
pause_work_addr = malloc(PAUSE_WORK_SIZE);
PCM_SetPauseWork(pause_work_addr, PAUSE_WORK_SIZE);
PCM_Pause(pcm, PCM_PAUSE_ON_AT_ONCE);
free(pause_work_addr);

one View table Title function specification Function Setting the data transfer method (CD block → ring buffer) Function name PCM_SetTrModeCd No 4.7

Format

void PCM_SetTrModeCd(PcmHn pcm, PcmTrMode mode)

input

pcm	:handle
mode	:Data transfer method

output

none

function value

none

function

Set the data transfer method from CD block to ring buffer.
The default is CPU DMA.
You can specify program transfer, CPU DMA, or SCU DMA.

Note

Call PCM_SetTrModeCd after creating the handle and before calling the first task function.

one View table Title function specification Function Setting playback information Function name PCM_SetInfo No 4.8

Format

void PCM_SetInfo(PcmHn pcm, PcmInfo *info)

input

pcm	:handle
info	:Playback information

output

none

function value

none

function

Set information for PCM playback.

remarks

Normally, this function is not used because playback information is obtained from the file header. Currently, it is required only when playing CD-ROM XA Audio.

Example of use

For CD-ROM XA Audio playback, set the playback information as follows.

PcmInfo info;
PCM_INFO_FILE_TYPE(&info)=PCM_FILE_TYPE_NO_HEADER; /* No header */
PCM_INFO_DATA_TYPE(&info)=PCM_DATA_TYPE_ADPCM_SCT; /* XA Audio sector processing */
PCM_SetInfo(pcm, &info);

Note

Call PCM_SetInfo after creating the handle and before calling the first task function.

one View table Title function specification Function Setting the processing upper limit per task Function name PCM_Set1TaskSample No 4.9

Format

void PCM_Set1TaskSample(PcmHn pcm, Sint32 sample)

input

pcm	:handle
sample	:Number of samples (sample/1ch)

output

none

function value

none

function

Set the upper limit for the amount that one task function (PCM_Task) can process.
This allows the task function load to be stabilized.
Default value is 1024 [sample/ch]

remarks

Although it is possible to change it during playback, it is preferable to set it before playback starts in order to stabilize the task load. If the value is set too small, normal playback will not be possible, so consider the frequency of task calls and the playback frequency and set a value with some margin.

one View table Title function specification Function Setting the playback start trigger size Function name PCM_SetStartTrgSize No 4.10

Format

void PCM_SetStartTrgSize(PcmHn pcm, Sint32 size)

input

pcm	:handle
size	:Data size (byte)

output

none

function value

none

function

Playback starts when data equal to or larger than size is supplied.
Default value is 0 [byte]

remarks

Set before starting playback. By setting playback start conditions, playback becomes more secure even if the data supply becomes unstable after playback starts.

one View table Title function specification Function Setting the playback start trigger sample Function name PCM_SetStartTrgSample No 4.11

Format

input

pcm	:handle
sample	: Number of samples (sample/1ch)

output

none

function value

none

function

When there is a supply of sample or more, playback starts.
Default value is 4096 [sample/ch]

remarks

Set before starting playback. By setting playback start conditions, playback becomes more secure even if the data supply becomes unstable after playback starts.

one View table Title function specification Function Setting the playback stop trigger sample Function name PCM_SetStopTrgSample No 4.12

Format

void PCM_SetStopTrgSample(PcmHn pcm, Sint32 sample)

input

pcm	:handle
sample	: Number of samples (sample/1ch)

output

none

function value

none

function

The condition for stopping playback is that the remaining amount is less than or equal to sample.
Default value is 2048 [sample/ch]

remarks

Set before starting playback. If the frequency of task calls is low, noise may occur when stopping. If you cannot increase the frequency, you can avoid this by setting it higher than the default value.

Information retrieval function

one View table Title function specification Function Get playback time Function name PCM_GetTime No 5.1
Format: Sint32 PCM_GetTime(PcmHn pcm)
input: pcm: handle
output: none
function value: current time
function: Get the current time.
(Number of samples played from the beginning of this file until now)

one View table Title function specification Function Get playback status Function name PCM_GetPlayStatus No 5.2
Format: PcmPlayStatus PCM_GetPlayStatus(PcmHn pcm)
input: pcm: handle
output: none
function value: playback status
function: Returns the current playback status.

buffer control

one View table Title function specification Function Get write buffer Function name PCM_GetWriteBuf No 6.1

Format

Uint32 *PCM_GetWriteBuf(PcmHn pcm, Sint32 *free_size, Sint32 *free_total)

input

pcm: Handle

output

free_size	: Number of bytes of area that can be written continuously
free_total	: Total number of bytes of writable area including non-contiguous areas

function value

Start address of continuous writable area (NULL if writable is not possible)

function

Get the buffer address to write to and the number of bytes that can be written.

remarks

Use this when you want to independently supply data to the ring buffer.

one View table Title function specification Function Write size notification Function name PCM_NotifyWriteSize No 6.2

Format

void PCM_NotifyWriteSize(PcmHn pcm, Sint32 write_size)

input

pcm	:handle
write_size	: Number of bytes written

output

none

function value

none

function

Informs the library of the number of bytes of data actually supplied to the ring buffer.

remarks

Use this when you want to independently supply data to the ring buffer.
When playing a file in memory, notify the buffer size (file size).

one View table Title function specification Function Preloading files Function name PCM_PreloadFile No 6.3

Format

void PCM_PreloadFile(PcmHn pcm, Sint32 size)

input

pcm	: Handle
size	: Number of bytes to read

output

none

function value

Number of bytes actually read

function

Reads the specified size of data into the ring buffer before starting file playback.

remarks

The number of bytes to be read is in sectors (multiples of 2048).

error control

one View table Title function specification Function Get error information Function name PCM_GetErr No 7.1
Format: PcmErrCode PCM_GetErr(void)
input: none
output: none
function value: Error code
function: Returns the most recent error code.

one View table Title function specification Function Registering an error function Function name PCM_SetErrFunc No 7.2

Format

void PRM_SetErrFunc(PcmErrFunc func, void *obj)

input

func	:Function to call when an error occurs
obj	:Registered object

output

none

function value

none

function

Set the function to be called when an error occurs. The registration object is passed as the first argument of the registration function.

▲ Back | ■

★ PROGRAMMER'S GUIDE ★ PCM/ADPCM playback library

6.2 Function details

Initialization and termination processing

function specification

Initialization

PCM_Init

1.1

function specification

End processing

PCM_Finish

1.2

function specification

ADPCM usage declaration

PCM_DeclareUseAdpcm

1.3

function specification

SaturnPCM usage declaration (file system)

PCM_DeclareUseSapGfs

1.4

function specification

SaturnPCM usage declaration (stream system)

PCM_DeclareUseSapStm

1.5

Handle operation

function specification

Creating a handle (memory)

PCM_CreateMemHandle

2.1

function specification

Erasing handles (memory)

PCM_DestroyMemHandle

2.2

function specification

Creating a handle (file system)

PCM_CreateGfsHandle

2.3

function specification

Clearing a handle (file system)

PCM_DestroyGfsHandle

2.4

function specification

Creating a handle (stream system)

PCM_CreateStmHandle

2.5

function specification

Clearing handles (stream system)

PCM_DestroyStmHandle

2.6

function specification

replay task

PCM_Task

2.7

function specification

V blank IN processing function

PCM_VblIn

2.8

playback control

function specification

Start playing

PCM_Start

3.1

function specification

Stop playing

PCM_Stop

3.2

function specification

Pause

PCM_Pause

3.3

function specification

Registering the handle to play next

PCM_EntryNext

3.4

function specification

Forced handle switching

PCM_Change

3.5

function specification

Get handle switching state

PCM_CheckChange

3.6

Setting the data transfer method
(CD block → ring buffer)