## IpatchSampleData

IpatchSampleData — Sample data proxy object.

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSampleData;
    #define             IPATCH_SAMPLE_DATA_UNUSED_FLAG_SHIFT
    IpatchList *        ipatch_get_sample_data_list         (void);
    IpatchSampleData *  ipatch_sample_data_new              (void);
    void                ipatch_sample_data_add              (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);
    void                ipatch_sample_data_remove           (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);
    void                ipatch_sample_data_replace_native_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);
    IpatchList *        ipatch_sample_data_get_samples      (IpatchSampleData *sampledata);
    guint               ipatch_sample_data_get_size         (IpatchSampleData *sampledata);
    IpatchSampleStore * ipatch_sample_data_get_native_sample
                                                            (IpatchSampleData *sampledata);
    int                 ipatch_sample_data_get_native_format
                                                            (IpatchSampleData *sampledata);
    gboolean            ipatch_sample_data_open_native_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleHandle *handle,
                                                             char mode,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    IpatchSampleStore * ipatch_sample_data_get_cache_sample (IpatchSampleData *sampledata,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    IpatchSampleStore * ipatch_sample_data_lookup_cache_sample
                                                            (IpatchSampleData *sampledata,
                                                             int format,
                                                             guint32 channel_map);
    gboolean            ipatch_sample_data_open_cache_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleHandle *handle,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    void                ipatch_sample_cache_clean           (guint64 max_unused_size,
                                                             guint max_unused_age);
    IpatchSampleData *  ipatch_sample_data_get_blank        (void);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchSampleData

## Implemented Interfaces

IpatchSampleData implements IpatchSample.

## Description

An object which acts as a proxy for sample data and one or more cached versions of the same audio but potentially differing in sample format and/or storage media. IpatchSampleStore is used instead of the IpatchSample interface, for increased performance.

## Details

### IpatchSampleData

    typedef struct _IpatchSampleData IpatchSampleData;

### IPATCH_SAMPLE_DATA_UNUSED_FLAG_SHIFT

    #define             IPATCH_SAMPLE_DATA_UNUSED_FLAG_SHIFT

### ipatch_get_sample_data_list ()

    IpatchList *        ipatch_get_sample_data_list         (void);

Creates an object list copy of the master sample data list (all existing sample data objects).

Returns : | New object list populated with all IpatchSampleData objects with a reference count of 1 which the caller owns, removing the reference will free the list.

### ipatch_sample_data_new ()

    IpatchSampleData *  ipatch_sample_data_new              (void);

Create a new sample data object.

Returns : | New sample data with a reference count of 1. Caller owns the reference and removing it will destroy the item, unless another reference is added (if its parented for example).

### ipatch_sample_data_add ()

    void                ipatch_sample_data_add              (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);

Add a sample to a sample data object. If no samples have yet been added, then the added sample becomes the native sample. All samples added to a given `sampledata` object must have the same frame count and should also have the same sample rate. This is not enforced though and is left to the caller to ensure.

`sampledata` : | Sample data object
`store` : | Sample store to add

### ipatch_sample_data_remove ()

    void                ipatch_sample_data_remove           (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);

Remove a sample from a sample data object. The native sample should not be removed from an active sample data object. Use `ipatch_sample_data_replace_native_sample()` if replacement is desired.

`sampledata` : | Sample data object
`store` : | Sample store to remove

### ipatch_sample_data_replace_native_sample ()

    void                ipatch_sample_data_replace_native_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleStore *store);

Replace the native sample of a sample data object. This function can be used even if there are no samples yet, in which case it behaves just like `ipatch_sample_data_add()`.

`sampledata` : | Sample data object
`store` : | Sample store object

### ipatch_sample_data_get_samples ()

    IpatchList *        ipatch_sample_data_get_samples      (IpatchSampleData *sampledata);

Get an object list of samples in a sample data object. The first sample is the native sample.

`sampledata` : | Sample data object
Returns : | Newly created list of IpatchSampleStore objects with a refcount of 1 which the caller owns.

### ipatch_sample_data_get_size ()

    guint               ipatch_sample_data_get_size         (IpatchSampleData *sampledata);

Get the size in frames of the samples in the `sampledata` object.

`sampledata` : | Sample data to get size of
Returns : | Size in frames of stores in sample data.

### ipatch_sample_data_get_native_sample ()

    IpatchSampleStore * ipatch_sample_data_get_native_sample
                                                            (IpatchSampleData *sampledata);

