![]() |
![]() |
![]() |
libInstPatch Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----IpatchItem +----IpatchSampleStore +----IpatchSampleStoreFile +----IpatchSampleStoreRAM +----IpatchSampleStoreROM
"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
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.
gboolean (*IpatchSampleStoreVerifyFunc) (IpatchSampleStore *store);
IpatchSampleStore class method function type to verify a sample store's internal state.
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.
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.
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 ).
|
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 ).
|
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).
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).
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. |
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;
#define IPATCH_SAMPLE_STORE_FORMAT_SHIFT IPATCH_ITEM_UNUSED_FLAG_SHIFT
typedef enum /*< flags >*/ { IPATCH_SAMPLE_STORE_ACTIVE = 1 << (IPATCH_SAMPLE_STORE_FORMAT_SHIFT + IPATCH_SAMPLE_FORMAT_BITCOUNT) } IpatchSampleStoreFlags;
IpatchItem flags for sample store objects.
#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
|
#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.
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.
|
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.
|
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 |
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.
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 |
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). |
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 |
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. |
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).
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).
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 .
|
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).
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 .
|
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 .
|
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. |
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).
|
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 |
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 .
|
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 .
|
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.
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.
|
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
|
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
|
channels
" property"channels" gint : Read / Write
Audio channels.
Allowed values: [1,2]
Default value: 1
format
" property"format" gint : Read / Write
Complete sample format integer.
Allowed values: >= 0
Default value: 2
lil-endian
" property"lil-endian" gboolean : Read / Write
Little endian byte order.
Default value: TRUE
width
" property"width" IpatchSampleWidth : Read / Write
Sample store bit width enumeration.
Default value: IPATCH_SAMPLE_16BIT