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