IpatchSampleData

IpatchSampleData — Sample data proxy object.

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── IpatchItem
        ╰── IpatchSampleData

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.

Functions

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.

[transfer full]

Since: 1.1.0


ipatch_migrate_file_sample_data ()

gboolean
ipatch_migrate_file_sample_data (IpatchFile *oldfile,
                                 IpatchFile *newfile,
                                 const char *filename,
                                 guint flags,
                                 GError **err);

Used for migrating sample data when saving, deleting, replacing or closing instrument files.

If oldfile is set, sample data will be migrated for those that have native sample references to it, and the old sample stores are removed.

When saving a file, newfile can be set. In this case new IpatchSampleStore objects should have already been added to their applicable IpatchSampleData objects. IpatchSampleData objects will be migrated to these stores if they match the native format and the criteria set by the flags parameter.

If sample data needs to be migrated but there is no format identical store from newfile , then a new duplicate IpatchSampleStoreSwap will be created and set as the new native sample.

If the IPATCH_SAMPLE_DATA_MIGRATE_REMOVE_NEW_IF_UNUSED flag is set in flags , then unused IpatchSampleStore objects referencing newfile will be removed if unused.

The IPATCH_SAMPLE_DATA_MIGRATE_TO_NEWFILE flag can be used to migrate all native compatible samples to newfile . Default is to only migrate samples which reference oldfile or swap.

The IPATCH_SAMPLE_DATA_MIGRATE_LEAVE_IN_SWAP flag can be used to not migrate samples out of swap. The default is to migrate samples out of swap to newfile if possible.

The IPATCH_SAMPLE_DATA_MIGRATE_REPLACE flag can be used to replace oldfile with newfile using ipatch_file_replace(). If oldfile is not set, filename can be used to replace a file, which should not be referenced by any other IpatchFile object. If neither of these is set, then this flag is ignored.

NOTE - Not really thread safe. It is assumed that sample stores referencing oldfile or newfile will not be added or removed (respectively) by other threads during this function. The side effect of this would potentially be added samples still referencing oldfile or removed samples being re-added.

Parameters

oldfile

Old file to migrate samples from (can be NULL, but not both oldfile and newfile ).

[nullable]

newfile

New file which has stores which may be used for migration (can be NULL, but not both oldfile and newfile ).

[nullable]

filename

File name used for replace if oldfile is NULL and IPATCH_SAMPLE_DATA_MIGRATE_REPLACE is set in flags .

[nullable]

flags

Flag options for migration.

[type IpatchSampleDataMigrateFlags]

err

Location to store error info or NULL to ignore

 

Returns

TRUE on succcess, FALSE otherwise (in which case err may be set)

Since: 1.1.0


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 which the caller owns. Use count should be incremented when added to an active instrument sample using ipatch_sample_data_used() which will add it to the pool of sample data objects.


ipatch_sample_data_used ()

void
ipatch_sample_data_used (IpatchSampleData *sampledata);

Increment use count of a sample data object. Use references are not the same as object references and in contrast indicate if a sample data object should continue to be a part of the sample data pool - if it is a dependency of an active loaded instrument for example.

Parameters

sampledata

Sample data object

 

Since: 1.1.0


ipatch_sample_data_unused ()

void
ipatch_sample_data_unused (IpatchSampleData *sampledata);

Decrement use count of a sample data object. When the use count drops to 0 it will be removed from the pool of active sample data objects. Sample data object is only freed after it's reference count goes to 0 though.

Parameters

sampledata

Sample data object

 

Since: 1.1.0


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.

Parameters

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.

Parameters

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

The store object can already be added to sampledata , does nothing if already native sample (libInstPatch version 1.1.0+).

Parameters

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.

Parameters

sampledata

Sample data object

 

Returns

Newly created list of IpatchSampleStore objects with a refcount of 1 which the caller owns.

[transfer full]


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.

Parameters

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.

Parameters

sampledata

Sample data object

 

Returns

Native sample, or NULL if no native sample in the sample data object, caller owns a reference.

[transfer full]


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.

Parameters

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.

Parameters

sampledata

Sample data

 

handle

Caller supplied structure to initialize.

[out]

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.

Parameters

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

[transfer full]


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.

Parameters

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.

[transfer full]


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.

Parameters

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

guint64
ipatch_sample_cache_get_unused_size (void);

Get the current unused sample cache data size.

Returns

Total amount of unused sample cache data in RAM.

Since: 1.1.0


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

[transfer full]

Types and Values

IPATCH_SAMPLE_DATA_UNUSED_FLAG_SHIFT

#define             IPATCH_SAMPLE_DATA_UNUSED_FLAG_SHIFT

enum IpatchSampleDataMigrateFlags

Members

IPATCH_SAMPLE_DATA_MIGRATE_REMOVE_NEW_IF_UNUSED

Remove unused IpatchSampleStore objects referencing newfile.

 

IPATCH_SAMPLE_DATA_MIGRATE_TO_NEWFILE

Migrate all IpatchSampleData objects to newfile which have a IpatchSampleStore with the same format as the native format therein, default is to only migrate those with their native samples in oldfile or swap storage.

 

IPATCH_SAMPLE_DATA_MIGRATE_LEAVE_IN_SWAP

Leave native samples in IpatchSampleData objects in swap, even if present in newfile, default is to migrate samples out of swap in preference for newfile.

 

IPATCH_SAMPLE_DATA_MIGRATE_REPLACE

Replace oldfile with newfile (has no effect if newfile is NULL)

 

Since: 1.1.0

See Also

IpatchSampleStore