Work on improving PpbAudioConfig:RecommendSampleFrameCount

ppapi/c/ppb_audio_config.h

 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
-/* From ppb_audio_config.idl modified Fri Jan 20 13:12:44 2012. */
+/* From ppb_audio_config.idl modified Thu Feb 16 16:23:46 2012. */
 
 #ifndef PPAPI_C_PPB_AUDIO_CONFIG_H_
 #define PPAPI_C_PPB_AUDIO_CONFIG_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
 #define PPB_AUDIO_CONFIG_INTERFACE_1_0 "PPB_AudioConfig;1.0"
-#define PPB_AUDIO_CONFIG_INTERFACE PPB_AUDIO_CONFIG_INTERFACE_1_0
+#define PPB_AUDIO_CONFIG_INTERFACE_1_1 "PPB_AudioConfig;1.1"
+#define PPB_AUDIO_CONFIG_INTERFACE PPB_AUDIO_CONFIG_INTERFACE_1_1
 
 /**
  * @file
  * This file defines the PPB_AudioConfig interface for establishing an
  * audio configuration resource within the browser.
  */
 
 
 /**
  * @addtogroup Enums
@@ skipping 32 matching lines @@
  */
 /**
  * The <code>PPB_AudioConfig</code> interface contains pointers to several
  * functions for establishing your audio configuration within the browser.
  * This interface only supports 16-bit stereo output.
  *
  * Refer to the
  * <a href="/chrome/nativeclient/docs/audio.html">Pepper
  * Audio API</a> for information on using this interface.
  */
-struct PPB_AudioConfig_1_0 {
+struct PPB_AudioConfig_1_1 {
   /**
    * CreateStereo16bit() creates a 16 bit audio configuration resource. The
-   * <code>sample_frame_count</code> should be the result of calling
-   * <code>RecommendSampleFrameCount</code>. If the sample frame count or bit
-   * rate isn't supported, this function will fail and return a null resource.
+   * <code>sample_rate</code> should be the result of calling
+   * <code>RecommendSampleRate</code> and <code>sample_frame_count</code> should
+   * be the result of calling <code>RecommendSampleFrameCount</code>. If the
+   * sample frame count or bit rate isn't supported, this function will fail and
+   * return a null resource.
    *
    * A single sample frame on a stereo device means one value for the left
    * channel and one value for the right channel.
    *
    * Buffer layout for a stereo int16 configuration:
    * <code>int16_t *buffer16;</code>
    * <code>buffer16[0]</code> is the first left channel sample.
    * <code>buffer16[1]</code> is the first right channel sample.
    * <code>buffer16[2]</code> is the second left channel sample.
    * <code>buffer16[3]</code> is the second right channel sample.
@@ skipping 26 matching lines @@
    * smaller frame counts will yield lower latency, but higher CPU utilization.
    *
    * Supported sample frame counts will vary by hardware and system (consider
    * that the local system might be anywhere from a cell phone or a high-end
    * audio workstation). Sample counts less than
    * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
    * <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
    * system, but values in between aren't necessarily valid. This function
    * will return a supported count closest to the requested value.
    *
+   * RecommendSampleFrameCount() result is intended for audio output devices.
+   *
+   * @param[in] instance
    * @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
    * <code>PP_AUDIOSAMPLERATE_44100</code> or
    * <code>PP_AUDIOSAMPLERATE_48000.</code>
    * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
    * frame count.
    *
    * @return A <code>uint32_t</code> containing the recommended sample frame
    * count if successful.
    */
   uint32_t (*RecommendSampleFrameCount)(
+      PP_Instance instance,
       PP_AudioSampleRate sample_rate,
       uint32_t requested_sample_frame_count);
   /**
    * IsAudioConfig() determines if the given resource is a
    * <code>PPB_Audio_Config</code>.
    *
    * @param[in] resource A <code>PP_Resource</code> corresponding to an audio
    * config resource.
    *
    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the given
@@ skipping 17 matching lines @@
    * <code>PPB_Audio_Config</code>.
    *
    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
    * config resource.
    *
    * @return A <code>uint32_t</code> containing sample frame count or
    * 0 if the resource is invalid. Refer to
    * RecommendSampleFrameCount() for more on sample frame counts.
    */
   uint32_t (*GetSampleFrameCount)(PP_Resource config);
+  /**
+   * RecommendSampleRate() returns the native sample rate that the browser
+   * is using in the backend.  Applications that use the recommended sample
+   * rate will have potentially better latency and fidelity.  The return value
+   * is indended for audio output devices.
+   *
+   * @param[in] instance
+   *
+   * @return A <code>uint32_t</code> containing the recommended sample frame
+   * count if successful.
+   */
+  PP_AudioSampleRate (*RecommendSampleRate)(PP_Instance instance);
 };
 
-typedef struct PPB_AudioConfig_1_0 PPB_AudioConfig;
+typedef struct PPB_AudioConfig_1_1 PPB_AudioConfig;
+
+struct PPB_AudioConfig_1_0 {
+  PP_Resource (*CreateStereo16Bit)(PP_Instance instance,
+                                   PP_AudioSampleRate sample_rate,
+                                   uint32_t sample_frame_count);
+  uint32_t (*RecommendSampleFrameCount)(
+      PP_AudioSampleRate sample_rate,
+      uint32_t requested_sample_frame_count);
+  PP_Bool (*IsAudioConfig)(PP_Resource resource);
+  PP_AudioSampleRate (*GetSampleRate)(PP_Resource config);
+  uint32_t (*GetSampleFrameCount)(PP_Resource config);
+};
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_AUDIO_CONFIG_H_ */