src/ppapi/c/ppb_audio.h

   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 /* From ppb_audio.idl modified Thu Aug 01 13:19:46 2013. */
   7
   8 #ifndef PPAPI_C_PPB_AUDIO_H_
   9 #define PPAPI_C_PPB_AUDIO_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/c/pp_stdint.h"
  16 #include "ppapi/c/pp_time.h"
  17
  18 #define PPB_AUDIO_INTERFACE_1_0 "PPB_Audio;1.0"
  19 #define PPB_AUDIO_INTERFACE_1_1 "PPB_Audio;1.1"
  20 #define PPB_AUDIO_INTERFACE PPB_AUDIO_INTERFACE_1_1
  21
  22 /**
  23  * @file
  24  * This file defines the <code>PPB_Audio</code> interface, which provides
  25  * realtime stereo audio streaming capabilities.
  26  */
  27
  28
  29 /**
  30  * @addtogroup Typedefs
  31  * @{
  32  */
  33 /**
  34  * <code>PPB_Audio_Callback</code> defines the type of an audio callback
  35  * function used to fill the audio buffer with data. Please see the
  36  * Create() function in the <code>PPB_Audio</code> interface for
  37  * more details on this callback.
  38  *
  39  * @param[in] sample_buffer A buffer to fill with audio data.
  40  * @param[in] buffer_size_in_bytes The size of the buffer in bytes.
  41  * @param[in] latency How long before the audio data is to be presented.
  42  * @param[inout] user_data An opaque pointer that was passed into
  43  * <code>PPB_Audio.Create()</code>.
  44  */
  45 typedef void (*PPB_Audio_Callback)(void* sample_buffer,
  46                                    uint32_t buffer_size_in_bytes,
  47                                    PP_TimeDelta latency,
  48                                    void* user_data);
  49
  50 typedef void (*PPB_Audio_Callback_1_0)(void* sample_buffer,
  51                                        uint32_t buffer_size_in_bytes,
  52                                        void* user_data);
  53 /**
  54  * @}
  55  */
  56
  57 /**
  58  * @addtogroup Interfaces
  59  * @{
  60  */
  61 /**
  62  * The <code>PPB_Audio</code> interface contains pointers to several functions
  63  * for handling audio resources. Refer to the
  64  * <a href="/native-client/{{pepperversion}}/devguide/coding/audio">Audio</a>
  65  * chapter in the Developer's Guide for information on using this interface.
  66  * Please see descriptions for each <code>PPB_Audio</code> and
  67  * <code>PPB_AudioConfig</code> function for more details. A C example using
  68  * <code>PPB_Audio</code> and <code>PPB_AudioConfig</code> follows.
  69  *
  70  * <strong>Example: </strong>
  71  *
  72  * @code
  73  * void audio_callback(void* sample_buffer,
  74  *                     uint32_t buffer_size_in_bytes,
  75  *                     void* user_data) {
  76  *   ... quickly fill in the buffer with samples and return to caller ...
  77  *  }
  78  *
  79  * ...Assume the application has cached the audio configuration interface in
  80  * audio_config_interface and the audio interface in
  81  * audio_interface...
  82  *
  83  * uint32_t count = audio_config_interface->RecommendSampleFrameCount(
  84  *     PP_AUDIOSAMPLERATE_44100, 4096);
  85  * PP_Resource pp_audio_config = audio_config_interface->CreateStereo16Bit(
  86  *     pp_instance, PP_AUDIOSAMPLERATE_44100, count);
  87  * PP_Resource pp_audio = audio_interface->Create(pp_instance, pp_audio_config,
  88  *     audio_callback, NULL);
  89  * audio_interface->StartPlayback(pp_audio);
  90  *
  91  * ...audio_callback() will now be periodically invoked on a separate thread...
  92  * @endcode
  93  */
  94 struct PPB_Audio_1_1 {
  95   /**
  96    * Create() creates an audio resource. No sound will be heard until
  97    * StartPlayback() is called. The callback is called with the buffer address
  98    * and given user data whenever the buffer needs to be filled. From within the
  99    * callback, you should not call <code>PPB_Audio</code> functions. The
 100    * callback will be called on a different thread than the one which created
 101    * the interface. For performance-critical applications (i.e. low-latency
 102    * audio), the callback should avoid blocking or calling functions that can
 103    * obtain locks, such as malloc. The layout and the size of the buffer passed
 104    * to the audio callback will be determined by the device configuration and is
 105    * specified in the <code>AudioConfig</code> documentation.
 106    *
 107    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 108    * of a module.
 109    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 110    * config resource.
 111    * @param[in] audio_callback A <code>PPB_Audio_Callback</code> callback
 112    * function that the browser calls when it needs more samples to play.
 113    * @param[in] user_data A pointer to user data used in the callback function.
 114    *
 115    * @return A <code>PP_Resource</code> containing the audio resource if
 116    * successful or 0 if the configuration cannot be honored or the callback is
 117    * null.
 118    */
 119   PP_Resource (*Create)(PP_Instance instance,
 120                         PP_Resource config,
 121                         PPB_Audio_Callback audio_callback,
 122                         void* user_data);
 123   /**
 124    * IsAudio() determines if the provided resource is an audio resource.
 125    *
 126    * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
 127    * resource.
 128    *
 129    * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
 130    * if the given resource is an Audio resource, otherwise
 131    * <code>PP_FALSE</code>.
 132    */
 133   PP_Bool (*IsAudio)(PP_Resource resource);
 134   /**
 135    * GetCurrrentConfig() returns an audio config resource for the given audio
 136    * resource.
 137    *
 138    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 139    * resource.
 140    *
 141    * @return A <code>PP_Resource</code> containing the audio config resource if
 142    * successful.
 143    */
 144   PP_Resource (*GetCurrentConfig)(PP_Resource audio);
 145   /**
 146    * StartPlayback() starts the playback of the audio resource and begins
 147    * periodically calling the callback.
 148    *
 149    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 150    * resource.
 151    *
 152    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 153    * successful, otherwise <code>PP_FALSE</code>. Also returns
 154    * <code>PP_TRUE</code> (and be a no-op) if called while playback is already
 155    * in progress.
 156    */
 157   PP_Bool (*StartPlayback)(PP_Resource audio);
 158   /**
 159    * StopPlayback() stops the playback of the audio resource.
 160    *
 161    * @param[in] config A <code>PP_Resource</code> corresponding to an audio
 162    * resource.
 163    *
 164    * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if
 165    * successful, otherwise <code>PP_FALSE</code>. Also returns
 166    * <code>PP_TRUE</code> (and is a no-op) if called while playback is already
 167    * stopped. If a callback is in progress, StopPlayback() will block until the
 168    * callback completes.
 169    */
 170   PP_Bool (*StopPlayback)(PP_Resource audio);
 171 };
 172
 173 typedef struct PPB_Audio_1_1 PPB_Audio;
 174
 175 struct PPB_Audio_1_0 {
 176   PP_Resource (*Create)(PP_Instance instance,
 177                         PP_Resource config,
 178                         PPB_Audio_Callback_1_0 audio_callback,
 179                         void* user_data);
 180   PP_Bool (*IsAudio)(PP_Resource resource);
 181   PP_Resource (*GetCurrentConfig)(PP_Resource audio);
 182   PP_Bool (*StartPlayback)(PP_Resource audio);
 183   PP_Bool (*StopPlayback)(PP_Resource audio);
 184 };
 185 /**
 186  * @}
 187  */
 188
 189 #endif  /* PPAPI_C_PPB_AUDIO_H_ */
 190