## IpatchDLS2Sample

IpatchDLS2Sample — DLS audio sample object

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchDLS2SampleInfo;
                        IpatchDLS2Sample;
    #define             IPATCH_DLS2_SAMPLE_INFO_INIT
    #define             IPATCH_DLS2_SAMPLE_INFO_FIRST_PROPERTY_ID
    #define             IPATCH_DLS2_SAMPLE_INFO_PROPERTY_COUNT
    enum                IpatchDLS2SampleFlags;
    #define             IPATCH_DLS2_SAMPLE_LOOP_MASK
    #define             IPATCH_DLS2_SAMPLE_FLAGS_MASK
    IpatchDLS2Sample *  ipatch_dls2_sample_new              (void);
    IpatchDLS2Sample *  ipatch_dls2_sample_first            (IpatchIter *iter);
    IpatchDLS2Sample *  ipatch_dls2_sample_next             (IpatchIter *iter);
    void                ipatch_dls2_sample_set_data         (IpatchDLS2Sample *sample,
                                                             IpatchSampleData *sampledata);
    IpatchSampleData *  ipatch_dls2_sample_get_data         (IpatchDLS2Sample *sample);
    IpatchSampleData *  ipatch_dls2_sample_peek_data        (IpatchDLS2Sample *sample);
    void                ipatch_dls2_sample_set_blank        (IpatchDLS2Sample *sample);
    IpatchDLS2SampleInfo * ipatch_dls2_sample_info_new      (void);
    void                ipatch_dls2_sample_info_free        (IpatchDLS2SampleInfo *sample_info);
    IpatchDLS2SampleInfo * ipatch_dls2_sample_info_duplicate
                                                            (IpatchDLS2SampleInfo *sample_info);
    void                ipatch_dls2_sample_info_init        (IpatchDLS2SampleInfo *sample_info);
    void                ipatch_dls2_sample_info_install_class_properties
                                                            (GObjectClass *obj_class);
    gboolean            ipatch_dls2_sample_info_is_property_id_valid
                                                            (guint property_id);
    gboolean            ipatch_dls2_sample_info_set_property
                                                            (IpatchDLS2SampleInfo **sample_info,
                                                             guint property_id,
                                                             const GValue *value);
    gboolean            ipatch_dls2_sample_info_get_property
                                                            (IpatchDLS2SampleInfo *sample_info,
                                                             guint property_id,
                                                             GValue *value);
    void                ipatch_dls2_sample_info_notify_changes
                                                            (IpatchItem *item,
                                                             IpatchDLS2SampleInfo *newinfo,
                                                             IpatchDLS2SampleInfo *oldinfo);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchDLS2Sample
                   +----IpatchGigSample

## Implemented Interfaces

IpatchDLS2Sample implements IpatchSample.

## Properties

      "archive-location"         gchar*                : Read / Write
      "artist"                   gchar*                : Read / Write
      "comment"                  gchar*                : Read / Write
      "commissioned"             gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "date"                     gchar*                : Read / Write
      "engineer"                 gchar*                : Read / Write
      "fine-tune"                gint                  : Read / Write
      "flags"                    IpatchDLS2SampleFlags  : Read / Write
      "gain"                     gint                  : Read / Write
      "genre"                    gchar*                : Read / Write
      "keywords"                 gchar*                : Read / Write
      "loop-end"                 guint                 : Read / Write
      "loop-start"               guint                 : Read / Write
      "loop-type"                IpatchSampleLoopType  : Read / Write
      "medium"                   gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "product"                  gchar*                : Read / Write
      "root-note"                gint                  : Read / Write
      "sample-data"              IpatchSampleData*     : Read / Write
      "sample-rate"              gint                  : Read / Write
      "software"                 gchar*                : Read / Write
      "source"                   gchar*                : Read / Write
      "source-form"              gchar*                : Read / Write
      "subject"                  gchar*                : Read / Write
      "technician"               gchar*                : Read / Write

## Description

Object which defines a DLS audio sample. These objects are contained in IpatchDLS objects and linked (referenced) from IpatchDLSRegion objects.

## Details

