DLS::File Class Reference

Parses DLS Level 1 and 2 compliant files and provides abstract access to the data. More...

`#include <DLS.h>`

Inheritance diagram for DLS::File:

## Public Member Functions

| File ()
| Constructor.
| File (RIFF::File *pRIFF)
| Constructor.
String | GetFileName ()
| File name of this DLS file.
void | SetFileName (const String &name)
| You may call this method store a future file name, so you don't have to to pass it to the Save() call later on.
Sample * | GetSample (size_t index)
| Returns Sample object of index.
Sample * | GetFirstSample ()
| Returns a pointer to the first Sample object of the file, NULL otherwise.
Sample * | GetNextSample ()
| Returns a pointer to the next Sample object of the file, NULL otherwise.
Sample * | AddSample ()
| Add a new sample.
size_t | CountSamples ()
| Returns the total amount of samples of this DLS file.
void | DeleteSample (Sample *pSample)
| Delete a sample.
Instrument * | GetInstrument (size_t index)
| Returns the instrument with the given index from the list of instruments of this file.
Instrument * | GetFirstInstrument ()
| Returns a pointer to the first Instrument object of the file, NULL otherwise.
Instrument * | GetNextInstrument ()
| Returns a pointer to the next Instrument object of the file, NULL otherwise.
Instrument * | AddInstrument ()
| Add a new instrument definition.
void | DeleteInstrument (Instrument *pInstrument)
| Delete an instrument.
RIFF::File * | GetRiffFile ()
| Returns the underlying RIFF::File used for persistency of this DLS::File object.
RIFF::File * | GetExtensionFile (int index)
| Returns extension file of given index.
virtual void | UpdateChunks (progress_t *pProgress)
| Apply all the DLS file's current instruments, samples and settings to the respective RIFF chunks.
virtual void | Save (const String &Path, progress_t *pProgress=NULL)
| Save changes to another file.
virtual void | Save (progress_t *pProgress=NULL)
| Save changes to same file.
Resource * | GetParent ()
const Resource * | GetParent () const
virtual void | DeleteChunks ()
| Remove all RIFF chunks associated with this Resource object.
void | GenerateDLSID ()
| Generates a new DLSID for the resource.
virtual void | CopyAssign (const Resource *orig)
| Make a deep copy of the Resource object given by orig and assign it to this object.

## Static Public Member Functions

static void | GenerateDLSID (dlsid_t *pDLSID)

## Public Attributes

version_t * | pVersion
| Points to a version_t structure if the file provided a version number else is set to NULL.
uint32_t | Instruments
| Reflects the number of available Instrument objects.
Info * | pInfo
| Points (in any case) to an Info object, providing additional, optional infos and comments.
dlsid_t * | pDLSID
| Points to a dlsid_t structure if the file provided a DLS ID else is NULL.

## Protected Types

typedef std::vector< Sample * > | SampleList
typedef std::vector< Instrument * > | InstrumentList

## Protected Member Functions

virtual void | LoadSamples ()
virtual void | LoadInstruments ()
virtual void | UpdateFileOffsets ()
| Updates all file offsets stored all over the file.
void | __ensureMandatoryChunksExist ()
| Checks if all (for DLS) mandatory chunks exist, if not they will be created.

## Protected Attributes

RIFF::File * | pRIFF
std::list< RIFF::File * > | ExtensionFiles
SampleList * | pSamples
SampleList::iterator | SamplesIterator
InstrumentList * | pInstruments
InstrumentList::iterator | InstrumentsIterator
uint32_t | WavePoolHeaderSize
uint32_t | WavePoolCount
uint32_t * | pWavePoolTable
uint32_t * | pWavePoolTableHi
bool | b64BitWavePoolOffsets
bool | bOwningRiff
| If `true` then `pRIFF` was implicitly allocated by this class and hence pRIFF will automatically be freed by the `DLS::File` destructor in that case.
Resource * | pParent
RIFF::List * | pResourceList

## Detailed Description

Parses DLS Level 1 and 2 compliant files and provides abstract access to the data.

Definition at line 564 of file DLS.h.

## Member Typedef Documentation

## InstrumentList

typedef std::vector<Instrument*> DLS::File::InstrumentList

protected

Definition at line 592 of file DLS.h.

## SampleList

typedef std::vector<Sample*> DLS::File::SampleList

protected

Definition at line 591 of file DLS.h.

## Constructor & Destructor Documentation

## File() [1/2]

DLS::File::File | ( |  | ) |

Constructor.

Default constructor, use this to create an empty DLS file. You have to add samples, instruments and finally call Save() to actually write a DLS file.

Definition at line 1660 of file DLS.cpp.

References bOwningRiff, File(), Instruments, pVersion, and DLS::Resource::Resource().

