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 Fri Jan 24 16:18:44 2014. */
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 */
45typedef void (*PPB_Audio_Callback)(void* sample_buffer,
46                                   uint32_t buffer_size_in_bytes,
47                                   PP_TimeDelta latency,
48                                   void* user_data);
49
50typedef 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/devguide/coding/audio.html">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 */
94struct 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
173typedef struct PPB_Audio_1_1 PPB_Audio;
174
175struct 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