## IpatchSample

IpatchSample — Sample audio interface

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSample;
                        IpatchSampleIface;
                        IpatchSampleHandle;
    gboolean            (*IpatchSampleHandleOpenFunc)       (IpatchSampleHandle *handle,
                                                             GError **err);
    void                (*IpatchSampleHandleCloseFunc)      (IpatchSampleHandle *handle);
    gboolean            (*IpatchSampleHandleReadFunc)       (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);
    gboolean            (*IpatchSampleHandleWriteFunc)      (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);
    enum                IpatchSampleLoopType;
    #define             IPATCH_SAMPLE_FORMAT_DEFAULT
    #define             IPATCH_SAMPLE_RATE_MIN
    #define             IPATCH_SAMPLE_RATE_MAX
    #define             IPATCH_SAMPLE_RATE_DEFAULT
    #define             IPATCH_SAMPLE_ROOT_NOTE_DEFAULT
    #define             IPATCH_SAMPLE_LOOP_TYPE_TERM
    #define             IPATCH_SAMPLE_HANDLE_FORMAT         (handle)
    int *               ipatch_sample_get_loop_types        (IpatchSample *sample);
    int *               ipatch_sample_type_get_loop_types   (GType type);
    void                ipatch_sample_set_format            (IpatchSample *sample,
                                                             int format);
    int                 ipatch_sample_get_format            (IpatchSample *sample);
    void                ipatch_sample_set_size              (IpatchSample *sample,
                                                             guint size);
    guint               ipatch_sample_get_size              (IpatchSample *sample,
                                                             guint *bytes);
    int                 ipatch_sample_get_frame_size        (IpatchSample *sample);
    IpatchSampleData *  ipatch_sample_get_sample_data       (IpatchSample *sample);
    gboolean            ipatch_sample_set_sample_data       (IpatchSample *sample,
                                                             IpatchSampleData *sampledata);
    gboolean            ipatch_sample_read                  (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);
    gboolean            ipatch_sample_write                 (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);
    gboolean            ipatch_sample_read_transform        (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    gboolean            ipatch_sample_write_transform       (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    gboolean            ipatch_sample_copy                  (IpatchSample *dest_sample,
                                                             IpatchSample *src_sample,
                                                             guint32 channel_map,
                                                             GError **err);
    gboolean            ipatch_sample_save_to_file          (IpatchSample *sample,
                                                             const char *filename,
                                                             int file_format,
                                                             int sub_format,
                                                             GError **err);
    gboolean            ipatch_sample_handle_open           (IpatchSample *sample,
                                                             IpatchSampleHandle *handle,
                                                             char mode,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);
    void                ipatch_sample_handle_close          (IpatchSampleHandle *handle);
    IpatchSampleTransform * ipatch_sample_handle_get_transform
                                                            (IpatchSampleHandle *handle);
    void                ipatch_sample_handle_set_transform  (IpatchSampleHandle *handle,
                                                             IpatchSampleTransform *transform);
    int                 ipatch_sample_handle_get_format     (IpatchSampleHandle *handle);
    int                 ipatch_sample_handle_get_frame_size (IpatchSampleHandle *handle);
    guint               ipatch_sample_handle_get_max_frames (IpatchSampleHandle *handle);
    gpointer            ipatch_sample_handle_read           (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);
    gboolean            ipatch_sample_handle_write          (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);
    gboolean            ipatch_sample_handle_cascade_open   (IpatchSampleHandle *handle,
                                                             IpatchSample *sample,
                                                             GError **err);
    GParamSpec *        ipatch_sample_install_property      (GObjectClass *oclass,
                                                             guint property_id,
                                                             const char *property_name);
    GParamSpec *        ipatch_sample_install_property_readonly
                                                            (GObjectClass *oclass,
                                                             guint property_id,
                                                             const char *property_name);
    GParamSpec *        ipatch_sample_new_property_param_spec
                                                            (const char *property_name,
                                                             GParamFlags flags);

## Object Hierarchy

      GInterface
       +----IpatchSample

## Prerequisites

IpatchSample requires IpatchItem.

## Known Implementations

IpatchSample is implemented by IpatchSampleStoreCache, IpatchSampleStoreRom, IpatchGigSample, IpatchSampleStoreSplit24, IpatchDLS2Region, IpatchSampleStoreRam, IpatchSampleStore, IpatchSampleStoreFile, IpatchSampleData, IpatchDLS2Sample, IpatchGigSubRegion, IpatchSampleStoreSwap, IpatchSF2IZone, IpatchSampleStoreSndFile, IpatchSampleStoreVirtual and IpatchSF2Sample.

## Properties

      "fine-tune"                gint                  : Read
      "loop-end"                 guint                 : Read
      "loop-start"               guint                 : Read
      "loop-type"                IpatchSampleLoopType  : Read
      "root-note"                gint                  : Read
      "sample-data"              IpatchSampleData*     : Read
      "sample-format"            gint                  : Read
      "sample-rate"              gint                  : Read
      "sample-size"              guint                 : Read

## Description

This interface provides a basic API for accessing audio of sample objects.

## Details

### IpatchSample

    typedef struct _IpatchSample IpatchSample;

### IpatchSampleIface

    typedef struct {
      GTypeInterface parent_class;

      IpatchSampleHandleOpenFunc open;
      IpatchSampleHandleCloseFunc close;
      IpatchSampleHandleReadFunc read;
      IpatchSampleHandleWriteFunc write;

      int *loop_types; /* -1 terminated array of supp. loop types (NULL = none) */
    } IpatchSampleIface;

### IpatchSampleHandle

    typedef struct {
      IpatchSample *sample;		      /* The sample which this handle applies to */
      IpatchSampleTransform *transform;   /* Set if sample is being converted */
      IpatchSampleHandleReadFunc read;    /* Read method pointer (copied from IpatchItem interface) */
      IpatchSampleHandleWriteFunc write;  /* Write method pointer (copied from IpatchItem interface) */
      IpatchSampleHandleCloseFunc close;  /* Write method pointer (copied from IpatchItem interface) */
      guint32 read_mode : 1;              /* TRUE if read mode, FALSE if write mode */
      guint32 manual_transform : 1;       /* Methods handle sample transform */
      guint32 release_transform : 1;      /* TRUE if transform should be released from transform pool */
      guint32 format : 12;                /* Format to transform to */
      guint32 reserved : 17;
      guint32 channel_map;                /* Channel map for multi-channel audio transform */
      gpointer data1;		      /* sample interface defined */
      gpointer data2;		      /* sample interface defined */
      gpointer data3;		      /* sample interface defined */
      gpointer data4;		      /* sample interface defined */
      guint32 reserved2;
    } IpatchSampleHandle;

### IpatchSampleHandleOpenFunc ()

    gboolean            (*IpatchSampleHandleOpenFunc)       (IpatchSampleHandle *handle,
                                                             GError **err);

IpatchSample interface method function type to open a sample for reading or writing. This method is optional for an IpatchSample interface and if not specified then it is assumed that the open was successful and nothing additional need be done. All fields of `handle` structure are already initialized, except `data1`, `data2` and `data3` which are available for the interface implementation.

`handle` : | Caller supplied structure to initialize
`err` : | Location to store error information
Returns : | `TRUE` on success, `FALSE` otherwise (in which case an error should optionally be stored in `err`).

### IpatchSampleHandleCloseFunc ()

    void                (*IpatchSampleHandleCloseFunc)      (IpatchSampleHandle *handle);

IpatchSample interface method to free any resources allocated in IpatchSampleOpenFunc to `handle`. This method is optional for an IpatchSample interface and need not be specified if nothing needs to be done to release any resources allocated by IpatchSampleHandleOpenFunc.

`handle` : | Sample handle to close (as returned from IpatchSampleHandleOpenFunc)

### IpatchSampleHandleReadFunc ()

    gboolean            (*IpatchSampleHandleReadFunc)       (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);

IpatchSample interface method function type to read data from a sample handle. Can be `NULL` in IpatchSampleIface if sample data is not readable. Sample data should be stored in its native format.

`handle` : | Handle to read from (as returned from IpatchSampleOpenFunc)
`offset` : | Offset in sample to start read from (in frames), use IPATCH_SAMPLE_CUROFS to use current offset (starts at 0 if not specified)
`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`).

### IpatchSampleHandleWriteFunc ()

    gboolean            (*IpatchSampleHandleWriteFunc)      (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);

IpatchSample interface method function type to write data to a sample handle. Can be `NULL` in IpatchSampleIface if sample data is not writable. Sample data will be supplied in its native format.

`handle` : | Handle to write to (as returned from IpatchSampleOpenFunc)
`offset` : | Offset in sample to start write to (in frames), use IPATCH_SAMPLE_CUROFS to use current offset (starts at 0 if not specified)
`frames` : | Size of sample data to write (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`).

### enum IpatchSampleLoopType

    typedef enum
    {
      IPATCH_SAMPLE_LOOP_NONE,
      IPATCH_SAMPLE_LOOP_STANDARD,
      IPATCH_SAMPLE_LOOP_RELEASE,
      IPATCH_SAMPLE_LOOP_PINGPONG
    } IpatchSampleLoopType;

Sample looping type.

`IPATCH_SAMPLE_LOOP_NONE` | No loop.
`IPATCH_SAMPLE_LOOP_STANDARD` | Standard loop.
`IPATCH_SAMPLE_LOOP_RELEASE` | Loop till note release stage.
`IPATCH_SAMPLE_LOOP_PINGPONG` | Play forward and then in reverse continously.

### IPATCH_SAMPLE_FORMAT_DEFAULT

    #define             IPATCH_SAMPLE_FORMAT_DEFAULT

Default sample format for IpatchSample interface.

### IPATCH_SAMPLE_RATE_MIN

    #define IPATCH_SAMPLE_RATE_MIN     8000

Minimum sample rate.

### IPATCH_SAMPLE_RATE_MAX

    #define IPATCH_SAMPLE_RATE_MAX     192000

Maximum sample rate.

### IPATCH_SAMPLE_RATE_DEFAULT

    #define IPATCH_SAMPLE_RATE_DEFAULT 44100

Default sample rate.

### IPATCH_SAMPLE_ROOT_NOTE_DEFAULT

    #define IPATCH_SAMPLE_ROOT_NOTE_DEFAULT  60

Default root note.

### IPATCH_SAMPLE_LOOP_TYPE_TERM

    #define IPATCH_SAMPLE_LOOP_TYPE_TERM (-1)

Value used for terminating list of supported loop types.

### IPATCH_SAMPLE_HANDLE_FORMAT()

    #define IPATCH_SAMPLE_HANDLE_FORMAT(handle)  ((handle)->format)

Macro to access transform sample format of a sample handle.

`handle` : | Sample handle
Returns : | Sample transform format.

### ipatch_sample_get_loop_types ()

    int *               ipatch_sample_get_loop_types        (IpatchSample *sample);

Get an array of supported loop type enums for a sample object.

`sample` : | Object with IpatchSample interface
Returns : | -1 terminated array of IpatchSampleLoopType values. If no loop types are supported, then `NULL` is returned. Array is internal and should not be modified or freed.

### ipatch_sample_type_get_loop_types ()

    int *               ipatch_sample_type_get_loop_types   (GType type);

Like `ipatch_sample_get_loop_types()` but retrieves the supported loop types from an object type rather than an instance of an object.

`type` : | A GType that has a IpatchItem interface
Returns : | -1 terminated array of IpatchSampleLoopType values. If no loop types are supported, then `NULL` is returned. Array is internal and should not be modified or freed.

### ipatch_sample_set_format ()

    void                ipatch_sample_set_format            (IpatchSample *sample,
                                                             int format);

Set sample format of a new sample. Should only be assigned once. Same as assigning to a sample's "sample-format" property.

`sample` : | Sample to set format of
`format` : | Sample format to assign to sample (see IpatchSampleWidth, etc)

### ipatch_sample_get_format ()

    int                 ipatch_sample_get_format            (IpatchSample *sample);

Get the sample format of a sample. Same as getting a sample's "sample-format" property.

`sample` : | Sample to get format of
Returns : | Sample format integer (see IpatchSampleWidth, etc).

### ipatch_sample_set_size ()

    void                ipatch_sample_set_size              (IpatchSample *sample,
                                                             guint size);

Set the size of a sample. Should be done once, and only once when created.

`sample` : | Sample to set size of
`size` : | Size to assign (in frames)

### ipatch_sample_get_size ()

    guint               ipatch_sample_get_size              (IpatchSample *sample,
                                                             guint *bytes);

Get the size of a sample. Same as getting a sample's "sample-size" property.

`sample` : | Sample to get size of
`bytes` : | Location to store sample size in bytes (size * frame size) or NULL to ignore
Returns : | Sample size (in frames)

### ipatch_sample_get_frame_size ()

    int                 ipatch_sample_get_frame_size        (IpatchSample *sample);

A convenience function to get size of a single sample frame for a given `sample`. This is useful for determining buffer allocation sizes when reading or writing data.

`sample` : | Sample to get data frame size of
Returns : | Size in bytes of a single sample frame

### ipatch_sample_get_sample_data ()

    IpatchSampleData *  ipatch_sample_get_sample_data       (IpatchSample *sample);

Get sample data object from a sample. Not every sample object supports this property, in which case `NULL` is returned.

`sample` : | Sample to get sample data from
Returns : | Sample data object of the sample or `NULL` if not set or unsupported by this sample type. Caller owns a reference to the returned object.

### ipatch_sample_set_sample_data ()

    gboolean            ipatch_sample_set_sample_data       (IpatchSample *sample,
                                                             IpatchSampleData *sampledata);

Set sample data object of a sample. Not every sample object supports writing to this property, in which case `FALSE` will be returned.

`sample` : | Sample to set sample data of
Returns : | `TRUE` if the sample supports this property and it was assigned, `FALSE` otherwise.

### ipatch_sample_read ()

    gboolean            ipatch_sample_read                  (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);

Read sample data from a sample. This is a convenience function which opens/reads/closes a IpatchSampleHandle and is therefore not as efficient when making multiple accesses. Sample data transform is also not handled (see `ipatch_sample_read_transform()`).

`sample` : | Sample to read from
`offset` : | Offset in frames to read from
`frames` : | Number of frames to read
`buf` : | Buffer to store sample data in (should be at least `frames` * sizeof (frame), the frame size can be had from `ipatch_sample_get_frame_size()`).
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### ipatch_sample_write ()

    gboolean            ipatch_sample_write                 (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);

Write sample data to a sample. This is a convenience function which opens/writes/closes a IpatchSampleHandle and is therefore not as efficient when making multiple accesses. Sample data transform is also not handled (see `ipatch_sample_write_transform()`).

`sample` : | Sample to write to
`offset` : | Offset in frames to write to
`frames` : | Number of frames to write
`buf` : | Buffer of sample data to write (should be at least `frames` * sizeof (frame), the frame size can be had from `ipatch_sample_get_frame_size()`).
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_sample_read_transform ()

    gboolean            ipatch_sample_read_transform        (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

Like `ipatch_sample_read()` but allows for sample transformation.

`sample` : | Sample to read from
`offset` : | Offset in frames to read from
`frames` : | Number of frames to read
`buf` : | Buffer to store sample data in (should be at least `frames` * `ipatch_sample_format_size()` of `format`).
`format` : | Format to transform sample data to (if its the same as the native format of `sample` no transformation occurs)
`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 info or `NULL`
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### ipatch_sample_write_transform ()

    gboolean            ipatch_sample_write_transform       (IpatchSample *sample,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

Like `ipatch_sample_write()` but allows for sample transformation.

`sample` : | Sample to write to
`offset` : | Offset in frames to write to
`frames` : | Number of frames to write
`buf` : | Buffer of sample data to write (should be at least `frames` * `ipatch_sample_format_size()` of `format`).
`format` : | Format to transform sample data from (if its the same as the native format of `sample` no transformation occurs)
`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 info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_sample_copy ()

    gboolean            ipatch_sample_copy                  (IpatchSample *dest_sample,
                                                             IpatchSample *src_sample,
                                                             guint32 channel_map,
                                                             GError **err);

Copy sample data from one sample to another. The two samples may differ in format, in which case the sample data will be converted. The `dest_sample` must either be the same size in frames as `src_sample` or not yet assigned a size.

`dest_sample` : | Destination sample to copy data to
`src_sample` : | Source sample to copy data from
`channel_map` : | Channel mapping, 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 or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_sample_save_to_file ()

    gboolean            ipatch_sample_save_to_file          (IpatchSample *sample,
                                                             const char *filename,
                                                             int file_format,
                                                             int sub_format,
                                                             GError **err);

Convenience function to save a sample to a file using libsndfile.

`sample` : | Sample to save to file
`filename` : | File name to save to
`file_format` : | A value from the dynamic GEnum "IpatchSndFileFormat".
`sub_format` : | A value from the dynamic GEnum "IpatchSndFileSubFormat" or -1 to calculate optimal value based on the format of `sample`.
`err` : | Location to store error info or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` otherwise

### ipatch_sample_handle_open ()

    gboolean            ipatch_sample_handle_open           (IpatchSample *sample,
                                                             IpatchSampleHandle *handle,
                                                             char mode,
                                                             int format,
                                                             guint32 channel_map,
                                                             GError **err);

Open a handle to a sample for reading or writing sample data. Can optionally provide data conversion if `format` is set. If it is desirable to have more control over the transform object and buffer allocation, the transform object can be assigned with `ipatch_sample_handle_set_transform()`. Note that a sample transform is acquired if `format` is set, even if the format is identical to the `sample` format, as a convenience to always provide a data buffer.

`sample` : | Sample to open a handle to
`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_handle_close ()

    void                ipatch_sample_handle_close          (IpatchSampleHandle *handle);

Close a handle previously opened with `ipatch_sample_handle_open()`.

`handle` : | Sample handle to close

### ipatch_sample_handle_get_transform ()

    IpatchSampleTransform * ipatch_sample_handle_get_transform
                                                            (IpatchSampleHandle *handle);

Get sample transform from a sample handle. Only exists if sample data conversion is taking place or even if formats are the same but was implicitly supplied to `ipatch_sample_handle_open()`. Transform should not be modified unless it was assigned via `ipatch_sample_handle_set_transform()`.

`handle` : | Sample handle to get transform from
Returns : | Sample transform or `NULL` if none.

### ipatch_sample_handle_set_transform ()

    void                ipatch_sample_handle_set_transform  (IpatchSampleHandle *handle,
                                                             IpatchSampleTransform *transform);

Assign a sample transform to a sample handle. Provided for added control over `transform` allocation. A transform can also be automatically created and assigned with `ipatch_sample_handle_open()`. Sample transform allocation is taken over by `handle`.

`handle` : | Sample handle to set transform of
`transform` : | Transform to assign, source format must match that of the handle's sample (read mode) or destination format must match (write mode), can be `NULL` to de-activate sample transformation for `handle`.

### ipatch_sample_handle_get_format ()

    int                 ipatch_sample_handle_get_format     (IpatchSampleHandle *handle);

Get the sample format of a sample handle. May differ from the IpatchSample format of the handle, if it was opened with a different format and is therefore being converted.

`handle` : | Sample handle to get format of
Returns : | Sample format integer (see IpatchSampleWidth, etc).

### ipatch_sample_handle_get_frame_size ()

    int                 ipatch_sample_handle_get_frame_size (IpatchSampleHandle *handle);

A convenience function to get size of a single sample frame for a given sample `handle`. This is useful for determining buffer allocation sizes when reading or writing data.

`handle` : | Sample handle to get data frame size of
Returns : | Size in bytes of a single sample frame

### ipatch_sample_handle_get_max_frames ()

    guint               ipatch_sample_handle_get_max_frames (IpatchSampleHandle *handle);

A convenience function to get the maximum transform frames that can fit in the sample transform of `handle`.

`handle` : | Sample handle to get max transform frames of
Returns : | Maximum frames that can be read or written using the sample transform buffers. 0 if no sample transform is assigned.

### ipatch_sample_handle_read ()

    gpointer            ipatch_sample_handle_read           (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gpointer buf,
                                                             GError **err);

Read sample data from a sample handle. If the number of frames read is within the sample transform buffer size and `buf` is `NULL` then the transform buffer will be returned (extra copy not needed).

`handle` : | Sample handle
`offset` : | Offset in frames to read from
`frames` : | Number of frames to read
`buf` : | Buffer to store sample data in (should be at least `frames` * sizeof (frame), the frame size can be had from `ipatch_sample_handle_get_frame_size()`). Can be `NULL` if transforming audio data with not more than the maximum frames that can be transformed at a time, in which case the internal transform buffer pointer will be returned.
`err` : | Location to store error info or `NULL`
Returns : | Pointer to sample data on success, `NULL` on error (in which case `err` may be set). The internal transform buffer will only be returned if the `buf` parameter is `NULL`.

### ipatch_sample_handle_write ()

    gboolean            ipatch_sample_handle_write          (IpatchSampleHandle *handle,
                                                             guint offset,
                                                             guint frames,
                                                             gconstpointer buf,
                                                             GError **err);

Write sample data to a sample handle.

`handle` : | Sample handle
`offset` : | Offset in frames to write to
`frames` : | Number of frames to write
`buf` : | Buffer of sample data to write (should be at least `frames` * sizeof (frame), the frame size can be had from `ipatch_sample_handle_get_frame_size()`). Can be `NULL`, in which case it is assumed that the sample data has been loaded into the first buffer of the handle's sample transform.
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_sample_handle_cascade_open ()

    gboolean            ipatch_sample_handle_cascade_open   (IpatchSampleHandle *handle,
                                                             IpatchSample *sample,
                                                             GError **err);

This can be called from IpatchSampleIface.open methods for objects which contain a pointer to an IpatchSample that contains the sample's data.

`handle` : | Already open handle
`sample` : | The cascade sample containing the actual data
`err` : | Location to store error information
Returns : | `TRUE` on success, `FALSE` on failure (in which case `err` may be set)

### ipatch_sample_install_property ()

    GParamSpec *        ipatch_sample_install_property      (GObjectClass *oclass,
                                                             guint property_id,
                                                             const char *property_name);

A helper function for objects that have an IpatchSample interface. Installs a IpatchSample interface property for the given object class. The parameter will be G_PARAM_READWRITE.

`oclass` : | Object class to install IpatchSample property
`property_id` : | Property ID for set/get property class method
`property_name` : | IpatchSample property name to install
Returns : | The newly created and installed parameter spec.

### ipatch_sample_install_property_readonly ()

    GParamSpec *        ipatch_sample_install_property_readonly
                                                            (GObjectClass *oclass,
                                                             guint property_id,
                                                             const char *property_name);

A helper function for objects that have an IpatchSample interface. Identical to `ipatch_sample_install_property()` but installs the property as readonly and uses `g_object_class_override_property()` instead of creating a new GParamSpec.

`oclass` : | Object class to install IpatchSample property
`property_id` : | Property ID for set/get property class method
`property_name` : | IpatchSample property name to install
Returns : | The newly created and installed parameter spec (GParamSpecOverride).

### ipatch_sample_new_property_param_spec ()

    GParamSpec *        ipatch_sample_new_property_param_spec
                                                            (const char *property_name,
                                                             GParamFlags flags);

Seldom used function that creates a new GParamSpec that is identical to a IpatchSample property by the name `property_name`, except the flags can differ.

`property_name` : | Name of a IpatchSample property
`flags` : | Flags to use for the new GParamSpec
Returns : | New GParamSpec.

## Property Details

### The `"fine-tune"` property

      "fine-tune"                gint                  : Read

Fine tuning in cents.

Allowed values: [-99,99]

Default value: 0

### The `"loop-end"` property

      "loop-end"                 guint                 : Read

Loop end in frames (after loop).

Default value: 0

### The `"loop-start"` property

      "loop-start"               guint                 : Read

Start of loop in frames.

Default value: 0

### The `"loop-type"` property

      "loop-type"                IpatchSampleLoopType  : Read

Loop method type.

Default value: IPATCH_SAMPLE_LOOP_NONE

### The `"root-note"` property

      "root-note"                gint                  : Read

Root MIDI note.

Allowed values: [0,127]

Default value: 60

### The `"sample-data"` property

      "sample-data"              IpatchSampleData*     : Read

Sample data.

### The `"sample-format"` property

      "sample-format"            gint                  : Read

Sample format.

Allowed values: >= 0

Default value: 2

### The `"sample-rate"` property

      "sample-rate"              gint                  : Read

Sampling rate in Hertz.

Allowed values: [8000,192000]

Default value: 44100

### The `"sample-size"` property

      "sample-size"              guint                 : Read

Size in frames.

Default value: 0