sf2::Sample Class Reference

#include <SF.h>

List of all members.

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 ()
 
Returns:
The frame size in bytes

bool HasLoops ()
bool IsUnpitched ()
buffer_t LoadSampleData ()
 Loads the whole sample wave into RAM.
buffer_t LoadSampleData (unsigned long SampleCount)
 Reads and caches the first SampleCount numbers of SamplePoints in RAM.
buffer_t LoadSampleDataWithNullSamplesExtension (uint NullSamplesCount)
 Loads the whole sample wave into RAM.
buffer_t LoadSampleDataWithNullSamplesExtension (unsigned long SampleCount, uint NullSamplesCount)
 Reads and caches the first SampleCount numbers of SamplePoints in RAM.
buffer_t GetCache ()
 Returns current cached sample points.
void ReleaseSampleData ()
 Frees the cached sample from RAM if loaded with LoadSampleData() previously.
unsigned long SetPos (unsigned long SampleCount)
 Sets the position within the sample (in sample points, not in bytes).
unsigned long GetPos ()
 Returns the current position in the sample (in sample points).
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 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).

Public Attributes

String Name
buffer_t RAMCache
 Buffers samples (already uncompressed) in RAM.
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

Classes

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


Detailed Description

Definition at line 258 of file SF.h.


Member Enumeration Documentation

enum sf2::Sample::Link

Enumerator:
MONO_SAMPLE 
RIGHT_SAMPLE 
LEFT_SAMPLE 
LINKED_SAMPLE 
ROM_MONO_SAMPLE 
ROM_RIGHT_SAMPLE 
ROM_LEFT_SAMPLE 
ROM_LINKED_SAMPLE 

Definition at line 261 of file SF.h.


Constructor & Destructor Documentation

sf2::Sample::Sample ( RIFF::Chunk ck,
RIFF::Chunk pCkSmpl,
RIFF::Chunk pCkSm24 
)

Definition at line 151 of file SF.cpp.

References ChannelCount, End, EndLoop, RIFF::Chunk::GetSize(), LEFT_SAMPLE, LINKED_SAMPLE, sf2::LoadString(), MONO_SAMPLE, Name, sf2::Sample::buffer_t::NullExtensionSize, OriginalPitch, pCkSm24, pCkSmpl, PitchCorrection, sf2::Sample::buffer_t::pStart, RAMCache, RIFF::Chunk::ReadInt16(), RIFF::Chunk::ReadInt32(), RIFF::Chunk::ReadInt8(), RIGHT_SAMPLE, ROM_LEFT_SAMPLE, ROM_LINKED_SAMPLE, ROM_MONO_SAMPLE, ROM_RIGHT_SAMPLE, SampleLink, SampleRate, SampleType, sf2::Sample::buffer_t::Size, Start, and StartLoop.


Member Function Documentation

String sf2::Sample::GetName (  )  [inline]

Definition at line 296 of file SF.h.

References Name.

int sf2::Sample::GetChannelCount (  ) 

Definition at line 189 of file SF.cpp.

References ChannelCount.

Referenced by Read().

long sf2::Sample::GetTotalFrameCount (  ) 

Definition at line 193 of file SF.cpp.

References End, and Start.

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

int sf2::Sample::GetFrameSize (  ) 

Returns:
The frame size in bytes

Definition at line 200 of file SF.cpp.

References ChannelCount, and pCkSm24.

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

bool sf2::Sample::HasLoops (  ) 

Definition at line 204 of file SF.cpp.

References EndLoop, and StartLoop.

bool sf2::Sample::IsUnpitched (  )  [inline]

Definition at line 301 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 1170 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 1192 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 1215 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 1247 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.

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

void sf2::Sample::ReleaseSampleData (  ) 

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

See also:
LoadSampleData();

Definition at line 1285 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:
SampleCount number of sample points to jump
Returns:
the new sample position
See also:
Read()

Definition at line 1301 of file SF.cpp.

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

Referenced by LoadSampleDataWithNullSamplesExtension(), and ReadAndLoop().

unsigned long sf2::Sample::GetPos (  ) 

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

Definition at line 1310 of file SF.cpp.

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

Referenced by Read(), and ReadAndLoop().

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:
pBuffer destination buffer
SampleCount number of sample points to read
Returns:
number of successfully read sample points
See also:
SetPos()

Definition at line 1330 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:
pBuffer destination buffer
FrameCount number of sample points to read
pPlaybackState will be used to store and reload the playback state for the next ReadAndLoop() call
Returns:
number of successfully read sample points

Definition at line 234 of file SF.cpp.

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


Member Data Documentation

String sf2::Sample::Name

Definition at line 292 of file SF.h.

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

buffer_t sf2::Sample::RAMCache

Buffers samples (already uncompressed) in RAM.

Definition at line 321 of file SF.h.

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

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

Definition at line 322 of file SF.h.

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

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

Definition at line 323 of file SF.h.

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

int sf2::Sample::ChannelCount

Definition at line 326 of file SF.h.

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

uint32_t sf2::Sample::Start

Definition at line 328 of file SF.h.

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

uint32_t sf2::Sample::End

Definition at line 329 of file SF.h.

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

uint32_t sf2::Sample::StartLoop

Definition at line 330 of file SF.h.

Referenced by HasLoops(), and Sample().

uint32_t sf2::Sample::EndLoop

Definition at line 331 of file SF.h.

Referenced by HasLoops(), and Sample().

uint32_t sf2::Sample::SampleRate

Definition at line 332 of file SF.h.

Referenced by Sample().

uint8_t sf2::Sample::OriginalPitch

Definition at line 333 of file SF.h.

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

uint8_t sf2::Sample::PitchCorrection

Definition at line 334 of file SF.h.

Referenced by Sample().

uint16_t sf2::Sample::SampleLink

Definition at line 335 of file SF.h.

Referenced by Sample().

uint16_t sf2::Sample::SampleType

Definition at line 338 of file SF.h.

Referenced by Read(), and Sample().


The documentation for this class was generated from the following files:
Generated on Sun May 1 03:22:48 2011 for libgig by  doxygen 1.5.2