Home | History | Annotate | Download | only in c
      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 
    212