OLD | NEW |
(Empty) | |
| 1 /* Copyright (c) 2017 The Chromium Authors. All rights reserved. |
| 2 * Use of this source code is governed by a BSD-style license that can be |
| 3 * found in the LICENSE file. |
| 4 */ |
| 5 |
| 6 /* From dev/ppb_audio_output_dev.idl modified Fri Apr 7 07:07:59 2017. */ |
| 7 |
| 8 #ifndef PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_ |
| 9 #define PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_ |
| 10 |
| 11 #include "ppapi/c/dev/ppb_device_ref_dev.h" |
| 12 #include "ppapi/c/pp_array_output.h" |
| 13 #include "ppapi/c/pp_bool.h" |
| 14 #include "ppapi/c/pp_completion_callback.h" |
| 15 #include "ppapi/c/pp_instance.h" |
| 16 #include "ppapi/c/pp_macros.h" |
| 17 #include "ppapi/c/pp_resource.h" |
| 18 #include "ppapi/c/pp_stdint.h" |
| 19 #include "ppapi/c/pp_time.h" |
| 20 |
| 21 #define PPB_AUDIO_OUTPUT_DEV_INTERFACE_0_1 "PPB_AudioOutput(Dev);0.1" |
| 22 #define PPB_AUDIO_OUTPUT_DEV_INTERFACE PPB_AUDIO_OUTPUT_DEV_INTERFACE_0_1 |
| 23 |
| 24 /** |
| 25 * @file |
| 26 * This file defines the <code>PPB_AudioOutput_dev</code> interface, which |
| 27 * provides realtime stereo audio streaming capabilities. |
| 28 */ |
| 29 |
| 30 |
| 31 /** |
| 32 * @addtogroup Typedefs |
| 33 * @{ |
| 34 */ |
| 35 /** |
| 36 * <code>PPB_AudioOutput_Callback</code> defines the type of an audio callback |
| 37 * function used to fill the audio buffer with data. Please see the |
| 38 * Create() function in the <code>PPB_AudioOutput</code> interface for |
| 39 * more details on this callback. |
| 40 * |
| 41 * @param[out] sample_buffer A buffer to fill with audio data. |
| 42 * @param[in] buffer_size_in_bytes The size of the buffer in bytes. |
| 43 * @param[in] latency How long before the audio data is to be presented. |
| 44 * @param[inout] user_data An opaque pointer that was passed into |
| 45 * <code>PPB_AudioOutput.Create()</code>. |
| 46 */ |
| 47 typedef void (*PPB_AudioOutput_Callback)(void* sample_buffer, |
| 48 uint32_t buffer_size_in_bytes, |
| 49 PP_TimeDelta latency, |
| 50 void* user_data); |
| 51 /** |
| 52 * @} |
| 53 */ |
| 54 |
| 55 /** |
| 56 * @addtogroup Interfaces |
| 57 * @{ |
| 58 */ |
| 59 /** |
| 60 * The <code>PPB_AudioOutput</code> interface contains pointers to several |
| 61 * functions for handling audio resources. |
| 62 * Please see descriptions for each <code>PPB_AudioOutput</code> and |
| 63 * <code>PPB_AudioConfig</code> function for more details. A C example using |
| 64 * <code>PPB_AudioOutput</code> and <code>PPB_AudioConfig</code> follows. |
| 65 * |
| 66 * <strong>Example: </strong> |
| 67 * |
| 68 * @code |
| 69 * void audio_output_callback(void* sample_buffer, |
| 70 * uint32_t buffer_size_in_bytes, |
| 71 * PP_TimeDelta latency, |
| 72 * void* user_data) { |
| 73 * ... quickly fill in the buffer with samples and return to caller ... |
| 74 * } |
| 75 * |
| 76 * ...Assume the application has cached the audio configuration interface in |
| 77 * audio_config_interface and the audio interface in |
| 78 * audio_output_interface... |
| 79 * |
| 80 * uint32_t count = audio_config_interface->RecommendSampleFrameCount( |
| 81 * PP_AUDIOSAMPLERATE_44100, 4096); |
| 82 * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit( |
| 83 * pp_instance, PP_AUDIOSAMPLERATE_44100, count); |
| 84 * PP_Resource pp_audio_output = audio_interface->Create(pp_instance, |
| 85 * pp_audio_config, audio_callback, NULL); |
| 86 * audio_interface->EnumerateDevices(pp_audio_output, output_device_list, |
| 87 * callback); |
| 88 * audio_interface->Open(pp_audio_output, device_ref, pp_audio_config, |
| 89 * audio_output_callback, user_data, callback); |
| 90 * audio_output_interface->StartPlayback(pp_audio_output); |
| 91 * |
| 92 * ...audio_output_callback() will now be periodically invoked on a separate |
| 93 * thread... |
| 94 * @endcode |
| 95 */ |
| 96 struct PPB_AudioOutput_Dev_0_1 { |
| 97 /** |
| 98 * Creates an audio output resource. |
| 99 * |
| 100 * @param[in] instance A <code>PP_Instance</code> identifying one instance of |
| 101 * a module. |
| 102 * |
| 103 * @return A <code>PP_Resource</code> corresponding to an audio output |
| 104 resource |
| 105 * if successful, 0 if failed. |
| 106 */ |
| 107 PP_Resource (*Create)(PP_Instance instance); |
| 108 /** |
| 109 * Determines if the given resource is an audio output resource. |
| 110 * |
| 111 * @param[in] resource A <code>PP_Resource</code> containing a resource. |
| 112 * |
| 113 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given |
| 114 * resource is an audio output resource, otherwise <code>PP_FALSE</code>. |
| 115 */ |
| 116 PP_Bool (*IsAudioOutput)(PP_Resource resource); |
| 117 /** |
| 118 * Enumerates audio output devices. |
| 119 * |
| 120 * @param[in] audio_output A <code>PP_Resource</code> corresponding to an |
| 121 audio |
| 122 * output resource. |
| 123 * @param[in] output An output array which will receive |
| 124 * <code>PPB_DeviceRef_Dev</code> resources on success. Please note that the |
| 125 * ref count of those resources has already been increased by 1 for the |
| 126 * caller. |
| 127 * @param[in] callback A <code>PP_CompletionCallback</code> to run on |
| 128 * completion. |
| 129 * |
| 130 * @return An error code from <code>pp_errors.h</code>. |
| 131 */ |
| 132 int32_t (*EnumerateDevices)(PP_Resource audio_output, |
| 133 struct PP_ArrayOutput output, |
| 134 struct PP_CompletionCallback callback); |
| 135 /** |
| 136 * Requests device change notifications. |
| 137 * |
| 138 * @param[in] audio_output A <code>PP_Resource</code> corresponding to an |
| 139 audio |
| 140 * output resource. |
| 141 * @param[in] callback The callback to receive notifications. If not NULL, it |
| 142 * will be called once for the currently available devices, and then every |
| 143 * time the list of available devices changes. All calls will happen on the |
| 144 * same thread as the one on which MonitorDeviceChange() is called. It will |
| 145 * receive notifications until <code>audio_output</code> is destroyed or |
| 146 * <code>MonitorDeviceChange()</code> is called to set a new callback for |
| 147 * <code>audio_output</code>. You can pass NULL to cancel sending |
| 148 * notifications. |
| 149 * @param[inout] user_data An opaque pointer that will be passed to |
| 150 * <code>callback</code>. |
| 151 * |
| 152 * @return An error code from <code>pp_errors.h</code>. |
| 153 */ |
| 154 int32_t (*MonitorDeviceChange)(PP_Resource audio_output, |
| 155 PP_MonitorDeviceChangeCallback callback, |
| 156 void* user_data); |
| 157 /** |
| 158 * Open() opens an audio output device. No sound will be heard until |
| 159 * StartPlayback() is called. The callback is called with the buffer address |
| 160 * and given user data whenever the buffer needs to be filled. From within the |
| 161 * callback, you should not call <code>PPB_AudioOutput</code> functions. The |
| 162 * callback will be called on a different thread than the one which created |
| 163 * the interface. For performance-critical applications (i.e. low-latency |
| 164 * audio), the callback should avoid blocking or calling functions that can |
| 165 * obtain locks, such as malloc. The layout and the size of the buffer passed |
| 166 * to the audio callback will be determined by the device configuration and is |
| 167 * specified in the <code>AudioConfig</code> documentation. |
| 168 * |
| 169 * @param[in] audio_output A <code>PP_Resource</code> corresponding to an |
| 170 audio |
| 171 * output resource. |
| 172 * @param[in] device_ref Identifies an audio output device. It could be one of |
| 173 * the resource in the array returned by EnumerateDevices(), or 0 which means |
| 174 * the default device. |
| 175 * @param[in] config A <code>PPB_AudioConfig</code> audio configuration |
| 176 * resource. |
| 177 * @param[in] audio_output_callback A <code>PPB_AudioOutput_Callback</code> |
| 178 * function that will be called when audio buffer needs to be filled. |
| 179 * @param[inout] user_data An opaque pointer that will be passed into |
| 180 * <code>audio_output_callback</code>. |
| 181 * @param[in] callback A <code>PP_CompletionCallback</code> to run when this |
| 182 * open operation is completed. |
| 183 * |
| 184 * @return An error code from <code>pp_errors.h</code>. |
| 185 */ |
| 186 int32_t (*Open)(PP_Resource audio_output, |
| 187 PP_Resource device_ref, |
| 188 PP_Resource config, |
| 189 PPB_AudioOutput_Callback audio_output_callback, |
| 190 void* user_data, |
| 191 struct PP_CompletionCallback callback); |
| 192 /** |
| 193 * GetCurrrentConfig() returns an audio config resource for the given audio |
| 194 * output resource. |
| 195 * |
| 196 * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 197 * output resource. |
| 198 * |
| 199 * @return A <code>PP_Resource</code> containing the audio config resource if |
| 200 * successful. |
| 201 */ |
| 202 PP_Resource (*GetCurrentConfig)(PP_Resource audio_output); |
| 203 /** |
| 204 * StartPlayback() starts the playback of the audio output resource and begins |
| 205 * periodically calling the callback. |
| 206 * |
| 207 * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 208 * output resource. |
| 209 * |
| 210 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if |
| 211 * successful, otherwise <code>PP_FALSE</code>. Also returns |
| 212 * <code>PP_TRUE</code> (and be a no-op) if called while playback is already |
| 213 * in progress. |
| 214 */ |
| 215 PP_Bool (*StartPlayback)(PP_Resource audio_output); |
| 216 /** |
| 217 * StopPlayback() stops the playback of the audio resource. |
| 218 * |
| 219 * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 220 * output resource. |
| 221 * |
| 222 * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if |
| 223 * successful, otherwise <code>PP_FALSE</code>. Also returns |
| 224 * <code>PP_TRUE</code> (and is a no-op) if called while playback is already |
| 225 * stopped. If a callback is in progress, StopPlayback() will block until the |
| 226 * callback completes. |
| 227 */ |
| 228 PP_Bool (*StopPlayback)(PP_Resource audio_output); |
| 229 /** |
| 230 * Close() closes the audio output device, |
| 231 and stops playback if necessary. It is |
| 232 * not valid to call Open() again after a call to this method. |
| 233 * If an audio output resource is destroyed while a device is still open, then |
| 234 * it will be implicitly closed, so you are not required to call this method. |
| 235 * |
| 236 * @param[in] audio_output A <code>PP_Resource</code> corresponding to an |
| 237 audio |
| 238 * output resource. |
| 239 */ |
| 240 void (*Close)(PP_Resource audio_output); |
| 241 }; |
| 242 |
| 243 typedef struct PPB_AudioOutput_Dev_0_1 PPB_AudioOutput_Dev; |
| 244 /** |
| 245 * @} |
| 246 */ |
| 247 |
| 248 #endif /* PPAPI_C_DEV_PPB_AUDIO_OUTPUT_DEV_H_ */ |
| 249 |
OLD | NEW |