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 Tue Aug 23 14:05:44 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 * 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 of a |
93 * @param[in] config A PP_Resource containing the audio config resource. | 96 * 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 |