IpatchSampleStore

IpatchSampleStore — A base class for sample storage methods.

Synopsis




gboolean            (*IpatchSampleStoreVerifyFunc)      (IpatchSampleStore *store);
gboolean            (*IpatchSampleStoreAllocFunc)       (IpatchSampleStore *store,
                                                         GError **err);
gboolean            (*IpatchSampleStoreFreeFunc)        (IpatchSampleStore *store,
                                                         GError **err);
gboolean            (*IpatchSampleStoreReadFunc)        (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         gpointer buf,
                                                         GError **err);
gboolean            (*IpatchSampleStoreWriteFunc)       (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         gconstpointer buf,
                                                         GError **err);
gboolean            (*IpatchSampleStoreReadableFunc)    (IpatchSampleStore *store);
gboolean            (*IpatchSampleStoreWritableFunc)    (IpatchSampleStore *store);
guint               (*IpatchSampleStoreSpeedFunc)       (IpatchSampleStore *store);
                    IpatchSampleStore;
                    IpatchSampleStoreClass;
#define             IPATCH_SAMPLE_STORE_FORMAT_SHIFT
#define             IPATCH_SAMPLE_STORE_GET_FORMAT      (store)
enum                IpatchSampleStoreFlags;
#define             IPATCH_SAMPLE_STORE_IS_ACTIVE       (store)
#define             IPATCH_SAMPLE_STORE_UNUSED_FLAG_SHIFT
IpatchSampleStore*  ipatch_sample_store_first           (IpatchIter *iter);
IpatchSampleStore*  ipatch_sample_store_next            (IpatchIter *iter);
void                ipatch_sample_store_activate        (IpatchSampleStore *store);
gboolean            ipatch_sample_store_get_active      (IpatchSampleStore *store);
void                ipatch_sample_store_set_format      (IpatchSampleStore *store,
                                                         int format);
int                 ipatch_sample_store_get_format      (IpatchSampleStore *store);
guint               ipatch_sample_store_get_size        (IpatchSampleStore *store,
                                                         guint *bytes);
guint               ipatch_sample_store_get_frame_size  (IpatchSampleStore *store);
gboolean            ipatch_sample_store_is_readable     (IpatchSampleStore *store);
gboolean            ipatch_sample_store_is_writable     (IpatchSampleStore *store);
int                 ipatch_sample_store_get_speed       (IpatchSampleStore *store);
gboolean            ipatch_sample_store_alloc           (IpatchSampleStore *store,
                                                         GError **err);
gboolean            ipatch_sample_store_read            (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         void *buf,
                                                         GError **err);
gboolean            ipatch_sample_store_write           (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         const void *buf,
                                                         GError **err);
IpatchSampleTransform* ipatch_sample_store_transform_new
                                                        (IpatchSampleStore *store,
                                                         int format,
                                                         guint frames,
                                                         gboolean is_read);
void                ipatch_sample_store_transform_init  (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         int format,
                                                         guint frames,
                                                         gboolean is_read);
int                 ipatch_sample_store_transform_init_size
                                                        (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         int format,
                                                         guint size,
                                                         gboolean is_read);
gpointer            ipatch_sample_store_transform_read  (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         guint offset,
                                                         guint frames,
                                                         GError **err);
gboolean            ipatch_sample_store_transform_write (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         guint offset,
                                                         guint frames,
                                                         GError **err);
gboolean            ipatch_sample_store_copy            (IpatchSampleStore *dest_store,
                                                         IpatchSampleStore *src_store,
                                                         GError **err);
IpatchSampleStore*  ipatch_sample_store_duplicate       (IpatchSampleStore *store,
                                                         GType new_type,
                                                         int new_format,
                                                         GError **err);
gboolean            ipatch_sample_store_TRUE            (IpatchSampleStore *store);
gboolean            ipatch_sample_store_FALSE           (IpatchSampleStore *store);

Object Hierarchy


  GObject
   +----IpatchItem
         +----IpatchSampleStore
               +----IpatchSampleStoreFile
               +----IpatchSampleStoreRAM
               +----IpatchSampleStoreROM

Properties


  "active"                   gboolean              : Read / Write
  "channels"                 gint                  : Read / Write
  "format"                   gint                  : Read / Write
  "lil-endian"               gboolean              : Read / Write
  "signed"                   gboolean              : Read / Write
  "width"                    IpatchSampleWidth     : Read / Write

