Sample format

Sample format — Sample format enums and functions

Synopsis




enum                IpatchSampleWidth;
enum                IpatchSampleSign;
enum                IpatchSampleEndian;
enum                IpatchSampleChannel;
enum                IpatchSampleChannelRoute;
#define             IPATCH_SAMPLE_ENDIAN_HOST
#define             IPATCH_SAMPLE_WIDTH_MASK
#define             IPATCH_SAMPLE_SIGN_MASK
#define             IPATCH_SAMPLE_ENDIAN_MASK
#define             IPATCH_SAMPLE_CHANNEL_MASK
#define             IPATCH_SAMPLE_ROUTE_MASK
#define             IPATCH_SAMPLE_WIDTH_SHIFT
#define             IPATCH_SAMPLE_SIGN_SHIFT
#define             IPATCH_SAMPLE_ENDIAN_SHIFT
#define             IPATCH_SAMPLE_CHANNEL_SHIFT
#define             IPATCH_SAMPLE_ROUTE_SHIFT
#define             IPATCH_SAMPLE_FORMAT_MASK
#define             IPATCH_SAMPLE_FORMAT_BITCOUNT
#define             IPATCH_SAMPLE_FORMAT_GET_WIDTH      (format)
#define             IPATCH_SAMPLE_FORMAT_IS_FLOATING    (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_GET_CHANNELS   (format)
gboolean            ipatch_sample_format_verify         (int format);
#define             ipatch_sample_format_size           (format)
IpatchSampleTransformFunc* ipatch_sample_new_transform_func_array
                                                        (int src_format,
                                                         int dest_format,
                                                         guint *buf1_max_frame,
                                                         guint *buf2_max_frame,
                                                         guint *func_count);

Description

Enums and functions for describing audio formats. In libInstPatch audio formats are described by an audio format integer which is composed of values from IpatchSampleWidth, IpatchSampleSign, IpatchSampleEndian, and IpatchSampleChannel all logically ORed (|) together. An example of such a format is "IPATCH_SAMPLE_WIDTH_16BIT | IPATCH_SAMPLE_SIGNED | IPATCH_SAMPLE_LENDIAN | IPATCH_SAMPLE_MONO" which would mean 16 bit signed PCM little endian mono audio. Note that the sign, endian and channels could be omitted in this case since they are the default values (0 valued).

Details

enum IpatchSampleWidth

typedef enum
{
  IPATCH_SAMPLE_INVALID = 0, /* A NULL value */
  IPATCH_SAMPLE_8BIT  = 1, /* 8 bit integer PCM */
  IPATCH_SAMPLE_16BIT = 2, /* 16 bit integer PCM */
  IPATCH_SAMPLE_24BIT = 3, /* 24 bit integer PCM (32 bit ints) */
  IPATCH_SAMPLE_32BIT = 4, /* 32 bit integer PCM */
  IPATCH_SAMPLE_FLOAT = 5, /* 32 bit IEEE float (0.0 - 1.0) */
  IPATCH_SAMPLE_DOUBLE = 6, /* 64 bit IEEE double (0.0 - 1.0) */
  IPATCH_SAMPLE_REAL24BIT = 7 /* real 3 byte 24 bit data */
} IpatchSampleWidth;

Sample bit width format.

IPATCH_SAMPLE_INVALID A NULL value
IPATCH_SAMPLE_8BIT 8 bit integer PCM
IPATCH_SAMPLE_16BIT 16 bit integer PCM
IPATCH_SAMPLE_24BIT 24 bit integer PCM (stored in 32 bit integers)
IPATCH_SAMPLE_32BIT 32 bit integer PCM
IPATCH_SAMPLE_FLOAT 32 bit IEEE float (0.0 - 1.0)
IPATCH_SAMPLE_DOUBLE 64 bit IEEE float (0.0 - 1.0)
IPATCH_SAMPLE_REAL24BIT Real 3 byte 24 bit data

enum IpatchSampleSign

typedef enum
{
  IPATCH_SAMPLE_SIGNED   = 0 << IPATCH_SAMPLE_SIGN_SHIFT, /* data is signed */
  IPATCH_SAMPLE_UNSIGNED = 1 << IPATCH_SAMPLE_SIGN_SHIFT /* data is unsigned */
} IpatchSampleSign;

Sample sign format.

IPATCH_SAMPLE_SIGNED Sample data is signed (default)
IPATCH_SAMPLE_UNSIGNED Sample data is unsigned

enum IpatchSampleEndian

typedef enum
{
  IPATCH_SAMPLE_LENDIAN = 0 << IPATCH_SAMPLE_ENDIAN_SHIFT, /* little endian */
  IPATCH_SAMPLE_BENDIAN = 1 << IPATCH_SAMPLE_ENDIAN_SHIFT /* big endian flag */
} IpatchSampleEndian;

Sample endian format.

IPATCH_SAMPLE_LENDIAN Sample data is little endian (default)
IPATCH_SAMPLE_BENDIAN Sample data is big endian

enum IpatchSampleChannel

typedef enum
{
  IPATCH_SAMPLE_MONO    = 0 << IPATCH_SAMPLE_CHANNEL_SHIFT, /* mono audio */
  IPATCH_SAMPLE_STEREO  = 1 << IPATCH_SAMPLE_CHANNEL_SHIFT /* stereo audio */
} IpatchSampleChannel;

Sample channel format.

IPATCH_SAMPLE_MONO Mono data
IPATCH_SAMPLE_STEREO Stereo data

enum IpatchSampleChannelRoute

typedef enum
{
  IPATCH_SAMPLE_ROUTE_LEFT  = 0 << IPATCH_SAMPLE_ROUTE_SHIFT,
  IPATCH_SAMPLE_ROUTE_RIGHT = 1 << IPATCH_SAMPLE_ROUTE_SHIFT
} IpatchSampleChannelRoute;

