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 */
37typedef 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 */
81struct 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
160typedef struct PPB_Audio_1_0 PPB_Audio;
161/**
162 * @}
163 */
164
165#endif  /* PPAPI_C_PPB_AUDIO_H_ */
166
167