Description

This object defines an abstract class for sample storage types and also defines sample audio format. A storage method is a way of storing sample audio, examples include: RAM memory, file on a hard disk, a WAV file, etc. Sample stores are contained in IpatchSampleData objects. Each IpatchSampleData object may contain multiple IpatchSampleStore objects with differing storage methods and/or formats.

Details

IpatchSampleStoreVerifyFunc ()

gboolean            (*IpatchSampleStoreVerifyFunc)      (IpatchSampleStore *store);

IpatchSampleStore class method function type to verify a sample store's internal state.

store : Sample store to verify
Returns : Should return TRUE if sample store's internal state is valid, FALSE otherwise.

IpatchSampleStoreAllocFunc ()

gboolean            (*IpatchSampleStoreAllocFunc)       (IpatchSampleStore *store,
                                                         GError **err);

IpatchSampleStore class method function type to allocate space for a sample store. Function should ensure that data has not already been allocated.

store : Sample store to allocate for
err : Location to store error information
Returns : Should return TRUE on success, FALSE otherwise (in which case an error should optionally be stored in err).

IpatchSampleStoreFreeFunc ()

gboolean            (*IpatchSampleStoreFreeFunc)        (IpatchSampleStore *store,
                                                         GError **err);

IpatchSampleStore class method function type to free space of a sample store. Function should ensure that there is data to free, etc.

store : Sample store to free space of
err : Location to store error information
Returns : Should return TRUE on success, FALSE otherwise (in which case an error should optionally be stored in err).

IpatchSampleStoreReadFunc ()

gboolean            (*IpatchSampleStoreReadFunc)        (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         gpointer buf,
                                                         GError **err);

IpatchSampleStore class method function type to read data from a sample store. The sample store does not need to be verified, this is done by any functions accessing this method. Also the store will already be write locked when control is passed to this method.

store : Sample store to read data from
offset : Offset in sample to start read from (in frames)
frames : Size of sample data to read (in frames)
buf : Buffer to store sample data in
err : Location to store error information
Returns : Should return TRUE on success, FALSE otherwise (in which case an error should optionally be stored in err).

IpatchSampleStoreWriteFunc ()

gboolean            (*IpatchSampleStoreWriteFunc)       (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         gconstpointer buf,
                                                         GError **err);

IpatchSampleStore class method function type to write data to a sample store. The sample store does not need to be verified, this is done by any functions accessing this method. Also the store will already be write locked when control is passed to this method.

store : Sample store to write data to
offset : Offset in sample to start write to (in frames)
frames : Size of sample data to write (in frames)
buf : Buffer to read sample data from
err : Location to store error information
Returns : Should return TRUE on success, FALSE otherwise (in which case an error should optionally be stored in err).

IpatchSampleStoreReadableFunc ()

gboolean            (*IpatchSampleStoreReadableFunc)    (IpatchSampleStore *store);

IpatchSampleStore class method function type to check if a sample store is readable. This function should only check if a store has reading capability and not verify any other unrelated parameters (i.e., this function is not concerned with whether a read would fail or not, only that this store is read capable).

store : Sample store to check if readable
Returns : Should return TRUE if sample store is readable, FALSE otherwise.

IpatchSampleStoreWritableFunc ()

gboolean            (*IpatchSampleStoreWritableFunc)    (IpatchSampleStore *store);

IpatchSampleStore class method function type to check if a sample store is writable. This function should only check if a store has writing capability and not verify any other unrelated parameters (i.e., this function is not concerned with whether a write would fail or not, only that this store is write capable).

store : Sample store to check if writable
Returns : Should return TRUE if sample store is writable, FALSE otherwise.

IpatchSampleStoreSpeedFunc ()

guint               (*IpatchSampleStoreSpeedFunc)       (IpatchSampleStore *store);

IpatchSampleStore class method function type to get speed rating of a sample store. A value between 1-10 (see IpatchSampleSpeed enum).

store : Sample store to get speed rating of
Returns : Should return a value between 1 and 10.

IpatchSampleStore

typedef struct _IpatchSampleStore IpatchSampleStore;


IpatchSampleStoreClass