### IpatchDLS2SampleInfo

    typedef struct {
      guint8 options; /* IpatchSampleLoopType and IpatchDLS2SampleFlags */
      guint8 root_note;		/* root MIDI note number */
      gint16 fine_tune;		/* fine tuning */
      gint32 gain;			/* gain to apply to sample */

      guint32 loop_start;		/* loop start offset (in samples) */
      guint32 loop_end;		/* loop end offset (in samples) */
    } IpatchDLS2SampleInfo;

### IpatchDLS2Sample

    typedef struct _IpatchDLS2Sample IpatchDLS2Sample;

### IPATCH_DLS2_SAMPLE_INFO_INIT

    #define IPATCH_DLS2_SAMPLE_INFO_INIT  { 0, 60, 0, 0, 0, 0 }

### IPATCH_DLS2_SAMPLE_INFO_FIRST_PROPERTY_ID

    #define IPATCH_DLS2_SAMPLE_INFO_FIRST_PROPERTY_ID   256

### IPATCH_DLS2_SAMPLE_INFO_PROPERTY_COUNT

    #define IPATCH_DLS2_SAMPLE_INFO_PROPERTY_COUNT      7

### enum IpatchDLS2SampleFlags

    typedef enum
    {
      IPATCH_DLS2_SAMPLE_NO_TRUNCATION = 1 << 6,
      IPATCH_DLS2_SAMPLE_NO_COMPRESSION = 1 << 7
    } IpatchDLS2SampleFlags;

### IPATCH_DLS2_SAMPLE_LOOP_MASK

    #define IPATCH_DLS2_SAMPLE_LOOP_MASK   0x03

### IPATCH_DLS2_SAMPLE_FLAGS_MASK

    #define IPATCH_DLS2_SAMPLE_FLAGS_MASK  0x0C0

### ipatch_dls2_sample_new ()

    IpatchDLS2Sample *  ipatch_dls2_sample_new              (void);

Create a new DLS sample object.

Returns : | New DLS 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_dls2_sample_first ()

    IpatchDLS2Sample *  ipatch_dls2_sample_first            (IpatchIter *iter);

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

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

### ipatch_dls2_sample_next ()

    IpatchDLS2Sample *  ipatch_dls2_sample_next             (IpatchIter *iter);

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

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

