## IpatchSF2Sample

IpatchSF2Sample — SoundFont audio sample

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSF2Sample;
    enum                IpatchSF2SampleChannel;
    #define             IPATCH_SF2_SAMPLE_RATE_MIN
    #define             IPATCH_SF2_SAMPLE_RATE_MAX
    #define             IPATCH_SF2_SAMPLE_LENGTH_MIN
    #define             IPATCH_SF2_SAMPLE_FLAG_ROM
    #define             IPATCH_SAMPLE_UNUSED_FLAG_SHIFT
    IpatchSF2Sample *   ipatch_sf2_sample_new               (void);
    IpatchSF2Sample *   ipatch_sf2_sample_first             (IpatchIter *iter);
    IpatchSF2Sample *   ipatch_sf2_sample_next              (IpatchIter *iter);
    void                ipatch_sf2_sample_set_name          (IpatchSF2Sample *sample,
                                                             const char *name);
    char *              ipatch_sf2_sample_get_name          (IpatchSF2Sample *sample);
    void                ipatch_sf2_sample_set_data          (IpatchSF2Sample *sample,
                                                             IpatchSampleData *sampledata);
    IpatchSampleData *  ipatch_sf2_sample_get_data          (IpatchSF2Sample *sample);
    IpatchSampleData *  ipatch_sf2_sample_peek_data         (IpatchSF2Sample *sample);
    void                ipatch_sf2_sample_set_linked        (IpatchSF2Sample *sample,
                                                             IpatchSF2Sample *linked);
    IpatchSF2Sample *   ipatch_sf2_sample_get_linked        (IpatchSF2Sample *sample);
    IpatchSF2Sample *   ipatch_sf2_sample_peek_linked       (IpatchSF2Sample *sample);
    void                ipatch_sf2_sample_set_blank         (IpatchSF2Sample *sample);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchSF2Sample

## Implemented Interfaces

IpatchSF2Sample implements IpatchSample.

## Properties

      "channel"                  IpatchSF2SampleChannel  : Read / Write
      "fine-tune"                gint                  : Read / Write
      "linked-sample"            IpatchSF2Sample*      : Read / Write
      "loop-end"                 guint                 : Read / Write
      "loop-start"               guint                 : Read / Write
      "name"                     gchar*                : Read / Write
      "rom"                      gboolean              : Read / Write
      "root-note"                gint                  : Read / Write
      "sample-data"              IpatchSampleData*     : Read / Write
      "sample-rate"              gint                  : Read / Write

## Description

SoundFont samples are children of IpatchSF2 objects and are referenced by IpatchSF2IZone objects. They define the audio which is synthesized.

## Details

### IpatchSF2Sample

    typedef struct _IpatchSF2Sample IpatchSF2Sample;

### enum IpatchSF2SampleChannel

    typedef enum
    {
      IPATCH_SF2_SAMPLE_CHANNEL_MONO,
      IPATCH_SF2_SAMPLE_CHANNEL_LEFT,
      IPATCH_SF2_SAMPLE_CHANNEL_RIGHT
    } IpatchSF2SampleChannel;

Sample channel orientation.

`IPATCH_SF2_SAMPLE_CHANNEL_MONO` | Mono sample
`IPATCH_SF2_SAMPLE_CHANNEL_LEFT` | Left channel of a stereo pair ("linked-sample" will be set to the right channel)
`IPATCH_SF2_SAMPLE_CHANNEL_RIGHT` | Right channel of a stereo pair ("linked-sample" will be set to the left channel)

### IPATCH_SF2_SAMPLE_RATE_MIN

    #define IPATCH_SF2_SAMPLE_RATE_MIN	400 /* min sample rate (by standard) */

### IPATCH_SF2_SAMPLE_RATE_MAX

    #define IPATCH_SF2_SAMPLE_RATE_MAX	50000 /* max rate (by the standard) */

### IPATCH_SF2_SAMPLE_LENGTH_MIN

    #define IPATCH_SF2_SAMPLE_LENGTH_MIN	32 /* min length (by the standard) */

### IPATCH_SF2_SAMPLE_FLAG_ROM

    #define IPATCH_SF2_SAMPLE_FLAG_ROM  (1 << IPATCH_ITEM_UNUSED_FLAG_SHIFT)

### IPATCH_SAMPLE_UNUSED_FLAG_SHIFT

    #define             IPATCH_SAMPLE_UNUSED_FLAG_SHIFT

### ipatch_sf2_sample_new ()

    IpatchSF2Sample *   ipatch_sf2_sample_new               (void);

Create a new SoundFont sample object.

Returns : | New SoundFont sample 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_sf2_sample_first ()

    IpatchSF2Sample *   ipatch_sf2_sample_first             (IpatchIter *iter);

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

`iter` : | Patch item iterator containing IpatchSF2Sample items
Returns : | The first sample in `iter` or `NULL` if empty.

