libgig  3.3.0.svn4
sf2::Sample Class Reference

#include <SF.h>

Classes

struct  buffer_t
 Pointer address and size of a buffer. More...
 
class  PlaybackState
 Reflects the current playback state for a sample. More...
 

Public Types

enum  Link {
  MONO_SAMPLE = 1, RIGHT_SAMPLE = 2, LEFT_SAMPLE = 4, LINKED_SAMPLE = 8,
  ROM_MONO_SAMPLE = 0x8001, ROM_RIGHT_SAMPLE = 0x8002, ROM_LEFT_SAMPLE = 0x8004, ROM_LINKED_SAMPLE = 0x8008
}
 

Public Member Functions

 Sample (RIFF::Chunk *ck, RIFF::Chunk *pCkSmpl, RIFF::Chunk *pCkSm24)
 
String GetName ()
 
int GetChannelCount ()
 
long GetTotalFrameCount ()
 
int GetFrameSize ()
 
bool HasLoops ()
 
bool IsUnpitched ()
 
buffer_t LoadSampleData ()
 Loads the whole sample wave into RAM. More...
 
buffer_t LoadSampleData (unsigned long SampleCount)
 Reads and caches the first SampleCount numbers of SamplePoints in RAM. More...
 
buffer_t LoadSampleDataWithNullSamplesExtension (uint NullSamplesCount)
 Loads the whole sample wave into RAM. More...
 
buffer_t LoadSampleDataWithNullSamplesExtension (unsigned long SampleCount, uint NullSamplesCount)
 Reads 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...
 
unsigned long SetPos (unsigned long SampleCount)
 Sets the position within the sample (in sample points, not in bytes). More...
 
unsigned long GetPos ()
 Returns the current position in the sample (in sample points). 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...
 
unsigned long ReadAndLoop (void *pBuffer, unsigned long FrameCount, PlaybackState *pPlaybackState, Region *pRegion)
 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...
 

Public Attributes

String Name
 
buffer_t RAMCache
 Buffers samples (already uncompressed) in RAM. More...
 
RIFF::ChunkpCkSmpl
 
RIFF::ChunkpCkSm24
 
int ChannelCount
 
uint32_t Start
 
uint32_t End
 
uint32_t StartLoop
 
uint32_t EndLoop
 
uint32_t SampleRate
 
uint8_t OriginalPitch
 
uint8_t PitchCorrection
 
uint16_t SampleLink
 
uint16_t SampleType
 

Detailed Description

Definition at line 262 of file SF.h.

Member Enumeration Documentation

Enumerator
MONO_SAMPLE 
RIGHT_SAMPLE 
LEFT_SAMPLE 
LINKED_SAMPLE 
ROM_MONO_SAMPLE 
ROM_RIGHT_SAMPLE 
ROM_LEFT_SAMPLE 
ROM_LINKED_SAMPLE 

Definition at line 265 of file SF.h.

Constructor & Destructor Documentation

Member Function Documentation

Sample::buffer_t sf2::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.

Returns
buffer_t structure with current cached sample points
See Also
LoadSampleData();

Definition at line 1363 of file SF.cpp.

References sf2::Sample::buffer_t::NullExtensionSize, sf2::Sample::buffer_t::pStart, RAMCache, and sf2::Sample::buffer_t::Size.

Referenced by LoadSampleDataWithNullSamplesExtension().

int sf2::Sample::GetChannelCount ( )

Definition at line 188 of file SF.cpp.

References ChannelCount.

Referenced by Read().

int sf2::Sample::GetFrameSize ( )
Returns
The frame size in bytes

Definition at line 199 of file SF.cpp.

References ChannelCount, and pCkSm24.

Referenced by LoadSampleDataWithNullSamplesExtension(), Read(), and ReadAndLoop().

String sf2::Sample::GetName ( )
inline

Definition at line 300 of file SF.h.

References Name.

unsigned long sf2::Sample::GetPos ( )

Returns the current position in the sample (in sample points).

Definition at line 1403 of file SF.cpp.

References RIFF::Chunk::GetPos(), pCkSmpl, and Start.

Referenced by Read(), and ReadAndLoop().

long sf2::Sample::GetTotalFrameCount ( )

Definition at line 192 of file SF.cpp.

References End, and Start.

Referenced by LoadSampleData(), LoadSampleDataWithNullSamplesExtension(), and Read().

bool sf2::Sample::HasLoops ( )

Definition at line 203 of file SF.cpp.

References EndLoop, and StartLoop.

bool sf2::Sample::IsUnpitched ( )
inline

Definition at line 305 of file SF.h.

References OriginalPitch.

Sample::buffer_t sf2::Sample::LoadSampleData ( )

Loads the whole sample wave into RAM.

Use ReleaseSampleData() to free the memory if you don't need the cached sample data anymore.

Returns
buffer_t structure with start address and size of the buffer in bytes
See Also
ReleaseSampleData(), Read(), SetPos()

Definition at line 1263 of file SF.cpp.

References GetTotalFrameCount(), and LoadSampleDataWithNullSamplesExtension().

Sample::buffer_t sf2::Sample::LoadSampleData ( unsigned long  SampleCount)

Reads 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. 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:

buffer_t buf = pSample->LoadSampleData(acquired_samples);
long cachedsamples = buf.Size / pSample->FrameSize;
Parameters
SampleCount- number of sample points to load into RAM
Returns
buffer_t structure with start address and size of the cached sample data in bytes
See Also
ReleaseSampleData(), Read(), SetPos()

Definition at line 1285 of file SF.cpp.

References LoadSampleDataWithNullSamplesExtension().

Sample::buffer_t sf2::Sample::LoadSampleDataWithNullSamplesExtension ( uint  NullSamplesCount)

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

Parameters
NullSamplesCount- number of silence samples the buffer should be extended past it's data end
Returns
buffer_t structure with start address and size of the buffer in bytes
See Also
ReleaseSampleData(), Read(), SetPos()

Definition at line 1308 of file SF.cpp.

References GetTotalFrameCount().

Referenced by LoadSampleData().

Sample::buffer_t sf2::Sample::LoadSampleDataWithNullSamplesExtension ( unsigned long  SampleCount,
uint  NullSamplesCount 
)

Reads 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. 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:

buffer_t buf = pSample->LoadSampleDataWithNullSamplesExtension(acquired_samples, null_samples);
long cachedsamples = buf.Size / pSample->FrameSize;

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.

Parameters
SampleCount- number of sample points to load into RAM
NullSamplesCount- number of silence samples the buffer should be extended past it's data end
Returns
buffer_t structure with start address and size of the cached sample data in bytes
See Also
ReleaseSampleData(), Read(), SetPos()

Definition at line 1340 of file SF.cpp.

References GetCache(), GetFrameSize(), GetTotalFrameCount(), sf2::Sample::buffer_t::NullExtensionSize, sf2::Sample::buffer_t::pStart, RAMCache, Read(), SetPos(), and sf2::Sample::buffer_t::Size.

unsigned long sf2::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.

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.

Parameters
pBufferdestination buffer
SampleCountnumber of sample points to read
Returns
number of successfully read sample points
See Also
SetPos()

Definition at line 1423 of file SF.cpp.

References End, GetChannelCount(), GetFrameSize(), RIFF::Chunk::GetPos(), GetPos(), GetTotalFrameCount(), LEFT_SAMPLE, MONO_SAMPLE, pCkSm24, pCkSmpl, RIFF::Chunk::Read(), RIGHT_SAMPLE, ROM_LEFT_SAMPLE, ROM_MONO_SAMPLE, ROM_RIGHT_SAMPLE, and SampleType.

