ppapi/cpp/audio_config.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 #ifndef PPAPI_CPP_AUDIO_CONFIG_H_
   6 #define PPAPI_CPP_AUDIO_CONFIG_H_
   7
   8 #include "ppapi/c/ppb_audio_config.h"
   9 #include "ppapi/c/pp_stdint.h"
  10 #include "ppapi/cpp/resource.h"
  11
  12 /// @file
  13 /// This file defines the interface for establishing an
  14 /// audio configuration resource within the browser.
  15
  16 namespace pp {
  17
  18 class InstanceHandle;
  19
  20 /// A 16 bit stereo AudioConfig resource. Refer to the
  21 /// <a href="/native-client/devguide/coding/audio.html">Audio
  22 /// </a>chapter in the Developer's Guide for information on using this
  23 /// interface.
  24 ///
  25 /// A single sample frame on a stereo device means one value for the left
  26 /// channel and one value for the right channel.
  27 ///
  28 /// Buffer layout for a stereo int16 configuration:
  29 ///
  30 /// <code>int16_t *buffer16;</code>
  31 /// <code>buffer16[0]</code> is the first left channel sample.
  32 /// <code>buffer16[1]</code> is the first right channel sample.
  33 /// <code>buffer16[2]</code> is the second left channel sample.
  34 /// <code>buffer16[3]</code> is the second right channel sample.
  35 /// <code>...</code>
  36 /// <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left
  37 /// channel sample.
  38 /// <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last right
  39 /// channel sample.
  40 /// Data will always be in the native endian format of the platform.
  41 ///
  42 /// <strong>Example:</strong>
  43 /// @code
  44 ///
  45 /// // Create an audio config with a supported frame count.
  46 /// uint32_t sample_frame_count = AudioConfig::RecommendSampleFrameCount(
  47 ///    PP_AUDIOSAMPLERATE_44100, 4096);
  48 ///  AudioConfig config(PP_AUDIOSAMPLERATE_44100, sample_frame_count);
  49 ///  if (config.is_null())
  50 ///    return false;  // Couldn't configure audio.
  51 ///
  52 ///   // Then use the config to create your audio resource.
  53 ///  Audio audio(instance, config, callback, user_data);
  54 ///   if (audio.is_null())
  55 ///     return false;  // Couldn't create audio.
  56 /// @endcode
  57 class AudioConfig : public Resource {
  58  public:
  59   /// An empty constructor for an <code>AudioConfig</code> resource.
  60   AudioConfig();
  61
  62   /// A constructor that creates an audio config based on the given sample rate
  63   /// and frame count. If the rate and frame count aren't supported, the
  64   /// resulting resource will be is_null(). You can pass the result of
  65   /// RecommendSampleFrameCount() as the sample frame count.
  66   ///
  67   /// @param[in] instance The instance associated with this resource.
  68   ///
  69   /// @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
  70   /// <code>PP_AUDIOSAMPLERATE_44100</code> or
  71   /// <code>PP_AUDIOSAMPLERATE_48000</code>.
  72   ///
  73   /// @param[in] sample_frame_count A uint32_t frame count returned from the
  74   /// <code>RecommendSampleFrameCount</code> function.
  75   AudioConfig(const InstanceHandle& instance,
  76               PP_AudioSampleRate sample_rate,
  77               uint32_t sample_frame_count);
  78
  79   /// RecommendSampleRate() returns the native sample rate used by the
  80   /// audio system.  Applications that use the recommended sample rate might
  81   /// obtain lower latency and higher fidelity output.
  82   ///
  83   /// @param[in] instance The instance associated with this resource.
  84   static PP_AudioSampleRate RecommendSampleRate(
  85       const InstanceHandle& instance);
  86
  87   /// RecommendSampleFrameCount() returns a supported frame count closest to
  88   /// the requested count. The sample frame count determines the overall
  89   /// latency of audio. Smaller frame counts will yield lower latency, but
  90   /// higher CPU utilization. Supported sample frame counts will vary by
  91   /// hardware and system (consider that the local system might be anywhere
  92   /// from a cell phone or a high-end audio workstation). Sample counts less
  93   /// than <code>PP_AUDIOMINSAMPLEFRAMECOUNT</code> and greater than
  94   /// <code>PP_AUDIOMAXSAMPLEFRAMECOUNT</code> are never supported on any
  95   /// system, but values in between aren't necessarily valid. This function
  96   /// will return a supported count closest to the requested value for use in
  97   /// the constructor.
  98   ///
  99   /// @param[in] instance The instance associated with this resource.
 100   /// @param[in] sample_rate A <code>PP_AudioSampleRate</code> which is either
 101   /// <code>PP_AUDIOSAMPLERATE_44100</code> or
 102   /// <code>PP_AUDIOSAMPLERATE_48000</code>.
 103   /// @param[in] requested_sample_frame_count A uint32_t requested frame count.
 104   ///
 105   /// @return A uint32_t containing the recommended sample frame count if
 106   /// successful. If the sample frame count or bit rate is not supported,
 107   /// this function will fail and return 0.
 108   static uint32_t RecommendSampleFrameCount(
 109       const InstanceHandle& instance,
 110       PP_AudioSampleRate sample_rate,
 111       uint32_t requested_sample_frame_count);
 112
 113   /// Getter function for returning the internal
 114   /// <code>PP_AudioSampleRate</code> enum.
 115   ///
 116   /// @return The <code>PP_AudioSampleRate</code> enum.
 117   PP_AudioSampleRate sample_rate() const { return sample_rate_; }
 118
 119   /// Getter function for returning the internal sample frame count.
 120   ///
 121   /// @return A uint32_t containing the sample frame count.
 122   uint32_t sample_frame_count() const { return sample_frame_count_; }
 123
 124  private:
 125   PP_AudioSampleRate sample_rate_;
 126   uint32_t sample_frame_count_;
 127 };
 128
 129 }  // namespace pp
 130
 131 #endif  // PPAPI_CPP_AUDIO_CONFIG_H_
 132