-
Notifications
You must be signed in to change notification settings - Fork 5
/
readme_org.txt
114 lines (86 loc) · 4.13 KB
/
readme_org.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
----------------------------------------------
SjPCM v2.1 - PCM streaming library for the PS2
----------------------------------------------
SjPCM v2.1 - by Nicholas Van Veen (aka Sjeep)
Buffer status code by Wonko
Documentation by Wonko and Sjeep
Introduction
------------
SjPCM provides a PS2 IOP module (sjpcm.irx) and EE-side interface (sjpcm.h
and sjpcm_rpc.c) to output a continuos sound stream to a stereo channel.
All sound must be sampled at 48kHz, 16bit and uncompressed.
SjPCM operated in two modes: synchronised and unsynchronised. Synchronised
mode is suited for use in applications where audio output must be accurately
synchronised with video output, and the ability to buffer sound a few frames
ahead is not possible (i.e.: emulator ports). Unsynchronised mode is suited for
use in applications where audio data can be buffered a few frames ahead
(i.e.: audio players - mod, mp3).
Synchronised mode may be necessary because the rates of video output and
audio output seem to differ, as the read and write offsets in the sound
buffer progress at _slightly_ different rates, causing gradual de-sync of
sound and video output. To remedy this, the read and write offsets are
synchronised every few frames - however this means that some samples will be
skipped, causing an undesirable crackling effect in the audio output.
In unsynchronised mode, the different video and audio output rates are not a
problem since if a buffer underrun is predicted to occur, you can just enqueue
another frame of sound data. If a buffer overrun is predicted to occur, you
can just skip sending sound data for that frame.
EE-side function reference
--------------------------
*** void SjPCM_Puts(char *format, ...);
Output log messages.
*** int SjPCM_Init(int sync);
Initialize sjpcm. Must be called once before any other call to the
sjpcm library. 'sync' is 1 for synchronised mode, 0 for unsyncrhonised mode.
*** void SjPCM_Enqueue(short *left, short *right, int size, int wait);
Send 'size' samples from 'left' and 'right' to the sjpcm sound output
buffers. 'size' MUST be 800 for NTSC machines or 960 for PAL machines.
'wait' = 0 for non-blocking mode, 1 for blocking mode (ie: wait for DMA
transfer of sound data to IOP to complete).
*** void SjPCM_Play();
Make the audio output audible.
*** void SjPCM_Pause();
Mute the audio output.
*** void SjPCM_Setvol(unsigned int volume);
Change the audio volume (0...0x3ff)
*** void SjPCM_Clearbuff();
Set the sound buffers to 0.
*** int SjPCM_Available();
Available space in the output buffer. Returns the number of
stereo 16bit samples that will fit into the buffer before
a buffer overrun.
*** int SjPCM_Buffered();
Number of stereo samples still available in the output buffer
before a buffer underrun.
*** int SjPCM_Quit();
Free SPU2 resources claimed by SjPCM, so they are available
for other libsd-based audio IRX's to use (such as Vzzrzzn's
modplayer).
Note on using unsynchronised mode
---------------------------------
SjPCM assumes that the sound chip plays 800/960 samples per
vertical blank period. However, this rate can change slightly
over time. It is the users responsibility to avoid buffer
overruns and buffer underruns.
*Example (NTSC):
This example keeps the buffered audio data one frame ahead
of the vertical sync, avoiding underrun and overrun.
while(1) {
int buffered = SjPCM_Buffered();
if (buffered<1*800) SjPCM_Enqueue(...); // avoid underrun
if (buffered<2*800) SjPCM_Enqueue(...); // regular buffer fill
vsync();
}
LEGAL
-----
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA