#include <DLS.h>
Public Member Functions | |
void * | LoadSampleData () |
Load sample data into RAM. | |
void | ReleaseSampleData () |
Free sample data from RAM. | |
unsigned long | GetSize () |
Returns sample size. | |
void | Resize (int iNewSize) |
Resize sample. | |
unsigned long | SetPos (unsigned long SampleCount, RIFF::stream_whence_t Whence=RIFF::stream_start) |
Sets the position within the sample (in sample points, not in bytes). | |
unsigned long | Read (void *pBuffer, unsigned long SampleCount) |
Reads SampleCount number of sample points from the current position into the buffer pointed by pBuffer and increments the position within the sample. | |
unsigned long | Write (void *pBuffer, unsigned long SampleCount) |
Write sample wave data. | |
virtual void | UpdateChunks () |
Apply sample and its settings to the respective RIFF chunks. | |
Resource * | GetParent () |
void | GenerateDLSID () |
Generates a new DLSID for the resource. | |
Public Attributes | |
uint16_t | FormatTag |
Format ID of the waveform data (should be DLS_WAVE_FORMAT_PCM for DLS1 compliant files, this is also the default value if Sample was created with Instrument::AddSample()). | |
uint16_t | Channels |
Number of channels represented in the waveform data, e.g. 1 for mono, 2 for stereo (defaults to 1=mono if Sample was created with Instrument::AddSample() previously). | |
uint32_t | SamplesPerSecond |
Sampling rate at which each channel should be played (defaults to 44100 if Sample was created with Instrument::AddSample() previously). | |
uint32_t | AverageBytesPerSecond |
The average number of bytes per second at which the waveform data should be transferred (Playback software can estimate the buffer size using this value). | |
uint16_t | BlockAlign |
The block alignment (in bytes) of the waveform data. Playback software needs to process a multiple of BlockAlign bytes of data at a time, so the value of BlockAlign can be used for buffer alignment. | |
uint16_t | BitDepth |
Size of each sample per channel (only if known sample data format is used, 0 otherwise). | |
unsigned long | SamplesTotal |
Reflects total number of sample points (only if known sample data format is used, 0 otherwise), do not bother to change this value, it will not be saved. | |
uint | FrameSize |
Reflects the size (in bytes) of one single sample point (only if known sample data format is used, 0 otherwise). Caution: with the current version of libgig you have to upate this field by yourself whenever you change one of the following fields: Channels, BitDepth ! Ignoring this might lead to undesired behavior when i.e. calling Resize(), SetPos(), Write() or Read(). | |
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 Member Functions | |
Sample (File *pFile, RIFF::List *waveList, unsigned long WavePoolOffset) | |
Constructor. | |
virtual | ~Sample () |
Destructor. | |
Protected Attributes | |
RIFF::List * | pWaveList |
RIFF::Chunk * | pCkData |
RIFF::Chunk * | pCkFormat |
unsigned long | ulWavePoolOffset |
Resource * | pParent |
RIFF::List * | pResourceList |
Friends | |
class | File |
class | Region |
In case you created a new sample with File::AddSample(), you should first update all attributes with the desired meta informations (amount of channels, bit depth, sample rate, etc.), then call Resize() with the desired sample size. The latter will create the mandatory RIFF chunk which will hold the sample wave data.
Definition at line 386 of file DLS.h.
DLS::Sample::Sample | ( | File * | pFile, | |
RIFF::List * | waveList, | |||
unsigned long | WavePoolOffset | |||
) | [protected] |
Constructor.
Load an existing sample or create a new one. A 'wave' list chunk must be given to this constructor. In case the given 'wave' list chunk contains a 'fmt' and 'data' chunk, the format and sample data will be loaded from there, otherwise default values will be used and those chunks will be created when File::Save() will be called later on.
pFile | - pointer to DLS::File where this sample is located (or will be located) | |
waveList | - pointer to 'wave' list chunk which is (or will be) associated with this sample | |
WavePoolOffset | - offset of this sample data from wave pool ('wvpl') list chunk |
Definition at line 634 of file DLS.cpp.
References AverageBytesPerSecond, BitDepth, BlockAlign, Channels, CHUNK_ID_DATA, CHUNK_ID_FMT, DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, RIFF::Chunk::GetSize(), RIFF::List::GetSubChunk(), LIST_HEADER_SIZE, pCkData, pCkFormat, pWaveList, RIFF::Chunk::ReadUint16(), RIFF::Chunk::ReadUint32(), SamplesPerSecond, SamplesTotal, and ulWavePoolOffset.
DLS::Sample::~Sample | ( | ) | [protected, virtual] |
Destructor.
Removes RIFF chunks associated with this Sample and frees all memory occupied by this sample.
Reimplemented in gig::Sample.
Definition at line 673 of file DLS.cpp.
References RIFF::List::DeleteSubChunk(), RIFF::Chunk::GetParent(), DLS::Resource::pParent, and pWaveList.
void DLS::Resource::GenerateDLSID | ( | ) | [inherited] |
Generates a new DLSID for the resource.
Definition at line 450 of file DLS.cpp.
References DLS::dlsid_t::abData, DLS::Resource::pDLSID, DLS::dlsid_t::ulData1, DLS::dlsid_t::usData2, and DLS::dlsid_t::usData3.
Referenced by gig::File::AddInstrument(), and gig::File::File().
Resource* DLS::Resource::GetParent | ( | ) | [inline, inherited] |
Definition at line 344 of file DLS.h.
References DLS::Resource::pParent.
Referenced by gig::Region::AddDimension(), DLS::Region::GetSample(), gig::Region::GetSampleFromWavePool(), gig::Region::Region(), gig::Region::SetKeyRange(), DLS::Region::SetKeyRange(), gig::Instrument::UpdateChunks(), gig::Region::UpdateChunks(), gig::DimensionRegion::UpdateChunks(), DLS::Region::UpdateChunks(), and gig::Sample::Write().
unsigned long DLS::Sample::GetSize | ( | ) |
Returns sample size.
Returns the sample wave form's data size (in sample points). This is actually the current, physical size (converted to sample points) of the RIFF chunk which encapsulates the sample's wave data. The returned value is dependant to the current FrameSize value.
Definition at line 727 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, RIFF::Chunk::GetSize(), and pCkData.
Referenced by gig::Sample::Write(), and Write().
void * DLS::Sample::LoadSampleData | ( | ) |
Load sample data into RAM.
In case the respective 'data' chunk exists, the sample data will be loaded into RAM (if not done already) and a pointer to the data in RAM will be returned. If this is a new sample, you have to call Resize() with the desired sample size to create the mandatory RIFF chunk for the sample wave data.
You can call LoadChunkData() again if you previously scheduled to enlarge the sample data RIFF chunk with a Resize() call. In that case the buffer will be enlarged to the new, scheduled size and you can already place the sample wave data to the buffer and finally call File::Save() to enlarge the sample data's chunk physically and write the new sample wave data in one rush. This approach is definitely recommended if you have to enlarge and write new sample data to a lot of samples.
Caution: the buffer pointer will be invalidated once File::Save() was called. You have to call LoadChunkData() again to get a new, valid pointer whenever File::Save() was called.
Exception | if data buffer could not be enlarged |
Reimplemented in gig::Sample.
Definition at line 704 of file DLS.cpp.
References RIFF::Chunk::LoadChunkData(), and pCkData.
unsigned long DLS::Sample::Read | ( | void * | pBuffer, | |
unsigned long | SampleCount | |||
) |
Reads SampleCount number of sample points from the current position into the buffer pointed by pBuffer and increments the position within the sample.
Use this method and SetPos() if you don't want to load the sample into RAM, thus for disk streaming.
pBuffer | destination buffer | |
SampleCount | number of sample points to read |
Definition at line 803 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, pCkData, and RIFF::Chunk::Read().
void DLS::Sample::ReleaseSampleData | ( | ) |
Free sample data from RAM.
In case sample data was previously successfully loaded into RAM with LoadSampleData(), this method will free the sample data from RAM.
Reimplemented in gig::Sample.
Definition at line 713 of file DLS.cpp.
References pCkData, and RIFF::Chunk::ReleaseChunkData().
void DLS::Sample::Resize | ( | int | iNewSize | ) |
Resize sample.
Resizes the sample's wave form data, that is the actual size of sample wave data possible to be written for this sample. This call will return immediately and just schedule the resize operation. You should call File::Save() to actually perform the resize operation(s) "physically" to the file. As this can take a while on large files, it is recommended to call Resize() first on all samples which have to be resized and finally to call File::Save() to perform all those resize operations in one rush.
The actual size (in bytes) is dependant to the current FrameSize value. You may want to set FrameSize before calling Resize().
Caution: You cannot directly write to enlarged samples before calling File::Save() as this might exceed the current sample's boundary!
Also note: only DLS_WAVE_FORMAT_PCM is currently supported, that is FormatTag must be DLS_WAVE_FORMAT_PCM. Trying to resize samples with other formats will fail!
iNewSize | - new sample wave data size in sample points (must be greater than zero) |
Excecption | if FormatTag != DLS_WAVE_FORMAT_PCM | |
Exception | if iNewSize is less than 1 |
Reimplemented in gig::Sample.
Definition at line 760 of file DLS.cpp.
References RIFF::List::AddSubChunk(), CHUNK_ID_DATA, DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, RIFF::List::GetSubChunk(), pCkData, pWaveList, and RIFF::Chunk::Resize().
unsigned long DLS::Sample::SetPos | ( | unsigned long | SampleCount, | |
RIFF::stream_whence_t | Whence = RIFF::stream_start | |||
) |
Sets the position within the sample (in sample points, not in bytes).
Use this method and Read() if you don't want to load the sample into RAM, thus for disk streaming.
Also note: only DLS_WAVE_FORMAT_PCM is currently supported, that is FormatTag must be DLS_WAVE_FORMAT_PCM. Trying to reposition the sample with other formats will fail!
SampleCount | number of sample points | |
Whence | to which relation SampleCount refers to |
Reimplemented in gig::Sample.
Definition at line 785 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, pCkData, and RIFF::Chunk::SetPos().
void DLS::Sample::UpdateChunks | ( | ) | [virtual] |
Apply sample and its settings to the respective RIFF chunks.
You have to call File::Save() to make changes persistent.
Exception | if FormatTag != DLS_WAVE_FORMAT_PCM or no sample data was provided yet |
Reimplemented from DLS::Resource.
Reimplemented in gig::Sample.
Definition at line 836 of file DLS.cpp.
References RIFF::List::AddSubChunk(), AverageBytesPerSecond, BitDepth, BlockAlign, Channels, CHUNK_ID_FMT, DLS_WAVE_FORMAT_PCM, FormatTag, RIFF::List::GetSubChunk(), RIFF::Chunk::LoadChunkData(), pCkData, pCkFormat, pWaveList, and SamplesPerSecond.
unsigned long DLS::Sample::Write | ( | void * | pBuffer, | |
unsigned long | SampleCount | |||
) |
Write sample wave data.
Writes SampleCount number of sample points from the buffer pointed by pBuffer and increments the position within the sample. Use this method to directly write the sample data to disk, i.e. if you don't want or cannot load the whole sample data into RAM.
You have to Resize() the sample to the desired size and call File::Save() before using Write().
pBuffer | - source buffer | |
SampleCount | - number of sample points to write |
Exception | if current sample size is too small |
Reimplemented in gig::Sample.
Definition at line 823 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, FormatTag, FrameSize, GetSize(), pCkData, and RIFF::Chunk::Write().
friend class File [friend] |
friend class Region [friend] |
uint32_t DLS::Sample::AverageBytesPerSecond |
The average number of bytes per second at which the waveform data should be transferred (Playback software can estimate the buffer size using this value).
Definition at line 391 of file DLS.h.
Referenced by Sample(), and UpdateChunks().
uint16_t DLS::Sample::BitDepth |
Size of each sample per channel (only if known sample data format is used, 0 otherwise).
Definition at line 393 of file DLS.h.
Referenced by gig::Sample::GuessSize(), gig::Sample::Read(), gig::Sample::Sample(), Sample(), UpdateChunks(), and gig::Sample::Write().
uint16_t DLS::Sample::BlockAlign |
The block alignment (in bytes) of the waveform data. Playback software needs to process a multiple of BlockAlign bytes of data at a time, so the value of BlockAlign can be used for buffer alignment.
Definition at line 392 of file DLS.h.
Referenced by Sample(), and UpdateChunks().
uint16_t DLS::Sample::Channels |
Number of channels represented in the waveform data, e.g. 1 for mono, 2 for stereo (defaults to 1=mono if Sample was created with Instrument::AddSample() previously).
Definition at line 389 of file DLS.h.
Referenced by gig::Sample::GuessSize(), gig::Sample::Sample(), Sample(), gig::File::UpdateChunks(), and UpdateChunks().
uint16_t DLS::Sample::FormatTag |
Format ID of the waveform data (should be DLS_WAVE_FORMAT_PCM for DLS1 compliant files, this is also the default value if Sample was created with Instrument::AddSample()).
Definition at line 388 of file DLS.h.
Referenced by GetSize(), Read(), Resize(), Sample(), SetPos(), UpdateChunks(), and Write().
Reflects the size (in bytes) of one single sample point (only if known sample data format is used, 0 otherwise). Caution: with the current version of libgig you have to upate this field by yourself whenever you change one of the following fields: Channels, BitDepth ! Ignoring this might lead to undesired behavior when i.e. calling Resize(), SetPos(), Write() or Read().
Definition at line 395 of file DLS.h.
Referenced by gig::Sample::GetPos(), GetSize(), gig::Sample::LoadSampleDataWithNullSamplesExtension(), gig::Sample::Read(), Read(), gig::Sample::ReadAndLoop(), Resize(), Sample(), gig::Sample::SetPos(), SetPos(), gig::Sample::Write(), and Write().
RIFF::Chunk* DLS::Sample::pCkData [protected] |
Definition at line 407 of file DLS.h.
Referenced by gig::Sample::GetPos(), GetSize(), LoadSampleData(), gig::Sample::Read(), Read(), ReleaseSampleData(), Resize(), Sample(), gig::Sample::SetPos(), SetPos(), UpdateChunks(), gig::Sample::Write(), and Write().
RIFF::Chunk* DLS::Sample::pCkFormat [protected] |
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 342 of file DLS.h.
Referenced by DLS::Resource::GenerateDLSID(), DLS::Resource::Resource(), DLS::Resource::UpdateChunks(), and DLS::Resource::~Resource().
Info* DLS::Resource::pInfo [inherited] |
Points (in any case) to an Info object, providing additional, optional infos and comments.
Definition at line 341 of file DLS.h.
Referenced by gig::File::AddInstrument(), gig::File::File(), gig::Instrument::Instrument(), DLS::Resource::Resource(), gig::Sample::Sample(), DLS::Resource::UpdateChunks(), and DLS::Resource::~Resource().
Resource* DLS::Resource::pParent [protected, inherited] |
Definition at line 348 of file DLS.h.
Referenced by DLS::Resource::GetParent(), DLS::Resource::Resource(), gig::Sample::UpdateChunks(), DLS::Instrument::~Instrument(), DLS::Region::~Region(), and ~Sample().
RIFF::List* DLS::Resource::pResourceList [protected, inherited] |
Definition at line 349 of file DLS.h.
Referenced by DLS::Resource::Resource(), and DLS::Resource::UpdateChunks().
RIFF::List* DLS::Sample::pWaveList [protected] |
Definition at line 406 of file DLS.h.
Referenced by Resize(), Sample(), gig::Sample::UpdateChunks(), UpdateChunks(), and ~Sample().
uint32_t DLS::Sample::SamplesPerSecond |
Sampling rate at which each channel should be played (defaults to 44100 if Sample was created with Instrument::AddSample() previously).
Definition at line 390 of file DLS.h.
Referenced by gig::Sample::Sample(), Sample(), gig::Sample::UpdateChunks(), and UpdateChunks().
unsigned long DLS::Sample::SamplesTotal |
Reflects total number of sample points (only if known sample data format is used, 0 otherwise), do not bother to change this value, it will not be saved.
Definition at line 394 of file DLS.h.
Referenced by gig::Sample::LoadSampleData(), gig::Sample::LoadSampleDataWithNullSamplesExtension(), gig::Sample::Read(), Sample(), and gig::Sample::SetPos().
unsigned long DLS::Sample::ulWavePoolOffset [protected] |
Definition at line 409 of file DLS.h.
Referenced by DLS::Region::GetSample(), gig::Region::GetSampleFromWavePool(), and Sample().