### ipatch_dls2_sample_set_data ()

    void                ipatch_dls2_sample_set_data         (IpatchDLS2Sample *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_dls2_sample_get_data ()

    IpatchSampleData *  ipatch_dls2_sample_get_data         (IpatchDLS2Sample *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_dls2_sample_peek_data ()

    IpatchSampleData *  ipatch_dls2_sample_peek_data        (IpatchDLS2Sample *sample);

Get the IpatchSampleData item of a sample. Like `ipatch_dls2_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_dls2_sample_set_blank ()

    void                ipatch_dls2_sample_set_blank        (IpatchDLS2Sample *sample);

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

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

### ipatch_dls2_sample_info_new ()

    IpatchDLS2SampleInfo * ipatch_dls2_sample_info_new      (void);

Allocates a new sample info structure.

Returns : | New sample info structure, free it with `ipatch_dls2_sample_info_free()` when finished.

### ipatch_dls2_sample_info_free ()

    void                ipatch_dls2_sample_info_free        (IpatchDLS2SampleInfo *sample_info);

Free a sample info structure allocated with `ipatch_dls2_sample_info_new()`.

`sample_info` : | Sample info structure

### ipatch_dls2_sample_info_duplicate ()

    IpatchDLS2SampleInfo * ipatch_dls2_sample_info_duplicate
                                                            (IpatchDLS2SampleInfo *sample_info);

Duplicate a sample info structure.

`sample_info` : | Sample info structure to duplicate
Returns : | Newly allocated sample info structure which should be freed with `ipatch_dls2_sample_info_free()` when done with it.

### ipatch_dls2_sample_info_init ()

    void                ipatch_dls2_sample_info_init        (IpatchDLS2SampleInfo *sample_info);

Initialize a sample info structure to defaults.

`sample_info` : | Sample info structure to initialize

### ipatch_dls2_sample_info_install_class_properties ()

    void                ipatch_dls2_sample_info_install_class_properties
                                                            (GObjectClass *obj_class);

Installs sample info properties for the given `obj_class`. Useful for objects that implement IpatchDLS2SampleInfo properties.

`obj_class` : | GObjectClass to install properties for

### ipatch_dls2_sample_info_is_property_id_valid ()

    gboolean            ipatch_dls2_sample_info_is_property_id_valid
                                                            (guint property_id);

Check if a property ID is a valid sample info property ID.

`property_id` : | Property ID to test
Returns : | `TRUE` if property_id is a sample info property ID, `FALSE` otherwise.

### ipatch_dls2_sample_info_set_property ()

    gboolean            ipatch_dls2_sample_info_set_property
                                                            (IpatchDLS2SampleInfo **sample_info,
                                                             guint property_id,
                                                             const GValue *value);

A function used by set_property methods that implement IpatchDLS2SampleInfo properties.

`sample_info` : | Pointer to pointer to sample info
`property_id` : | Property ID
`value` : | Value for property
Returns : | `TRUE` if property_id was handled, `FALSE` otherwise

### ipatch_dls2_sample_info_get_property ()

    gboolean            ipatch_dls2_sample_info_get_property
                                                            (IpatchDLS2SampleInfo *sample_info,
                                                             guint property_id,
                                                             GValue *value);

A function used by get_property methods that implement IpatchDLS2SampleInfo properties.

`sample_info` : | Pointer to sample info
`property_id` : | Property ID
`value` : | Value to set
Returns : | `TRUE` if property_id was handled, `FALSE` otherwise

### ipatch_dls2_sample_info_notify_changes ()

    void                ipatch_dls2_sample_info_notify_changes
                                                            (IpatchItem *item,
                                                             IpatchDLS2SampleInfo *newinfo,
                                                             IpatchDLS2SampleInfo *oldinfo);

Sends IpatchItem property notifies for changed sample info parameters.

`item` : | Item to send IpatchItem property notifies on
`newinfo` : | New sample info values
`oldinfo` : | Old sample info values

## Property Details

### The `"archive-location"` property

      "archive-location"         gchar*                : Read / Write

Location where subject is archived.

Default value: NULL

### The `"artist"` property

      "artist"                   gchar*                : Read / Write

Original artist.

Default value: NULL

### The `"comment"` property

      "comment"                  gchar*                : Read / Write

Comments.

Default value: NULL

### The `"commissioned"` property

      "commissioned"             gchar*                : Read / Write

Who commissioned the material.

Default value: NULL

### The `"copyright"` property

      "copyright"                gchar*                : Read / Write

Copyright.

Default value: NULL

### The `"date"` property

      "date"                     gchar*                : Read / Write

Creation date (YYYY-MM-DD).

Default value: NULL

### The `"engineer"` property

      "engineer"                 gchar*                : Read / Write

Engineers separated by "; ".

Default value: NULL

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

      "fine-tune"                gint                  : Read / Write

Fine tuning in cents.

Allowed values: [-99,99]

Default value: 0

### The `"flags"` property

      "flags"                    IpatchDLS2SampleFlags  : Read / Write

Sample flags.

### The `"gain"` property

      "gain"                     gint                  : Read / Write

Gain in DLS relative gain units.

Default value: 0

### The `"genre"` property

      "genre"                    gchar*                : Read / Write

Genre.

Default value: NULL

### The `"keywords"` property

      "keywords"                 gchar*                : Read / Write

Keywords (separated by "; ").

Default value: NULL

### 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 `"loop-type"` property

      "loop-type"                IpatchSampleLoopType  : Read / Write

Loop method type.

Default value: IPATCH_SAMPLE_LOOP_NONE

### The `"medium"` property

      "medium"                   gchar*                : Read / Write

Original medium of the material (record, CD, etc).

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name.

Default value: "untitled"

### The `"product"` property

      "product"                  gchar*                : Read / Write

Product intended for.

Default value: NULL

### 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

### The `"software"` property

      "software"                 gchar*                : Read / Write

Editor software used.

Default value: NULL

### The `"source"` property

      "source"                   gchar*                : Read / Write

Source of the original material.

Default value: NULL

### The `"source-form"` property

      "source-form"              gchar*                : Read / Write

Original source that was digitized.

Default value: NULL

### The `"subject"` property

      "subject"                  gchar*                : Read / Write

Subject of the material.

Default value: NULL

### The `"technician"` property

      "technician"               gchar*                : Read / Write

Technician who sampled the material.

Default value: NULL

## See Also

#IpatchDLS, IpatchDLSRegion