libgig
3.3.0.19svn2660
|
Encapsulates sample waves used for playback. More...
#include <gig.h>
Public Member Functions | |
buffer_t | LoadSampleData () |
Loads (and uncompresses if needed) the whole sample wave into RAM. More... | |
buffer_t | LoadSampleData (unsigned long SampleCount) |
Reads (uncompresses if needed) and caches the first SampleCount numbers of SamplePoints in RAM. More... | |
buffer_t | LoadSampleDataWithNullSamplesExtension (uint NullSamplesCount) |
Loads (and uncompresses if needed) the whole sample wave into RAM. More... | |
buffer_t | LoadSampleDataWithNullSamplesExtension (unsigned long SampleCount, uint NullSamplesCount) |
Reads (uncompresses if needed) and caches the first SampleCount numbers of SamplePoints in RAM. More... | |
buffer_t | GetCache () |
Returns current cached sample points. More... | |
void | ReleaseSampleData () |
Frees the cached sample from RAM if loaded with LoadSampleData() previously. More... | |
void | Resize (int iNewSize) |
Resize sample. More... | |
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). More... | |
unsigned long | GetPos () const |
Returns the current position in the sample (in sample points). More... | |
unsigned long | Read (void *pBuffer, unsigned long SampleCount, buffer_t *pExternalDecompressionBuffer=NULL) |
Reads SampleCount number of sample points from the current position into the buffer pointed by pBuffer and increments the position within the sample. More... | |
unsigned long | ReadAndLoop (void *pBuffer, unsigned long SampleCount, playback_state_t *pPlaybackState, DimensionRegion *pDimRgn, buffer_t *pExternalDecompressionBuffer=NULL) |
Reads SampleCount number of sample points from the position stored in pPlaybackState into the buffer pointed by pBuffer and moves the position within the sample respectively, this method honors the looping informations of the sample (if any). More... | |
unsigned long | Write (void *pBuffer, unsigned long SampleCount) |
Write sample wave data. More... | |
Group * | GetGroup () const |
Returns pointer to the Group this Sample belongs to. More... | |
virtual void | UpdateChunks () |
Apply sample and its settings to the respective RIFF chunks. More... | |
void | CopyAssignMeta (const Sample *orig) |
Make a (semi) deep copy of the Sample object given by orig (without the actual waveform data) and assign it to this object. More... | |
void | CopyAssignWave (const Sample *orig) |
Should be called after CopyAssignMeta() and File::Save() sequence. More... | |
unsigned long | GetSize () const |
Returns sample size. More... | |
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. More... | |
virtual void | CopyAssign (const Sample *orig) |
Make a deep copy of the Sample object given by orig and assign it to this object. 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... | |
Resource * | GetParent () |
const Resource * | GetParent () const |
void | GenerateDLSID () |
Generates a new DLSID for the resource. More... | |
Static Public Member Functions | |
static buffer_t | CreateDecompressionBuffer (unsigned long MaxReadSize) |
Allocates a decompression buffer for streaming (compressed) samples with Sample::Read(). More... | |
static void | DestroyDecompressionBuffer (buffer_t &DecompressionBuffer) |
Free decompression buffer, previously created with CreateDecompressionBuffer(). More... | |
Public Attributes | |
uint32_t | Manufacturer |
Specifies the MIDI Manufacturer's Association (MMA) Manufacturer code for the sampler intended to receive this file's waveform. If no particular manufacturer is to be specified, a value of 0 should be used. More... | |
uint32_t | Product |
Specifies the MIDI model ID defined by the manufacturer corresponding to the Manufacturer field. If no particular manufacturer's product is to be specified, a value of 0 should be used. More... | |
uint32_t | SamplePeriod |
Specifies the duration of time that passes during the playback of one sample in nanoseconds (normally equal to 1 / Samples Per Second, where Samples Per Second is the value found in the format chunk), don't bother to update this attribute, it won't be saved. More... | |
uint32_t | MIDIUnityNote |
Specifies the musical note at which the sample will be played at it's original sample rate. More... | |
uint32_t | FineTune |
Specifies the fraction of a semitone up from the specified MIDI unity note field. A value of 0x80000000 means 1/2 semitone (50 cents) and a value of 0x00000000 means no fine tuning between semitones. More... | |
smpte_format_t | SMPTEFormat |
Specifies the Society of Motion Pictures and Television E time format used in the following SMPTEOffset field. If a value of 0 is set, SMPTEOffset should also be set to 0. More... | |
uint32_t | SMPTEOffset |
The SMPTE Offset value specifies the time offset to be used for the synchronization / calibration to the first sample in the waveform. This value uses a format of 0xhhmmssff where hh is a signed value that specifies the number of hours (-23 to 23), mm is an unsigned value that specifies the number of minutes (0 to 59), ss is an unsigned value that specifies the number of seconds (0 to 59) and ff is an unsigned value that specifies the number of frames (0 to -1). More... | |
uint32_t | Loops |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: Number of defined sample loops. So far only seen single loops in gig files - please report if you encounter more!) More... | |
uint32_t | LoopID |
Specifies the unique ID that corresponds to one of the defined cue points in the cue point list (only if Loops > 0), as the Gigasampler format only allows one loop definition at the moment, this attribute isn't really useful for anything. More... | |
loop_type_t | LoopType |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The type field defines how the waveform samples will be looped.) More... | |
uint32_t | LoopStart |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The start value specifies the offset [in sample points] in the waveform data of the first sample to be played in the loop [only if Loops > 0].) More... | |
uint32_t | LoopEnd |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The end value specifies the offset [in sample points] in the waveform data which represents the end of the loop [only if Loops > 0].) More... | |
uint32_t | LoopSize |
Caution: Use the respective fields in the DimensionRegion instead of this one! (Intended purpose: Length of the looping area [in sample points] which is equivalent to More... | |
uint32_t | LoopFraction |
The fractional value specifies a fraction of a sample at which to loop. This allows a loop to be fine tuned at a resolution greater than one sample. A value of 0 means no fraction, a value of 0x80000000 means 1/2 of a sample length. 0xFFFFFFFF is the smallest fraction of a sample that can be represented. More... | |
uint32_t | LoopPlayCount |
Number of times the loop should be played (a value of 0 = infinite). More... | |
bool | Compressed |
If the sample wave is compressed (probably just interesting for instrument and sample editors, as this library already handles the decompression in it's sample access methods anyway). More... | |
uint32_t | TruncatedBits |
For 24-bit compressed samples only: number of bits truncated during compression (0, 4 or 6) More... | |
bool | Dithered |
For 24-bit compressed samples only: if dithering was used during compression with bit reduction. More... | |
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()). More... | |
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). More... | |
uint32_t | SamplesPerSecond |
Sampling rate at which each channel should be played (defaults to 44100 if Sample was created with Instrument::AddSample() previously). More... | |
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). More... | |
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. More... | |
uint16_t | BitDepth |
Size of each sample per channel (only if known sample data format is used, 0 otherwise). More... | |
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. More... | |
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(). More... | |
Info * | pInfo |
Points (in any case) to an Info object, providing additional, optional infos and comments. More... | |
dlsid_t * | pDLSID |
Points to a dlsid_t structure if the file provided a DLS ID else is NULL. More... | |
Protected Member Functions | |
Sample (File *pFile, RIFF::List *waveList, unsigned long WavePoolOffset, unsigned long fileNo=0) | |
Constructor. More... | |
~Sample () | |
Destructor. More... | |
unsigned long | GuessSize (unsigned long samples) |
unsigned long | WorstCaseMaxSamples (buffer_t *pDecompressionBuffer) |
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. More... | |
Protected Attributes | |
Group * | pGroup |
pointer to the Group this sample belongs to (always not-NULL) More... | |
unsigned long | FrameOffset |
Current offset (sample points) in current sample frame (for decompression only). More... | |
unsigned long * | FrameTable |
For positioning within compressed samples only: stores the offset values for each frame. More... | |
unsigned long | SamplePos |
For compressed samples only: stores the current position (in sample points). More... | |
unsigned long | SamplesInLastFrame |
For compressed samples only: length of the last sample frame. More... | |
unsigned long | WorstCaseFrameSize |
For compressed samples only: size (in bytes) of the largest possible sample frame. More... | |
unsigned long | SamplesPerFrame |
For compressed samples only: number of samples in a full sample frame. More... | |
buffer_t | RAMCache |
Buffers samples (already uncompressed) in RAM. More... | |
unsigned long | FileNo |
File number (> 0 when sample is stored in an extension file, 0 when it's in the gig) More... | |
RIFF::Chunk * | pCk3gix |
RIFF::Chunk * | pCkSmpl |
uint32_t | crc |
CRC-32 checksum of the raw sample data. More... | |
RIFF::List * | pWaveList |
RIFF::Chunk * | pCkData |
RIFF::Chunk * | pCkFormat |
unsigned long | ulWavePoolOffset |
Resource * | pParent |
RIFF::List * | pResourceList |
Static Protected Attributes | |
static unsigned int | Instances = 0 |
Number of instances of class Sample. More... | |
static buffer_t | InternalDecompressionBuffer |
Buffer used for decompression as well as for truncation of 24 Bit -> 16 Bit samples. More... | |
Friends | |
class | File |
class | Region |
class | Group |
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, followed by File::Save(), this will create the mandatory RIFF chunk which will hold the sample wave data and / or resize the file so you will be able to Write() the sample data directly to disk.
Caution: for gig synthesis, most looping relevant information are retrieved from the respective DimensionRegon instead from the Sample itself. This was made for allowing different loop definitions for the same sample under different conditions.
|
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', 'data' (and optionally a '3gix', 'smpl') 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 gig::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 |
fileNo | - number of an extension file where this sample is located, 0 otherwise |
Definition at line 370 of file gig.cpp.
References DLS::Sample::BitDepth, DLS::Sample::Channels, CHUNK_ID_3GIX, CHUNK_ID_EWAV, CHUNK_ID_INAM, CHUNK_ID_SMPL, Compressed, Dithered, FileNo, FineTune, FrameOffset, FrameTable, gig::File::GetGroup(), RIFF::List::GetSubChunk(), INITIAL_SAMPLE_BUFFER_SIZE, Instances, InternalDecompressionBuffer, gig::loop_type_normal, LoopEnd, LoopFraction, LoopID, LoopPlayCount, Loops, LoopSize, LoopStart, LoopType, Manufacturer, MIDIUnityNote, gig::buffer_t::NullExtensionSize, pCk3gix, pCkSmpl, pGroup, DLS::Resource::pInfo, Product, gig::buffer_t::pStart, RAMCache, RIFF::Chunk::Read(), RIFF::Chunk::ReadInt16(), RIFF::Chunk::ReadInt32(), SamplePeriod, SamplePos, DLS::Sample::SamplesPerSecond, DLS::Info::SetFixedStringLengths(), RIFF::Chunk::SetPos(), gig::buffer_t::Size, gig::smpte_format_no_offset, SMPTEFormat, SMPTEOffset, and TruncatedBits.
|
protectedvirtual |
Destructor.
Removes RIFF chunks associated with this Sample and frees all memory occupied by this sample.
Reimplemented from DLS::Sample.
Definition at line 1371 of file gig.cpp.
References FrameTable, Instances, InternalDecompressionBuffer, gig::buffer_t::pStart, RAMCache, and gig::buffer_t::Size.
|
virtualinherited |
Make a deep copy of the Resource object given by orig and assign it to this object.
orig | - original Resource object to be copied from |
Definition at line 534 of file DLS.cpp.
References DLS::Info::CopyAssign(), and DLS::Resource::pInfo.
Referenced by DLS::Region::CopyAssign(), DLS::Sample::CopyAssignCore(), and DLS::Instrument::CopyAssignCore().
|
virtualinherited |
Make a deep copy of the Sample object given by orig and assign it to this object.
orig | - original Sample object to be copied from |
Definition at line 779 of file DLS.cpp.
References DLS::Sample::CopyAssignCore(), DLS::Sample::FrameSize, RIFF::Chunk::GetPos(), DLS::Sample::GetSize(), DLS::Sample::LoadSampleData(), DLS::Sample::pCkData, DLS::Sample::Read(), DLS::Sample::Resize(), RIFF::Chunk::SetPos(), and DLS::Sample::SetPos().
|
protectedinherited |
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.
orig | - original Sample object to be copied from |
Definition at line 759 of file DLS.cpp.
References DLS::Sample::AverageBytesPerSecond, DLS::Sample::BitDepth, DLS::Sample::BlockAlign, DLS::Sample::Channels, DLS::Resource::CopyAssign(), DLS::Sample::FormatTag, DLS::Sample::FrameSize, DLS::Sample::SamplesPerSecond, and DLS::Sample::SamplesTotal.
Referenced by DLS::Sample::CopyAssign(), and CopyAssignMeta().
void gig::Sample::CopyAssignMeta | ( | const Sample * | orig | ) |
Make a (semi) deep copy of the Sample object given by orig (without the actual waveform data) and assign it to this object.
Discussion: copying .gig samples is a bit tricky. It requires three steps:
orig | - original Sample object to be copied from |
Definition at line 472 of file gig.cpp.
References DLS::Sample::CopyAssignCore(), FineTune, DLS::Sample::GetSize(), LoopEnd, LoopFraction, LoopID, LoopPlayCount, Loops, LoopSize, LoopStart, LoopType, Manufacturer, MIDIUnityNote, Product, Resize(), SamplePeriod, SMPTEFormat, and SMPTEOffset.
Referenced by gig::File::AddContentOf().
void gig::Sample::CopyAssignWave | ( | const Sample * | orig | ) |
Should be called after CopyAssignMeta() and File::Save() sequence.
Read more about it in the discussion of CopyAssignMeta(). This method copies the actual waveform data by disk streaming.
CAUTION: this method is currently not thread safe! During this operation the sample must not be used for other purposes by other threads!
orig | - original Sample object to be copied from |
Definition at line 508 of file gig.cpp.
References DLS::Sample::FrameSize, GetPos(), Read(), SetPos(), and Write().
|
static |
Allocates a decompression buffer for streaming (compressed) samples with Sample::Read().
If you are using more than one streaming thread in your application you HAVE to create a decompression buffer for EACH of your streaming threads and provide it with the Sample::Read() call in order to avoid race conditions and crashes.
You should free the memory occupied by the allocated buffer(s) once you don't need one of your streaming threads anymore by calling DestroyDecompressionBuffer().
MaxReadSize | - the maximum size (in sample points) you ever expect to read with one Read() call |
Definition at line 1333 of file gig.cpp.
References gig::buffer_t::NullExtensionSize, gig::buffer_t::pStart, and gig::buffer_t::Size.
|
static |
Free decompression buffer, previously created with CreateDecompressionBuffer().
DecompressionBuffer | - previously allocated decompression buffer to free |
Definition at line 1350 of file gig.cpp.
References gig::buffer_t::NullExtensionSize, gig::buffer_t::pStart, and gig::buffer_t::Size.
|
inherited |
Generates a new DLSID for the resource.
Definition at line 487 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().
buffer_t gig::Sample::GetCache | ( | ) |
Returns current cached sample points.
A buffer_t structure will be returned which contains address pointer to the begin of the cache and the size of the cached sample data in bytes. Use LoadSampleData() to cache a specific amount of sample points in RAM.
Definition at line 775 of file gig.cpp.
References gig::buffer_t::NullExtensionSize, gig::buffer_t::pStart, RAMCache, and gig::buffer_t::Size.
Referenced by LoadSampleDataWithNullSamplesExtension().
Group * gig::Sample::GetGroup | ( | ) | const |
Returns pointer to the Group this Sample belongs to.
In the .gig format a sample always belongs to one group. If it wasn't explicitly assigned to a certain group, it will be automatically assigned to a default group.
Definition at line 1367 of file gig.cpp.
References pGroup.
Referenced by gig::File::AddContentOf().
|
inlineinherited |
Definition at line 349 of file DLS.h.
References DLS::Resource::pParent.
Referenced by gig::Region::AddDimension(), DLS::Region::CopyAssign(), gig::DimensionRegion::CopyAssign(), gig::Region::DeleteDimensionZone(), DLS::Region::GetSample(), gig::Region::GetSampleFromWavePool(), gig::Instrument::LoadScripts(), gig::Region::Region(), DLS::Region::SetKeyRange(), gig::Region::SetKeyRange(), gig::Region::SplitDimensionZone(), DLS::Region::UpdateChunks(), gig::DimensionRegion::UpdateChunks(), gig::Region::UpdateChunks(), gig::Instrument::UpdateChunks(), and Write().
|
inlineinherited |
Definition at line 350 of file DLS.h.
References DLS::Resource::pParent.
unsigned long gig::Sample::GetPos | ( | ) | const |
Returns the current position in the sample (in sample points).
Definition at line 887 of file gig.cpp.
References Compressed, DLS::Sample::FrameSize, RIFF::Chunk::GetPos(), DLS::Sample::pCkData, and SamplePos.
Referenced by CopyAssignWave(), and ReadAndLoop().
|
inherited |
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 848 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, DLS::Sample::FormatTag, DLS::Sample::FrameSize, RIFF::Chunk::GetSize(), and DLS::Sample::pCkData.
Referenced by DLS::Sample::CopyAssign(), CopyAssignMeta(), DLS::Sample::Write(), and Write().
|
inlineprotected |
Definition at line 673 of file gig.h.
References DLS::Sample::BitDepth, DLS::Sample::Channels, and WorstCaseFrameSize.
Referenced by Read().
buffer_t gig::Sample::LoadSampleData | ( | ) |
Loads (and uncompresses if needed) the whole sample wave into RAM.
Use ReleaseSampleData() to free the memory if you don't need the cached sample data anymore.
Definition at line 667 of file gig.cpp.
References LoadSampleDataWithNullSamplesExtension(), and DLS::Sample::SamplesTotal.
buffer_t gig::Sample::LoadSampleData | ( | unsigned long | SampleCount | ) |
Reads (uncompresses if needed) and caches the first SampleCount numbers of SamplePoints in RAM.
Use ReleaseSampleData() to free the memory space if you don't need the cached samples anymore. There is no guarantee that exactly SampleCount samples will be cached; this is not an error. The size will be eventually truncated e.g. to the beginning of a frame of a compressed sample. This is done for efficiency reasons while streaming the wave by your sampler engine later. Read the Size member of the buffer_t structure that will be returned to determine the actual cached samples, but note that the size is given in bytes! You get the number of actually cached samples by dividing it by the frame size of the sample:
SampleCount | - number of sample points to load into RAM |
Definition at line 693 of file gig.cpp.
References LoadSampleDataWithNullSamplesExtension().
buffer_t gig::Sample::LoadSampleDataWithNullSamplesExtension | ( | uint | NullSamplesCount | ) |
Loads (and uncompresses if needed) the whole sample wave into RAM.
Use ReleaseSampleData() to free the memory if you don't need the cached sample data anymore. The method will add NullSamplesCount silence samples past the official buffer end (this won't affect the 'Size' member of the buffer_t structure, that means 'Size' always reflects the size of the actual sample data, the buffer might be bigger though). Silence samples past the official buffer are needed for differential algorithms that always have to take subsequent samples into account (resampling/interpolation would be an important example) and avoids memory access faults in such cases.
NullSamplesCount | - number of silence samples the buffer should be extended past it's data end |
Definition at line 716 of file gig.cpp.
References DLS::Sample::SamplesTotal.
Referenced by LoadSampleData().
buffer_t gig::Sample::LoadSampleDataWithNullSamplesExtension | ( | unsigned long | SampleCount, |
uint | NullSamplesCount | ||
) |
Reads (uncompresses if needed) and caches the first SampleCount numbers of SamplePoints in RAM.
Use ReleaseSampleData() to free the memory space if you don't need the cached samples anymore. There is no guarantee that exactly SampleCount samples will be cached; this is not an error. The size will be eventually truncated e.g. to the beginning of a frame of a compressed sample. This is done for efficiency reasons while streaming the wave by your sampler engine later. Read the Size member of the buffer_t structure that will be returned to determine the actual cached samples, but note that the size is given in bytes! You get the number of actually cached samples by dividing it by the frame size of the sample:
The method will add NullSamplesCount silence samples past the official buffer end (this won't affect the 'Size' member of the buffer_t structure, that means 'Size' always reflects the size of the actual sample data, the buffer might be bigger though). Silence samples past the official buffer are needed for differential algorithms that always have to take subsequent samples into account (resampling/interpolation would be an important example) and avoids memory access faults in such cases.
SampleCount | - number of sample points to load into RAM |
NullSamplesCount | - number of silence samples the buffer should be extended past it's data end |
Definition at line 752 of file gig.cpp.
References DLS::Sample::FrameSize, GetCache(), gig::buffer_t::NullExtensionSize, gig::buffer_t::pStart, RAMCache, Read(), DLS::Sample::SamplesTotal, SetPos(), and gig::buffer_t::Size.
|
inherited |
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 924 of file DLS.cpp.
References DLS_WAVE_FORMAT_PCM, DLS::Sample::FormatTag, DLS::Sample::FrameSize, DLS::Sample::pCkData, and RIFF::Chunk::Read().
Referenced by DLS::Sample::CopyAssign().
unsigned long gig::Sample::Read | ( | void * | pBuffer, |
unsigned long | SampleCount, | ||
buffer_t * | pExternalDecompressionBuffer = NULL |
||
) |
Reads SampleCount number of sample points from the current position into the buffer pointed by pBuffer and increments the position within the sample.
The sample wave stream will be decompressed on the fly if using a compressed sample. Use this method and SetPos() if you don't want to load the sample into RAM, thus for disk streaming.
Caution: If you are using more than one streaming thread, you have to use an external decompression buffer for EACH streaming thread to avoid race conditions and crashes!
For 16 bit samples, the data in the buffer will be int16_t (using native endianness). For 24 bit, the buffer will contain three bytes per sample, little-endian.
pBuffer | destination buffer |
SampleCount | number of sample points to read |
pExternalDecompressionBuffer | (optional) external buffer to use for decompression |
Definition at line 1101 of file gig.cpp.
References DLS::Sample::BitDepth, DLS::Sample::Channels, Compressed, FrameOffset, DLS::Sample::FrameSize, GuessSize(), InternalDecompressionBuffer, DLS::Sample::pCkData, gig::buffer_t::pStart, RIFF::Chunk::Read(), RIFF::Chunk::RemainingBytes(), SamplePos, SamplesInLastFrame, SamplesPerFrame, DLS::Sample::SamplesTotal, RIFF::Chunk::SetPos(), gig::buffer_t::Size, RIFF::stream_backward, RIFF::stream_ready, TruncatedBits, and WorstCaseMaxSamples().
Referenced by CopyAssignWave(), LoadSampleDataWithNullSamplesExtension(), and ReadAndLoop().
unsigned long gig::Sample::ReadAndLoop | ( | void * | pBuffer, |
unsigned long | SampleCount, | ||
playback_state_t * | pPlaybackState, | ||
DimensionRegion * | pDimRgn, | ||
buffer_t * | pExternalDecompressionBuffer = NULL |
||
) |
Reads SampleCount number of sample points from the position stored in pPlaybackState into the buffer pointed by pBuffer and moves the position within the sample respectively, this method honors the looping informations of the sample (if any).
The sample wave stream will be decompressed on the fly if using a compressed sample. Use this method if you don't want to load the sample into RAM, thus for disk streaming. All this methods needs to know to proceed with streaming for the next time you call this method is stored in pPlaybackState. You have to allocate and initialize the playback_state_t structure by yourself before you use it to stream a sample:
You don't have to take care of things like if there is actually a loop defined or if the current read position is located within a loop area. The method already handles such cases by itself.
Caution: If you are using more than one streaming thread, you have to use an external decompression buffer for EACH streaming thread to avoid race conditions and crashes!
pBuffer | destination buffer |
SampleCount | number of sample points to read |
pPlaybackState | will be used to store and reload the playback state for the next ReadAndLoop() call |
pDimRgn | dimension region with looping information |
pExternalDecompressionBuffer | (optional) external buffer to use for decompression |
Definition at line 926 of file gig.cpp.
References DLS::Sample::FrameSize, GetPos(), gig::playback_state_t::loop_cycles_left, gig::loop_type_backward, gig::loop_type_bidirectional, gig::loop_type_normal, DLS::sample_loop_t::LoopLength, LoopPlayCount, DLS::sample_loop_t::LoopStart, DLS::sample_loop_t::LoopType, gig::playback_state_t::position, DLS::Sampler::pSampleLoops, Read(), gig::playback_state_t::reverse, DLS::Sampler::SampleLoops, and SetPos().
void gig::Sample::ReleaseSampleData | ( | ) |
Frees the cached sample from RAM if loaded with LoadSampleData() previously.
Definition at line 790 of file gig.cpp.
References gig::buffer_t::NullExtensionSize, gig::buffer_t::pStart, RAMCache, and gig::buffer_t::Size.
void gig::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 (i.e. with 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) |
DLS::Excecption | if FormatTag != DLS_WAVE_FORMAT_PCM or if iNewSize is less than 1 |
gig::Exception | if existing sample is compressed |
Definition at line 827 of file gig.cpp.
References Compressed, and DLS::Sample::Resize().
Referenced by CopyAssignMeta().
unsigned long gig::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.
Although the original Gigasampler engine doesn't allow positioning within compressed samples, I decided to implement it. Even though the Gigasampler format doesn't allow to define loops for compressed samples at the moment, positioning within compressed samples might be interesting for some sampler engines though. The only drawback about my decision is that it takes longer to load compressed gig Files on startup, because it's neccessary to scan the samples for some mandatory informations. But I think as it doesn't affect the runtime efficiency, nobody will have a problem with that.
SampleCount | number of sample points to jump |
Whence | optional: to which relation SampleCount refers to, if omited RIFF::stream_start is assumed |
Definition at line 853 of file gig.cpp.
References Compressed, FrameOffset, DLS::Sample::FrameSize, FrameTable, DLS::Sample::pCkData, SamplePos, DLS::Sample::SamplesTotal, RIFF::Chunk::SetPos(), RIFF::stream_backward, RIFF::stream_curpos, RIFF::stream_end, and RIFF::stream_start.
Referenced by CopyAssignWave(), LoadSampleDataWithNullSamplesExtension(), and ReadAndLoop().
|
virtual |
Apply sample and its settings to the respective RIFF chunks.
You have to call File::Save() to make changes persistent.
Usually there is absolutely no need to call this method explicitly. It will be called automatically when File::Save() was called.
DLS::Exception | if FormatTag != DLS_WAVE_FORMAT_PCM or no sample data was provided yet |
gig::Exception | if there is any invalid sample setting |
Reimplemented from DLS::Sample.
Definition at line 535 of file gig.cpp.
References RIFF::List::AddSubChunk(), CHUNK_ID_3GIX, CHUNK_ID_EWAV, CHUNK_ID_SMPL, Compressed, RIFF::List::DeleteSubChunk(), FineTune, RIFF::List::GetSubChunk(), RIFF::Chunk::LoadChunkData(), LoopEnd, LoopFraction, LoopID, LoopPlayCount, Loops, LoopStart, LoopType, Manufacturer, MIDIUnityNote, pCk3gix, pCkSmpl, pGroup, DLS::Resource::pParent, Product, DLS::Sample::pWaveList, SamplePeriod, DLS::Sample::SamplesPerSecond, SMPTEFormat, SMPTEOffset, and DLS::Sample::UpdateChunks().
|
inlineprotected |
Definition at line 690 of file gig.h.
References SamplesPerFrame, gig::buffer_t::Size, and WorstCaseFrameSize.
Referenced by Read().
unsigned long gig::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().
Note: there is currently no support for writing compressed samples.
For 16 bit samples, the data in the source buffer should be int16_t (using native endianness). For 24 bit, the buffer should contain three bytes per sample, little-endian.
pBuffer | - source buffer |
SampleCount | - number of sample points to write |
DLS::Exception | if current sample size is too small |
gig::Exception | if sample is compressed |
Definition at line 1290 of file gig.cpp.
References DLS::Sample::BitDepth, Compressed, DLS::Sample::FrameSize, DLS::Resource::GetParent(), RIFF::Chunk::GetPos(), RIFF::Chunk::GetSize(), DLS::Sample::GetSize(), DLS::Sample::pCkData, gig::File::SetSampleChecksum(), and RIFF::Chunk::Write().
Referenced by CopyAssignWave().
|
inherited |
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 399 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), DLS::Sample::Sample(), and DLS::Sample::UpdateChunks().
|
inherited |
Size of each sample per channel (only if known sample data format is used, 0 otherwise).
Definition at line 401 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), GuessSize(), Read(), DLS::Sample::Sample(), Sample(), DLS::Sample::UpdateChunks(), and Write().
|
inherited |
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 400 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), DLS::Sample::Sample(), and DLS::Sample::UpdateChunks().
|
inherited |
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 397 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), GuessSize(), Read(), DLS::Sample::Sample(), Sample(), DLS::Sample::UpdateChunks(), and gig::File::UpdateChunks().
bool gig::Sample::Compressed |
If the sample wave is compressed (probably just interesting for instrument and sample editors, as this library already handles the decompression in it's sample access methods anyway).
Definition at line 628 of file gig.h.
Referenced by GetPos(), Read(), Resize(), Sample(), SetPos(), UpdateChunks(), and Write().
|
protected |
bool gig::Sample::Dithered |
|
protected |
File number (> 0 when sample is stored in an extension file, 0 when it's in the gig)
Definition at line 664 of file gig.h.
Referenced by gig::Region::GetSampleFromWavePool(), and Sample().
uint32_t gig::Sample::FineTune |
Specifies the fraction of a semitone up from the specified MIDI unity note field. A value of 0x80000000 means 1/2 semitone (50 cents) and a value of 0x00000000 means no fine tuning between semitones.
Definition at line 617 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
|
inherited |
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 396 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), DLS::Sample::GetSize(), DLS::Sample::Read(), DLS::Sample::Resize(), DLS::Sample::Sample(), DLS::Sample::SetPos(), DLS::Sample::UpdateChunks(), and DLS::Sample::Write().
|
protected |
|
inherited |
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 403 of file DLS.h.
Referenced by DLS::Sample::CopyAssign(), DLS::Sample::CopyAssignCore(), CopyAssignWave(), GetPos(), DLS::Sample::GetSize(), LoadSampleDataWithNullSamplesExtension(), DLS::Sample::Read(), Read(), ReadAndLoop(), DLS::Sample::Resize(), DLS::Sample::Sample(), DLS::Sample::SetPos(), SetPos(), DLS::Sample::Write(), and Write().
|
protected |
|
staticprotected |
|
staticprotected |
uint32_t gig::Sample::LoopEnd |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The end value specifies the offset [in sample points] in the waveform data which represents the end of the loop [only if Loops > 0].)
Definition at line 624 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::LoopFraction |
The fractional value specifies a fraction of a sample at which to loop. This allows a loop to be fine tuned at a resolution greater than one sample. A value of 0 means no fraction, a value of 0x80000000 means 1/2 of a sample length. 0xFFFFFFFF is the smallest fraction of a sample that can be represented.
Definition at line 626 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::LoopID |
Specifies the unique ID that corresponds to one of the defined cue points in the cue point list (only if Loops > 0), as the Gigasampler format only allows one loop definition at the moment, this attribute isn't really useful for anything.
Definition at line 621 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::LoopPlayCount |
Number of times the loop should be played (a value of 0 = infinite).
Definition at line 627 of file gig.h.
Referenced by CopyAssignMeta(), ReadAndLoop(), Sample(), and UpdateChunks().
uint32_t gig::Sample::Loops |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: Number of defined sample loops. So far only seen single loops in gig files - please report if you encounter more!)
Definition at line 620 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::LoopSize |
Caution: Use the respective fields in the DimensionRegion instead of this one! (Intended purpose: Length of the looping area [in sample points] which is equivalent to
.)
Definition at line 625 of file gig.h.
Referenced by CopyAssignMeta(), and Sample().
uint32_t gig::Sample::LoopStart |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The start value specifies the offset [in sample points] in the waveform data of the first sample to be played in the loop [only if Loops > 0].)
Definition at line 623 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
loop_type_t gig::Sample::LoopType |
Caution: Use the respective field in the DimensionRegion instead of this one! (Intended purpose: The type field defines how the waveform samples will be looped.)
Definition at line 622 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::Manufacturer |
Specifies the MIDI Manufacturer's Association (MMA) Manufacturer code for the sampler intended to receive this file's waveform. If no particular manufacturer is to be specified, a value of 0 should be used.
Definition at line 613 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::MIDIUnityNote |
Specifies the musical note at which the sample will be played at it's original sample rate.
Definition at line 616 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
|
protected |
Definition at line 665 of file gig.h.
Referenced by Sample(), and UpdateChunks().
|
protectedinherited |
Definition at line 416 of file DLS.h.
Referenced by DLS::Sample::CopyAssign(), GetPos(), DLS::Sample::GetSize(), DLS::Sample::LoadSampleData(), DLS::Sample::Read(), Read(), DLS::Sample::ReleaseSampleData(), DLS::Sample::Resize(), DLS::Sample::Sample(), DLS::Sample::SetPos(), SetPos(), DLS::Sample::UpdateChunks(), DLS::Sample::Write(), and Write().
|
protectedinherited |
Definition at line 417 of file DLS.h.
Referenced by DLS::Sample::Sample(), and DLS::Sample::UpdateChunks().
|
protected |
Definition at line 666 of file gig.h.
Referenced by Sample(), and UpdateChunks().
|
inherited |
Points to a dlsid_t structure if the file provided a DLS ID else is NULL.
Definition at line 347 of file DLS.h.
Referenced by DLS::Resource::GenerateDLSID(), DLS::Resource::Resource(), DLS::Resource::UpdateChunks(), and DLS::Resource::~Resource().
|
protected |
pointer to the Group this sample belongs to (always not-NULL)
Definition at line 656 of file gig.h.
Referenced by gig::Group::AddSample(), GetGroup(), Sample(), and UpdateChunks().
|
inherited |
Points (in any case) to an Info object, providing additional, optional infos and comments.
Definition at line 346 of file DLS.h.
Referenced by gig::File::AddInstrument(), DLS::Resource::CopyAssign(), gig::File::File(), gig::Instrument::Instrument(), DLS::Resource::Resource(), Sample(), DLS::Resource::UpdateChunks(), and DLS::Resource::~Resource().
|
protectedinherited |
Definition at line 355 of file DLS.h.
Referenced by DLS::Resource::GetParent(), DLS::Resource::Resource(), UpdateChunks(), DLS::Instrument::~Instrument(), DLS::Region::~Region(), and DLS::Sample::~Sample().
|
protectedinherited |
Definition at line 356 of file DLS.h.
Referenced by DLS::Resource::Resource(), and DLS::Resource::UpdateChunks().
uint32_t gig::Sample::Product |
Specifies the MIDI model ID defined by the manufacturer corresponding to the Manufacturer field. If no particular manufacturer's product is to be specified, a value of 0 should be used.
Definition at line 614 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
|
protectedinherited |
Definition at line 415 of file DLS.h.
Referenced by DLS::Sample::Resize(), DLS::Sample::Sample(), DLS::Sample::UpdateChunks(), UpdateChunks(), and DLS::Sample::~Sample().
|
protected |
Buffers samples (already uncompressed) in RAM.
Definition at line 663 of file gig.h.
Referenced by GetCache(), LoadSampleDataWithNullSamplesExtension(), ReleaseSampleData(), Sample(), and ~Sample().
uint32_t gig::Sample::SamplePeriod |
Specifies the duration of time that passes during the playback of one sample in nanoseconds (normally equal to 1 / Samples Per Second, where Samples Per Second is the value found in the format chunk), don't bother to update this attribute, it won't be saved.
Definition at line 615 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
|
protected |
|
protected |
|
protected |
For compressed samples only: number of samples in a full sample frame.
Definition at line 662 of file gig.h.
Referenced by Read(), and WorstCaseMaxSamples().
|
inherited |
Sampling rate at which each channel should be played (defaults to 44100 if Sample was created with Instrument::AddSample() previously).
Definition at line 398 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), DLS::Sample::Sample(), Sample(), DLS::Sample::UpdateChunks(), and UpdateChunks().
|
inherited |
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 402 of file DLS.h.
Referenced by DLS::Sample::CopyAssignCore(), LoadSampleData(), LoadSampleDataWithNullSamplesExtension(), Read(), DLS::Sample::Sample(), and SetPos().
smpte_format_t gig::Sample::SMPTEFormat |
Specifies the Society of Motion Pictures and Television E time format used in the following SMPTEOffset field. If a value of 0 is set, SMPTEOffset should also be set to 0.
Definition at line 618 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::SMPTEOffset |
The SMPTE Offset value specifies the time offset to be used for the synchronization / calibration to the first sample in the waveform. This value uses a format of 0xhhmmssff where hh is a signed value that specifies the number of hours (-23 to 23), mm is an unsigned value that specifies the number of minutes (0 to 59), ss is an unsigned value that specifies the number of seconds (0 to 59) and ff is an unsigned value that specifies the number of frames (0 to -1).
Definition at line 619 of file gig.h.
Referenced by CopyAssignMeta(), Sample(), and UpdateChunks().
uint32_t gig::Sample::TruncatedBits |
|
protectedinherited |
Definition at line 418 of file DLS.h.
Referenced by DLS::Region::GetSample(), gig::Region::GetSampleFromWavePool(), and DLS::Sample::Sample().
|
protected |
For compressed samples only: size (in bytes) of the largest possible sample frame.
Definition at line 661 of file gig.h.
Referenced by GuessSize(), and WorstCaseMaxSamples().