Work on improving PpbAudioConfig:RecommendSampleFrameCount

Add version 1.1 which will query the audio back end for the best available
sample frame count. Also add RecommendSampleRate.  Switch pepper plugin
delegate to use AUDIO_PCM_LOW_LATENCY if client request is compatible.

TEST=included
BUG=http://code.google.com/p/chromium/issues/detail?id=107572
Review URL: https://chromiumcodereview.appspot.com/9129007

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@122653 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 59 insertions, 4 deletions

diff --git a/ppapi/api/ppb_audio_config.idl b/ppapi/api/ppb_audio_config.idl
index 4c2e3a2..8ba2a28 100644
--- a/ppapi/api/ppb_audio_config.idl
+++ b/ppapi/api/ppb_audio_config.idl
@@ -9,7 +9,8 @@
  */
 
 label Chrome {
-  M14 = 1.0
+  M14 = 1.0,
+  M18 = 1.1
 };
 
 /**
@@ -51,9 +52,11 @@ enum PP_AudioSampleRate {
 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,6 +92,37 @@ interface PPB_AudioConfig {
       [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,
@@ -102,6 +136,9 @@ interface PPB_AudioConfig {
    * 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 @@ interface PPB_AudioConfig {
    * @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 @@ interface PPB_AudioConfig {
    */
   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);
+
 };