Channel routing (for stereo to mono sample conversion only)

IPATCH_SAMPLE_ROUTE_LEFT Convert stereo to left channel
IPATCH_SAMPLE_ROUTE_RIGHT Convert stereo to right channel

IPATCH_SAMPLE_ENDIAN_HOST

#define             IPATCH_SAMPLE_ENDIAN_HOST

Host (native) endian byte order audio.


IPATCH_SAMPLE_WIDTH_MASK

#define IPATCH_SAMPLE_WIDTH_MASK    0x07

Bit mask for width field in sample format integer.


IPATCH_SAMPLE_SIGN_MASK

#define IPATCH_SAMPLE_SIGN_MASK     0x20

Bit mask for sign flag in sample format integer.


IPATCH_SAMPLE_ENDIAN_MASK

#define IPATCH_SAMPLE_ENDIAN_MASK   0x40

Bit mask for endian flag in sample format integer.


IPATCH_SAMPLE_CHANNEL_MASK

#define IPATCH_SAMPLE_CHANNEL_MASK  0x18

Bit mask for channel field in sample format integer.


IPATCH_SAMPLE_ROUTE_MASK

#define IPATCH_SAMPLE_ROUTE_MASK    0x80 /* not normally part of format */


IPATCH_SAMPLE_WIDTH_SHIFT

#define IPATCH_SAMPLE_WIDTH_SHIFT   0

Bit shift to width field in sample format integer.


IPATCH_SAMPLE_SIGN_SHIFT

#define IPATCH_SAMPLE_SIGN_SHIFT    5

Bit shift to sign flag in sample format integer.


IPATCH_SAMPLE_ENDIAN_SHIFT

#define IPATCH_SAMPLE_ENDIAN_SHIFT  6

Bit shift to endian flag in sample format integer.


IPATCH_SAMPLE_CHANNEL_SHIFT

#define IPATCH_SAMPLE_CHANNEL_SHIFT 3

Bit shift to channel field in sample format integer.


IPATCH_SAMPLE_ROUTE_SHIFT

#define IPATCH_SAMPLE_ROUTE_SHIFT   7 /* not normally part of format */


IPATCH_SAMPLE_FORMAT_MASK

#define IPATCH_SAMPLE_FORMAT_MASK   0x7F

Bit mask for complete sample format integer.


IPATCH_SAMPLE_FORMAT_BITCOUNT

#define IPATCH_SAMPLE_FORMAT_BITCOUNT  7

Number of bits used for complete sample format integer.


IPATCH_SAMPLE_FORMAT_GET_WIDTH()

#define             IPATCH_SAMPLE_FORMAT_GET_WIDTH(format)

Get the IpatchSampleWidth field from a sample format integer.

format : Sample format integer
Returns : IpatchSampleWidth value

IPATCH_SAMPLE_FORMAT_IS_FLOATING()

#define             IPATCH_SAMPLE_FORMAT_IS_FLOATING(format)

Check if a sample format is a float type (IPATCH_SAMPLE_FLOAT or IPATCH_SAMPLE_DOUBLE).

format : Sample format integer
Returns : TRUE if float format, FALSE if integer

IPATCH_SAMPLE_FORMAT_IS_SIGNED()

#define             IPATCH_SAMPLE_FORMAT_IS_SIGNED(format)

Check if a sample format is signed.

format : Sample format integer
Returns : TRUE if signed, FALSE if unsigned

IPATCH_SAMPLE_FORMAT_IS_UNSIGNED()

#define             IPATCH_SAMPLE_FORMAT_IS_UNSIGNED(format)

Check if a sample format is unsigned.

format : Sample format integer
Returns : TRUE if unsigned, FALSE if unsigned

IPATCH_SAMPLE_FORMAT_IS_LENDIAN()

#define             IPATCH_SAMPLE_FORMAT_IS_LENDIAN(format)

Check if a sample format is little endian.

format : Sample format integer
Returns : TRUE if little endian, FALSE if big endian

IPATCH_SAMPLE_FORMAT_IS_BENDIAN()

#define             IPATCH_SAMPLE_FORMAT_IS_BENDIAN(format)

Check if a sample format is big endian.

format : Sample format integer
Returns : TRUE if big endian, FALSE if little endian

IPATCH_SAMPLE_FORMAT_GET_CHANNELS()

#define             IPATCH_SAMPLE_FORMAT_GET_CHANNELS(format)

Get the number of channels defined in a sample format integer. Note that this is the IpatchSampleChannel enum plus 1.

format : Sample format integer
Returns : Number of channels defined in 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_size()

#define             ipatch_sample_format_size(format)

Get the size in bytes of a sample format integer.

format : Sample format integer.
Returns : Number of bytes per frame.

ipatch_sample_new_transform_func_array ()

IpatchSampleTransformFunc* ipatch_sample_new_transform_func_array
                                                        (int src_format,
                                                         int dest_format,
                                                         guint *buf1_max_frame,
                                                         guint *buf2_max_frame,
                                                         guint *func_count);

Create a transform function array for converting from src_format to dest_format.

src_format : Source audio format to convert from
dest_format : Destination audio format to convert to (IpatchSampleChannelRoute defines can be used for stereo to mono conversion)
buf1_max_frame : Output - maximum sample frame size for first buffer
buf2_max_frame : Output - maximum sample frame size for second buffer
func_count : Output - count of function pointers in returned array
Returns : Newly allocated transform function array or NULL if no transform required between the given formats. The array should be freed with g_free when finished with it.

See Also

IpatchSampleTransform