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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
/* Copyright 2017 The Chromium Authors
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
/* From dev/ppb_audio_output_dev.idl modified Fri Apr 7 07:07:59 2017. */
#ifndef PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_
#define PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_
#include "ppapi/c/dev/ppb_device_ref_dev.h"
#include "ppapi/c/pp_array_output.h"
#include "ppapi/c/pp_bool.h"
#include "ppapi/c/pp_completion_callback.h"
#include "ppapi/c/pp_instance.h"
#include "ppapi/c/pp_macros.h"
#include "ppapi/c/pp_resource.h"
#include "ppapi/c/pp_stdint.h"
#include "ppapi/c/pp_time.h"
#define PPB_AUDIO_OUTPUT_DEV_INTERFACE_0_1 "PPB_AudioOutput(Dev);0.1"
#define PPB_AUDIO_OUTPUT_DEV_INTERFACE PPB_AUDIO_OUTPUT_DEV_INTERFACE_0_1
/**
* @file
* This file defines the <code>PPB_AudioOutput_dev</code> interface, which
* provides realtime stereo audio streaming capabilities.
*/
/**
* @addtogroup Typedefs
* @{
*/
/**
* <code>PPB_AudioOutput_Callback</code> defines the type of an audio callback
* function used to fill the audio buffer with data. Please see the
* Create() function in the <code>PPB_AudioOutput</code> interface for
* more details on this callback.
*
* @param[out] sample_buffer A buffer to fill with audio data.
* @param[in] buffer_size_in_bytes The size of the buffer in bytes.
* @param[in] latency How long before the audio data is to be presented.
* @param[inout] user_data An opaque pointer that was passed into
* <code>PPB_AudioOutput.Create()</code>.
*/
typedef void (*PPB_AudioOutput_Callback)(void* sample_buffer,
uint32_t buffer_size_in_bytes,
PP_TimeDelta latency,
void* user_data);
/**
* @}
*/
/**
* @addtogroup Interfaces
* @{
*/
/**
* The <code>PPB_AudioOutput</code> interface contains pointers to several
* functions for handling audio resources.
* Please see descriptions for each <code>PPB_AudioOutput</code> and
* <code>PPB_AudioConfig</code> function for more details. A C example using
* <code>PPB_AudioOutput</code> and <code>PPB_AudioConfig</code> follows.
*
* <strong>Example: </strong>
*
* @code
* void audio_output_callback(void* sample_buffer,
* uint32_t buffer_size_in_bytes,
* PP_TimeDelta latency,
* void* user_data) {
* ... quickly fill in the buffer with samples and return to caller ...
* }
*
* ...Assume the application has cached the audio configuration interface in
* audio_config_interface and the audio interface in
* audio_output_interface...
*
* uint32_t count = audio_config_interface->RecommendSampleFrameCount(
* PP_AUDIOSAMPLERATE_44100, 4096);
* PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
* pp_instance, PP_AUDIOSAMPLERATE_44100, count);
* PP_Resource pp_audio_output = audio_interface->Create(pp_instance,
* pp_audio_config, audio_callback, NULL);
* audio_interface->EnumerateDevices(pp_audio_output, output_device_list,
* callback);
* audio_interface->Open(pp_audio_output, device_ref, pp_audio_config,
* audio_output_callback, user_data, callback);
* audio_output_interface->StartPlayback(pp_audio_output);
*
* ...audio_output_callback() will now be periodically invoked on a separate
* thread...
* @endcode
*/
struct PPB_AudioOutput_Dev_0_1 {
/**
* Creates an audio output resource.
*
* @param[in] instance A <code>PP_Instance</code> identifying one instance of
* a module.
*
* @return A <code>PP_Resource</code> corresponding to an audio output
resource
* if successful, 0 if failed.
*/
PP_Resource (*Create)(PP_Instance instance);
/**
* Determines if the given resource is an audio output resource.
*
* @param[in] resource A <code>PP_Resource</code> containing a resource.
*
* @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
* resource is an audio output resource, otherwise <code>PP_FALSE</code>.
*/
PP_Bool (*IsAudioOutput)(PP_Resource resource);
/**
* Enumerates audio output devices.
*
* @param[in] audio_output A <code>PP_Resource</code> corresponding to an
audio
* output resource.
* @param[in] output An output array which will receive
* <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the
* ref count of those resources has already been increased by 1 for the
* caller.
* @param[in] callback A <code>PP_CompletionCallback</code> to run on
* completion.
*
* @return An error code from <code>pp_errors.h</code>.
*/
int32_t (*EnumerateDevices)(PP_Resource audio_output,
struct PP_ArrayOutput output,
struct PP_CompletionCallback callback);
/**
* Requests device change notifications.
*
* @param[in] audio_output A <code>PP_Resource</code> corresponding to an
audio
* output resource.
* @param[in] callback The callback to receive notifications. If not NULL, it
* will be called once for the currently available devices, and then every
* time the list of available devices changes. All calls will happen on the
* same thread as the one on which MonitorDeviceChange() is called. It will
* receive notifications until <code>audio_output</code> is destroyed or
* <code>MonitorDeviceChange()</code> is called to set a new callback for
* <code>audio_output</code>. You can pass NULL to cancel sending
* notifications.
* @param[inout] user_data An opaque pointer that will be passed to
* <code>callback</code>.
*
* @return An error code from <code>pp_errors.h</code>.
*/
int32_t (*MonitorDeviceChange)(PP_Resource audio_output,
PP_MonitorDeviceChangeCallback callback,
void* user_data);
/**
* Open() opens an audio output device. No sound will be heard until
* StartPlayback() is called. The callback is called with the buffer address
* and given user data whenever the buffer needs to be filled. From within the
* callback, you should not call <code>PPB_AudioOutput</code> functions. The
* callback will be called on a different thread than the one which created
* the interface. For performance-critical applications (i.e. low-latency
* audio), the callback should avoid blocking or calling functions that can
* obtain locks, such as malloc. The layout and the size of the buffer passed
* to the audio callback will be determined by the device configuration and is
* specified in the <code>AudioConfig</code> documentation.
*
* @param[in] audio_output A <code>PP_Resource</code> corresponding to an
audio
* output resource.
* @param[in] device_ref Identifies an audio output device. It could be one of
* the resource in the array returned by EnumerateDevices(), or 0 which means
* the default device.
* @param[in] config A <code>PPB_AudioConfig</code> audio configuration
* resource.
* @param[in] audio_output_callback A <code>PPB_AudioOutput_Callback</code>
* function that will be called when audio buffer needs to be filled.
* @param[inout] user_data An opaque pointer that will be passed into
* <code>audio_output_callback</code>.
* @param[in] callback A <code>PP_CompletionCallback</code> to run when this
* open operation is completed.
*
* @return An error code from <code>pp_errors.h</code>.
*/
int32_t (*Open)(PP_Resource audio_output,
PP_Resource device_ref,
PP_Resource config,
PPB_AudioOutput_Callback audio_output_callback,
void* user_data,
struct PP_CompletionCallback callback);
/**
* GetCurrrentConfig() returns an audio config resource for the given audio
* output resource.
*
* @param[in] config A <code>PP_Resource</code> corresponding to an audio
* output resource.
*
* @return A <code>PP_Resource</code> containing the audio config resource if
* successful.
*/
PP_Resource (*GetCurrentConfig)(PP_Resource audio_output);
/**
* StartPlayback() starts the playback of the audio output resource and begins
* periodically calling the callback.
*
* @param[in] config A <code>PP_Resource</code> corresponding to an audio
* output resource.
*
* @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
* successful, otherwise <code>PP_FALSE</code>. Also returns
* <code>PP_TRUE</code> (and be a no-op) if called while playback is already
* in progress.
*/
PP_Bool (*StartPlayback)(PP_Resource audio_output);
/**
* StopPlayback() stops the playback of the audio resource.
*
* @param[in] config A <code>PP_Resource</code> corresponding to an audio
* output resource.
*
* @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
* successful, otherwise <code>PP_FALSE</code>. Also returns
* <code>PP_TRUE</code> (and is a no-op) if called while playback is already
* stopped. If a callback is in progress, StopPlayback() will block until the
* callback completes.
*/
PP_Bool (*StopPlayback)(PP_Resource audio_output);
/**
* Close() closes the audio output device,
and stops playback if necessary. It is
* not valid to call Open() again after a call to this method.
* If an audio output resource is destroyed while a device is still open, then
* it will be implicitly closed, so you are not required to call this method.
*
* @param[in] audio_output A <code>PP_Resource</code> corresponding to an
audio
* output resource.
*/
void (*Close)(PP_Resource audio_output);
};
typedef struct PPB_AudioOutput_Dev_0_1 PPB_AudioOutput_Dev;
/**
* @}
*/
#endif /* PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_ */
|
