libgig  4.0.0
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:
DLS::Resource gig::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. More...
 
SampleGetFirstSample ()
 Returns a pointer to the first Sample object of the file, NULL otherwise. More...
 
SampleGetNextSample ()
 Returns a pointer to the next Sample object of the file, NULL otherwise. More...
 
SampleAddSample ()
 Add a new sample. More...
 
void DeleteSample (Sample *pSample)
 Delete a sample. More...
 
InstrumentGetFirstInstrument ()
 Returns a pointer to the first Instrument object of the file, NULL otherwise. More...
 
InstrumentGetNextInstrument ()
 Returns a pointer to the next Instrument object of the file, NULL otherwise. More...
 
InstrumentAddInstrument ()
 Add a new instrument definition. More...
 
void DeleteInstrument (Instrument *pInstrument)
 Delete an instrument. More...
 
RIFF::FileGetExtensionFile (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...
 
virtual ~File ()
 
ResourceGetParent ()
 
const ResourceGetParent () const
 
void GenerateDLSID ()
 Generates a new DLSID for the resource. More...
 
virtual void CopyAssign (const Resource *orig)
 Make a deep copy of the Resource object given by orig and assign it to this object. More...
 

Public Attributes

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

Protected Types

typedef std::list< Sample * > SampleList
 
typedef std::list< 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::FilepRIFF
 
std::list< RIFF::File * > ExtensionFiles
 
SampleListpSamples
 
SampleList::iterator SamplesIterator
 
InstrumentListpInstruments
 
InstrumentList::iterator InstrumentsIterator
 
uint32_t WavePoolHeaderSize
 
uint32_t WavePoolCount
 
uint32_t * pWavePoolTable
 
uint32_t * pWavePoolTableHi
 
bool b64BitWavePoolOffsets
 
ResourcepParent
 
RIFF::ListpResourceList
 

Friends

class Region
 

Detailed Description

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

Definition at line 496 of file DLS.h.

Member Typedef Documentation

◆ InstrumentList

typedef std::list<Instrument*> DLS::File::InstrumentList
protected

Definition at line 520 of file DLS.h.

◆ SampleList

typedef std::list<Sample*> DLS::File::SampleList
protected

Definition at line 519 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 1406 of file DLS.cpp.

References b64BitWavePoolOffsets, DLS::version_t::build, RIFF::endian_little, Instruments, DLS::version_t::major, DLS::version_t::minor, pInstruments, pRIFF, pSamples, pVersion, pWavePoolTable, pWavePoolTableHi, DLS::version_t::release, RIFF::File::SetByteOrder(), WavePoolCount, and WavePoolHeaderSize.

◆ 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
Exceptionif given file is not a DLS file, expected chunks are missing

Definition at line 1435 of file DLS.cpp.

References b64BitWavePoolOffsets, CHUNK_ID_COLH, CHUNK_ID_PTBL, CHUNK_ID_VERS, RIFF::Chunk::GetSize(), RIFF::List::GetSubChunk(), Instruments, pInstruments, pRIFF, pSamples, pVersion, pWavePoolTable, pWavePoolTableHi, RIFF::Chunk::Read(), RIFF::Chunk::ReadUint32(), RIFF::Chunk::SetPos(), WavePoolCount, and WavePoolHeaderSize.

◆ ~File()

DLS::File::~File ( )
virtual

Reimplemented in gig::File.

Definition at line 1483 of file DLS.cpp.

References ExtensionFiles, pInstruments, pSamples, pVersion, pWavePoolTable, and pWavePoolTableHi.

Member Function Documentation

◆ __ensureMandatoryChunksExist()

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

References __ensureMandatoryChunksExist(), RIFF::List::AddSubList(), RIFF::List::GetSubList(), LIST_TYPE_INS, LIST_TYPE_LINS, LoadInstruments(), pInstruments, and pRIFF.

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

References __ensureMandatoryChunksExist(), RIFF::List::AddSubList(), RIFF::List::GetSubList(), LIST_TYPE_WAVE, LIST_TYPE_WVPL, LoadSamples(), pRIFF, and pSamples.

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

References DLS::Resource::pInfo.

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

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

References pInstruments.

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

References pSamples.

◆ GenerateDLSID()

void Resource::GenerateDLSID ( )
inherited

Generates a new DLSID for the resource.

Definition at line 495 of file DLS.cpp.

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

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

References ExtensionFiles.

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

References RIFF::File::GetFileName(), and pRIFF.

Referenced by gig::File::AddContentOf().

◆ GetFirstInstrument()

Instrument * DLS::File::GetFirstInstrument ( )

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

Definition at line 1587 of file DLS.cpp.

References InstrumentsIterator, LoadInstruments(), and pInstruments.

◆ GetFirstSample()

Sample * DLS::File::GetFirstSample ( )

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

Definition at line 1511 of file DLS.cpp.

References LoadSamples(), pSamples, and SamplesIterator.

Referenced by gig::File::GetInstrument(), DLS::Region::GetSample(), and gig::File::UpdateChunks().

◆ GetNextInstrument()

Instrument * DLS::File::GetNextInstrument ( )

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

Definition at line 1594 of file DLS.cpp.

References InstrumentsIterator, and pInstruments.

◆ GetNextSample()

Sample * DLS::File::GetNextSample ( )

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

Definition at line 1518 of file DLS.cpp.

References pSamples, and SamplesIterator.

Referenced by DLS::Region::GetSample().

◆ GetParent() [1/2]

◆ GetParent() [2/2]

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

Definition at line 351 of file DLS.h.

◆ LoadInstruments()

void DLS::File::LoadInstruments ( )
protectedvirtual

◆ LoadSamples()

void DLS::File::LoadSamples ( )
protectedvirtual

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

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

Referenced by gig::File::AddContentOf().

◆ 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::Exceptionif any kind of IO error occurred
DLS::Exceptionif any kind of DLS specific error occurred

Definition at line 1817 of file DLS.cpp.

References pRIFF, RIFF::File::Save(), 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 1683 of file DLS.cpp.

References pRIFF, and RIFF::File::SetFileName().

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

References RIFF::List::AddSubChunk(), b64BitWavePoolOffsets, DLS::version_t::build, CHUNK_ID_COLH, CHUNK_ID_PTBL, CHUNK_ID_VERS, RIFF::List::GetSubChunk(), Instruments, RIFF::Chunk::LoadChunkData(), DLS::version_t::major, DLS::version_t::minor, pInstruments, pRIFF, pSamples, pVersion, DLS::version_t::release, RIFF::Chunk::Resize(), DLS::Resource::UpdateChunks(), WavePoolCount, and WavePoolHeaderSize.

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

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

Friends And Related Function Documentation

◆ Region

friend class Region
friend

Definition at line 538 of file DLS.h.

Member Data Documentation

◆ b64BitWavePoolOffsets

bool DLS::File::b64BitWavePoolOffsets
protected

Definition at line 532 of file DLS.h.

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

◆ ExtensionFiles

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

Definition at line 523 of file DLS.h.

Referenced by GetExtensionFile(), gig::File::LoadSamples(), and ~File().

◆ Instruments

uint32_t DLS::File::Instruments

Reflects the number of available Instrument objects.

Definition at line 499 of file DLS.h.

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

◆ InstrumentsIterator

InstrumentList::iterator DLS::File::InstrumentsIterator
protected

◆ 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 348 of file DLS.h.

◆ pInfo

Info* DLS::Resource::pInfo
inherited

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

Definition at line 347 of file DLS.h.

Referenced by gig::File::AddInstrument(), DLS::Resource::CopyAssign(), gig::File::File(), gig::Instrument::Instrument(), and gig::Sample::Sample().

◆ pInstruments

◆ pParent

Resource* DLS::Resource::pParent
protectedinherited

◆ pResourceList

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

Definition at line 357 of file DLS.h.

◆ pRIFF

◆ pSamples

◆ pVersion

version_t* DLS::File::pVersion

◆ pWavePoolTable

uint32_t* DLS::File::pWavePoolTable
protected

◆ pWavePoolTableHi

uint32_t* DLS::File::pWavePoolTableHi
protected

◆ SamplesIterator

SampleList::iterator DLS::File::SamplesIterator
protected

◆ WavePoolCount

uint32_t DLS::File::WavePoolCount
protected

◆ WavePoolHeaderSize

uint32_t DLS::File::WavePoolHeaderSize
protected

Definition at line 528 of file DLS.h.

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


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