typedef struct {
  IpatchItemClass parent_class;


  /* methods for derived sample store types */
  IpatchSampleStoreVerifyFunc verify;
  IpatchSampleStoreAllocFunc alloc;
  IpatchSampleStoreFreeFunc free;
  IpatchSampleStoreReadFunc read;
  IpatchSampleStoreWriteFunc write;
  IpatchSampleStoreReadableFunc readable;
  IpatchSampleStoreWritableFunc writable;
  IpatchSampleStoreSpeedFunc speed;
} IpatchSampleStoreClass;


IPATCH_SAMPLE_STORE_FORMAT_SHIFT

#define IPATCH_SAMPLE_STORE_FORMAT_SHIFT IPATCH_ITEM_UNUSED_FLAG_SHIFT


IPATCH_SAMPLE_STORE_GET_FORMAT()

#define             IPATCH_SAMPLE_STORE_GET_FORMAT(store)

store :

enum IpatchSampleStoreFlags

typedef enum /*< flags >*/
{
  IPATCH_SAMPLE_STORE_ACTIVE = 1 << (IPATCH_SAMPLE_STORE_FORMAT_SHIFT + IPATCH_SAMPLE_FORMAT_BITCOUNT)
} IpatchSampleStoreFlags;

IpatchItem flags for sample store objects.


IPATCH_SAMPLE_STORE_IS_ACTIVE()

#define             IPATCH_SAMPLE_STORE_IS_ACTIVE(store)

A macro to test if a IpatchSampleStore is active.

store : IpatchSampleStore to test if active.
Returns : TRUE if active, FALSE otherwise

IPATCH_SAMPLE_STORE_UNUSED_FLAG_SHIFT

#define             IPATCH_SAMPLE_STORE_UNUSED_FLAG_SHIFT

IpatchItem flag shift value for next free flag position. Useful for derived types to define their own flags.


ipatch_sample_store_first ()

IpatchSampleStore*  ipatch_sample_store_first           (IpatchIter *iter);

Gets the first item in a sample store iterator. A convenience wrapper for ipatch_iter_first().

iter : Patch item iterator containing IpatchSampleStore items
Returns : The first sample store in iter or NULL if empty.

ipatch_sample_store_next ()

IpatchSampleStore*  ipatch_sample_store_next            (IpatchIter *iter);

Gets the next item in a sample store iterator. A convenience wrapper for ipatch_iter_next().

iter : Patch item iterator containing IpatchSampleStore items
Returns : The next sample store in iter or NULL if at the end of the list.

ipatch_sample_store_activate ()

void                ipatch_sample_store_activate        (IpatchSampleStore *store);

New sample stores are inactive until activated by calling this function. The sample store's "verify" method is called to verify its internal parameters and if TRUE is returned then the sample store is activated. Sample stores cannot be "de-activated", only removed (store itself is not destroyed until all references are relinquished).

store : Sample store to activate

ipatch_sample_store_get_active ()

gboolean            ipatch_sample_store_get_active      (IpatchSampleStore *store);

Gets the value of the active flag in a sample store. Only active sample stores can be read or written to. See ipatch_sample_store_activate() for more info.

store : Sample store to get value of active flag
Returns : TRUE if store is active, FALSE otherwise. MT-NOTE: Once a sample store is active, it cannot be de-activated. A sample store can be activated at any time though.

ipatch_sample_store_set_format ()

void                ipatch_sample_store_set_format      (IpatchSampleStore *store,
                                                         int format);

Set the sample data format of a sample store. Can only be set once and must be done before sample store is activated.

store : Sample store to set format of
format : Sample format enumeration

ipatch_sample_store_get_format ()

int                 ipatch_sample_store_get_format      (IpatchSampleStore *store);

Gets the sample data format of a sample store.

store : Sample store to get sample format of
Returns : Sample store data format integer of sample store (see IpatchSampleWidth, IpatchSampleChannel and sign/endian flags in sample.h).

ipatch_sample_store_get_size ()

guint               ipatch_sample_store_get_size        (IpatchSampleStore *store,
                                                         guint *bytes);

Gets sample size information from a sample store from its parent sample data object. Like ipatch_sample_data_get_size() but also gets actual storage size of sample data in bytes (since stores in the same sample data can differ in sample data format and/or number of channels).

store : Sample store to get size of
bytes : Pointer to store data size in bytes (samples * sample format * channels) or NULL
Returns : Sample size in frames

