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 6 /* From ppb_audio.idl modified Thu Aug 01 13:19:46 2013. */ 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" 16 #include "ppapi/c/pp_time.h" 17 18 #define PPB_AUDIO_INTERFACE_1_0 "PPB_Audio;1.0" 19 #define PPB_AUDIO_INTERFACE_1_1 "PPB_Audio;1.1" 20 #define PPB_AUDIO_INTERFACE PPB_AUDIO_INTERFACE_1_1 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. 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>. 44 */ 45 typedef void (*PPB_Audio_Callback)(void* sample_buffer, 46 uint32_t buffer_size_in_bytes, 47 PP_TimeDelta latency, 48 void* user_data); 49 50 typedef void (*PPB_Audio_Callback_1_0)(void* sample_buffer, 51 uint32_t buffer_size_in_bytes, 52 void* user_data); 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 64 * <a href="/native-client/{{pepperversion}}/devguide/coding/audio">Audio</a> 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 */ 94 struct PPB_Audio_1_1 { 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 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 }; 185 /** 186 * @} 187 */ 188 189 #endif /* PPAPI_C_PPB_AUDIO_H_ */ 190 191