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
Generated by GTK-Doc V1.15