Get the native sample of a sample data object.

`sampledata` : | Sample data object
Returns : | Native sample, or `NULL` if no native sample in the sample data object, caller owns a reference.

### ipatch_sample_data_get_native_format ()

    int                 ipatch_sample_data_get_native_format
                                                            (IpatchSampleData *sampledata);

Convenience function to get the sample format of the native sample in a sample data object. See `ipatch_sample_get_format()` for more info.

`sampledata` : | Sample data object
Returns : | Sample format or 0 if `sampledata` has no native sample.

### ipatch_sample_data_open_native_sample ()

    gboolean            ipatch_sample_data_open_native_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleHandle *handle,
                                                             char mode,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

A convenience function to open a handle to a `sampledata` object's native sample. See `ipatch_sample_handle_open()` for more details. This is identical to calling `ipatch_sample_data_get_native_sample()` and then `ipatch_sample_handle_open()` on the returned sample.

`sampledata` : | Sample data
`handle` : | Caller supplied structure to initialize
`mode` : | Access mode to sample, 'r' for reading and 'w' for writing
`format` : | Sample format to convert to/from (0 for no conversion or to assign a transform object with `ipatch_sample_handle_set_transform()`).
`channel_map` : | Channel mapping if `format` is set (set to 0 otherwise), use IPATCH_SAMPLE_UNITY_CHANNEL_MAP for 1 to 1 channel mapping (see `ipatch_sample_get_transform_funcs()` for details).
`err` : | Location to store error information
Returns : | `TRUE` on success, `FALSE` on failure (in which case `err` may be set)

### ipatch_sample_data_get_cache_sample ()

    IpatchSampleStore * ipatch_sample_data_get_cache_sample (IpatchSampleData *sampledata,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

Get a cached version, in RAM, of a sample. If an existing cached sample already exists with the given format and channel map, it is used. Otherwise a new IpatchSampleStoreCache sample is created and the native sample is converted as necessary. If a matching cached sample is currently being created by another thread, this function will block until it is created and return it.

`sampledata` : | Sample data object
`format` : | Sample format of cached sample to convert native sample to
`channel_map` : | Channel mapping to use for new cached sample when converting from native format, use IPATCH_SAMPLE_UNITY_CHANNEL_MAP for 1 to 1 channel mapping (see `ipatch_sample_get_transform_funcs()` for details).
`err` : | Location to store error information
Returns : | Cached sample with the given `format` for which the caller owns a reference or `NULL` if `sampledata` contains no samples or a sample conversion error occurred (I/O error for example).

### ipatch_sample_data_lookup_cache_sample ()

    IpatchSampleStore * ipatch_sample_data_lookup_cache_sample
                                                            (IpatchSampleData *sampledata,
                                                             int format,
                                                             guint32 channel_map);

Like `ipatch_sample_data_get_cache_sample()` but does not create a new cache sample if it doesn't exist.

`sampledata` : | Sample data object
`format` : | Sample format
`channel_map` : | Channel mapping of cached sample relative to native sample format.
Returns : | Cached sample store with the given `format` and `channel_map` for which the caller owns a reference or `NULL` if `sampledata` does not contain a matching cached sample.

### ipatch_sample_data_open_cache_sample ()

    gboolean            ipatch_sample_data_open_cache_sample
                                                            (IpatchSampleData *sampledata,
                                                             IpatchSampleHandle *handle,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

Like `ipatch_sample_data_get_cache_sample()` but opens the resulting cached sample as a convenience.

`sampledata` : | Sample data object
`handle` : | Caller supplied sample handle to initialize
`format` : | Sample format
`err` : | Location to store error information
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_sample_cache_clean ()

    void                ipatch_sample_cache_clean           (guint64 max_unused_size,
                                                             guint max_unused_age);

### ipatch_sample_data_get_blank ()

    IpatchSampleData *  ipatch_sample_data_get_blank        (void);

Get blank sample data object. Return's a sample data structure with the minimum amount of data which is blank. Only creates it on the first call, subsequent calls return the same sample data object. Therefore it should not be modified. The blank sample data's reference count has been incremented and should be removed by the caller with `g_object_unref()` when finished with it.

Returns : | The blank sample data object. Remember to unref it when not using it anymore with `g_object_unref()`.

## See Also

#IpatchSampleStore