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 133
