libgig 4.5.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 DLS::Storage gig::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.
SampleGetSample (size_t index)
 Returns Sample object of index.
SampleGetFirstSample ()
 Returns a pointer to the first Sample object of the file, NULL otherwise.
SampleGetNextSample ()
 Returns a pointer to the next Sample object of the file, NULL otherwise.
SampleAddSample ()
 Add a new sample.
size_t CountSamples ()
 Returns the total amount of samples of this DLS file.
void DeleteSample (Sample *pSample)
 Delete a sample.
InstrumentGetInstrument (size_t index)
 Returns the instrument with the given index from the list of instruments of this file.
InstrumentGetFirstInstrument ()
 Returns a pointer to the first Instrument object of the file, NULL otherwise.
InstrumentGetNextInstrument ()
 Returns a pointer to the next Instrument object of the file, NULL otherwise.
InstrumentAddInstrument ()
 Add a new instrument definition.
void DeleteInstrument (Instrument *pInstrument)
 Delete an instrument.
RIFF::FileGetRiffFile ()
 Returns the underlying RIFF::File used for persistency of this DLS::File object.
RIFF::FileGetExtensionFile (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.
ResourceGetParent ()
const ResourceGetParent () 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_tpVersion
 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.
InfopInfo
 Points (in any case) to an Info object, providing additional, optional infos and comments.
dlsid_tpDLSID
 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::FilepRIFF
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.
ResourcepParent
RIFF::ListpResourceList

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
Exceptionif 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)
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 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 ( )
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 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)
staticinherited

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 ( )
inlineinherited

Definition at line 409 of file DLS.h.

◆ GetParent() [2/2]

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

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 ( )
protectedvirtual

Definition at line 1943 of file DLS.cpp.

◆ LoadSamples()

void DLS::File::LoadSamples ( )
protectedvirtual

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::Exceptionif any kind of IO error occurred
DLS::Exceptionif 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 ( )
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 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
protectedinherited

Definition at line 417 of file DLS.h.

◆ pResourceList

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

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: