sample

sample — Audio sample format conversion functions and defines.

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Description

This module provides functions for converting audio formats as well as a system for defining audio formats with a single integer composed of multiple fields for sample width, channel count, sign and endian byte order.

Functions

IPATCH_SAMPLE_FORMAT_GET_WIDTH()

#define             IPATCH_SAMPLE_FORMAT_GET_WIDTH(format)

Get IpatchSampleWidth enum from a sample format integer.

Parameters

format

Sample format integer

 

Returns

Format field of sample format integer.


IPATCH_SAMPLE_FORMAT_GET_CHANNELS()

#define             IPATCH_SAMPLE_FORMAT_GET_CHANNELS(format)

Get the channel field from a sample format integer.

Parameters

format

Sample format integer

 

Returns

Channel field value (see IpatchSampleChannel)


IPATCH_SAMPLE_FORMAT_GET_CHANNEL_COUNT()

#define             IPATCH_SAMPLE_FORMAT_GET_CHANNEL_COUNT(format)

Get the channel count from a sample format integer.

Parameters

format

Sample format integer

 

Returns

Channel count (starting at 1 for mono).


ipatch_sample_format_size()

#define             ipatch_sample_format_size(format)

Get frame byte size for a given sample format (sample byte size * channels).

Parameters

format

Sample format integer

 

Returns

Size in bytes of a single sample frame.


ipatch_sample_format_width()

#define             ipatch_sample_format_width(format)

Gets the number of bytes used for storing a single sample for format . Doesn't take into account channels. This is the number of bytes used to store the samples, not the effective bit width. For example: IPATCH_SAMPLE_24BIT uses 4 bytes for each sample.

Parameters

format

Sample format

 

Returns

Byte width of a single sample (not including channels).


IPATCH_SAMPLE_MAP_CHANNEL()

#define IPATCH_SAMPLE_MAP_CHANNEL(dest, src)   ((src) << (3 * (dest)))

Macro to calculate a channel mapping value for a given destination and source. A channel mapping is composed of up to 24 bits (3 bits * 8 channels = 24). Channel mappings are used for sample conversions to route channels from a source format to a destination format. Multiple channel map values should be OR'd together.

Parameters

dest

Destination channel in mapping bit field (0-7)

 

src

Source channel (0-7)

 

IPATCH_SAMPLE_MAP_GET_CHANNEL()

#define IPATCH_SAMPLE_MAP_GET_CHANNEL(map, dest)   (((map) >> ((dest) * 3)) & 0x07)

Macro to get a source channel value given a destination channel.

Parameters

map

Channel map value (guint32 - only 24 bits are used)

 

dest

Destination channel in map bit field (0-7)

 

Returns

Source channel for dest (0-7)


ipatch_sample_format_bit_width ()

int
ipatch_sample_format_bit_width (int format);

Like ipatch_sample_format_width() but gets the effective bit width of the format. Of note is this is not always equivelant to the format width * 8. For example: IPATCH_SAMPLE_FLOAT has an effective bit width of 23, IPATCH_SAMPLE_24BIT has an effective bit width of 24 but is stored in 32 bits. This function is really only useful for comparing the relative "quality" of formats, and the actual returned values may change in the future.

Parameters

format

Sample format

 

Returns

Effective bit width of format.


ipatch_sample_format_verify ()

gboolean
ipatch_sample_format_verify (int format);

Verify a sample format integer.

Parameters

Returns

TRUE if valid, FALSE otherwise


ipatch_sample_format_transform_verify ()

gboolean
ipatch_sample_format_transform_verify (int src_format,
                                       int dest_format,
                                       guint32 channel_map);

Verify source and destination sample formats and channel map for a sample transform operation.

Parameters

src_format

Source sample format

 

dest_format

Destination sample format

 

channel_map

Channel mapping (use IPATCH_SAMPLE_UNITY_CHANNEL_MAP to map all input channels to the same output channels, see IPATCH_SAMPLE_MAP_CHANNEL macro for constructing channel map values)

 

Returns

TRUE on success, FALSE otherwise


ipatch_sample_get_transform_funcs ()

guint
ipatch_sample_get_transform_funcs (int src_format,
                                   int dest_format,
                                   guint32 channel_map,
                                   guint *buf1_max_frame,
                                   guint *buf2_max_frame,
                                   IpatchSampleTransformFunc *funcs);

Get transform function array for converting from src_format to dest_format .

[skip]

Parameters

src_format

Source audio format to convert from

 

dest_format

Destination audio format to convert to

 

channel_map

Channel mapping (use IPATCH_SAMPLE_UNITY_CHANNEL_MAP to map all input channels to the same output channels, 3 bits times IPATCH_SAMPLE_MAX_CHANNELS (8) = 24 bits total, see IPATCH_SAMPLE_MAP_CHANNEL macro for constructing channel map values)

 

buf1_max_frame

Output - maximum sample frame size for first buffer

 

buf2_max_frame

Output - maximum sample frame size for second buffer

 

funcs

Caller provided array to store transform functions to. It should have at least IPATCH_SAMPLE_MAX_TRANSFORM_FUNCS elements.

 

Returns

