/[pcsx2_0.9.7]/trunk/3rdparty/portaudio/src/hostapi/coreaudio/notes.txt
ViewVC logotype

Contents of /trunk/3rdparty/portaudio/src/hostapi/coreaudio/notes.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 273 - (show annotations) (download)
Fri Nov 12 01:10:22 2010 UTC (9 years, 2 months ago) by william
File MIME type: text/plain
File size: 9136 byte(s)
Auto Commited Import of: pcsx2-0.9.7-DEBUG (upstream: v0.9.7.4013 local: v0.9.7.197-latest) in ./trunk
1 Notes on status of CoreAudio Implementation of PortAudio
2
3 Document Last Updated December 9, 2005
4
5 There are currently two implementations of PortAudio for Mac Core Audio.
6
7 The original is in pa_mac_core_old.c, and the newer, default implementation
8 is in pa_mac_core.c.
9 Only pa_mac_core.c is currently developed and supported as it uses apple's
10 current core audio technology. To select use the old implementation, replace
11 pa_mac_core.c with pa_mac_core_old.c (eg. "cp pa_mac_core_auhal.c
12 pa_mac_core.c"), then run configure and make as usual.
13
14 -------------------------------------------
15
16 Notes on Newer/Default AUHAL implementation:
17
18 by Bjorn Roche
19
20 Last Updated December 9, 2005
21
22 Principle of Operation:
23
24 This implementation uses AUHAL for audio I/O. To some extent, it also
25 operates at the "HAL" Layer, though this behavior can be limited by
26 platform specific flags (see pa_mac_core.h for details). The default
27 settings should be reasonable: they don't change the SR of the device and
28 don't cause interruptions if other devices are using the device.
29
30 Major Software Elements Used: Apple's HAL AUs provide output SR
31 conversion transparently, however, only on output, so this
32 implementation uses AudioConverters to convert the sample rate on input.
33 A PortAudio ring buffer is used to buffer input when sample rate
34 conversion is required or when separate audio units are used for duplex
35 IO. Finally, a PortAudio buffer processor is used to convert formats and
36 provide additional buffers if needed. Internally, interleaved floating
37 point data streams are used exclusively - the audio unit converts from
38 the audio hardware's native format to interleaved float PCM and
39 PortAudio's Buffer processor is used for conversion to user formats.
40
41 Simplex Input: Simplex input uses a single callback. If sample rate
42 conversion is required, a ring buffer and AudioConverter are used as
43 well.
44
45 Simplex output: Simplex output uses a single callback. No ring buffer or
46 audio converter is used because AUHAL does its own output SR conversion.
47
48 Duplex, one device (no SR conversion): When one device is used, a single
49 callback is used. This achieves very low latency.
50
51 Duplex, separate devices or SR conversion: When SR conversion is
52 required, data must be buffered before it is converted and data is not
53 always available at the same times on input and output, so SR conversion
54 requires the same treatment as separate devices. The input callback
55 reads data and puts it in the ring buffer. The output callback reads the
56 data off the ring buffer, into an audio converter and finally to the
57 buffer processor.
58
59 Platform Specific Options:
60
61 By using the flags in pa_mac_core.h, the user may specify several options.
62 For example, the user can specify the sample-rate conversion quality, and
63 the extent to which PA will attempt to "play nice" and to what extent it
64 will interrupt other apps to improve performance. For example, if 44100 Hz
65 sample rate is requested but the device is set at 48000 Hz, PA can either
66 change the device for optimal playback ("Pro" mode), which may interrupt
67 other programs playing back audio, or simple use a sample-rate coversion,
68 which allows for friendlier sharing of the device ("Play Nice" mode).
69
70 Additionally, the user may define a "channel mapping" by calling
71 paSetupMacCoreChannelMap() on their stream info structure before opening
72 the stream with it. See below for creating a channel map.
73
74 Known issues:
75
76 - Buffering: No buffering beyond that provided by core audio is provided
77 except where absolutely needed for the implementation to work. This may cause
78 issues with large framesPerBuffer settings and it also means that no additional
79 latency will be provided even if a large latency setting is selected.
80
81 - Latency: Latency settings are generally ignored. They may be used as a
82 hint for buffer size in paHostFramesPerBufferUnspecified, or the value may
83 be used in cases where additional buffering is needed, such as doing input and
84 output on seperate devices. Latency settings are always automatically bound
85 to "safe" values, however, so setting extreme values here should not be
86 an issue.
87
88 - Buffer Size: paHostFramesPerBufferUnspecified and specific host buffer sizes
89 are supported. paHostFramesPerBufferUnspecified works best in "pro" mode,
90 where the buffer size and sample rate of the audio device is most likely
91 to match the expected values. In the case of paHostFramesPerBuffer, an
92 appropriate framesPerBuffer value will be used that guarantees minimum
93 requested latency if that's possible.
94
95 - Timing info. It reports on stream time, but I'm probably doing something
96 wrong since patest_sine_time often reports negative latency numbers. Also,
97 there are currently issues with some devices whehn plugging/unplugging
98 devices.
99
100 - xrun detection: The only xrun detection performed is when reading
101 and writing the ring buffer. There is probably more that can be done.
102
103 - abort/stop issues: stopping a stream is always a complete operation,
104 but latency should be low enough to make the lack of a separate abort
105 unnecessary. Apple clarifies its AudioOutputUnitStop() call here:
106 http://lists.apple.com/archives/coreaudio-api/2005/Dec/msg00055.html
107
108 - blocking interface: should work fine.
109
110 - multichannel: It has been tested successfully on multichannel hardware
111 from MOTU: traveler and 896HD. Also Presonus firepod and others. It is
112 believed to work with all Core Audio devices, including virtual devices
113 such as soundflower.
114
115 - sample rate conversion quality: By default, SR conversion is the maximum
116 available. This can be tweaked using flags pa_mac_core.h. Note that the AU
117 render quyality property is used to set the sample rate conversion quality
118 as "documented" here:
119 http://lists.apple.com/archives/coreaudio-api/2004/Jan/msg00141.html
120
121 - x86/Universal Binary: Universal binaries can be build.
122
123
124
125 Creating a channel map:
126
127 How to create the map array - Text taken From AUHAL.rtfd :
128 [3] Channel Maps
129 Clients can tell the AUHAL units which channels of the device they are interested in. For example, the client may be processing stereo data, but outputting to a six-channel device. This is done by using the kAudioOutputUnitProperty_ChannelMap property. To use this property:
130
131 For Output:
132 Create an array of SInt32 that is the size of the number of channels of the device (Get the Format of the AUHAL's output Element == 0)
133 Initialize each of the array's values to -1 (-1 indicates that that channel is NOT to be presented in the conversion.)
134
135 Next, for each channel of your app's output, set:
136 channelMapArray[deviceOutputChannel] = desiredAppOutputChannel.
137
138 For example: we have a 6 channel output device and our application has a stereo source it wants to provide to the device. Suppose we want that stereo source to go to the 3rd and 4th channels of the device. The channel map would look like this: { -1, -1, 0, 1, -1, -1 }
139
140 Where the formats are:
141 Input Element == 0: 2 channels (- client format - settable)
142 Output Element == 0: 6 channels (- device format - NOT settable)
143
144 So channel 2 (zero-based) of the device will take the first channel of output and channel 3 will take the second channel of output. (This translates to the 3rd and 4th plugs of the 6 output plugs of the device of course!)
145
146 For Input:
147 Create an array of SInt32 that is the size of the number of channels of the format you require for input. Get (or Set in this case as needed) the AUHAL's output Element == 1.
148
149 Next, for each channel of input you require, set:
150 channelMapArray[desiredAppInputChannel] = deviceOutputChannel;
151
152 For example: we have a 6 channel input device from which we wish to receive stereo input from the 3rd and 4th channels. The channel map looks like this: { 2, 3 }
153
154 Where the formats are:
155 Input Element == 0: 2 channels (- device format - NOT settable)
156 Output Element == 0: 6 channels (- client format - settable)
157
158
159
160 ----------------------------------------
161
162 Notes on Original implementation:
163
164 by Phil Burk and Darren Gibbs
165
166 Last updated March 20, 2002
167
168 WHAT WORKS
169
170 Output with very low latency, <10 msec.
171 Half duplex input or output.
172 Full duplex on the same CoreAudio device.
173 The paFLoat32, paInt16, paInt8, paUInt8 sample formats.
174 Pa_GetCPULoad()
175 Pa_StreamTime()
176
177 KNOWN BUGS OR LIMITATIONS
178
179 We do not yet support simultaneous input and output on different
180 devices. Note that some CoreAudio devices like the Roland UH30 look
181 like one device but are actually two different CoreAudio devices. The
182 Built-In audio is typically one CoreAudio device.
183
184 Mono doesn't work.
185
186 DEVICE MAPPING
187
188 CoreAudio devices can support both input and output. But the sample
189 rates supported may be different. So we have map one or two PortAudio
190 device to each CoreAudio device depending on whether it supports
191 input, output or both.
192
193 When we query devices, we first get a list of CoreAudio devices. Then
194 we scan the list and add a PortAudio device for each CoreAudio device
195 that supports input. Then we make a scan for output devices.
196

  ViewVC Help
Powered by ViewVC 1.1.22