ppapi/cpp/audio_config.h

// 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.

#ifndef PPAPI_CPP_AUDIO_CONFIG_H_
#define PPAPI_CPP_AUDIO_CONFIG_H_

#include "ppapi/c/ppb_audio_config.h"
#include "ppapi/c/pp_stdint.h"
#include "ppapi/cpp/resource.h"

/// @file
/// This file defines the interface for establishing an
/// audio configuration resource within the browser.

namespace pp {

class InstanceHandle;

/// A 16 bit stereo AudioConfig resource. Refer to the
/// <a href="/native-client/devguide/coding/audio.html">Audio
/// </a>chapter in the Developer's Guide for information on using this
/// interface.
///
/// 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.
/// <code>...</code>
/// <code>buffer16[2 * (sample_frame_count - 1)]</code> is the last left
/// channel sample.
/// <code>buffer16[2 * (sample_frame_count - 1) + 1]</code> is the last right
/// channel sample.
/// Data will always be in the native endian format of the platform.
///
/// <strong>Example:</strong>
/// @code
///
/// // Create an audio config with a supported frame count.
/// uint32_t sample_frame_count = AudioConfig::RecommendSampleFrameCount(
///    PP_AUDIOSAMPLERATE_44100, 4096);
///  AudioConfig config(PP_AUDIOSAMPLERATE_44100, sample_frame_count);
///  if (config.is_null())
///    return false;  // Couldn't configure audio.
///
///   // Then use the config to create your audio resource.
///  Audio audio(instance, config, callback, user_data);
///   if (audio.is_null())
///     return false;  // Couldn't create audio.
/// @endcode
class AudioConfig : public Resource {
 public:
  /// An empty constructor for an <code>AudioConfig</code> resource.
  AudioConfig();

  /// A constructor that creates an audio config based on the given sample rate
  /// and frame count. If the rate and frame count aren't supported, the
  /// resulting resource will be is_null(). You can pass the result of
  /// RecommendSampleFrameCount() as the sample frame count.
  ///
  /// @param[in] instance The instance associated with this resource.
  ///
  /// @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] sample_frame_count A uint32_t frame count returned from the
  /// <code>RecommendSampleFrameCount</code> function.
  AudioConfig(const InstanceHandle& instance,
              PP_AudioSampleRate sample_rate,
              uint32_t sample_frame_count);

  /// RecommendSampleRate() returns the native sample rate used by the
  /// audio system.  Applications that use the recommended sample rate might
  /// obtain lower latency and higher fidelity output.
  ///
  /// @param[in] instance The instance associated with this resource.
  static PP_AudioSampleRate RecommendSampleRate(
      const InstanceHandle& instance);

  /// RecommendSampleFrameCount() returns a supported frame count closest to
  /// the requested count. The sample frame count determines the overall
  /// latency of audio. 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 for use in
  /// the constructor.
  ///
  /// @param[in] instance The instance associated with this resource.
  /// @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 uint32_t requested frame count.
  ///
  /// @return A uint32_t containing the recommended sample frame count if
  /// successful. If the sample frame count or bit rate is not supported,
  /// this function will fail and return 0.
  static uint32_t RecommendSampleFrameCount(
      const InstanceHandle& instance,
      PP_AudioSampleRate sample_rate,
      uint32_t requested_sample_frame_count);

  /// Getter function for returning the internal
  /// <code>PP_AudioSampleRate</code> enum.
  ///
  /// @return The <code>PP_AudioSampleRate</code> enum.
  PP_AudioSampleRate sample_rate() const { return sample_rate_; }

  /// Getter function for returning the internal sample frame count.
  ///
  /// @return A uint32_t containing the sample frame count.
  uint32_t sample_frame_count() const { return sample_frame_count_; }

 private:
  PP_AudioSampleRate sample_rate_;
  uint32_t sample_frame_count_;
};

}  // namespace pp

#endif  // PPAPI_CPP_AUDIO_CONFIG_H_