sample.h File Reference

Constants and routines for sample type handling. More...

Go to the source code of this file.

Data Structures
struct	pa_sample_spec
	A sample format and attribute specification. More...
Defines
#define	PA_CHANNELS_MAX   32U
	Maximum number of allowed channels.
#define	PA_RATE_MAX   (48000U*4U)
	Maximum allowed sample rate.
#define	PA_SAMPLE_S16NE   PA_SAMPLE_S16LE
	Signed 16 Bit PCM, native endian.
#define	PA_SAMPLE_FLOAT32NE   PA_SAMPLE_FLOAT32LE
	32 Bit IEEE floating point, native endian
#define	PA_SAMPLE_S32NE   PA_SAMPLE_S32LE
	Signed 32 Bit PCM, native endian.
#define	PA_SAMPLE_S24NE   PA_SAMPLE_S24LE
	Signed 24 Bit PCM packed, native endian.
#define	PA_SAMPLE_S24_32NE   PA_SAMPLE_S24_32LE
	Signed 24 Bit PCM in LSB of 32 Bit words, native endian.
#define	PA_SAMPLE_S16RE   PA_SAMPLE_S16BE
	Signed 16 Bit PCM, reverse endian.
#define	PA_SAMPLE_FLOAT32RE   PA_SAMPLE_FLOAT32BE
	32 Bit IEEE floating point, reverse endian
#define	PA_SAMPLE_S32RE   PA_SAMPLE_S32BE
	Signed 32 Bit PCM, reverse endian.
#define	PA_SAMPLE_S24RE   PA_SAMPLE_S24BE
	Signed 24 Bit PCM, packed reverse endian.
#define	PA_SAMPLE_S24_32RE   PA_SAMPLE_S24_32BE
	Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian.
#define	PA_SAMPLE_FLOAT32   PA_SAMPLE_FLOAT32NE
	A Shortcut for PA_SAMPLE_FLOAT32NE.
#define	PA_SAMPLE_SPEC_SNPRINT_MAX   32
	Maximum required string length for pa_sample_spec_snprint().
#define	PA_BYTES_SNPRINT_MAX   11
	Maximum required string length for pa_bytes_snprint().
#define	pa_sample_format_is_ne(f)   pa_sample_format_is_le(f)
	Return 1 when the specified format is native endian, return -1 when endianess does not apply to this format.
#define	pa_sample_format_is_re(f)   pa_sample_format_is_be(f)
	Return 1 when the specified format is reverse endian, return -1 when endianess does not apply to this format.
Typedefs
typedef enum pa_sample_format	pa_sample_format_t
	Sample format.
typedef struct pa_sample_spec	pa_sample_spec
	A sample format and attribute specification.
typedef uint64_t	pa_usec_t
	Type for usec specifications (unsigned).
Enumerations
enum	pa_sample_format {   PA_SAMPLE_U8,   PA_SAMPLE_ALAW,   PA_SAMPLE_ULAW,   PA_SAMPLE_S16LE,   PA_SAMPLE_S16BE,   PA_SAMPLE_FLOAT32LE,   PA_SAMPLE_FLOAT32BE,   PA_SAMPLE_S32LE,   PA_SAMPLE_S32BE,   PA_SAMPLE_S24LE,   PA_SAMPLE_S24BE,   PA_SAMPLE_S24_32LE,   PA_SAMPLE_S24_32BE,   PA_SAMPLE_MAX,   PA_SAMPLE_INVALID = -1 }
	Sample format. More...
Functions
size_t	pa_bytes_per_second (const pa_sample_spec *spec) PA_GCC_PURE
	Return the amount of bytes playback of a second of audio with the specified sample type takes.
size_t	pa_frame_size (const pa_sample_spec *spec) PA_GCC_PURE
	Return the size of a frame with the specific sample type.
size_t	pa_sample_size (const pa_sample_spec *spec) PA_GCC_PURE
	Return the size of a sample with the specific sample type.
size_t	pa_sample_size_of_format (pa_sample_format_t f) PA_GCC_PURE
	Similar to pa_sample_size() but take a sample format instead of a full sample spec.
