IpatchSampleTransform

IpatchSampleTransform — Audio format conversion instance

Stability Level

Stable, unless otherwise indicated

Functions

Object Hierarchy

    GBoxed
    ╰── IpatchSampleTransform

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.

Functions

IpatchSampleTransformFunc ()

void
(*IpatchSampleTransformFunc) (IpatchSampleTransform *transform);

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

Parameters

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().

Parameters

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.

Parameters

transform

Transform structure

 

ipatch_sample_transform_duplicate ()

IpatchSampleTransform *
ipatch_sample_transform_duplicate (const IpatchSampleTransform *transform);

Duplicate a sample transform.

Parameters

transform

Transform structure

 

Returns

New duplicated sample transform structure.

Since: 1.1.0


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.

[skip]

Parameters

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.

[skip]

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

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.

[skip]

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

transform

Sample transform object

 

buf

Buffer to assign for transforming sample formats.

[array length=size][element-type guint8][transfer none]

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.

[skip]

Parameters

transform

Sample transform object

 

buf1

First buffer or NULL to ignore.

[out][optional]

buf2

Second buffer or NULL to ignore.

[out][optional]

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.

Parameters

transform

Initialized transform object

 

buf1_size

Maximum frame size for buffer 1 or NULL to ignore.

[out][optional]

buf2_size

Maximum frame size for buffer 2 or NULL to ignore.

[out][optional]

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.

Parameters

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.

[skip]

Parameters

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.

[transfer none]


ipatch_sample_transform_convert_sizes ()

gpointer
ipatch_sample_transform_convert_sizes (IpatchSampleTransform *transform,
                                       gconstpointer src,
                                       guint src_size,
                                       guint *dest_size);

Convert an arbitrary number of audio frames from user provided buffer. This is like ipatch_sample_transform_convert() but friendly to GObject introspection and the destination conversion buffer is allocated. The sample formats should already be assigned and internal buffers assigned or allocated.

[rename-to ipatch_sample_transform_convert]

Parameters

transform

An initialized sample transform object

 

src

Audio source buffer.

[array length=src_size][element-type guint8][transfer none]

src_size

Size of src buffer data to convert (in bytes, must be a multiple of the source format)

 

dest_size

Location to store size of returned converted audio buffer.

[out]

Returns

Newly allocated converted audio data buffer. Free with g_free() when done with it.

[array length=dest_size][element-type guint8][transfer full]

Since: 1.1.0


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.

[skip]

Parameters

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

[transfer none]