## IpatchSampleTransform IpatchSampleTransform — Audio format conversion instance |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSampleTransform;
    void                (*IpatchSampleTransformFunc)        (IpatchSampleTransform *transform);
    IpatchSampleTransform * ipatch_sample_transform_new     (int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);
    void                ipatch_sample_transform_free        (IpatchSampleTransform *transform);
    void                ipatch_sample_transform_init        (IpatchSampleTransform *transform);
    IpatchSampleTransform * ipatch_sample_transform_pool_acquire
                                                            (int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);
    void                ipatch_sample_transform_pool_release
                                                            (IpatchSampleTransform *transform);
    void                ipatch_sample_transform_set_formats (IpatchSampleTransform *transform,
                                                             int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);
    void                ipatch_sample_transform_alloc       (IpatchSampleTransform *transform,
                                                             guint frames);
    int                 ipatch_sample_transform_alloc_size  (IpatchSampleTransform *transform,
                                                             guint size);
    void                ipatch_sample_transform_free_buffers
                                                            (IpatchSampleTransform *transform);
    guint               ipatch_sample_transform_set_buffers_size
                                                            (IpatchSampleTransform *transform,
                                                             gpointer buf,
                                                             guint size);
    void                ipatch_sample_transform_get_buffers (IpatchSampleTransform *transform,
                                                             gpointer *buf1,
                                                             gpointer *buf2);
    void                ipatch_sample_transform_get_frame_sizes
                                                            (IpatchSampleTransform *transform,
                                                             guint *buf1_size,
                                                             guint *buf2_size);
    guint               ipatch_sample_transform_get_max_frames
                                                            (IpatchSampleTransform *transform);
    gpointer            ipatch_sample_transform_convert     (IpatchSampleTransform *transform,
                                                             gconstpointer src,
                                                             gpointer dest,
                                                             guint frames);
    gpointer            ipatch_sample_transform_convert_single
                                                            (IpatchSampleTransform *transform,
                                                             guint frames);

## Description

A structure for converting between audio formats (for example the bit width or number of channels). This structure is initialized with the source and destination audio formats, multi-channel mapping and conversion buffers.

## Details

### IpatchSampleTransform

    typedef struct {
      guint16 src_format;		/* source sample format */
      guint16 dest_format;		/* destination sample format */
      guint8 channel_map[8];        /* channel mapping for multi-channel audio */
      guint8 buf1_max_frame;	/* max bytes per frame for buf1 */
      guint8 buf2_max_frame;	/* max bytes per frame for buf2 */
      guint8 func_count;		/* number of functions in funcs array */
      guint8 free_buffers;		/* set to TRUE if buffers need to be freed */
      guint max_frames;		/* max frames that can be converted in batch */
      guint frames;			/* number of frames to transform */
      guint samples; /* # of samples for current transform func (not frames!)*/
      gpointer buf1;		/* buffer 1 (first input) */
      gpointer buf2;		/* buffer 2 */
      guint combined_size;	/* size in bytes of both buffers (if combined) */
      gpointer reserved1;           /* Reserved field */
      gpointer reserved2;           /* Reserved field */

      /* array of transform funcs */
      IpatchSampleTransformFunc funcs[IPATCH_SAMPLE_MAX_TRANSFORM_FUNCS];
    } IpatchSampleTransform;

### IpatchSampleTransformFunc ()

    void                (*IpatchSampleTransformFunc)        (IpatchSampleTransform *transform);

Audio conversion handler prototype. Handler will modify `samples` of `transform` if number of samples changes (a change in the number of channels occurs).

`transform` : | Sample transform object

### ipatch_sample_transform_new ()

    IpatchSampleTransform * ipatch_sample_transform_new     (int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);

Create a new sample transform object. If `src_format` and `dest_format` are not 0 then the transform is initialized for the given source and destination formats, otherwise they are expected to be set later with `ipatch_sample_transform_set_formats()`.

`src_format` : | Source sample format or 0 to set later
`dest_format` : | Destination sample format or 0 to set later
`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 : | New allocated sample transform structure which should be freed with `ipatch_sample_transform_free()` when done with it.

### ipatch_sample_transform_free ()

    void                ipatch_sample_transform_free        (IpatchSampleTransform *transform);

Free a transform structure as allocated by `ipatch_sample_transform_new()` and its allocated resources.

`transform` : | Transform structure

### ipatch_sample_transform_init ()

    void                ipatch_sample_transform_init        (IpatchSampleTransform *transform);

Initialize a sample transform structure. Usually only used to initialize transform structures allocated on the stack, which is done to avoid mallocs.

`transform` : | Sample transform to initialize

### ipatch_sample_transform_pool_acquire ()

    IpatchSampleTransform * ipatch_sample_transform_pool_acquire
                                                            (int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);

Get an unused sample transform object from the sample transform pool. Used for quickly getting a transform object for temporary use without the overhead of allocating one. Note though, that if no more transforms exist in the pool an allocation will occur.

`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 : | Sample transform object. Should be released after use with `ipatch_sample_transform_pool_release()`.

### ipatch_sample_transform_pool_release ()

    void                ipatch_sample_transform_pool_release
                                                            (IpatchSampleTransform *transform);

Release a sample transform object, returned by `ipatch_sample_transform_pool_grab()`, back to the transform pool.

`transform` : | Sample transform

### ipatch_sample_transform_set_formats ()

    void                ipatch_sample_transform_set_formats (IpatchSampleTransform *transform,
                                                             int src_format,
                                                             int dest_format,
                                                             guint32 channel_map);

Initialize a sample transform object for converting from `src_format` to `dest_format`.

`transform` : | Transform object
`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, see IPATCH_SAMPLE_MAP_CHANNEL macro for constructing channel map values)

### ipatch_sample_transform_alloc ()

    void                ipatch_sample_transform_alloc       (IpatchSampleTransform *transform,
                                                             guint frames);

Allocate buffers for transforming between two audio formats, for which `transform` has previously been initialized for with `ipatch_sample_transform_new()` or `ipatch_sample_transform_set_formats()`.

Note: Assigning buffers with this function allows sample formats to be changed without re-assigning the buffers.

`transform` : | Sample transform object
`frames` : | Number of frames to allocate for (max frames processed in batch)

### ipatch_sample_transform_alloc_size ()

    int                 ipatch_sample_transform_alloc_size  (IpatchSampleTransform *transform,
                                                             guint size);

Like `ipatch_sample_transform_alloc()` but allocates buffers based on a maximum size and returns the maximum number of sample frames which can be converted at a time using this size. Another difference is that conversion formats do not need to be set before calling this function.

`transform` : | Sample transform object
`size` : | Maximum total size in bytes of allocation for both transform buffers.
Returns : | The maximum number of frames that can be converted at a time for the given `size` of transform buffers. If conversion formats have not yet been set, then this function returns 0.

### ipatch_sample_transform_free_buffers ()

    void                ipatch_sample_transform_free_buffers
                                                            (IpatchSampleTransform *transform);

Free sample transform buffers.

`transform` : | Sample transform object

### ipatch_sample_transform_set_buffers_size ()

    guint               ipatch_sample_transform_set_buffers_size
                                                            (IpatchSampleTransform *transform,
                                                             gpointer buf,
                                                             guint size);

Assign transform buffers using a single buffer of a specific size in bytes and determine optimal division for source and destination buffers. Conversion formats must not be set before calling this function (can be set later).

`transform` : | Sample transform object
`buf` : | Buffer to assign for transforming sample formats
`size` : | Size of `buf` in bytes
Returns : | The maximum number of frames that can be converted at a time for the given `size` of transform buffers. If conversion formats have not yet been set, then this function returns 0.

### ipatch_sample_transform_get_buffers ()

    void                ipatch_sample_transform_get_buffers (IpatchSampleTransform *transform,
                                                             gpointer *buf1,
                                                             gpointer *buf2);

Get the sample data buffers in a sample transform object.

`transform` : | Sample transform object
`buf1` : | Output - first buffer or `NULL` to ignore
`buf2` : | Output - second buffer or `NULL` to ignore

### ipatch_sample_transform_get_frame_sizes ()

    void                ipatch_sample_transform_get_frame_sizes
                                                            (IpatchSampleTransform *transform,
                                                             guint *buf1_size,
                                                             guint *buf2_size);

Get max frame sizes for transform buffers. When transforming audio the first buffer must be at least frames * buf1_size bytes in size and the second buffer must be at least frames * buf2_size, where frames is the max number of frames to convert in batch.

`transform` : | Initialized transform object
`buf1_size` : | Out: Maximum frame size for buffer 1 or `NULL` to ignore
`buf2_size` : | Out: Maximum frame size for buffer 2 or `NULL` to ignore

### ipatch_sample_transform_get_max_frames ()

    guint               ipatch_sample_transform_get_max_frames
                                                            (IpatchSampleTransform *transform);

Get the maximum frames that the `transform` object can convert at a time.

`transform` : | Sample transform object
Returns : | Max number of frames that can be converted at a time, 0 if buffers have not been allocated yet.

### ipatch_sample_transform_convert ()

    gpointer            ipatch_sample_transform_convert     (IpatchSampleTransform *transform,
                                                             gconstpointer src,
                                                             gpointer dest,
                                                             guint frames);

Convert an arbitrary number of audio frames from user provided buffers, contrary to `ipatch_sample_transform_convert_single()` which uses internal buffers and converts a max of 1 buffer at a time. The sample formats should already be assigned and internal buffers assigned or allocated.

`transform` : | An initialized sample transform object
`src` : | Audio source buffer (`frames` X the source frame size in bytes), can be `NULL` to use internal buffer (provided `frames` is less than or equal to the max frames that can be converted at a time), in which case buf1 of `transform` should already be loaded with source data.
`dest` : | Converted audio destination buffer (`frames` X the destination frame size in bytes), can be `NULL` to use internal buffer (provided `frames` is less than or equal to the max frames that can be converted at a time).
`frames` : | Number of audio frames to convert
Returns : | Pointer to converted data. Will be `dest` if it was not `NULL` or internal buffer containing the converted data otherwise.

### ipatch_sample_transform_convert_single ()

    gpointer            ipatch_sample_transform_convert_single
                                                            (IpatchSampleTransform *transform,
                                                             guint frames);

Convert the format of a single buffer of audio. The `transform` object must have had its sample formats set and buffers assigned or allocated. Use `ipatch_sample_transform_convert()` to convert from one buffer to another regardless of the number of frames.

`transform` : | An initialized sample transform object
`frames` : | Number of frames to convert (should be less than or equal to the maximum frames which can be converted at a time (see `ipatch_sample_transform_get_max_frames()`).
Returns : | Pointer to converted audio data (buffer is internal to `transform` object).