Pepper_31_C++_interfaces
audio_config.h
Go to the documentation of this file.
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/{{pepperversion}}/devguide/coding/audio">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 
static uint32_t RecommendSampleFrameCount(const InstanceHandle &instance, PP_AudioSampleRate sample_rate, uint32_t requested_sample_frame_count)
PP_AudioSampleRate sample_rate() const
Definition: audio_config.h:117
static PP_AudioSampleRate RecommendSampleRate(const InstanceHandle &instance)
uint32_t sample_frame_count() const
Definition: audio_config.h:122
AudioConfig()
An empty constructor for an AudioConfig resource.
A reference counted module resource.
Definition: resource.h:18