Referenced by File().

## File() [2/2]

DLS::File::File | ( | RIFF::File * | pRIFF | ) |

Constructor.

Load an existing DLS file.

Parameters

  pRIFF | - pointer to a RIFF file which is actually the DLS file to load

Exceptions

  Exception | if given file is not a DLS file, expected chunks are missing

Definition at line 1690 of file DLS.cpp.

References bOwningRiff, RIFF::Chunk::GetSize(), Instruments, pVersion, RIFF::Chunk::Read(), RIFF::Chunk::ReadUint32(), DLS::Resource::Resource(), and RIFF::Chunk::SetPos().

## ~File()

DLS::File::~File | ( |  | ) |

virtual

Definition at line 1744 of file DLS.cpp.

## Member Function Documentation

## __ensureMandatoryChunksExist()

void DLS::File::__ensureMandatoryChunksExist | ( |  | ) |

protected

Checks if all (for DLS) mandatory chunks exist, if not they will be created.

Note that those chunks will not be made persistent until Save() was called.

Definition at line 2471 of file DLS.cpp.

References RIFF::List::AddSubList(), and RIFF::List::GetSubList().

Referenced by AddInstrument(), gig::File::AddInstrument(), AddSample(), and gig::File::AddSample().

## AddInstrument()

Instrument * DLS::File::AddInstrument | ( |  | ) |

Add a new instrument definition.

This will create a new Instrument object for the DLS file. You have to call Save() to make this persistent to the file.

Returns
  pointer to new Instrument object

Definition at line 1965 of file DLS.cpp.

References __ensureMandatoryChunksExist(), RIFF::List::AddSubList(), and RIFF::List::GetSubList().

## AddSample()

Sample * DLS::File::AddSample | ( |  | ) |

Add a new sample.

This will create a new Sample object for the DLS file. You have to call Save() to make this persistent to the file.

Returns
  pointer to new Sample object

Definition at line 1871 of file DLS.cpp.

References __ensureMandatoryChunksExist(), RIFF::List::AddSubList(), and RIFF::List::GetSubList().

## CopyAssign()

void Resource::CopyAssign | ( | const Resource * | orig | ) |

virtual inherited

Make a deep copy of the Resource object given by orig and assign it to this object.

Parameters

  orig | - original Resource object to be copied from

Definition at line 654 of file DLS.cpp.

References pInfo, and Resource().

Referenced by DLS::Region::CopyAssign(), and DLS::Sample::CopyAssignCore().

## CountSamples()

size_t DLS::File::CountSamples | ( |  | ) |

Returns the total amount of samples of this DLS file.

Note that this method might block for a long time in case it is required to load the sample info for the first time.

Returns
  total amount of samples

Definition at line 1858 of file DLS.cpp.

## DeleteChunks()

void Resource::DeleteChunks | ( |  | ) |

virtual inherited

Remove all RIFF chunks associated with this Resource object.

At the moment Resource::DeleteChunks() does nothing. It is recommended to call this method explicitly though from deriving classes's own overridden implementation of this method to avoid potential future compatibility issues.

See Storage::DeleteChunks() for details.

Implements DLS::Storage.

Reimplemented in DLS::Instrument, DLS::Region, and DLS::Sample.

Definition at line 572 of file DLS.cpp.

Referenced by DLS::Instrument::DeleteChunks(), DLS::Region::DeleteChunks(), and DLS::Sample::DeleteChunks().

## DeleteInstrument()

void DLS::File::DeleteInstrument | ( | Instrument * | pInstrument | ) |

Delete an instrument.

This will delete the given Instrument object from the DLS file. You have to call Save() to make this persistent to the file.

Parameters

  pInstrument | - instrument to delete

Definition at line 1984 of file DLS.cpp.

References DLS::Instrument::DeleteChunks().

## DeleteSample()

void DLS::File::DeleteSample | ( | Sample * | pSample | ) |

Delete a sample.

This will delete the given Sample object from the DLS file. You have to call Save() to make this persistent to the file.

Parameters

  pSample | - sample to delete

Definition at line 1891 of file DLS.cpp.

References DLS::Sample::DeleteChunks().

## GenerateDLSID() [1/2]

void Resource::GenerateDLSID | ( |  | ) |

inherited

Generates a new DLSID for the resource.

Definition at line 604 of file DLS.cpp.

References GenerateDLSID(), and pDLSID.

Referenced by gig::File::AddInstrument(), GenerateDLSID(), gig::Script::GenerateUuid(), and DLS::File::UpdateChunks().

## GenerateDLSID() [2/2]

void Resource::GenerateDLSID | ( | dlsid_t * | pDLSID | ) |

static inherited

Definition at line 611 of file DLS.cpp.

## GetExtensionFile()

