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. More...

	File (RIFF::File *pRIFF)
	Constructor. More...

String	GetFileName ()
	File name of this DLS file. More...

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. More...

Sample *	GetFirstSample ()
	Returns a pointer to the first Sample object of the file, NULL otherwise. More...

Sample *	GetNextSample ()
	Returns a pointer to the next Sample object of the file, NULL otherwise. More...

Sample *	AddSample ()
	Add a new sample. More...

void	DeleteSample (Sample *pSample)
	Delete a sample. More...

Instrument *	GetInstrument (size_t index)
	Returns the instrument with the given index from the list of instruments of this file. More...

Instrument *	GetFirstInstrument ()
	Returns a pointer to the first Instrument object of the file, NULL otherwise. More...

Instrument *	GetNextInstrument ()
	Returns a pointer to the next Instrument object of the file, NULL otherwise. More...

Instrument *	AddInstrument ()
	Add a new instrument definition. More...

void	DeleteInstrument (Instrument *pInstrument)
	Delete an instrument. More...

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. More...

virtual void	UpdateChunks (progress_t *pProgress)
	Apply all the DLS file's current instruments, samples and settings to the respective RIFF chunks. More...

virtual void	Save (const String &Path, progress_t *pProgress=NULL)
	Save changes to another file. More...

virtual void	Save (progress_t *pProgress=NULL)
	Save changes to same file. More...

Resource *	GetParent ()

const Resource *	GetParent () const

virtual void	DeleteChunks ()
	Remove all RIFF chunks associated with this Resource object. More...

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. More...

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. More...

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

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.

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 1643 of file DLS.cpp.

References bOwningRiff, Instruments, pVersion, and RIFF::File::SetByteOrder().

◆ 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 1673 of file DLS.cpp.

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

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 2394 of file DLS.cpp.

References RIFF::List::AddSubChunk(), RIFF::List::AddSubList(), RIFF::Chunk::GetFile(), RIFF::File::GetFileOffsetSize(), RIFF::Chunk::GetFilePos(), RIFF::Chunk::GetPos(), RIFF::Chunk::GetSize(), RIFF::List::GetSubChunk(), RIFF::List::GetSubList(), RIFF::Chunk::SetPos(), and RIFF::Chunk::WriteUint32().

Referenced by AddInstrument(), and 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 1934 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 1840 of file DLS.cpp.

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

◆ CopyAssign()

void Resource::CopyAssign ( const Resource * orig )

virtualinherited

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 637 of file DLS.cpp.

References RIFF::List::GetSubChunk(), DLS::Resource::pInfo, RIFF::Chunk::Read(), RIFF::Chunk::ReadInt16(), RIFF::Chunk::ReadInt32(), RIFF::Chunk::ReadUint16(), RIFF::Chunk::ReadUint32(), and RIFF::Chunk::SetPos().

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

◆ DeleteChunks()

void Resource::DeleteChunks ( )

virtualinherited

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 compatiblity issues.

See Storage::DeleteChunks() for details.

Implements DLS::Storage.

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

Definition at line 555 of file DLS.cpp.

Referenced by DLS::Sample::DeleteChunks(), DLS::Region::DeleteChunks(), and DLS::Instrument::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 1953 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 1860 of file DLS.cpp.

References DLS::Sample::DeleteChunks().

◆ 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 1984 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 2001 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 1892 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 1777 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 1878 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 1906 of file DLS.cpp.

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

◆ 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 1791 of file DLS.cpp.

References RIFF::Chunk::GetFilePos(), RIFF::Chunk::GetPos(), RIFF::List::GetSubList(), and RIFF::List::GetSubListAt().

◆ 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 1763 of file DLS.cpp.

Referenced by DLS::Region::DeleteChunks(), gig::Group::GetFirstSample(), gig::Group::GetNextSample(), and gig::Group::GetSample().

◆ 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

Definition at line 2263 of file DLS.cpp.

References RIFF::File::Save(), 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

Definition at line 2330 of file DLS.cpp.

References RIFF::File::Save(), UpdateChunks(), and UpdateFileOffsets().

◆ 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 2021 of file DLS.cpp.

References RIFF::List::AddSubChunk(), RIFF::List::DeleteSubChunk(), 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(), and gig::File::UpdateChunks().

◆ UpdateFileOffsets()

void DLS::File::UpdateFileOffsets ( )

protectedvirtual

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 2385 of file DLS.cpp.

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

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

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ File() [1/2]

◆ File() [2/2]

Member Function Documentation

◆ __ensureMandatoryChunksExist()

◆ AddInstrument()

◆ AddSample()

◆ CopyAssign()

◆ DeleteChunks()

◆ DeleteInstrument()

◆ DeleteSample()

◆ GetExtensionFile()

◆ GetFileName()

◆ GetFirstInstrument()

◆ GetFirstSample()

◆ GetInstrument()

◆ GetNextInstrument()

◆ GetNextSample()

◆ GetSample()

◆ Save() [1/2]

◆ Save() [2/2]

◆ UpdateChunks()

◆ UpdateFileOffsets()