Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 1 | /* Copyright (c) 2012 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 | |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 6 | /* From ppb_audio.idl modified Fri Jan 24 16:18:44 2014. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 7 | |
| 8 | #ifndef PPAPI_C_PPB_AUDIO_H_ |
| 9 | #define PPAPI_C_PPB_AUDIO_H_ |
| 10 | |
| 11 | #include "ppapi/c/pp_bool.h" |
| 12 | #include "ppapi/c/pp_instance.h" |
| 13 | #include "ppapi/c/pp_macros.h" |
| 14 | #include "ppapi/c/pp_resource.h" |
| 15 | #include "ppapi/c/pp_stdint.h" |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 16 | #include "ppapi/c/pp_time.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 17 | |
| 18 | #define PPB_AUDIO_INTERFACE_1_0 "PPB_Audio;1.0" |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 19 | #define PPB_AUDIO_INTERFACE_1_1 "PPB_Audio;1.1" |
| 20 | #define PPB_AUDIO_INTERFACE PPB_AUDIO_INTERFACE_1_1 |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 21 | |
| 22 | /** |
| 23 | * @file |
| 24 | * This file defines the <code>PPB_Audio</code> interface, which provides |
| 25 | * realtime stereo audio streaming capabilities. |
| 26 | */ |
| 27 | |
| 28 | |
| 29 | /** |
| 30 | * @addtogroup Typedefs |
| 31 | * @{ |
| 32 | */ |
| 33 | /** |
| 34 | * <code>PPB_Audio_Callback</code> defines the type of an audio callback |
| 35 | * function used to fill the audio buffer with data. Please see the |
| 36 | * Create() function in the <code>PPB_Audio</code> interface for |
| 37 | * more details on this callback. |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 38 | * |
| 39 | * @param[in] sample_buffer A buffer to fill with audio data. |
| 40 | * @param[in] buffer_size_in_bytes The size of the buffer in bytes. |
| 41 | * @param[in] latency How long before the audio data is to be presented. |
| 42 | * @param[inout] user_data An opaque pointer that was passed into |
| 43 | * <code>PPB_Audio.Create()</code>. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 44 | */ |
| 45 | typedef void (*PPB_Audio_Callback)(void* sample_buffer, |
| 46 | uint32_t buffer_size_in_bytes, |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 47 | PP_TimeDelta latency, |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 48 | void* user_data); |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 49 | |
| 50 | typedef void (*PPB_Audio_Callback_1_0)(void* sample_buffer, |
| 51 | uint32_t buffer_size_in_bytes, |
| 52 | void* user_data); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 53 | /** |
| 54 | * @} |
| 55 | */ |
| 56 | |
| 57 | /** |
| 58 | * @addtogroup Interfaces |
| 59 | * @{ |
| 60 | */ |
| 61 | /** |
| 62 | * The <code>PPB_Audio</code> interface contains pointers to several functions |
| 63 | * for handling audio resources. Refer to the |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 64 | * <a href="/native-client/devguide/coding/audio.html">Audio</a> |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 65 | * chapter in the Developer's Guide for information on using this interface. |
| 66 | * Please see descriptions for each <code>PPB_Audio</code> and |
| 67 | * <code>PPB_AudioConfig</code> function for more details. A C example using |
| 68 | * <code>PPB_Audio</code> and <code>PPB_AudioConfig</code> follows. |
| 69 | * |
| 70 | * <strong>Example: </strong> |
| 71 | * |
| 72 | * @code |
| 73 | * void audio_callback(void* sample_buffer, |
| 74 | * uint32_t buffer_size_in_bytes, |
| 75 | * void* user_data) { |
| 76 | * ... quickly fill in the buffer with samples and return to caller ... |
| 77 | * } |
| 78 | * |
| 79 | * ...Assume the application has cached the audio configuration interface in |
| 80 | * audio_config_interface and the audio interface in |
| 81 | * audio_interface... |
| 82 | * |
| 83 | * uint32_t count = audio_config_interface->RecommendSampleFrameCount( |
| 84 | * PP_AUDIOSAMPLERATE_44100, 4096); |
| 85 | * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit( |
| 86 | * pp_instance, PP_AUDIOSAMPLERATE_44100, count); |
| 87 | * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config, |
| 88 | * audio_callback, NULL); |
| 89 | * audio_interface->StartPlayback(pp_audio); |
| 90 | * |
| 91 | * ...audio_callback() will now be periodically invoked on a separate thread... |
| 92 | * @endcode |
| 93 | */ |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 94 | struct PPB_Audio_1_1 { |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 95 | /** |
| 96 | * Create() creates an audio resource. No sound will be heard until |
| 97 | * StartPlayback() is called. The callback is called with the buffer address |
| 98 | * and given user data whenever the buffer needs to be filled. From within the |
| 99 | * callback, you should not call <code>PPB_Audio</code> functions. The |
| 100 | * callback will be called on a different thread than the one which created |
| 101 | * the interface. For performance-critical applications (i.e. low-latency |
| 102 | * audio), the callback should avoid blocking or calling functions that can |
| 103 | * obtain locks, such as malloc. The layout and the size of the buffer passed |
| 104 | * to the audio callback will be determined by the device configuration and is |
| 105 | * specified in the <code>AudioConfig</code> documentation. |
| 106 | * |
| 107 | * @param[in] instance A <code>PP_Instance</code> identifying one instance |
| 108 | * of a module. |
| 109 | * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 110 | * config resource. |
| 111 | * @param[in] audio_callback A <code>PPB_Audio_Callback</code> callback |
| 112 | * function that the browser calls when it needs more samples to play. |
| 113 | * @param[in] user_data A pointer to user data used in the callback function. |
| 114 | * |
| 115 | * @return A <code>PP_Resource</code> containing the audio resource if |
| 116 | * successful or 0 if the configuration cannot be honored or the callback is |
| 117 | * null. |
| 118 | */ |
| 119 | PP_Resource (*Create)(PP_Instance instance, |
| 120 | PP_Resource config, |
| 121 | PPB_Audio_Callback audio_callback, |
| 122 | void* user_data); |
| 123 | /** |
| 124 | * IsAudio() determines if the provided resource is an audio resource. |
| 125 | * |
| 126 | * @param[in] resource A <code>PP_Resource</code> corresponding to a generic |
| 127 | * resource. |
| 128 | * |
| 129 | * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code> |
| 130 | * if the given resource is an Audio resource, otherwise |
| 131 | * <code>PP_FALSE</code>. |
| 132 | */ |
| 133 | PP_Bool (*IsAudio)(PP_Resource resource); |
| 134 | /** |
| 135 | * GetCurrrentConfig() returns an audio config resource for the given audio |
| 136 | * resource. |
| 137 | * |
| 138 | * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 139 | * resource. |
| 140 | * |
| 141 | * @return A <code>PP_Resource</code> containing the audio config resource if |
| 142 | * successful. |
| 143 | */ |
| 144 | PP_Resource (*GetCurrentConfig)(PP_Resource audio); |
| 145 | /** |
| 146 | * StartPlayback() starts the playback of the audio resource and begins |
| 147 | * periodically calling the callback. |
| 148 | * |
| 149 | * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 150 | * resource. |
| 151 | * |
| 152 | * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if |
| 153 | * successful, otherwise <code>PP_FALSE</code>. Also returns |
| 154 | * <code>PP_TRUE</code> (and be a no-op) if called while playback is already |
| 155 | * in progress. |
| 156 | */ |
| 157 | PP_Bool (*StartPlayback)(PP_Resource audio); |
| 158 | /** |
| 159 | * StopPlayback() stops the playback of the audio resource. |
| 160 | * |
| 161 | * @param[in] config A <code>PP_Resource</code> corresponding to an audio |
| 162 | * resource. |
| 163 | * |
| 164 | * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if |
| 165 | * successful, otherwise <code>PP_FALSE</code>. Also returns |
| 166 | * <code>PP_TRUE</code> (and is a no-op) if called while playback is already |
| 167 | * stopped. If a callback is in progress, StopPlayback() will block until the |
| 168 | * callback completes. |
| 169 | */ |
| 170 | PP_Bool (*StopPlayback)(PP_Resource audio); |
| 171 | }; |
| 172 | |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 173 | typedef struct PPB_Audio_1_1 PPB_Audio; |
| 174 | |
| 175 | struct PPB_Audio_1_0 { |
| 176 | PP_Resource (*Create)(PP_Instance instance, |
| 177 | PP_Resource config, |
| 178 | PPB_Audio_Callback_1_0 audio_callback, |
| 179 | void* user_data); |
| 180 | PP_Bool (*IsAudio)(PP_Resource resource); |
| 181 | PP_Resource (*GetCurrentConfig)(PP_Resource audio); |
| 182 | PP_Bool (*StartPlayback)(PP_Resource audio); |
| 183 | PP_Bool (*StopPlayback)(PP_Resource audio); |
| 184 | }; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 185 | /** |
| 186 | * @} |
| 187 | */ |
| 188 | |
| 189 | #endif /* PPAPI_C_PPB_AUDIO_H_ */ |
| 190 | |