sample

sample — Audio sample format conversion functions and defines.

Stability Level

Stable, unless otherwise indicated

Synopsis

#define             IPATCH_SAMPLE_MAX_TRANSFORM_FUNCS
#define             IPATCH_SAMPLE_FORMAT_MASK
#define             IPATCH_SAMPLE_FORMAT_BITCOUNT
#define             IPATCH_SAMPLE_WIDTH_MASK
#define             IPATCH_SAMPLE_CHANNEL_MASK
#define             IPATCH_SAMPLE_SIGN_MASK
#define             IPATCH_SAMPLE_ENDIAN_MASK
#define             IPATCH_SAMPLE_WIDTH_SHIFT
#define             IPATCH_SAMPLE_CHANNEL_SHIFT
#define             IPATCH_SAMPLE_SIGN_SHIFT
#define             IPATCH_SAMPLE_ENDIAN_SHIFT
enum                IpatchSampleWidth;
enum                IpatchSampleChannel;
enum                IpatchSampleChannelType;
#define             IPATCH_SAMPLE_MAX_CHANNELS
enum                IpatchSampleSign;
enum                IpatchSampleEndian;
#define             IPATCH_SAMPLE_ENDIAN_HOST
#define             IPATCH_SAMPLE_FORMAT_GET_WIDTH      (format)
#define             IPATCH_SAMPLE_FORMAT_GET_CHANNELS   (format)
#define             IPATCH_SAMPLE_FORMAT_GET_CHANNEL_COUNT(format)
#define             IPATCH_SAMPLE_FORMAT_IS_SIGNED      (format)
#define             IPATCH_SAMPLE_FORMAT_IS_UNSIGNED    (format)
#define             IPATCH_SAMPLE_FORMAT_IS_LENDIAN     (format)
#define             IPATCH_SAMPLE_FORMAT_IS_BENDIAN     (format)
#define             ipatch_sample_format_size           (format)
#define             ipatch_sample_format_width          (format)
#define             IPATCH_SAMPLE_MAP_CHANNEL           (dest,
                                                         src)
#define             IPATCH_SAMPLE_MAP_GET_CHANNEL       (map,
                                                         dest)
#define             IPATCH_SAMPLE_UNITY_CHANNEL_MAP
int                 ipatch_sample_format_bit_width      (int format);
gboolean            ipatch_sample_format_verify         (int format);
gboolean            ipatch_sample_format_transform_verify
                                                        (int src_format,
                                                         int dest_format,
                                                         guint32 channel_map);
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);

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.

Details

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

typedef enum
{
  IPATCH_SAMPLE_INVALID = 0,
  IPATCH_SAMPLE_8BIT  = 1,
  IPATCH_SAMPLE_16BIT = 2,
  IPATCH_SAMPLE_24BIT = 3,
  IPATCH_SAMPLE_32BIT = 4,
  IPATCH_SAMPLE_FLOAT = 5,
  IPATCH_SAMPLE_DOUBLE = 6,
  IPATCH_SAMPLE_REAL24BIT = 7
} IpatchSampleWidth;

Sample data widths/formats.

IPATCH_SAMPLE_INVALID

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

IPATCH_SAMPLE_8BIT

8 bit integer PCM

IPATCH_SAMPLE_16BIT

16 bit integer PCM

IPATCH_SAMPLE_24BIT

24 bit integer PCM (32 bit ints)

IPATCH_SAMPLE_32BIT

32 bit integer PCM

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)

enum IpatchSampleChannel

typedef enum
{
  IPATCH_SAMPLE_MONO    = 0 << IPATCH_SAMPLE_CHANNEL_SHIFT,
  IPATCH_SAMPLE_STEREO  = 1 << IPATCH_SAMPLE_CHANNEL_SHIFT
} 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().

IPATCH_SAMPLE_MONO

Mono audio

IPATCH_SAMPLE_STEREO

Stereo audio

enum IpatchSampleChannelType

typedef enum
{
  IPATCH_SAMPLE_LEFT =  0,
  IPATCH_SAMPLE_RIGHT = 1
} 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.

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

typedef enum
{
  IPATCH_SAMPLE_SIGNED   = 0 << IPATCH_SAMPLE_SIGN_SHIFT,
  IPATCH_SAMPLE_UNSIGNED = 1 << IPATCH_SAMPLE_SIGN_SHIFT
} IpatchSampleSign;

Defines the sign of PCM integer audio data.

IPATCH_SAMPLE_SIGNED

Signed PCM audio data.

IPATCH_SAMPLE_UNSIGNED

Unsigned PCM audio data.

enum IpatchSampleEndian

typedef enum
{
  IPATCH_SAMPLE_LENDIAN = 0 << IPATCH_SAMPLE_ENDIAN_SHIFT,
  IPATCH_SAMPLE_BENDIAN = 1 << IPATCH_SAMPLE_ENDIAN_SHIFT
} IpatchSampleEndian;

Defines the byte order of multi-byte audio data.

IPATCH_SAMPLE_LENDIAN

Little endian byte order

IPATCH_SAMPLE_BENDIAN

Big endian byte order

IPATCH_SAMPLE_ENDIAN_HOST

#define             IPATCH_SAMPLE_ENDIAN_HOST

Host byte order value (IPATCH_SAMPLE_LENDIAN or IPATCH_SAMPLE_BENDIAN).


IPATCH_SAMPLE_FORMAT_GET_WIDTH()

#define             IPATCH_SAMPLE_FORMAT_GET_WIDTH(format)

Get IpatchSampleWidth enum from a sample format integer.

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.

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.

format :

Sample format integer

Returns :

Channel count (starting at 1 for mono).

IPATCH_SAMPLE_FORMAT_IS_SIGNED()

#define             IPATCH_SAMPLE_FORMAT_IS_SIGNED(format)

Check if a sample format integer defines signed audio.

format :

Sample format integer

Returns :

TRUE if sample format is signed.

IPATCH_SAMPLE_FORMAT_IS_UNSIGNED()

#define             IPATCH_SAMPLE_FORMAT_IS_UNSIGNED(format)

Check if a sample format integer defines unsigned audio.

format :

Sample format integer

Returns :

TRUE if sample format is unsigned.

IPATCH_SAMPLE_FORMAT_IS_LENDIAN()

#define             IPATCH_SAMPLE_FORMAT_IS_LENDIAN(format)

Check if a sample format integer defines little endian audio.

format :

Sample format integer

Returns :

TRUE if sample format is little endian.

IPATCH_SAMPLE_FORMAT_IS_BENDIAN()

#define             IPATCH_SAMPLE_FORMAT_IS_BENDIAN(format)

Check if a sample format integer defines big endian audio.

format :

Sample format integer

Returns :

TRUE if sample format is big endian.

ipatch_sample_format_size()

#define             ipatch_sample_format_size(format)

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

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.

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.

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.

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_UNITY_CHANNEL_MAP

#define IPATCH_SAMPLE_UNITY_CHANNEL_MAP   0xFAC688

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


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.

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.

format :

Sample format (IpatchSampleWidth | IpatchSampleSign | IpatchSampleEndian | IpatchSampleChannel).

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.

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.

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

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.