SampleMappingOscillator Class Reference

A multi-zone sample dispatcher. More...

Inheritance diagram for SampleMappingOscillator:

Public Types
enum	Parameters {   MappingPath ,   InterpolationMode ,   RoundRobinMode ,   SampleStartMillisecond }
	SampleMappingOscillator Parameters. More...
Public Types inherited from Oscillator
enum	Parameters {   Pitch ,   NoteTracking ,   BaseNote ,   Gain ,   CoarseTune ,   FineTune }
	Oscillator Parameters. More...

Public Member Functions
bool	loadMapping (string path)
	load a mapping file, replacing the oscillator's whole zone set.
AsyncTask	loadMapping (string path, function completion)
	load a mapping file and report the outcome.
void	clearMapping ()
	drop every zone and cut the voices playing them.
void	purgeZones (int dim1, int dim2)
	free the samples of the matching zones.
void	unpurgeZones (int dim1, int dim2)
	reload previously purged zones.
number	getLoadingStatus ()
	loading progress, 0 to 1.
int	getNumZones ()
void	waitForLoading ()
	block until pending loads complete.
Public Member Functions inherited from Oscillator
table	getSliceInfo (int sliceId)
	get slice information for the given sliceId.
Public Member Functions inherited from Element
void	setParameter (string parameter, Value value)
	Sets an Element parameter.
Value	getParameter (string parameter)
	Gets an Element parameter.
bool	hasParameter (string parameter)
table	getParameterConnections (string parameter)
	Get all SignalConnection for this parameter.

Additional Inherited Members
Public Attributes inherited from Oscillator
Keygroup	keygroup
	parent keygroup for this oscillator
bool	purged
	purged status for this oscillator (when true sample is not loaded in memory)
int	numSlices
	number of slices (only valid for Slice oscillator)
table	looplabInfo
	looplab information.
table	sampleInfo
	sample information.
Public Attributes inherited from Element
string	name
	internal element name
string	displayName
	name to display on the User Interface, name is used if displayName is not specified.
string	type
	internal element type
string	path
	full path of the element in the synthesis tree
Element &	parent
	element parent
table	children
	element children using the element name as key
table	synthChildren
	children of the element in the synthesis hierarchy, as a 1-indexed array.
table	mods
	all ControlSignalSource for this node as a 1-indexed array (same content as modulations, keyed by index instead of name)
int	output
	output bus index for the element. Reading returns the index parsed from the current output bus name (1 when the element uses the default bus). Writing is asynchronous: the engine applies the new routing shortly after the assignment, so reading the property back immediately may still return the old value. Assigning on an element that cannot change its output raises an error.
int	numParams
	number of parameters
table	parameterDefinitions
	table of parameter definitions.

Detailed Description

A multi-zone sample dispatcher.

Holds a whole sample set as a list of zones and selects one per note along four axes — key, velocity, and the two script-controlled dimensions dim1 (logical layer: articulation, microphone, dynamic) and dim2 (round-robin variant). The zone list is read from a mapping file (.dmap, .xml or .sfz).

See Sample Mapping for the mapping file format, the dispatch model, and the loading pitfalls this reference only summarises.

local osc = Program.layers[1].keygroups[1].oscillators[1]
osc:loadMapping("Mappings/violin.dmap")
while osc:getLoadingStatus() < 1.0 do wait(50) end
print(osc:getNumZones(), "zones")

Note

This oscillator is not offered in the element browser; a script drives one that a program already contains but cannot create one.

It derives from Oscillator, not from SampleBasedOscillator, so the generic sample calls do not apply — and they fail in different ways. loadSample raises. purge / unpurge do nothing while still reporting success, and purged always reads false. Load through loadMapping and free memory with purgeZones / unpurgeZones.

Every method below exists only on this class, so calling one on a different oscillator raises rather than doing nothing — check type first.

Member Enumeration Documentation

Parameters

enum SampleMappingOscillator::Parameters

SampleMappingOscillator Parameters.

Enumerator
MappingPath	resolved path of the mapping the oscillator holds. Read-only in practice: writing it records the string without loading anything
InterpolationMode	resampling quality: 0 = Lo-fi, 1 = Standard (default), 2 = Best
RoundRobinMode	variant policy: 0 = First, 1 = Cycle (default), 2 = Random
SampleStartMillisecond	per-voice sample start in ms; use setSampleOffset. Capped by the zone's maxSampleStart when the sample is streamed

Member Function Documentation

getLoadingStatus()

number SampleMappingOscillator::getLoadingStatus

(

)

loading progress, 0 to 1.

This is what a script waits on, and what drives a progress display: it drops to 0 as soon as a load is requested, before the mapping is even parsed, and climbs back to 1 when every zone has finished.

osc:loadMapping(path)
spawn(function()
  while osc:getLoadingStatus() < 1.0 do wait(30) end
  print("ready")
end)

Returns

the fraction of zones that have finished loading or failed. 1 when no mapping is loaded and none is on its way.

getNumZones()

int SampleMappingOscillator::getNumZones

(

)

Returns

the number of zones in the live mapping, 0 when none is loaded

loadMapping() [1/2]

bool SampleMappingOscillator::loadMapping

(

string

path

)

load a mapping file, replacing the oscillator's whole zone set.

Returns immediately; the samples arrive on a background thread. Poll getLoadingStatus to wait for them.

Warning

The return value is not a success indicator — the load is queued and this returns true whatever happens next, the only false being an empty path. Pass a completion function to learn whether the mapping loaded.

Parameters

path	mapping file (.dmap, .xml or .sfz). Tried as written, then against the script's folder, the program's folder, the performance's folder, and finally the program's Sounds/Samples.

Returns

true unless path is empty

loadMapping() [2/2]

AsyncTask SampleMappingOscillator::loadMapping	(	string	path,
		function	completion )

load a mapping file and report the outcome.

The completion runs once every zone has finished loading or failed, and the task's success says whether they all made it. Waiting is still getLoadingStatus's job — this answers whether the load worked, not when it ended.

Parameters

path	mapping file; resolved as above
completion	a function called with the AsyncTask, or true to get the task back without a callback and poll it yourself

Returns

an AsyncTask

purgeZones()

void SampleMappingOscillator::purgeZones	(	int	dim1,
		int	dim2 )

free the samples of the matching zones.

Parameters

dim1	the logical layer
dim2	the round-robin variant, or a negative value for the whole dim1 layer

unpurgeZones()

void SampleMappingOscillator::unpurgeZones	(	int	dim1,
		int	dim2 )

reload previously purged zones.

Asynchronous, and reports nothing back.

Parameters

dim1	the logical layer
dim2	the round-robin variant, or a negative value for the whole dim1 layer

waitForLoading()

void SampleMappingOscillator::waitForLoading

(

)

block until pending loads complete.

Warning

Do not call this from a script: it blocks the audio thread, and it races the same way getLoadingStatus does, so it can return before the load it was meant to wait for has even started.