Update the IDL

Final update of the IDL so that we can switch to using
generated code for ppapi/c/ and ppapi/c/trusted.


BUG= http://code.google.com/p/chromium/issues/detail?id=74634
TEST= tryserver
TBR= dmichael@chromium.org
Review URL: http://codereview.chromium.org/7390023

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

1 files changed, 96 insertions, 35 deletions

diff --git a/ppapi/api/ppb_audio.idl b/ppapi/api/ppb_audio.idl
index 71abad6..d13f6bf 100644
--- a/ppapi/api/ppb_audio.idl
+++ b/ppapi/api/ppb_audio.idl
@@ -3,70 +3,131 @@
  * found in the LICENSE file.
  */
 
-/* This file defines the audio API.
+/**
+ * This file defines the <code>PPB_Audio</code> interface, which provides
+ * realtime stereo audio streaming capabilities.
  */
 
-/* Callback function type for SetCallback. */
+label Chrome {
+  M13 = 0.6,
+  M14 = 1.0
+};
+
+/**
+ * <code>PPB_Audio_Callback</code> defines the type of an audio callback
+ * function used to fill the audio buffer with data. Please see the
+ * <code>Create()</code> function in the <code>PPB_Audio</code> interface for
+ * more details on this callback.
+ */
 typedef void PPB_Audio_Callback([out] mem_t sample_buffer,
                                 [in] uint32_t buffer_size_in_bytes,
                                 [inout] mem_t user_data);
 
-/* Callback-based audio interface. User of audio must set the callback that will
- * be called each time that the buffer needs to be filled.
- *
- * A C++ example:
+/**
+ * The <code>PPB_Audio</code> interface contains pointers to several functions
+ * for handling audio resources. Please refer to the
+ * <a href="/chrome/nativeclient/docs/audio.html">Pepper
+ * Audio API Code Walkthrough</a> for information on using this interface.
+ * Please see descriptions for each <code>PPB_Audio</code> and
+ * <code>PPB_AudioConfig</code> function for more details.
  *
+ * A C example using PPB_Audio and PPB_AudioConfig:
+ * @code
  * void audio_callback(void* sample_buffer,
- *                     size_t buffer_size_in_bytes,
+ *                     uint32_t buffer_size_in_bytes,
  *                     void* user_data) {
- *   ... fill in the buffer with samples ...
- * }
+ *   ... quickly fill in the buffer with samples and return to caller ...
+ *  }
+ *
+ * ...Assume the application has cached the audio configuration interface in
+ * |audio_config_interface| and the audio interface in |audio_interface|...
  *
- * uint32_t obtained;
- * AudioConfig config(PP_AUDIOSAMPLERATE_44100, 4096, &obtained);
- * Audio audio(config, audio_callback, NULL);
- * audio.StartPlayback();
+ * uint32_t count = audio_config_interface->RecommendSampleFrameCount(
+ *     PP_AUDIOSAMPLERATE_44100, 4096);
+ * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
+ *     pp_instance, PP_AUDIOSAMPLERATE_44100, count);
+ * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config,
+ *     audio_callback, NULL);
+ * audio_interface->StartPlayback(pp_audio);
+ *
+ * ...audio_callback() will now be periodically invoked on a seperate thread...
  */
-interface PPB_Audio_0_5 {
-  /* Creates a paused audio interface. No sound will be heard until
-   * StartPlayback() is called. The callback is called with the buffer address
-   * and given user data whenever the buffer needs to be filled. From within the
-   * callback, you should not call PPB_Audio functions.  The callback will be
-   * called on a different thread than the one which created the interface. For
-   * performance-critical applications (i.e. low-latency audio), the callback
-   * should avoid blocking or calling functions that can obtain locks, such as
-   * malloc. The layout and the size of the buffer passed to the audio callback
-   * will be determined by the device configuration and is specified in the
-   * AudioConfig documentation. If the configuration cannot be honored, or the
-   * callback is null, the function returns 0.
-   */
+interface PPB_Audio {
+ /**
+  * Create is a pointer to a function that creates an audio resource.
+  * No sound will be heard until StartPlayback() is called. The callback
+  * is called with the buffer address and given user data whenever the
+  * buffer needs to be filled. From within the callback, you should not
+  * call PPB_Audio functions. The callback will be called on a different
+  * thread than the one which created the interface. For performance-critical
+  * applications (i.e. low-latency audio), the callback should avoid blocking
+  * or calling functions that can obtain locks, such as malloc. The layout and
+  * the size of the buffer passed to the audio callback will be determined by
+  * the device configuration and is specified in the AudioConfig documentation.
+  *
+  * @param[in] instance A PP_Instance indentifying one instance of a module.
+  * @param[in] config A PP_Resource containing the audio config resource.
+  * @param[in] audio_callback A PPB_Audio_Callback callback function that the
+  * browser calls when it needs more samples to play.
+  * @param[in] user_data A pointer to user data used in the callback function.
+  *
+  * @return A PP_Resource containing the audio resource if successful or
+  * 0 if the configuration cannot be honored or the callback is null.
+  */
   PP_Resource Create(
       [in] PP_Instance instance,
       [in] PP_Resource config,
       [in] PPB_Audio_Callback audio_callback,
       [inout] mem_t user_data);
 
-  /* Returns PP_TRUE if the given resource is an Audio resource, PP_FALSE
-   * otherwise.
+  /**
+   * IsAudio is a pointer to a function that determines if the given
+   * resource is an audio resource.
+   *
+   * @param[in] resource A PP_Resource containing a resource.
+   *
+   * @return A PP_BOOL containing containing PP_TRUE if the given resource is
+   * an Audio resource, otherwise PP_FALSE.
    */
   PP_Bool IsAudio(
       [in] PP_Resource resource);
 
-  /* Get the current configuration. */
+  /**
+   * GetCurrrentConfig is a pointer to a function that returns an audio config
+   * resource for the given audio resource.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   *
+   * @return A PP_Resource containing the audio config resource if successful.
+   */
   PP_Resource GetCurrentConfig(
       [in] PP_Resource audio);
 
-  /* Start the playback. Begin periodically calling the callback. If called
-   * while playback is already in progress, will return PP_TRUE and be a no-op.
-   * On error, return PP_FALSE.
+  /**
+   * StartPlayback is a pointer to a function that starts the playback of
+   * the audio resource and begins periodically calling the callback.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   *
+   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
+   * Also returns PP_TRUE (and be a no-op) if called while playback is already
+   * in progress.
    */
   PP_Bool StartPlayback(
       [in] PP_Resource audio);
 
-  /* Stop the playback. If playback is already stopped, this is a no-op and
-   * returns PP_TRUE. On error, returns PP_FALSE. If a callback is in progress,
-   * StopPlayback will block until callback completes.
+  /**
+   * StopPlayback is a pointer to a function that stops the playback of
+   * the audio resource.
+   *
+   * @param[in] config A PP_Resource containing the audio resource.
+   *
+   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
+   * Also returns PP_TRUE (and is a no-op) if called while playback is already
+   * stopped. If a callback is in progress, StopPlayback will block until the
+   * callback completes.
    */
   PP_Bool StopPlayback(
       [in] PP_Resource audio);
 };
+