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_config.idl modified Fri Jan 24 16:19:35 2014. */
7
8#ifndef PPAPI_C_PPB_AUDIO_CONFIG_H_
9#define PPAPI_C_PPB_AUDIO_CONFIG_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_CONFIG_INTERFACE_1_0 "PPB_AudioConfig;1.0"
18#define PPB_AUDIO_CONFIG_INTERFACE_1_1 "PPB_AudioConfig;1.1"
19#define PPB_AUDIO_CONFIG_INTERFACE PPB_AUDIO_CONFIG_INTERFACE_1_1
20
21/**
22 * @file
23 * This file defines the PPB_AudioConfig interface for establishing an
24 * audio configuration resource within the browser.
25 */
26
27
28/**
29 * @addtogroup Enums
30 * @{
31 */
32/**
33 * This enumeration contains audio frame count constants.
34 * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> is the minimum possible frame
35 * count. <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> is the maximum possible
36 * frame count.
37 */
38enum {
39  PP_AUDIOMINSAMPLEFRAMECOUNT = 64,
40  PP_AUDIOMAXSAMPLEFRAMECOUNT = 32768
41};
42
43/**
44 * PP_AudioSampleRate is an enumeration of the different audio sampling rates.
45 * <code>PP_AUDIOSAMPLERATE_44100</code> is the sample rate used on CDs and
46 * <code>PP_AUDIOSAMPLERATE_48000</code> is the sample rate used on DVDs and
47 * Digital Audio Tapes.
48 */
49typedef enum {
50  PP_AUDIOSAMPLERATE_NONE = 0,
51  PP_AUDIOSAMPLERATE_44100 = 44100,
52  PP_AUDIOSAMPLERATE_48000 = 48000
53} PP_AudioSampleRate;
54PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_AudioSampleRate, 4);
55/**
56 * @}
57 */
58
59/**
60 * @addtogroup Interfaces
61 * @{
62 */
63/**
64 * The <code>PPB_AudioConfig</code> interface contains pointers to several
65 * functions for establishing your audio configuration within the browser.
66 * This interface only supports 16-bit stereo output.
67 *
68 * Refer to the
69 * <a href="/native-client/devguide/coding/audio.html">Audio
70 * </a> chapter in the Developer's Guide for information on using this
71 * interface.
72 */
73struct PPB_AudioConfig_1_1 {
74  /**
75   * CreateStereo16bit() creates a 16 bit audio configuration resource. The
76   * <code>sample_rate</code> should be the result of calling
77   * <code>RecommendSampleRate</code> and <code>sample_frame_count</code> should
78   * be the result of calling <code>RecommendSampleFrameCount</code>. If the
79   * sample frame count or bit rate isn't supported, this function will fail and
80   * return a null resource.
81   *
82   * A single sample frame on a stereo device means one value for the left
83   * channel and one value for the right channel.
84   *
85   * Buffer layout for a stereo int16 configuration:
86   * <code>int16_t *buffer16;</code>
87   * <code>buffer16[0]</code> is the first left channel sample.
88   * <code>buffer16[1]</code> is the first right channel sample.
89   * <code>buffer16[2]</code> is the second left channel sample.
90   * <code>buffer16[3]</code> is the second right channel sample.
91   * ...
92   * <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left
93   * channel sample.
94   * <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last
95   * right channel sample.
96   * Data will always be in the native endian format of the platform.
97   *
98   * @param[in] instance A <code>PP_Instance</code> identifying one instance
99   * of a module.
100   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
101   * <code>PP_AUDIOSAMPLERATE_44100</code> or
102   * <code>PP_AUDIOSAMPLERATE_48000</code>.
103   * @param[in] sample_frame_count A <code>uint32_t</code> frame count returned
104   * from the <code>RecommendSampleFrameCount</code> function.
105   *
106   * @return A <code>PP_Resource</code> containing the
107   * <code>PPB_Audio_Config</code> if successful or a null resource if the
108   * sample frame count or bit rate are not supported.
109   */
110  PP_Resource (*CreateStereo16Bit)(PP_Instance instance,
111                                   PP_AudioSampleRate sample_rate,
112                                   uint32_t sample_frame_count);
113  /**
114   * RecommendSampleFrameCount() returns the supported sample frame count
115   * closest to the requested count. The sample frame count determines the
116   * overall latency of audio. Since one "frame" is always buffered in advance,
117   * smaller frame counts will yield lower latency, but higher CPU utilization.
118   *
119   * Supported sample frame counts will vary by hardware and system (consider
120   * that the local system might be anywhere from a cell phone or a high-end
121   * audio workstation). Sample counts less than
122   * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
123   * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
124   * system, but values in between aren't necessarily valid. This function
125   * will return a supported count closest to the requested frame count.
126   *
127   * RecommendSampleFrameCount() result is intended for audio output devices.
128   *
129   * @param[in] instance
130   * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
131   * <code>PP_AUDIOSAMPLERATE_44100</code> or
132   * <code>PP_AUDIOSAMPLERATE_48000.</code>
133   * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
134   * frame count.
135   *
136   * @return A <code>uint32_t</code> containing the recommended sample frame
137   * count if successful.
138   */
139  uint32_t (*RecommendSampleFrameCount)(
140      PP_Instance instance,
141      PP_AudioSampleRate sample_rate,
142      uint32_t requested_sample_frame_count);
143  /**
144   * IsAudioConfig() determines if the given resource is a
145   * <code>PPB_Audio_Config</code>.
146   *
147   * @param[in] resource A <code>PP_Resource</code> corresponding to an audio
148   * config resource.
149   *
150   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
151   * resource is an <code>AudioConfig</code> resource, otherwise
152   * <code>PP_FALSE</code>.
153   */
154  PP_Bool (*IsAudioConfig)(PP_Resource resource);
155  /**
156   * GetSampleRate() returns the sample rate for the given
157   * <code>PPB_Audio_Config</code>.
158   *
159   * @param[in] config A <code>PP_Resource</code> corresponding to a
160   * <code>PPB_Audio_Config</code>.
161   *
162   * @return A <code>PP_AudioSampleRate</code> containing sample rate or
163   * <code>PP_AUDIOSAMPLERATE_NONE</code> if the resource is invalid.
164   */
165  PP_AudioSampleRate (*GetSampleRate)(PP_Resource config);
166  /**
167   * GetSampleFrameCount() returns the sample frame count for the given
168   * <code>PPB_Audio_Config</code>.
169   *
170   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
171   * config resource.
172   *
173   * @return A <code>uint32_t</code> containing sample frame count or
174   * 0 if the resource is invalid. Refer to
175   * RecommendSampleFrameCount() for more on sample frame counts.
176   */
177  uint32_t (*GetSampleFrameCount)(PP_Resource config);
178  /**
179   * RecommendSampleRate() returns the native sample rate that the browser
180   * is using in the backend.  Applications that use the recommended sample
181   * rate will have potentially better latency and fidelity.  The return value
182   * is intended for audio output devices.  If the output sample rate cannot be
183   * determined, this function can return PP_AUDIOSAMPLERATE_NONE.
184   *
185   * @param[in] instance
186   *
187   * @return A <code>uint32_t</code> containing the recommended sample frame
188   * count if successful.
189   */
190  PP_AudioSampleRate (*RecommendSampleRate)(PP_Instance instance);
191};
192
193typedef struct PPB_AudioConfig_1_1 PPB_AudioConfig;
194
195struct PPB_AudioConfig_1_0 {
196  PP_Resource (*CreateStereo16Bit)(PP_Instance instance,
197                                   PP_AudioSampleRate sample_rate,
198                                   uint32_t sample_frame_count);
199  uint32_t (*RecommendSampleFrameCount)(
200      PP_AudioSampleRate sample_rate,
201      uint32_t requested_sample_frame_count);
202  PP_Bool (*IsAudioConfig)(PP_Resource resource);
203  PP_AudioSampleRate (*GetSampleRate)(PP_Resource config);
204  uint32_t (*GetSampleFrameCount)(PP_Resource config);
205};
206/**
207 * @}
208 */
209
210#endif  /* PPAPI_C_PPB_AUDIO_CONFIG_H_ */
211
212