Work on improving PpbAudioConfig:RecommendSampleFrameCount

ppapi/api/ppb_audio_config.idl

 /* 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.
  */
 
 /**
  * This file defines the PPB_AudioConfig interface for establishing an
  * audio configuration resource within the browser.
  */
 
 label Chrome {
-  M14 = 1.0
+  M14 = 1.0,
+  M18 = 1.1
 };
 
 /**
  * This enumeration contains audio frame count constants.
  * <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> is the minimum possible frame
  * count. <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> is the maximum possible
  * frame count.
  */
 [unnamed] enum PP_AudioFrameSize {
   PP_AUDIOMINSAMPLEFRAMECOUNT = 64,
@@ skipping 59 matching lines @@
    * @return A <code>PP_Resource</code> containing the
    * <code>PPB_Audio_Config</code> if successful or a null resource if the
    * sample frame count or bit rate are not supported.
    */
   PP_Resource CreateStereo16Bit(
       [in] PP_Instance instance,
       [in] PP_AudioSampleRate sample_rate,
       [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
    * <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.
    *
+   * @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.
    */
+  [version=1.1]
   uint32_t RecommendSampleFrameCount(
+      [in] PP_Instance instance,
       [in] PP_AudioSampleRate sample_rate,
       [in] 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.
    * 
@@ skipping 23 matching lines @@
    *
    * @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(
       [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);
+
 };