Referenced by LoadSampleDataWithNullSamplesExtension(), and ReadAndLoop().

unsigned long sf2::Sample::ReadAndLoop ( void *  pBuffer,
unsigned long  FrameCount,
PlaybackState pPlaybackState,
Region pRegion 
)

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

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:

PlaybackState playbackstate;
playbackstate.position = 0;
playbackstate.reverse = false;
playbackstate.loop_cycles_left = pSample->LoopPlayCount;

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.

Parameters
pBufferdestination buffer
FrameCountnumber of sample points to read
pPlaybackStatewill be used to store and reload the playback state for the next ReadAndLoop() call
Returns
number of successfully read sample points

Definition at line 233 of file SF.cpp.

References GetFrameSize(), GetPos(), sf2::Region::HasLoop, sf2::Region::LoopEnd, sf2::Region::LoopStart, sf2::Sample::PlaybackState::position, Read(), and SetPos().

void sf2::Sample::ReleaseSampleData ( )

Frees the cached sample from RAM if loaded with LoadSampleData() previously.

See Also
LoadSampleData();

Definition at line 1378 of file SF.cpp.

References sf2::Sample::buffer_t::NullExtensionSize, sf2::Sample::buffer_t::pStart, RAMCache, and sf2::Sample::buffer_t::Size.

unsigned long sf2::Sample::SetPos ( unsigned long  SampleCount)

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.

Parameters
SampleCountnumber of sample points to jump
Returns
the new sample position
See Also
Read()

Definition at line 1394 of file SF.cpp.

References pCkSm24, pCkSmpl, RIFF::Chunk::SetPos(), Start, and RIFF::stream_start.

Referenced by LoadSampleDataWithNullSamplesExtension(), and ReadAndLoop().

Member Data Documentation

int sf2::Sample::ChannelCount

Definition at line 330 of file SF.h.

Referenced by GetChannelCount(), GetFrameSize(), and Sample().

uint32_t sf2::Sample::End

Definition at line 333 of file SF.h.

Referenced by GetTotalFrameCount(), Read(), and Sample().

uint32_t sf2::Sample::EndLoop

Definition at line 335 of file SF.h.

Referenced by HasLoops(), and Sample().

String sf2::Sample::Name

Definition at line 296 of file SF.h.

Referenced by sf2::File::DeleteSample(), GetName(), and Sample().

uint8_t sf2::Sample::OriginalPitch

Definition at line 337 of file SF.h.

Referenced by sf2::Region::GetUnityNote(), IsUnpitched(), and Sample().

RIFF::Chunk* sf2::Sample::pCkSm24

Definition at line 327 of file SF.h.

Referenced by GetFrameSize(), Read(), Sample(), and SetPos().

RIFF::Chunk* sf2::Sample::pCkSmpl

Definition at line 326 of file SF.h.

Referenced by GetPos(), Read(), Sample(), and SetPos().

uint8_t sf2::Sample::PitchCorrection

Definition at line 338 of file SF.h.

Referenced by Sample().

buffer_t sf2::Sample::RAMCache

Buffers samples (already uncompressed) in RAM.

Definition at line 325 of file SF.h.

Referenced by GetCache(), LoadSampleDataWithNullSamplesExtension(), ReleaseSampleData(), and Sample().

uint16_t sf2::Sample::SampleLink

Definition at line 339 of file SF.h.

Referenced by Sample().

uint32_t sf2::Sample::SampleRate

Definition at line 336 of file SF.h.

Referenced by Sample().

uint16_t sf2::Sample::SampleType

Definition at line 342 of file SF.h.

Referenced by Read(), and Sample().

uint32_t sf2::Sample::Start

Definition at line 332 of file SF.h.

Referenced by GetPos(), GetTotalFrameCount(), Sample(), and SetPos().

uint32_t sf2::Sample::StartLoop

Definition at line 334 of file SF.h.

Referenced by HasLoops(), and Sample().


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