ppapi/c/ppb_audio_config.h

   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 Thu Mar 28 10:07:11 2013. */
   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  */
  38 enum {
  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  */
  49 typedef enum {
  50   PP_AUDIOSAMPLERATE_NONE = 0,
  51   PP_AUDIOSAMPLERATE_44100 = 44100,
  52   PP_AUDIOSAMPLERATE_48000 = 48000
  53 } PP_AudioSampleRate;
  54 PP_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/{{pepperversion}}/devguide/coding/audio">Audio
  70  * </a> chapter in the Developer's Guide for information on using this
  71  * interface.
  72  */
  73 struct 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
 193 typedef struct PPB_AudioConfig_1_1 PPB_AudioConfig;
 194
 195 struct 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