## 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.