Count of function pointers stored to funcs . Can be 0 if no transform is required.

Types and Values

IPATCH_SAMPLE_MAX_TRANSFORM_FUNCS

#define IPATCH_SAMPLE_MAX_TRANSFORM_FUNCS 16

Maximum number of transform functions returned by ipatch_sample_get_transform_funcs(). Is larger than current actual maximum to allow for future backwards compatible expansion (8 is the real current maximum).


IPATCH_SAMPLE_FORMAT_MASK

#define IPATCH_SAMPLE_FORMAT_MASK   0x1FF

Mask for all fields of sample format integers (width, sign, endian, channel).


IPATCH_SAMPLE_FORMAT_BITCOUNT

#define IPATCH_SAMPLE_FORMAT_BITCOUNT  9

Number of bits used for sample format integers.


IPATCH_SAMPLE_WIDTH_MASK

#define IPATCH_SAMPLE_WIDTH_MASK    0x00F  /* total of 16 formats (8 reserved) */

IPATCH_SAMPLE_CHANNEL_MASK

#define IPATCH_SAMPLE_CHANNEL_MASK  0x070  /* channel count (8 channels max) */

IPATCH_SAMPLE_SIGN_MASK

#define IPATCH_SAMPLE_SIGN_MASK     0x080  /* sign or unsigned (for PCM formats) */

IPATCH_SAMPLE_ENDIAN_MASK

#define IPATCH_SAMPLE_ENDIAN_MASK   0x100  /* endian byte order */

IPATCH_SAMPLE_WIDTH_SHIFT

#define IPATCH_SAMPLE_WIDTH_SHIFT   0

IPATCH_SAMPLE_CHANNEL_SHIFT

#define IPATCH_SAMPLE_CHANNEL_SHIFT 4

IPATCH_SAMPLE_SIGN_SHIFT

#define IPATCH_SAMPLE_SIGN_SHIFT    7

IPATCH_SAMPLE_ENDIAN_SHIFT

#define IPATCH_SAMPLE_ENDIAN_SHIFT  8

enum IpatchSampleWidth

Sample data widths/formats.

Members

IPATCH_SAMPLE_INVALID

Invalid format (so 0 can be used to indicate a NULL state)

 

IPATCH_SAMPLE_BIT8

   

IPATCH_SAMPLE_BIT16

   

IPATCH_SAMPLE_BIT24

   

IPATCH_SAMPLE_BIT32

   

IPATCH_SAMPLE_FLOAT

32 bit IEEE float (-1.0 - 1.0)

 

IPATCH_SAMPLE_DOUBLE

64 bit IEEE double (-1.0 - 1.0)

 

IPATCH_SAMPLE_REAL24BIT

Real 3 byte 24 bit data (not padded to 32 bits)

 

IPATCH_SAMPLE_8BIT

#define IPATCH_SAMPLE_8BIT      IPATCH_SAMPLE_BIT8

IPATCH_SAMPLE_16BIT

#define IPATCH_SAMPLE_16BIT     IPATCH_SAMPLE_BIT16

IPATCH_SAMPLE_24BIT

#define IPATCH_SAMPLE_24BIT     IPATCH_SAMPLE_BIT24

IPATCH_SAMPLE_32BIT

#define IPATCH_SAMPLE_32BIT     IPATCH_SAMPLE_BIT32

enum IpatchSampleChannel

Descriptive enums for common audio channel configurations. These values are actually channel count - 1 (0 = mono, 1 = stereo, etc) and can be compared with the macro IPATCH_SAMPLE_FORMAT_GET_CHANNELS().

Members

IPATCH_SAMPLE_MONO

Mono audio

 

IPATCH_SAMPLE_STEREO

Stereo audio

 

enum IpatchSampleChannelType

Channel designation. Currently there are only 2 designated channels, though the remaining 6 supported channels may be defined to be surround sound channels in the future.

Members

IPATCH_SAMPLE_LEFT

Left channel comes first

 

IPATCH_SAMPLE_RIGHT

Right channel comes second

 

IPATCH_SAMPLE_MAX_CHANNELS

#define IPATCH_SAMPLE_MAX_CHANNELS      8

Maximum number of audio channels handled by libInstPatch.


enum IpatchSampleSign

Defines the sign of PCM integer audio data.

Members

IPATCH_SAMPLE_SIGNED

Signed PCM audio data.

 

IPATCH_SAMPLE_UNSIGNED

Unsigned PCM audio data.

 

enum IpatchSampleEndian

Defines the byte order of multi-byte audio data.

Members

IPATCH_SAMPLE_LENDIAN

Little endian byte order

 

IPATCH_SAMPLE_BENDIAN

Big endian byte order

 

IPATCH_SAMPLE_ENDIAN_HOST

#define IPATCH_SAMPLE_ENDIAN_HOST IPATCH_SAMPLE_LENDIAN

Host byte order value (IPATCH_SAMPLE_LENDIAN or IPATCH_SAMPLE_BENDIAN).


IPATCH_SAMPLE_UNITY_CHANNEL_MAP

#define IPATCH_SAMPLE_UNITY_CHANNEL_MAP   0xFAC688

Unity channel mapping which routes each input channel to the same output channel.