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