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 21 matching lines @@
  * This interface only supports stereo * 16bit output.
  *
  * Refer to the
  * <a href="/chrome/nativeclient/docs/audio.html">Pepper
  * Audio API</a> for information on using this interface.
  */
 [macro="PPB_AUDIO_CONFIG_INTERFACE"]
 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.
    *
    * 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 15 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 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
    * <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.
    */
+  [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.  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);
+
 };