Work on improving PpbAudioConfig:RecommendSampleFrameCount

ppapi/api/ppb_audio_config.idl

Index: ppapi/api/ppb_audio_config.idl
===================================================================
--- ppapi/api/ppb_audio_config.idl	(revision 120806)
+++ ppapi/api/ppb_audio_config.idl	(working copy)
@@ -9,7 +9,8 @@
  */
 
 label Chrome {
-  M14 = 1.0
+  M14 = 1.0,
+  M18 = 1.1
 };
 
 /**
@@ -51,9 +52,11 @@
 interface PPB_AudioConfig {
   /**
    * 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.
@@ -89,11 +92,42 @@
       [in] uint32_t sample_frame_count);
 
   /**
+   * This comment block applies to version 1.0, which is deprecated in favor of
+   * the same function but with slightly different signature and behavior.
+   *
    * RecommendSampleFrameCount() returns the supported sample frame count
    * closest to the requested count. The sample frame count determines the
    * overall latency of audio. Since one "frame" is always buffered in advance,
    * smaller frame counts will yield lower latency, but higher CPU utilization.
+   * For best audio performance, use the value returned by RecommendSampleRate
+   * as the input sample rate, then use the RecommendSampleFrameCount return
+   * value when creating the audio configuration resource.
    *
+   * 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 glitch-free.
+   *
+   * @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.
+   */
+  [deprecate=1.1]
+  uint32_t RecommendSampleFrameCount(
+      [in] PP_AudioSampleRate sample_rate,
+      [in] uint32_t requested_sample_frame_count);
+
+  /**
+   * RecommendSampleFrameCount() returns the supported sample frame count
+   * closest to the requested count. The sample frame count determines the
+   * overall latency of audio. Since one "frame" is always buffered in advance,
+   * 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
@@ -102,6 +136,9 @@
    * 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>
@@ -111,7 +148,9 @@
    * @return A <code>uint32_t</code> containing the recommended sample frame
    * count if successful.
    */
+  [version=1.1]
   uint32_t RecommendSampleFrameCount(
+      [in] PP_Instance instance,
       [in] PP_AudioSampleRate sample_rate,
       [in] uint32_t requested_sample_frame_count);
 
@@ -155,5 +194,21 @@
    */
   uint32_t GetSampleFrameCount(
       [in] 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.
+   */
+  [version=1.1]
+  PP_AudioSampleRate RecommendSampleRate(
+      [in] PP_Instance instance);
+
 };