ppapi/api/ppb_audio.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_Audio</code> interface, which provides
   8  * realtime stereo audio streaming capabilities.
   9  */
  10
  11 label Chrome {
  12   M14 = 1.0
  13 };
  14
  15 /**
  16  * <code>PPB_Audio_Callback</code> defines the type of an audio callback
  17  * function used to fill the audio buffer with data. Please see the
  18  * Create() function in the <code>PPB_Audio</code> interface for
  19  * more details on this callback.
  20  */
  21 typedef void PPB_Audio_Callback([out] mem_t sample_buffer,
  22                                 [in] uint32_t buffer_size_in_bytes,
  23                                 [inout] mem_t user_data);
  24
  25 /**
  26  * The <code>PPB_Audio</code> interface contains pointers to several functions
  27  * for handling audio resources. Please refer to the
  28  * <a href="/chrome/nativeclient/docs/audio.html">Pepper
  29  * Audio API</a> for information on using this interface.
  30  * Please see descriptions for each <code>PPB_Audio</code> and
  31  * <code>PPB_AudioConfig</code> function for more details. A C example using
  32  * <code>PPB_Audio</code> and <code>PPB_AudioConfig</code> follows.
  33  *
  34  * <strong>Example: </strong>
  35  *
  36  * <code>
  37  * void audio_callback(void* sample_buffer,
  38  *                     uint32_t buffer_size_in_bytes,
  39  *                     void* user_data) {
  40  *   ... quickly fill in the buffer with samples and return to caller ...
  41  *  }
  42  *
  43  * ...Assume the application has cached the audio configuration interface in
  44  * <code>audio_config_interface</code> and the audio interface in
  45  * <code>audio_interface</code>...
  46  *
  47  * uint32_t count = audio_config_interface->RecommendSampleFrameCount(
  48  *     PP_AUDIOSAMPLERATE_44100, 4096);
  49  * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
  50  *     pp_instance, PP_AUDIOSAMPLERATE_44100, count);
  51  * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config,
  52  *     audio_callback, NULL);
  53  * audio_interface->StartPlayback(pp_audio);
  54  *
  55  * ...audio_callback() will now be periodically invoked on a separate thread...
  56  * </code>
  57  */
  58 interface PPB_Audio {
  59  /**
  60   * Create() creates an audio resource. No sound will be heard until
  61   * StartPlayback() is called. The callback is called with the buffer address
  62   * and given user data whenever the buffer needs to be filled. From within the
  63   * callback, you should not call <code>PPB_Audio</code> functions. The
  64   * callback will be called on a different thread than the one which created
  65   * the interface. For performance-critical applications (i.e. low-latency
  66   * audio), the callback should avoid blocking or calling functions that can
  67   * obtain locks, such as malloc. The layout and the size of the buffer passed
  68   * to the audio callback will be determined by the device configuration and is
  69   * specified in the <code>AudioConfig</code> documentation.
  70   *
  71   * @param[in] instance A <code>PP_Instance</code> identifying one instance
  72   * of a module.
  73   * @param[in] config A <code>PP_Resource</code> corresponding to an audio
  74   * config resource.
  75   * @param[in] audio_callback A <code>PPB_Audio_Callback</code> callback
  76   * function that the browser calls when it needs more samples to play.
  77   * @param[in] user_data A pointer to user data used in the callback function.
  78   *
  79   * @return A <code>PP_Resource</code> containing the audio resource if
  80   * successful or 0 if the configuration cannot be honored or the callback is
  81   * null.
  82   */
  83   PP_Resource Create(
  84       [in] PP_Instance instance,
  85       [in] PP_Resource config,
  86       [in] PPB_Audio_Callback audio_callback,
  87       [inout] mem_t user_data);
  88
  89   /**
  90    * IsAudio() determines if the provided resource is an audio resource.
  91    *
  92    * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
  93    * resource.
  94    *
  95    * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
  96    * if the given resource is an Audio resource, otherwise
  97    * <code>PP_FALSE</code>.
  98    */
  99   PP_Bool IsAudio(
 100       [in] PP_Resource resource);
 101
 102   /**
 103    * GetCurrrentConfig() returns an audio config resource for the given audio
 104    * resource.
 105    *
 106    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 107    * resource.
 108    *
 109    * @return A <code>PP_Resource</code> containing the audio config resource if
 110    * successful.
 111    */
 112   PP_Resource GetCurrentConfig(
 113       [in] PP_Resource audio);
 114
 115   /**
 116    * StartPlayback() starts the playback of the audio resource and begins
 117   * periodically calling the callback.
 118    *
 119    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 120    * resource.
 121    *
 122    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 123    * successful, otherwise <code>PP_FALSE</code>. Also returns
 124    * <code>PP_TRUE</code> (and be a no-op) if called while playback is already
 125    * in progress.
 126    */
 127   PP_Bool StartPlayback(
 128       [in] PP_Resource audio);
 129
 130   /**
 131    * StopPlayback() stops the playback of the audio resource.
 132    *
 133    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 134    * resource.
 135    *
 136    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 137    * successful, otherwise <code>PP_FALSE</code>. Also returns
 138    * <code>PP_TRUE</code> (and is a no-op) if called while playback is already
 139    * stopped. If a callback is in progress, StopPlayback() will block until the
 140    * callback completes.
 141    */
 142   PP_Bool StopPlayback(
 143       [in] PP_Resource audio);
 144 };
 145