ipatch_sample_store_get_frame_size ()

guint               ipatch_sample_store_get_frame_size  (IpatchSampleStore *store);

Get the size of a single audio frame in a sample store (bit width * channels).

store : Sample store object
Returns : Frame size in bytes.

ipatch_sample_store_is_readable ()

gboolean            ipatch_sample_store_is_readable     (IpatchSampleStore *store);

Checks if a sample store is readable. Only checks if sample store would be readable under normal conditions (i.e., internal parameters are not verified).

store : Sample store to check if readable
Returns : TRUE if sample store has read capability, FALSE otherwise

ipatch_sample_store_is_writable ()

gboolean            ipatch_sample_store_is_writable     (IpatchSampleStore *store);

Checks if a sample store is writable. Only checks if sample store would be writable under normal conditions (i.e., internal parameters are not verified).

store : Sample store to check if writable
Returns : TRUE if sample store has write capability, FALSE otherwise

ipatch_sample_store_get_speed ()

int                 ipatch_sample_store_get_speed       (IpatchSampleStore *store);

Gets the speed rating value for the type of sample store. This value is a number between 1-10 (1 = slowest, 10 = fastest) and rates how fast the storage method is (3 = hard disk, 9 = RAM, etc). This value is used to prioritize when there are multiple stores of the same sample data.

store : Sample store object
Returns : Speed rating of the sample store.

ipatch_sample_store_alloc ()

gboolean            ipatch_sample_store_alloc           (IpatchSampleStore *store,
                                                         GError **err);

Allocates space for sample data by calling the "alloc" method of a sample store's class. Can only be called on an in-active sample store, and should only be called once. Sample stores cannot be explicitly freed, only removed (store is freed after all references are relinquished).

store : Sample store to allocate sample data space for
err : Pointer to store error information or NULL
Returns : TRUE on success, FALSE on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_read ()

gboolean            ipatch_sample_store_read            (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         void *buf,
                                                         GError **err);

Reads sample data from a sample store by calling the "read" method of a sample store's class. A sample store does not need to be active, but its parameters should be correctly configured.

store : Sample store to read samples from
offset : Offset, in frames, to start read from
frames : Number of sample frames to read
buf : Buffer to fill with sample data that can hold at least frames * ipatch_sample_store_get_frame_size() bytes.
err : Pointer to store error information or NULL
Returns : TRUE on success, FALSE on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_write ()

gboolean            ipatch_sample_store_write           (IpatchSampleStore *store,
                                                         guint offset,
                                                         guint frames,
                                                         const void *buf,
                                                         GError **err);

Writes sample data from a sample store by calling the "write" method of a sample store's class.

store : Sample store to write samples to
offset : Offset, in frames, to start writing
frames : Number of sample frames to write
buf : Buffer of sample data to write with frames * ipatch_sample_store_get_frame_size() bytes of data.
err : Pointer to store error information or NULL
Returns : TRUE on success, FALSE on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_transform_new ()

IpatchSampleTransform* ipatch_sample_store_transform_new
                                                        (IpatchSampleStore *store,
                                                         int format,
                                                         guint frames,
                                                         gboolean is_read);

Creates a sample transform for converting between a sample store and another sample format and allocate buffers to process a maximum number of frames.

store : Sample store object
format : Source/Destination sample format depending on value of is_read. See ipatch_sample_transform_set_formats() for more details.
frames : Max number of frames to allocate buffers for
is_read : TRUE for read mode (store is the source, format is the destination), FALSE for write mode (store is destination, format is source).
Returns : New sample transform with a refcount of 1 which the caller owns.

ipatch_sample_store_transform_init ()

void                ipatch_sample_store_transform_init  (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         int format,
                                                         guint frames,
                                                         gboolean is_read);

Like ipatch_sample_store_transform_new() but initializes an existing IpatchSampleTransform object.

store : Sample store object
trans : Sample data transform object to initialize
format : Source/Destination sample format depending on value of is_read. See ipatch_sample_transform_set_formats() for more details.
frames : Max number of frames to allocate buffers for
is_read : TRUE for read mode (store is the source, format is the destination), FALSE for write mode (store is destination, format is source).

ipatch_sample_store_transform_init_size ()

int                 ipatch_sample_store_transform_init_size
                                                        (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         int format,
                                                         guint size,
                                                         gboolean is_read);