pa_usec_t	pa_bytes_to_usec (uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE
	Calculate the time the specified bytes take to play with the specified sample type.
size_t	pa_usec_to_bytes (pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE
	Calculates the number of bytes that are required for the specified time.
pa_sample_spec *	pa_sample_spec_init (pa_sample_spec *spec)
	Initialize the specified sample spec and return a pointer to it.
int	pa_sample_spec_valid (const pa_sample_spec *spec) PA_GCC_PURE
	Return non-zero when the sample type specification is valid.
int	pa_sample_spec_equal (const pa_sample_spec *a, const pa_sample_spec *b) PA_GCC_PURE
	Return non-zero when the two sample type specifications match.
const char *	pa_sample_format_to_string (pa_sample_format_t f) PA_GCC_PURE
	Return a descriptive string for the specified sample format.
pa_sample_format_t	pa_parse_sample_format (const char *format) PA_GCC_PURE
	Parse a sample format text.
char *	pa_sample_spec_snprint (char *s, size_t l, const pa_sample_spec *spec)
	Pretty print a sample type specification to a string.
char *	pa_bytes_snprint (char *s, size_t l, unsigned v)
	Pretty print a byte size value.
int	pa_sample_format_is_le (pa_sample_format_t f) PA_GCC_PURE
	Return 1 when the specified format is little endian, return -1 when endianess does not apply to this format.
int	pa_sample_format_is_be (pa_sample_format_t f) PA_GCC_PURE
	Return 1 when the specified format is big endian, return -1 when endianess does not apply to this format.

---

Detailed Description

Constants and routines for sample type handling.

See also Sample Format Specifications

---

Define Documentation

#define PA_BYTES_SNPRINT_MAX   11

Maximum required string length for pa_bytes_snprint().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Since:

0.9.16

#define PA_CHANNELS_MAX   32U

Maximum number of allowed channels.

#define PA_RATE_MAX   (48000U*4U)

Maximum allowed sample rate.

#define PA_SAMPLE_FLOAT32   PA_SAMPLE_FLOAT32NE

A Shortcut for PA_SAMPLE_FLOAT32NE.

#define PA_SAMPLE_FLOAT32NE   PA_SAMPLE_FLOAT32LE

32 Bit IEEE floating point, native endian

#define PA_SAMPLE_FLOAT32RE   PA_SAMPLE_FLOAT32BE

32 Bit IEEE floating point, reverse endian

#define pa_sample_format_is_ne

(

f )

pa_sample_format_is_le(f)

Return 1 when the specified format is native endian, return -1 when endianess does not apply to this format.

Since:

0.9.16

#define pa_sample_format_is_re

(

f )

pa_sample_format_is_be(f)

Return 1 when the specified format is reverse endian, return -1 when endianess does not apply to this format.

Since:

0.9.16

#define PA_SAMPLE_S16NE   PA_SAMPLE_S16LE

Signed 16 Bit PCM, native endian.

#define PA_SAMPLE_S16RE   PA_SAMPLE_S16BE

Signed 16 Bit PCM, reverse endian.

#define PA_SAMPLE_S24_32NE   PA_SAMPLE_S24_32LE

Signed 24 Bit PCM in LSB of 32 Bit words, native endian.

Since:

0.9.15

#define PA_SAMPLE_S24_32RE   PA_SAMPLE_S24_32BE

Signed 24 Bit PCM, in LSB of 32 Bit words, reverse endian.

Since:

0.9.15

#define PA_SAMPLE_S24NE   PA_SAMPLE_S24LE

Signed 24 Bit PCM packed, native endian.

Since:

0.9.15

#define PA_SAMPLE_S24RE   PA_SAMPLE_S24BE

Signed 24 Bit PCM, packed reverse endian.

Since:

0.9.15

#define PA_SAMPLE_S32NE   PA_SAMPLE_S32LE

Signed 32 Bit PCM, native endian.

#define PA_SAMPLE_S32RE   PA_SAMPLE_S32BE

Signed 32 Bit PCM, reverse endian.

#define PA_SAMPLE_SPEC_SNPRINT_MAX   32

Maximum required string length for pa_sample_spec_snprint().

Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

---

Typedef Documentation

typedef enum pa_sample_format pa_sample_format_t

Sample format.

typedef struct pa_sample_spec pa_sample_spec

A sample format and attribute specification.

typedef uint64_t pa_usec_t

Type for usec specifications (unsigned).

Always 64 bit.

---

Enumeration Type Documentation

enum pa_sample_format

Sample format.

Enumerator:

PA_SAMPLE_U8	Unsigned 8 Bit PCM.
PA_SAMPLE_ALAW	8 Bit a-Law
PA_SAMPLE_ULAW	8 Bit mu-Law
PA_SAMPLE_S16LE	Signed 16 Bit PCM, little endian (PC)
PA_SAMPLE_S16BE	Signed 16 Bit PCM, big endian.
PA_SAMPLE_FLOAT32LE	32 Bit IEEE floating point, little endian (PC), range -1.0 to 1.0
PA_SAMPLE_FLOAT32BE	32 Bit IEEE floating point, big endian, range -1.0 to 1.0
PA_SAMPLE_S32LE	Signed 32 Bit PCM, little endian (PC)
PA_SAMPLE_S32BE	Signed 32 Bit PCM, big endian.
PA_SAMPLE_S24LE	Signed 24 Bit PCM packed, little endian (PC). Since: 0.9.15
PA_SAMPLE_S24BE	Signed 24 Bit PCM packed, big endian. Since: 0.9.15
PA_SAMPLE_S24_32LE	Signed 24 Bit PCM in LSB of 32 Bit words, little endian (PC). Since: 0.9.15
PA_SAMPLE_S24_32BE	Signed 24 Bit PCM in LSB of 32 Bit words, big endian. Since: 0.9.15
PA_SAMPLE_MAX	Upper limit of valid sample types.
PA_SAMPLE_INVALID	An invalid value.

---

Function Documentation

size_t pa_bytes_per_second

(

const pa_sample_spec *

spec )

Return the amount of bytes playback of a second of audio with the specified sample type takes.

char* pa_bytes_snprint	(	char *	s,
		size_t	l,
		unsigned	v
	)

Pretty print a byte size value.

(i.e. "2.5 MiB")

pa_usec_t pa_bytes_to_usec	(	uint64_t	length,
		const pa_sample_spec *	spec
	)

Calculate the time the specified bytes take to play with the specified sample type.

The return value will always be rounded down for non-integral return values.

size_t pa_frame_size

(

const pa_sample_spec *

spec )

Return the size of a frame with the specific sample type.

pa_sample_format_t pa_parse_sample_format

(

const char *

format )

Parse a sample format text.

Inverse of pa_sample_format_to_string()

int pa_sample_format_is_be

(

pa_sample_format_t

f )

Return 1 when the specified format is big endian, return -1 when endianess does not apply to this format.

Since:

0.9.16

int pa_sample_format_is_le

(

pa_sample_format_t

f )

Return 1 when the specified format is little endian, return -1 when endianess does not apply to this format.

Since:

0.9.16

const char* pa_sample_format_to_string

(

pa_sample_format_t

f )

Return a descriptive string for the specified sample format.

Since:

0.8

size_t pa_sample_size

(

const pa_sample_spec *

spec )

Return the size of a sample with the specific sample type.

size_t pa_sample_size_of_format

(

pa_sample_format_t

f )

Similar to pa_sample_size() but take a sample format instead of a full sample spec.

Since:

0.9.15

int pa_sample_spec_equal	(	const pa_sample_spec *	a,
		const pa_sample_spec *	b
	)

Return non-zero when the two sample type specifications match.

pa_sample_spec* pa_sample_spec_init

(

pa_sample_spec *

spec )

Initialize the specified sample spec and return a pointer to it.

The sample spec will have a defined state but pa_sample_spec_valid() will fail for it.

Since:

0.9.13

char* pa_sample_spec_snprint	(	char *	s,
		size_t	l,
		const pa_sample_spec *	spec
	)

Pretty print a sample type specification to a string.

int pa_sample_spec_valid

(

const pa_sample_spec *

spec )

Return non-zero when the sample type specification is valid.

size_t pa_usec_to_bytes	(	pa_usec_t	t,
		const pa_sample_spec *	spec
	)

Calculates the number of bytes that are required for the specified time.

The return value will always be rounded down for non-integral return values.

Since:

0.9