### ipatch_sf2_sample_next ()

    IpatchSF2Sample *   ipatch_sf2_sample_next              (IpatchIter *iter);

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

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

### ipatch_sf2_sample_set_name ()

    void                ipatch_sf2_sample_set_name          (IpatchSF2Sample *sample,
                                                             const char *name);

Sets the name of a SoundFont sample.

`sample` : | Sample to set name of
`name` : | Value to set name to

### ipatch_sf2_sample_get_name ()

    char *              ipatch_sf2_sample_get_name          (IpatchSF2Sample *sample);

Gets the name of a SoundFont sample.

`sample` : | Sample to get name of
Returns : | Name of sample or `NULL` if not set. String value should be freed when finished with it.

### ipatch_sf2_sample_set_data ()

    void                ipatch_sf2_sample_set_data          (IpatchSF2Sample *sample,
                                                             IpatchSampleData *sampledata);

Set a sample's sample data object.

`sample` : | Sample to set sample data of
`sampledata` : | Sample data to set sample to

### ipatch_sf2_sample_get_data ()

    IpatchSampleData *  ipatch_sf2_sample_get_data          (IpatchSF2Sample *sample);

Get the IpatchSampleData item of a sample. Sample data item is referenced before returning and caller is responsible for unreferencing it with `g_object_unref()` when finished with it.

`sample` : | Sample to get sample data from
Returns : | Sample data object of sample or `NULL` if none. Remember to unreference with `g_object_unref()` when finished with it.

### ipatch_sf2_sample_peek_data ()

    IpatchSampleData *  ipatch_sf2_sample_peek_data         (IpatchSF2Sample *sample);

Get the IpatchSampleData item of a sample. Like `ipatch_sf2_sample_get_data()` but sample data object is not referenced. This function should only be used if a reference of the sample data object is ensured or only the pointer value is of importance.

`sample` : | Sample to get sample data from
Returns : | Sample data object of sample or `NULL` if none. Remember that a reference is NOT added.

### ipatch_sf2_sample_set_linked ()

    void                ipatch_sf2_sample_set_linked        (IpatchSF2Sample *sample,
                                                             IpatchSF2Sample *linked);

Sets the stereo linked sample of a sample item.

`sample` : | Sample to set linked sample of
`linked` : | Sample that is stereo linked to `sample` or `NULL` to unset.

### ipatch_sf2_sample_get_linked ()

    IpatchSF2Sample *   ipatch_sf2_sample_get_linked        (IpatchSF2Sample *sample);

Get the stereo linked sample from `sample`. If a sample is returned the caller owns a reference and should unref it with `g_object_unref()` when finished with it.

`sample` : | Sample to get linked sample from
Returns : | The linked stereo sample or `NULL` if no linked sample. Remember to unref the returned sample with `g_object_unref()` when finished with it.

### ipatch_sf2_sample_peek_linked ()

    IpatchSF2Sample *   ipatch_sf2_sample_peek_linked       (IpatchSF2Sample *sample);

Get the stereo linked sample from `sample`. Like `ipatch_sf2_sample_get_linked()` but sample object is not referenced. This function should only be used if a reference of the sample object is ensured or only the pointer value is of importance.

`sample` : | Sample to get linked sample from
Returns : | Linked sample object of sample or `NULL` if none. Remember that a reference is NOT added.

### ipatch_sf2_sample_set_blank ()

    void                ipatch_sf2_sample_set_blank         (IpatchSF2Sample *sample);

Set the sample data of a sample item to blank data.

`sample` : | Sample to set to blank sample data

## Property Details

### The `"channel"` property

      "channel"                  IpatchSF2SampleChannel  : Read / Write

Channel orientation.

Default value: IPATCH_SF2_SAMPLE_CHANNEL_MONO

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

      "fine-tune"                gint                  : Read / Write

Fine tuning in cents.

Allowed values: [-99,99]

Default value: 0

### The `"linked-sample"` property

      "linked-sample"            IpatchSF2Sample*      : Read / Write

Stereo linked sample object.

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

      "loop-end"                 guint                 : Read / Write

Loop end in frames (after loop).

Default value: 0

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

      "loop-start"               guint                 : Read / Write

Start of loop in frames.

Default value: 0

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name.

Default value: NULL

### The `"rom"` property

      "rom"                      gboolean              : Read / Write

ROM sample flag.

Default value: FALSE

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

      "root-note"                gint                  : Read / Write

Root MIDI note.

Allowed values: [0,127]

Default value: 60

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

      "sample-data"              IpatchSampleData*     : Read / Write

Sample data.

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

      "sample-rate"              gint                  : Read / Write

Sampling rate in Hertz.

Allowed values: [8000,192000]

Default value: 44100

## See Also

#IpatchSF2, IpatchSF2IZone