You need to sign in or sign up before continuing.
AudioFormat.hxx 5.69 KB
Newer Older
1
/*
Max Kellermann's avatar
Max Kellermann committed
2
 * Copyright 2003-2017 The Music Player Daemon Project
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
 * http://www.musicpd.org
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef MPD_AUDIO_FORMAT_HXX
#define MPD_AUDIO_FORMAT_HXX

23
#include "pcm/SampleFormat.hxx"
24
#include "Compiler.h"
25 26

#include <assert.h>
27 28 29 30
#include <stdint.h>
#include <stddef.h>

template<size_t CAPACITY> class StringBuffer;
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

static constexpr unsigned MAX_CHANNELS = 8;

/**
 * This structure describes the format of a raw PCM stream.
 */
struct AudioFormat {
	/**
	 * The sample rate in Hz.  A better name for this attribute is
	 * "frame rate", because technically, you have two samples per
	 * frame in stereo sound.
	 */
	uint32_t sample_rate;

	/**
	 * The format samples are stored in.  See the #sample_format
	 * enum for valid values.
	 */
	SampleFormat format;

	/**
52 53 54 55 56 57 58 59 60 61 62 63 64
	 * The number of channels.
	 *
	 * Channel order follows the FLAC convention
	 * (https://xiph.org/flac/format.html):
	 *
	 * - 1 channel: mono
	 * - 2 channels: left, right
	 * - 3 channels: left, right, center
	 * - 4 channels: front left, front right, back left, back right
	 * - 5 channels: front left, front right, front center, back/surround left, back/surround right
	 * - 6 channels: front left, front right, front center, LFE, back/surround left, back/surround right
	 * - 7 channels: front left, front right, front center, LFE, back center, side left, side right
	 * - 8 channels: front left, front right, front center, LFE, back left, back right, side left, side right
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
	 */
	uint8_t channels;

	AudioFormat() = default;

	constexpr AudioFormat(uint32_t _sample_rate,
			      SampleFormat _format, uint8_t _channels)
		:sample_rate(_sample_rate),
		 format(_format), channels(_channels) {}

	static constexpr AudioFormat Undefined() {
		return AudioFormat(0, SampleFormat::UNDEFINED,0);
	}

	/**
Max Kellermann's avatar
Max Kellermann committed
80 81
	 * Clears the object, i.e. sets all attributes to an undefined
	 * (invalid) value.
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
	 */
	void Clear() {
		sample_rate = 0;
		format = SampleFormat::UNDEFINED;
		channels = 0;
	}

	/**
	 * Checks whether the object has a defined value.
	 */
	constexpr bool IsDefined() const {
		return sample_rate != 0;
	}

	/**
	 * Checks whether the object is full, i.e. all attributes are
	 * defined.  This is more complete than IsDefined(), but
	 * slower.
	 */
	constexpr bool IsFullyDefined() const {
		return sample_rate != 0 && format != SampleFormat::UNDEFINED &&
			channels != 0;
	}

	/**
	 * Checks whether the object has at least one defined value.
	 */
	constexpr bool IsMaskDefined() const {
		return sample_rate != 0 || format != SampleFormat::UNDEFINED ||
			channels != 0;
	}

	bool IsValid() const;
	bool IsMaskValid() const;

	constexpr bool operator==(const AudioFormat other) const {
		return sample_rate == other.sample_rate &&
			format == other.format &&
			channels == other.channels;
	}

	constexpr bool operator!=(const AudioFormat other) const {
		return !(*this == other);
	}

127
	void ApplyMask(AudioFormat mask) noexcept;
128

129
	gcc_pure
130
	AudioFormat WithMask(AudioFormat mask) const noexcept {
131 132 133 134 135
		AudioFormat result = *this;
		result.ApplyMask(mask);
		return result;
	}

136 137 138 139 140
	gcc_pure
	bool MatchMask(AudioFormat mask) const noexcept {
		return WithMask(mask) == *this;
	}

141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
	/**
	 * Returns the size of each (mono) sample in bytes.
	 */
	unsigned GetSampleSize() const;

	/**
	 * Returns the size of each full frame in bytes.
	 */
	unsigned GetFrameSize() const;

	/**
	 * Returns the floating point factor which converts a time
	 * span to a storage size in bytes.
	 */
	double GetTimeToSize() const;
};

/**
 * Checks whether the sample rate is valid.
 *
 * @param sample_rate the sample rate in Hz
 */
static constexpr inline bool
audio_valid_sample_rate(unsigned sample_rate)
{
	return sample_rate > 0 && sample_rate < (1 << 30);
}

/**
 * Checks whether the number of channels is valid.
 */
static constexpr inline bool
audio_valid_channel_count(unsigned channels)
{
	return channels >= 1 && channels <= MAX_CHANNELS;
}

/**
 * Returns false if the format is not valid for playback with MPD.
 * This function performs some basic validity checks.
 */
inline bool
AudioFormat::IsValid() const
{
	return audio_valid_sample_rate(sample_rate) &&
		audio_valid_sample_format(format) &&
		audio_valid_channel_count(channels);
}

/**
 * Returns false if the format mask is not valid for playback with
 * MPD.  This function performs some basic validity checks.
 */
inline bool
AudioFormat::IsMaskValid() const
{
	return (sample_rate == 0 ||
		audio_valid_sample_rate(sample_rate)) &&
		(format == SampleFormat::UNDEFINED ||
		 audio_valid_sample_format(format)) &&
		(channels == 0 || audio_valid_channel_count(channels));
}

inline unsigned
AudioFormat::GetSampleSize() const
{
	return sample_format_size(format);
}

inline unsigned
AudioFormat::GetFrameSize() const
{
	return GetSampleSize() * channels;
}

inline double
AudioFormat::GetTimeToSize() const
{
	return sample_rate * GetFrameSize();
}

/**
Max Kellermann's avatar
Max Kellermann committed
223
 * Renders the #AudioFormat object into a string, e.g. for printing
224 225
 * it in a log file.
 *
Max Kellermann's avatar
Max Kellermann committed
226
 * @param af the #AudioFormat object
227
 * @return the string buffer
228
 */
229 230
gcc_const
StringBuffer<24>
231
ToString(AudioFormat af) noexcept;
232 233

#endif