RIFF::File * DLS::File::GetExtensionFile | ( | int | index | ) |

Returns extension file of given index.

Extension files are used sometimes to circumvent the 2 GB file size limit of the RIFF format and of certain operating systems in general. In this case, instead of just using one file, the content is spread among several files with similar file name scheme. This is especially used by some GigaStudio sound libraries.

Parameters

  index | - index of extension file

Returns
  sought extension file, NULL if index out of bounds

See also
  GetFileName()

Definition at line 2015 of file DLS.cpp.

## GetFileName()

String DLS::File::GetFileName | ( |  | ) |

File name of this DLS file.

This method returns the file name as it was provided when loading the respective DLS file. However in case the File object associates an empty, that is new DLS file, which was not yet saved to disk, this method will return an empty string.

See also
  GetExtensionFile()

Definition at line 2032 of file DLS.cpp.

## GetFirstInstrument()

Instrument * DLS::File::GetFirstInstrument | ( |  | ) |

Returns a pointer to the first Instrument object of the file, NULL otherwise.

Deprecated
  This method is not reentrant-safe, use GetInstrument() instead.

Definition at line 1923 of file DLS.cpp.

## GetFirstSample()

Sample * DLS::File::GetFirstSample | ( |  | ) |

Returns a pointer to the first Sample object of the file, NULL otherwise.

Deprecated
  This method is not reentrant-safe, use GetSample() instead.

Definition at line 1794 of file DLS.cpp.

## GetInstrument()

Instrument * DLS::File::GetInstrument | ( | size_t | index | ) |

Returns the instrument with the given index from the list of instruments of this file.

Parameters

  index | - number of the sought instrument (0..n)

Returns
  sought instrument or NULL if there's no such instrument

Definition at line 1909 of file DLS.cpp.

## GetNextInstrument()

Instrument * DLS::File::GetNextInstrument | ( |  | ) |

Returns a pointer to the next Instrument object of the file, NULL otherwise.

Deprecated
  This method is not reentrant-safe, use GetInstrument() instead.

Definition at line 1937 of file DLS.cpp.

## GetNextSample()

Sample * DLS::File::GetNextSample | ( |  | ) |

Returns a pointer to the next Sample object of the file, NULL otherwise.

Deprecated
  This method is not reentrant-safe, use GetSample() instead.

Definition at line 1808 of file DLS.cpp.

## GetParent() [1/2]

Resource * DLS::Resource::GetParent | ( |  | ) |

inline inherited

Definition at line 409 of file DLS.h.

## GetParent() [2/2]

const Resource * DLS::Resource::GetParent | ( |  | ) | const

inline inherited

Definition at line 410 of file DLS.h.

## GetRiffFile()

RIFF::File * DLS::File::GetRiffFile | ( |  | ) |

Returns the underlying RIFF::File used for persistency of this DLS::File object.

Definition at line 1999 of file DLS.cpp.

## GetSample()

Sample * DLS::File::GetSample | ( | size_t | index | ) |

Returns Sample object of index.

Parameters

  index | - position of sample in sample list (0..n)

Returns
  sample object or NULL if index is out of bounds

Definition at line 1780 of file DLS.cpp.

## LoadInstruments()

void DLS::File::LoadInstruments | ( |  | ) |

protected virtual

Definition at line 1943 of file DLS.cpp.

## LoadSamples()

void DLS::File::LoadSamples | ( |  | ) |

protected virtual

Definition at line 1814 of file DLS.cpp.

## Save() [1/2]

void DLS::File::Save | ( | const String & | Path,
|  | progress_t * | pProgress = NULL )

virtual

Save changes to another file.

Make all changes persistent by writing them to another file. Caution: this method is optimized for writing to another file, do not use it to save the changes to the same file! Use Save() (without path argument) in that case instead! Ignoring this might result in a corrupted file!

After calling this method, this File object will be associated with the new file (given by Path) afterwards.

Parameters

  Path | - path and file name where everything should be written to
  pProgress | - optional: callback function for progress notification

Reimplemented in gig::File.

Definition at line 2294 of file DLS.cpp.

References RIFF::progress_t::activity, UpdateChunks(), and UpdateFileOffsets().

## Save() [2/2]

void DLS::File::Save | ( | progress_t * | pProgress = NULL | ) |

virtual

Save changes to same file.

Make all changes persistent by writing them to the actual (same) file. The file might temporarily grow to a higher size than it will have at the end of the saving process.

Parameters

  pProgress | - optional: callback function for progress notification

Exceptions

  RIFF::Exception | if any kind of IO error occurred
  DLS::Exception | if any kind of DLS specific error occurred

Reimplemented in gig::File.

Definition at line 2385 of file DLS.cpp.

