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