DLS::Sample Class Reference

Encapsulates sample waves used for playback. More...

`#include <DLS.h>`

Inheritance diagram for DLS::Sample:

## Public Member Functions

void * | LoadSampleData ()
| Load sample data into RAM.
void | ReleaseSampleData ()
| Free sample data from RAM.
file_offset_t | GetSize () const
| Returns sample size.
void | Resize (file_offset_t NewSize)
| Resize sample.
file_offset_t | SetPos (file_offset_t SampleCount, RIFF::stream_whence_t Whence=RIFF::stream_start)
| Sets the position within the sample (in sample points, not in bytes).
file_offset_t | Read (void *pBuffer, file_offset_t SampleCount)
| Reads SampleCount number of sample points from the current position into the buffer pointed by pBuffer and increments the position within the sample.
file_offset_t | Write (void *pBuffer, file_offset_t SampleCount)
| Write sample wave data.
virtual void | UpdateChunks (progress_t *pProgress)
| Apply sample and its settings to the respective RIFF chunks.
virtual void | DeleteChunks ()
| Remove all RIFF chunks associated with this Sample object.
virtual void | CopyAssign (const Sample *orig)
| Make a deep copy of the Sample object given by orig and assign it to this object.
Resource * | GetParent ()
const Resource * | GetParent () const
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

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).
file_offset_t | 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, file_offset_t WavePoolOffset)
| Constructor.
virtual | ~Sample ()
| Destructor.
void | CopyAssignCore (const Sample *orig)
| Make a deep copy of the Sample object given by orig (without the actual sample waveform data however) and assign it to this object.

## Protected Attributes

RIFF::List * | pWaveList
RIFF::Chunk * | pCkData
RIFF::Chunk * | pCkFormat
file_offset_t | ullWavePoolOffset
Resource * | pParent
RIFF::List * | pResourceList

## Detailed Description

Encapsulates sample waves used for playback.

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

## Constructor & Destructor Documentation

## Sample()