References RIFF::progress_t::activity, UpdateChunks(), and UpdateFileOffsets().

## SetFileName()

void DLS::File::SetFileName | ( | const String & | name | ) |

You may call this method store a future file name, so you don't have to to pass it to the Save() call later on.

Definition at line 2040 of file DLS.cpp.

## UpdateChunks()

void DLS::File::UpdateChunks | ( | progress_t * | pProgress | ) |

virtual

Apply all the DLS file's current instruments, samples and settings to the respective RIFF chunks.

You have to call Save() to make changes persistent.

Parameters

  pProgress | - callback function for progress notification

Exceptions

  Exception | - on errors

Reimplemented from DLS::Resource.

Reimplemented in gig::File.

Definition at line 2052 of file DLS.cpp.

References DLS::Resource::GenerateDLSID(), RIFF::File::GetRequiredFileSize(), RIFF::List::GetSubChunk(), Instruments, RIFF::Chunk::LoadChunkData(), pVersion, RIFF::Chunk::Read(), RIFF::Chunk::Resize(), and DLS::Resource::UpdateChunks().

Referenced by Save(), Save(), and gig::File::UpdateChunks().

## UpdateFileOffsets()

void DLS::File::UpdateFileOffsets | ( |  | ) |

protected virtual

Updates all file offsets stored all over the file.

This virtual method is called whenever the overall file layout has been changed (i.e. file or individual RIFF chunks have been resized). It is then the responsibility of this method to update all file offsets stored in the file format. For example samples are referenced by instruments by file offsets. The gig format also stores references to instrument scripts as file offsets, and thus it overrides this method to update those file offsets as well.

Reimplemented in gig::File.

Definition at line 2462 of file DLS.cpp.

Referenced by Save(), Save(), and gig::File::UpdateFileOffsets().

## Member Data Documentation

## b64BitWavePoolOffsets

bool DLS::File::b64BitWavePoolOffsets

protected

Definition at line 604 of file DLS.h.

## bOwningRiff

bool DLS::File::bOwningRiff

protected

If `true` then `pRIFF` was implicitly allocated by this class and hence pRIFF will automatically be freed by the `DLS::File` destructor in that case.

Definition at line 605 of file DLS.h.

Referenced by File(), and File().

## ExtensionFiles

std::list<RIFF::File*> DLS::File::ExtensionFiles

protected

Definition at line 595 of file DLS.h.

## Instruments

uint32_t DLS::File::Instruments

Reflects the number of available Instrument objects.

Definition at line 567 of file DLS.h.

Referenced by File(), File(), and UpdateChunks().

## InstrumentsIterator

InstrumentList::iterator DLS::File::InstrumentsIterator

protected

Definition at line 599 of file DLS.h.

## pDLSID

dlsid_t* DLS::Resource::pDLSID

inherited

Points to a dlsid_t structure if the file provided a DLS ID else is NULL.

Definition at line 407 of file DLS.h.

Referenced by GenerateDLSID(), and Resource().

## pInfo

Info* DLS::Resource::pInfo

inherited

Points (in any case) to an Info object, providing additional, optional infos and comments.

Definition at line 406 of file DLS.h.

Referenced by CopyAssign(), Resource(), gig::Sample::Sample(), and UpdateChunks().

## pInstruments

InstrumentList* DLS::File::pInstruments

protected

Definition at line 598 of file DLS.h.

## pParent

Resource* DLS::Resource::pParent

protected inherited

Definition at line 417 of file DLS.h.

## pResourceList

RIFF::List* DLS::Resource::pResourceList

protected inherited

Definition at line 418 of file DLS.h.

## pRIFF

RIFF::File* DLS::File::pRIFF

protected

Definition at line 594 of file DLS.h.

## pSamples

SampleList* DLS::File::pSamples

protected

Definition at line 596 of file DLS.h.

## pVersion

version_t* DLS::File::pVersion

Points to a version_t structure if the file provided a version number else is set to NULL.

Definition at line 566 of file DLS.h.

Referenced by File(), File(), and UpdateChunks().

## pWavePoolTable

uint32_t* DLS::File::pWavePoolTable

protected

Definition at line 602 of file DLS.h.

## pWavePoolTableHi

uint32_t* DLS::File::pWavePoolTableHi

protected

Definition at line 603 of file DLS.h.

## SamplesIterator

SampleList::iterator DLS::File::SamplesIterator

protected

Definition at line 597 of file DLS.h.

## WavePoolCount

uint32_t DLS::File::WavePoolCount

protected

Definition at line 601 of file DLS.h.

## WavePoolHeaderSize

uint32_t DLS::File::WavePoolHeaderSize

protected

Definition at line 600 of file DLS.h.

The documentation for this class was generated from the following files:

- DLS.h
- DLS.cpp