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 118765)
+++ ppapi/api/ppb_audio_config.idl	(working copy)
@@ -9,7 +9,8 @@
  */
 
 label Chrome {
-  M14 = 1.0
+  M14 = 1.0,
+  M18 = 1.1
 };
 
 /**
@@ -89,11 +90,39 @@
       [in] uint32_t sample_frame_count);
 
   /**
+   * This comment block applies to version 1.0, which is deprecated in favor of
+   * the same function signature but with different behavior.

[dmichael (off chromium), 2012/01/24 16:54:38]

FWIW, it looks like the interface did change to require PP_Instance.

[nfullagar, 2012/01/24 19:14:58]

thx, comment updated.

On 2012/01/24 16:54:38, dmichael wrote:

+   *
    * 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.
    *
+   * 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 +131,7 @@
    * system, but values in between aren't necessarily valid. This function
    * will return a supported count closest to the requested value.
    *
+   * @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 +141,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 +187,20 @@
    */
   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.
+   *
+   * @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);
+
 };