DLS::Sample::Sample | ( | File * | pFile,
|  | RIFF::List * | waveList,
|  | file_offset_t | 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.

Parameters

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

References AverageBytesPerSecond, BitDepth, BlockAlign, Channels, FormatTag, FrameSize, RIFF::Chunk::GetFile(), RIFF::File::GetFileOffsetSize(), RIFF::List::GetSubChunk(), DLS::Resource::Resource(), SamplesPerSecond, and SamplesTotal.

Referenced by CopyAssign(), and CopyAssignCore().

## ~Sample()

DLS::Sample::~Sample | ( |  | ) |

protected virtual

Destructor.

Frees all memory occupied by this sample.

Reimplemented in gig::Sample.

Definition at line 880 of file DLS.cpp.

## Member Function Documentation

## CopyAssign() [1/2]

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

## CopyAssign() [2/2]

void DLS::Sample::CopyAssign | ( | const Sample * | orig | ) |

virtual

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

Parameters

  orig | - original Sample object to be copied from

Definition at line 934 of file DLS.cpp.

References CopyAssignCore(), FrameSize, RIFF::Chunk::GetPos(), GetSize(), LoadSampleData(), Read(), Resize(), Sample(), SetPos(), and RIFF::Chunk::SetPos().

## CopyAssignCore()

void DLS::Sample::CopyAssignCore | ( | const Sample * | orig | ) |

protected

Make a deep copy of the Sample object given by orig (without the actual sample waveform data however) and assign it to this object.

This is a special internal variant of CopyAssign() which only copies the most mandatory member variables. It will be called by gig::Sample descendent instead of CopyAssign() since gig::Sample has its own implementation to access and copy the actual sample waveform data.

Parameters

  orig | - original Sample object to be copied from

Definition at line 914 of file DLS.cpp.

References AverageBytesPerSecond, BitDepth, BlockAlign, Channels, DLS::Resource::CopyAssign(), FormatTag, FrameSize, Sample(), SamplesPerSecond, and SamplesTotal.

Referenced by CopyAssign(), and gig::Sample::CopyAssignMeta().

## DeleteChunks()

void DLS::Sample::DeleteChunks | ( |  | ) |

virtual

Remove all RIFF chunks associated with this Sample object.

See Storage::DeleteChunks() for details.

Reimplemented from DLS::Resource.

Definition at line 891 of file DLS.cpp.

References DLS::Resource::DeleteChunks(), RIFF::List::DeleteSubChunk(), and RIFF::Chunk::GetParent().

Referenced by DLS::File::DeleteSample(), and gig::File::DeleteSample().

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

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

## GetSize()

file_offset_t DLS::Sample::GetSize | ( |  | ) | const

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.

Returns
  number of sample points or 0 if FormatTag != DLS_WAVE_FORMAT_PCM

See also
  FrameSize, FormatTag

Definition at line 1003 of file DLS.cpp.

References FormatTag, and FrameSize.

Referenced by CopyAssign(), gig::Sample::CopyAssignMeta(), Write(), and gig::Sample::Write().

## LoadSampleData()

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.

Returns
  pointer to sample data in RAM, NULL in case respective 'data' chunk does not exist (yet)

Exceptions

  Exception | if data buffer could not be enlarged

See also
  Resize(), File::Save()

Definition at line 980 of file DLS.cpp.

Referenced by CopyAssign().

## Read()

file_offset_t DLS::Sample::Read | ( | void * | pBuffer,
|  | file_offset_t | 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.

Parameters

  pBuffer | destination buffer
  SampleCount | number of sample points to read

Definition at line 1081 of file DLS.cpp.

References FormatTag, and FrameSize.

Referenced by CopyAssign().

## ReleaseSampleData()

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.

Definition at line 989 of file DLS.cpp.

## Resize()

void DLS::Sample::Resize | ( | file_offset_t | NewSize | ) |

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!

Parameters

  NewSize | - new sample wave data size in sample points (must be greater than zero)

Exceptions

  Exception | if FormatTag != DLS_WAVE_FORMAT_PCM
  Exception | if NewSize is less than 1 or unrealistic large

See also
  File::Save(), FrameSize, FormatTag

Definition at line 1036 of file DLS.cpp.

References FormatTag, and FrameSize.

Referenced by CopyAssign(), and gig::Sample::Resize().

## SetPos()

file_offset_t DLS::Sample::SetPos | ( | file_offset_t | 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!

Parameters

  SampleCount | number of sample points
  Whence | to which relation SampleCount refers to

Returns
  new position within the sample, 0 if FormatTag != DLS_WAVE_FORMAT_PCM

Exceptions

  Exception | if no data RIFF chunk was created for the sample yet

See also
  FrameSize, FormatTag

Definition at line 1063 of file DLS.cpp.

References FormatTag, and FrameSize.

Referenced by CopyAssign().

## UpdateChunks()

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

virtual

Apply sample and its settings to the respective RIFF chunks.

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

Parameters

  pProgress | - callback function for progress notification

Exceptions

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

References AverageBytesPerSecond, BitDepth, BlockAlign, Channels, FormatTag, RIFF::Chunk::LoadChunkData(), SamplesPerSecond, and DLS::Resource::UpdateChunks().

Referenced by gig::Sample::UpdateChunks().

## Write()

file_offset_t DLS::Sample::Write | ( | void * | pBuffer,
|  | file_offset_t | 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().

Parameters

  pBuffer | - source buffer
  SampleCount | - number of sample points to write

Exceptions

  Exception | if current sample size is too small

See also
  LoadSampleData()

Definition at line 1101 of file DLS.cpp.

References FormatTag, FrameSize, and GetSize().

## Member Data Documentation

## AverageBytesPerSecond

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

Referenced by CopyAssignCore(), Sample(), and UpdateChunks().

## BitDepth

uint16_t DLS::Sample::BitDepth

Size of each sample per channel (only if known sample data format is used, 0 otherwise).

Definition at line 464 of file DLS.h.

Referenced by CopyAssignCore(), gig::Sample::Read(), Sample(), gig::Sample::Sample(), UpdateChunks(), and gig::Sample::Write().

## BlockAlign

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

Referenced by CopyAssignCore(), Sample(), and UpdateChunks().

## Channels

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

Referenced by CopyAssignCore(), gig::Sample::Read(), Sample(), gig::Sample::Sample(), UpdateChunks(), gig::File::UpdateChunks(), and gig::Sample::Write().

## FormatTag

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

Referenced by CopyAssignCore(), GetSize(), Read(), Resize(), Sample(), SetPos(), UpdateChunks(), and Write().

## FrameSize

uint DLS::Sample::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().

Definition at line 466 of file DLS.h.

Referenced by CopyAssign(), CopyAssignCore(), gig::Sample::CopyAssignWave(), gig::Sample::GetPos(), GetSize(), gig::Sample::LoadSampleDataWithNullSamplesExtension(), Read(), gig::Sample::Read(), gig::Sample::ReadAndLoop(), Resize(), Sample(), SetPos(), gig::Sample::SetPos(), Write(), and gig::Sample::Write().

## pCkData

RIFF::Chunk* DLS::Sample::pCkData

protected

Definition at line 481 of file DLS.h.

## pCkFormat

RIFF::Chunk* DLS::Sample::pCkFormat

protected

Definition at line 482 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().

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

## pWaveList

RIFF::List* DLS::Sample::pWaveList

protected

Definition at line 480 of file DLS.h.

## SamplesPerSecond

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

Referenced by CopyAssignCore(), Sample(), gig::Sample::Sample(), UpdateChunks(), and gig::Sample::UpdateChunks().

## SamplesTotal

file_offset_t 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 465 of file DLS.h.

Referenced by CopyAssignCore(), gig::Sample::LoadSampleData(), gig::Sample::LoadSampleDataWithNullSamplesExtension(), gig::Sample::LoadSampleDataWithNullSamplesExtension(), gig::Sample::Read(), Sample(), and gig::Sample::SetPos().

## ullWavePoolOffset

file_offset_t DLS::Sample::ullWavePoolOffset

protected

Definition at line 483 of file DLS.h.

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

- DLS.h
- DLS.cpp