Like ipatch_sample_store_transform_init() but allocates for a specific size rather than a frame count.

store : Sample store object
trans : Sample data transform object to initialize
format : Source/Destination sample format depending on value of is_read. See ipatch_sample_transform_set_formats() for more details.
size : Total size to allocate for transform buffers
is_read : TRUE for read mode (store is the source, format is the destination), FALSE for write mode (store is destination, format is source).
Returns : Max number of frames that can be converted at a time

ipatch_sample_store_transform_read ()

gpointer            ipatch_sample_store_transform_read  (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         guint offset,
                                                         guint frames,
                                                         GError **err);

Read from a sample store and transform the data to the destination format of trans. trans object must have been created or initialized with ipatch_sample_store_transform_new() or ipatch_sample_transform_init() respectively with is_read parameter set to TRUE and frames should not exceed the number of frames the transform was initialized to.

store : Sample store object
trans : Initialized sample data transform object
offset : Offset in sample store to read from, in frames
frames : Number of sample frames to read
err : Pointer to store error information or NULL
Returns : Pointer to converted sample data or NULL on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_transform_write ()

gboolean            ipatch_sample_store_transform_write (IpatchSampleStore *store,
                                                         IpatchSampleTransform *trans,
                                                         guint offset,
                                                         guint frames,
                                                         GError **err);

Write to a sample store transforming the data from the source format of trans. trans object must have been created or initialized with ipatch_sample_store_transform_new() or ipatch_sample_transform_init() respectively with is_read parameter set to FALSE. The first buffer of trans should contain frames samples of the source format.

store : Sample store object
trans : Initialized sample data transform object
offset : Offset in sample store to write to, in frames
frames : Number of sample frames to write
err : Pointer to store error information or NULL
Returns : TRUE on success, FALSE on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_copy ()

gboolean            ipatch_sample_store_copy            (IpatchSampleStore *dest_store,
                                                         IpatchSampleStore *src_store,
                                                         GError **err);

Copy data from one sample store to another. Parent destination sample data object must be at least the size of the source sample data object. Sample formats may differ in which case conversion will be performed.

dest_store : Destination sample store
src_store : Source sample store
err : Pointer to store error information or NULL
Returns : TRUE on success, FALSE on error in which case error information is returned in err provided it isn't NULL.

ipatch_sample_store_duplicate ()

IpatchSampleStore*  ipatch_sample_store_duplicate       (IpatchSampleStore *store,
                                                         GType new_type,
                                                         int new_format,
                                                         GError **err);

Duplicate a sample store within the same sample data object. The new store is not activated. The caller owns a reference to the new sample store and should remove it with g_object_unref when finished with it.

store : Sample store to duplicate
new_type : IpatchSampleStore derived type of new store to create
new_format : New sample format or 0 to use source store format
err : Location to store error information
Returns : The new inactive store with duplicated sample data or NULL on error, in which case err may contain error information provided its not NULL. Remember to unref the store when finished with it.

ipatch_sample_store_TRUE ()

gboolean            ipatch_sample_store_TRUE            (IpatchSampleStore *store);

A function that just returns TRUE. Useful for IpatchSampleStore derived types for constant "readable" and "writable" methods.

store : Sample store
Returns : TRUE

ipatch_sample_store_FALSE ()

gboolean            ipatch_sample_store_FALSE           (IpatchSampleStore *store);

A function that just returns FALSE. Useful for IpatchSampleStore derived types for constant "readable" and "writable" methods.

store : Sample store
Returns : FALSE

Property Details

The "active" property

  "active"                   gboolean              : Read / Write

Is sample store active?

Default value: FALSE


The "channels" property

  "channels"                 gint                  : Read / Write

Audio channels.

Allowed values: [1,2]

Default value: 1


The "format" property

  "format"                   gint                  : Read / Write

Complete sample format integer.

Allowed values: >= 0

Default value: 2


The "lil-endian" property

  "lil-endian"               gboolean              : Read / Write

Little endian byte order.

Default value: TRUE


The "signed" property

  "signed"                   gboolean              : Read / Write

Signed data format.

Default value: TRUE


The "width" property

  "width"                    IpatchSampleWidth     : Read / Write

Sample store bit width enumeration.

Default value: IPATCH_SAMPLE_16BIT

See Also

IpatchSampleData