## IpatchDLSReader IpatchDLSReader — DLS version 2 file reader |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #define             IPATCH_DLS_READER_ERROR
    enum                IpatchDLSReaderError;
                        IpatchDLSReader;
    IpatchDLSReader *   ipatch_dls_reader_new               (IpatchFileHandle *handle);
    IpatchDLS2 *        ipatch_dls_reader_load              (IpatchDLSReader *reader,
                                                             GError **err);
    gboolean            ipatch_dls_reader_start             (IpatchDLSReader *reader,
                                                             GError **err);
    void                ipatch_dls_reader_set_pool_table    (IpatchDLSReader *reader,
                                                             const guint32 pool_table[],
                                                             guint size);
    gboolean            ipatch_dls_reader_fixup             (IpatchDLSReader *reader,
                                                             GError **err);
    gboolean            ipatch_dls_reader_load_level_0      (IpatchDLSReader *reader,
                                                             GError **err);
    gboolean            ipatch_dls_reader_load_inst_list    (IpatchDLSReader *reader,
                                                             GError **err);
    gboolean            ipatch_dls_reader_load_region_list  (IpatchDLSReader *reader,
                                                             IpatchDLS2Inst *inst,
                                                             GError **err);
    gboolean            ipatch_gig_reader_load_region_list  (IpatchDLSReader *reader,
                                                             IpatchGigInst *giginst,
                                                             GError **err);
    gboolean            ipatch_dls_reader_load_art_list     (IpatchDLSReader *reader,
                                                             GSList **conn_list,
                                                             GError **err);
    gboolean            ipatch_dls_reader_load_wave_pool    (IpatchDLSReader *reader,
                                                             GError **err);
    gboolean            ipatch_gig_reader_load_sub_regions  (IpatchDLSReader *reader,
                                                             IpatchGigRegion *region,
                                                             GError **err);
    gboolean            ipatch_gig_reader_load_inst_lart    (IpatchDLSReader *reader,
                                                             IpatchGigInst *inst,
                                                             GError **err);
    gboolean            ipatch_dls_load_info                (IpatchRiff *riff,
                                                             IpatchDLS2Info **info,
                                                             GError **err);
    gboolean            ipatch_dls_load_region_header       (IpatchRiff *riff,
                                                             IpatchDLS2Region *region,
                                                             GError **err);
    gboolean            ipatch_gig_load_region_header       (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);
    gboolean            ipatch_dls_load_wave_link           (IpatchRiff *riff,
                                                             IpatchDLS2Region *region,
                                                             GError **err);
    gboolean            ipatch_dls_load_sample_info         (IpatchRiff *riff,
                                                             IpatchDLS2SampleInfo *info,
                                                             GError **err);
    gboolean            ipatch_dls_load_connection          (IpatchRiff *riff,
                                                             GSList **conn_list,
                                                             GError **err);
    gboolean            ipatch_dls_load_sample_format       (IpatchRiff *riff,
                                                             IpatchDLS2Sample *sample,
                                                             int *bitwidth,
                                                             int *channels,
                                                             GError **err);
    guint32 *           ipatch_dls_load_pool_table          (IpatchRiff *riff,
                                                             guint *size,
                                                             GError **err);
    gboolean            ipatch_dls_load_dlid                (IpatchRiff *riff,
                                                             guint8 *dlid,
                                                             GError **err);
    gboolean            ipatch_gig_load_sample_info         (IpatchRiff *riff,
                                                             IpatchDLS2SampleInfo *info,
                                                             GError **err);
    gboolean            ipatch_gig_load_dimension_info      (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);
    gboolean            ipatch_gig_load_dimension_names     (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);
    gboolean            ipatch_gig_load_group_names         (IpatchRiff *riff,
                                                             GSList **name_list,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----IpatchRiff
             +----IpatchDLSReader

## Description

Parses a DLS file into an object tree (IpatchDLS).

## Details

### IPATCH_DLS_READER_ERROR

    #define IPATCH_DLS_READER_ERROR  ipatch_dls_reader_error_quark()

### enum IpatchDLSReaderError

    typedef enum
    {
      /* this error is returned if a file originally thought to be a plain DLS
         file turns out to be a GigaSampler file, in which case loading should
         be restarted in GigaSampler mode */
      IPATCH_DLS_READER_ERROR_GIG
    } IpatchDLSReaderError;

### IpatchDLSReader

    typedef struct _IpatchDLSReader IpatchDLSReader;

### ipatch_dls_reader_new ()

    IpatchDLSReader *   ipatch_dls_reader_new               (IpatchFileHandle *handle);

Create a new DLS file reader

`handle` : | DLS file handle to parse or `NULL` to set later
Returns : | The new DLS reader

### ipatch_dls_reader_load ()

    IpatchDLS2 *        ipatch_dls_reader_load              (IpatchDLSReader *reader,
                                                             GError **err);

Load a DLS file.

`reader` : | DLS reader object
`err` : | Location to store error info or `NULL`
Returns : | New DLS object with refcount of 1.

### ipatch_dls_reader_start ()

    gboolean            ipatch_dls_reader_start             (IpatchDLSReader *reader,
                                                             GError **err);

Starts parsing a DLS/Gig file. This function only needs to be called if using an IpatchDLSReader without `ipatch_dls_load()` (custom readers). The file object of the `reader` must be set before calling this function. Loads the first "DLS" RIFF chunk to verify we are loading a DLS file and sets other internal variables.

`reader` : | DLS/Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

### ipatch_dls_reader_set_pool_table ()

    void                ipatch_dls_reader_set_pool_table    (IpatchDLSReader *reader,
                                                             const guint32 pool_table[],
                                                             guint size);

Set the pool table of a DLS/Gig reader. This function is only used when doing manual DLS loading (not using `ipatch_dls_load()`). The pool table is used to fixup region sample references which are indexes into the pool table.

`reader` : | DLS/Gig reader
`pool_table` : | An array of unsigned 32 bit integers which are file offsets to samples in a DLS file, can be `NULL` if `size` is 0
`size` : | Number of entries in `pool_table`

### ipatch_dls_reader_fixup ()

    gboolean            ipatch_dls_reader_fixup             (IpatchDLSReader *reader,
                                                             GError **err);

Fixup sample pointers in DLS/GigaSampler regions of the DLS object in `reader`. The sample pointers should be sample pool indexes previously stored by `ipatch_dls_load_wave_link()` or `ipatch_gig_load_dimension_info()`. The pool table must also have been previously loaded for this to make any sense.

`reader` : | DLS/Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

### ipatch_dls_reader_load_level_0 ()

    gboolean            ipatch_dls_reader_load_level_0      (IpatchDLSReader *reader,
                                                             GError **err);

Load the top level DLS chunk of a DLS or GigaSampler file (essentially the entire file except the toplevel chunk itself).

`reader` : | DLS/Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_reader_load_inst_list ()

    gboolean            ipatch_dls_reader_load_inst_list    (IpatchDLSReader *reader,
                                                             GError **err);

Loads DLS or GigaSampler instrument list from the current position in the file assigned to `reader`.

`reader` : | DLS/Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_reader_load_region_list ()

    gboolean            ipatch_dls_reader_load_region_list  (IpatchDLSReader *reader,
                                                             IpatchDLS2Inst *inst,
                                                             GError **err);

Loads DLS region list into an `inst` object from the current position in the file assigned to `reader`.

`reader` : | DLS reader
`inst` : | DLS instrument to fill with loaded regions
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_gig_reader_load_region_list ()

    gboolean            ipatch_gig_reader_load_region_list  (IpatchDLSReader *reader,
                                                             IpatchGigInst *giginst,
                                                             GError **err);

Loads GigaSampler region list into an `inst` object from the current position in the file assigned to `reader`.

`reader` : | DLS/Gig reader
`giginst` : | Gig instrument to fill with loaded regions
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_reader_load_art_list ()

    gboolean            ipatch_dls_reader_load_art_list     (IpatchDLSReader *reader,
                                                             GSList **conn_list,
                                                             GError **err);

Loads DLS or GigaSampler articulator list from the current position in the file assigned to `reader`.

`reader` : | DLS/Gig reader
`conn_list` : | Pointer to a list to populate
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_reader_load_wave_pool ()

    gboolean            ipatch_dls_reader_load_wave_pool    (IpatchDLSReader *reader,
                                                             GError **err);

Loads DLS or GigaSampler wave pool ("wvpl" chunk) from the current position in the file assigned to `reader`. Populates the `reader` wave pool hash with sample offsets for later fixup.

`reader` : | DLS/Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_gig_reader_load_sub_regions ()

    gboolean            ipatch_gig_reader_load_sub_regions  (IpatchDLSReader *reader,
                                                             IpatchGigRegion *region,
                                                             GError **err);

Loads GigaSampler sub regions ("3prg" chunk) from the current position in the file assigned to `reader`.

`reader` : | Gig reader
`region` : | Gig region to load GigaSampler sub regions into
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_gig_reader_load_inst_lart ()

    gboolean            ipatch_gig_reader_load_inst_lart    (IpatchDLSReader *reader,
                                                             IpatchGigInst *inst,
                                                             GError **err);

Loads a GigaSampler global parameter chunk '3ewg' from an instrument 'lart' list.

`reader` : | Gig reader
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_info ()

    gboolean            ipatch_dls_load_info                (IpatchRiff *riff,
                                                             IpatchDLS2Info **info,
                                                             GError **err);

Loads DLS or GigaSampler info from the current position in the file assigned to `riff`.

`riff` : | RIFF parser
`info` : | Pointer to DLS info list
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_region_header ()

    gboolean            ipatch_dls_load_region_header       (IpatchRiff *riff,
                                                             IpatchDLS2Region *region,
                                                             GError **err);

Loads DLS instrument region header ("rgnh" chunk) from the current position in the file assigned to `riff`. The "rgnh" chunk header should have already been loaded.

`riff` : | RIFF parser
`region` : | DLS region to store header info in
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_gig_load_region_header ()

    gboolean            ipatch_gig_load_region_header       (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);

Loads GigaSampler instrument region header ("rgnh" chunk) from the current position in the file assigned to `riff`. The "rgnh" chunk header should have already been loaded.

`riff` : | RIFF parser
`region` : | Gig region to store header info in
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_wave_link ()

    gboolean            ipatch_dls_load_wave_link           (IpatchRiff *riff,
                                                             IpatchDLS2Region *region,
                                                             GError **err);

Loads DLS wave link chunk ("wlnk" chunk) from the current position in the file assigned to `riff`. The "wlnk" chunk header should have already been loaded.

NOTE: Sample pool index is stored in `region` sample pointer. This index should be fixed up or cleared before the region is freed otherwise bad things will happen.

`riff` : | RIFF parser
`region` : | DLS region to load info into
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_sample_info ()

    gboolean            ipatch_dls_load_sample_info         (IpatchRiff *riff,
                                                             IpatchDLS2SampleInfo *info,
                                                             GError **err);

Loads DLS or GigaSampler sample info ("wsmp" chunk) from the current position in the file assigned to `riff`. The "wsmp" chunk header should already have been loaded.

`riff` : | RIFF parser
`info` : | Sample info structure to load info into
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_connection ()

    gboolean            ipatch_dls_load_connection          (IpatchRiff *riff,
                                                             GSList **conn_list,
                                                             GError **err);

Load a DLS articulator chunk ("art1" or "art2") containing connection blocks which are loded into `conn_list`. The articulation chunk header should already have been loaded.

`riff` : | RIFF parser
`conn_list` : | Pointer to a list to populate with loaded IpatchDLS2Conn structures.
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_dls_load_sample_format ()

    gboolean            ipatch_dls_load_sample_format       (IpatchRiff *riff,
                                                             IpatchDLS2Sample *sample,
                                                             int *bitwidth,
                                                             int *channels,
                                                             GError **err);

Parses DLS sample format info ("fmt " chunk) from the current position in the file assigned to the `riff` (chunk header should already be loaded).

`riff` : | RIFF parser
`sample` : | DLS sample to load data into
`bitwidth` : | Pointer to an integer to fill with the sample's bit width or `NULL`
`channels` : | Pointer to an integer to fill with the number of channels or `NULL`
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### ipatch_dls_load_pool_table ()

    guint32 *           ipatch_dls_load_pool_table          (IpatchRiff *riff,
                                                             guint *size,
                                                             GError **err);

Load a sample pool table ("ptbl" chunk) of a DLS or GigaSampler file from the current position in the file assigned to `riff` (chunk header should already be loaded).

`riff` : | RIFF parser
`size` : | Pointer to an unsigned integer to store number of entries in returned pool table array
`err` : | Location to store error info or `NULL`
Returns : | A newly allocated array of 32bit integers for each entry in the pool table, or `NULL` if empty pool table or on error (in which case `err` may be set). Free the table when finished with it.

### ipatch_dls_load_dlid ()

    gboolean            ipatch_dls_load_dlid                (IpatchRiff *riff,
                                                             guint8 *dlid,
                                                             GError **err);

Load a DLSID from the current position in a riff object. This is a 16 byte unique ID used for tracking data changes. The "dlid" header should have already been loaded.

`riff` : | Riff parser
`dlid` : | Location to store 16 byte DLSID
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

### ipatch_gig_load_sample_info ()

    gboolean            ipatch_gig_load_sample_info         (IpatchRiff *riff,
                                                             IpatchDLS2SampleInfo *info,
                                                             GError **err);

Load Gig sample info ("smpl" chunk) from current position in file assigned to `riff` (chunk header should already be loaded).

`riff` : | RIFF parser
`info` : | DLS sample info to load data into
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### ipatch_gig_load_dimension_info ()

    gboolean            ipatch_gig_load_dimension_info      (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);

Load Gigasampler dimension info ("3lnk" chunk), from the current position in the file assigned to `riff` (chunk header should already be loaded).

NOTE: Sample pool table indexes are stored in the sample pointer of sub regions. These indexes should be fixed up or cleared before the `region` is freed, otherwise bad things will happen.

`riff` : | RIFF parser
`region` : | Region to load data into
`err` : | Location to store an error or `NULL`
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### ipatch_gig_load_dimension_names ()

    gboolean            ipatch_gig_load_dimension_names     (IpatchRiff *riff,
                                                             IpatchGigRegion *region,
                                                             GError **err);

Loads Gigasampler dimension names from the current position in the file assigned to `riff`. The "3dnl" chunk header should already have been loaded.

`riff` : | RIFF parser
`region` : | Gig region to load names into
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_gig_load_group_names ()

    gboolean            ipatch_gig_load_group_names         (IpatchRiff *riff,
                                                             GSList **name_list,
                                                             GError **err);

Load a '3gri' sample group name chunk into a GSList of strings. The 3gri chunk header should have already been loaded.

`riff` : | Riff parser
`name_list` : | List to add names to
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

## See Also

#IpatchDLS