Encapsulates articulation informations of a dimension region. More...

#include <gig.h>

Inheritance diagram for gig::DimensionRegion:

Public Member Functions
double	GetVelocityAttenuation (uint8_t MIDIKeyVelocity)
	Returns the correct amplitude factor for the given MIDIKeyVelocity.

double	GetVelocityRelease (uint8_t MIDIKeyVelocity)

double	GetVelocityCutoff (uint8_t MIDIKeyVelocity)

void	SetVelocityResponseCurve (curve_type_t curve)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVelocityResponseDepth (uint8_t depth)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVelocityResponseCurveScaling (uint8_t scaling)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetReleaseVelocityResponseCurve (curve_type_t curve)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetReleaseVelocityResponseDepth (uint8_t depth)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVCFCutoffController (vcf_cutoff_ctrl_t controller)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVCFVelocityCurve (curve_type_t curve)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVCFVelocityDynamicRange (uint8_t range)
	Updates the respective member variable and the lookup table / cache that depends on this value.

void	SetVCFVelocityScale (uint8_t scaling)
	Updates the respective member variable and the lookup table / cache that depends on this value.

Region *	GetParent () const

virtual void	SetGain (int32_t gain)
	Updates the respective member variable and updates `SampleAttenuation` which depends on this value.

virtual void	UpdateChunks (progress_t *pProgress)
	Apply dimension region settings to the respective RIFF chunks.

virtual void	CopyAssign (const DimensionRegion *orig)
	Make a (semi) deep copy of the DimensionRegion object given by orig and assign it to this object.

Public Attributes
uint8_t	VelocityUpperLimit
	Defines the upper velocity value limit of a velocity split (only if an user defined limit was set, thus a value not equal to 128/NumberOfSplits, else this value is 0). Only for gig2, for gig3 and above the DimensionUpperLimits are used instead.

Sample *	pSample
	Points to the Sample which is assigned to the dimension region.

uint16_t	EG1PreAttack
	Preattack value of the sample amplitude EG (0 - 1000 permille).

double	EG1Attack
	Attack time of the sample amplitude EG (0.000 - 60.000s).

double	EG1Decay1
	Decay time of the sample amplitude EG (0.000 - 60.000s).

double	EG1Decay2
	Only if EG1InfiniteSustain == false: 2nd decay stage time of the sample amplitude EG (0.000 - 60.000s).

bool	EG1InfiniteSustain
	If true, instead of going into Decay2 phase, Decay1 level will be hold until note will be released.

uint16_t	EG1Sustain
	Sustain value of the sample amplitude EG (0 - 1000 permille).

double	EG1Release
	Release time of the sample amplitude EG (0.000 - 60.000s).

bool	EG1Hold
	If true, Decay1 stage should be postponed until the sample reached the sample loop start.

eg1_ctrl_t	EG1Controller
	MIDI Controller which has influence on sample amplitude EG parameters (attack, decay, release).

bool	EG1ControllerInvert
	Invert values coming from defined EG1 controller.

uint8_t	EG1ControllerAttackInfluence
	Amount EG1 Controller has influence on the EG1 Attack time (0 - 3, where 0 means off).

uint8_t	EG1ControllerDecayInfluence
	Amount EG1 Controller has influence on the EG1 Decay time (0 - 3, where 0 means off).

uint8_t	EG1ControllerReleaseInfluence
	Amount EG1 Controller has influence on the EG1 Release time (0 - 3, where 0 means off).

lfo_wave_t	LFO1WaveForm
	[gig extension]: The fundamental wave form to be used by the amplitude LFO, e.g. sine, triangle, saw, square (default: sine).

double	LFO1Frequency
	Frequency of the sample amplitude LFO (0.10 - 10.00 Hz).

double	LFO1Phase
	[gig extension]: Phase displacement of the amplitude LFO's wave form (0.0° - 360.0°).

uint16_t	LFO1InternalDepth
	Firm pitch of the sample amplitude LFO (0 - 1200 cents).

uint16_t	LFO1ControlDepth
	Controller depth influencing sample amplitude LFO pitch (0 - 1200 cents).

lfo1_ctrl_t	LFO1Controller
	MIDI Controller which controls sample amplitude LFO.

bool	LFO1FlipPhase
	Inverts the polarity of the sample amplitude LFO wave, so it flips the wave form vertically.

bool	LFO1Sync
	If set to true only one LFO should be used for all voices.

uint16_t	EG2PreAttack
	Preattack value of the filter cutoff EG (0 - 1000 permille).

double	EG2Attack
	Attack time of the filter cutoff EG (0.000 - 60.000s).

double	EG2Decay1
	Decay time of the filter cutoff EG (0.000 - 60.000s).

double	EG2Decay2
	Only if EG2InfiniteSustain == false: 2nd stage decay time of the filter cutoff EG (0.000 - 60.000s).

bool	EG2InfiniteSustain
	If true, instead of going into Decay2 phase, Decay1 level will be hold until note will be released.

uint16_t	EG2Sustain
	Sustain value of the filter cutoff EG (0 - 1000 permille).

double	EG2Release
	Release time of the filter cutoff EG (0.000 - 60.000s).

eg2_ctrl_t	EG2Controller
	MIDI Controller which has influence on filter cutoff EG parameters (attack, decay, release).

bool	EG2ControllerInvert
	Invert values coming from defined EG2 controller.

uint8_t	EG2ControllerAttackInfluence
	Amount EG2 Controller has influence on the EG2 Attack time (0 - 3, where 0 means off).

uint8_t	EG2ControllerDecayInfluence
	Amount EG2 Controller has influence on the EG2 Decay time (0 - 3, where 0 means off).

uint8_t	EG2ControllerReleaseInfluence
	Amount EG2 Controller has influence on the EG2 Release time (0 - 3, where 0 means off).

lfo_wave_t	LFO2WaveForm
	[gig extension]: The fundamental wave form to be used by the filter cutoff LFO, e.g. sine, triangle, saw, square (default: sine).

double	LFO2Frequency
	Frequency of the filter cutoff LFO (0.10 - 10.00 Hz).

double	LFO2Phase
	[gig extension]: Phase displacement of the filter cutoff LFO's wave form (0.0° - 360.0°).

uint16_t	LFO2InternalDepth
	Firm pitch of the filter cutoff LFO (0 - 1200 cents).

uint16_t	LFO2ControlDepth
	Controller depth influencing filter cutoff LFO pitch (0 - 1200).

lfo2_ctrl_t	LFO2Controller
	MIDI Controlle which controls the filter cutoff LFO.

bool	LFO2FlipPhase
	Inverts the polarity of the filter cutoff LFO wave, so it flips the wave form vertically.

bool	LFO2Sync
	If set to true only one LFO should be used for all voices.

double	EG3Attack
	Attack time of the sample pitch EG (0.000 - 10.000s).

int16_t	EG3Depth
	Depth of the sample pitch EG (-1200 - +1200).

lfo_wave_t	LFO3WaveForm
	[gig extension]: The fundamental wave form to be used by the pitch LFO, e.g. sine, triangle, saw, square (default: sine).

double	LFO3Frequency
	Frequency of the sample pitch LFO (0.10 - 10.00 Hz).

double	LFO3Phase
	[gig extension]: Phase displacement of the pitch LFO's wave form (0.0° - 360.0°).

int16_t	LFO3InternalDepth
	Firm depth of the sample pitch LFO (-1200 - +1200 cents).

int16_t	LFO3ControlDepth
	Controller depth of the sample pitch LFO (-1200 - +1200 cents).

lfo3_ctrl_t	LFO3Controller
	MIDI Controller which controls the sample pitch LFO.

bool	LFO3FlipPhase
	[gig extension]: Inverts the polarity of the pitch LFO wave, so it flips the wave form vertically (NOTE: this setting for LFO3 is a gig format extension; flipping the polarity was only available for LFO1 and LFO2 in the original Gigasampler/GigaStudio software).

bool	LFO3Sync
	If set to true only one LFO should be used for all voices.

bool	VCFEnabled
	If filter should be used.

vcf_type_t	VCFType
	Defines the general filter characteristic (lowpass, highpass, bandpass, etc.).

vcf_cutoff_ctrl_t	VCFCutoffController
	Specifies which external controller has influence on the filter cutoff frequency.

bool	VCFCutoffControllerInvert
	Inverts values coming from the defined cutoff controller.

uint8_t	VCFCutoff
	Max. cutoff frequency.

curve_type_t	VCFVelocityCurve
	Defines a transformation curve for the incoming velocity values, affecting the VCF.

uint8_t	VCFVelocityScale
	(0-127) Amount velocity controls VCF cutoff frequency (only if no other VCF cutoff controller is defined, otherwise this is the minimum cutoff).

uint8_t	VCFVelocityDynamicRange
	0x04 = lowest, 0x00 = highest .

uint8_t	VCFResonance
	Firm internal filter resonance weight.

bool	VCFResonanceDynamic
	If true: Increases the resonance Q according to changes of controllers that actually control the VCF cutoff frequency (EG2, ext. VCF MIDI controller).

vcf_res_ctrl_t	VCFResonanceController
	Specifies which external controller has influence on the filter resonance Q.

bool	VCFKeyboardTracking
	If true: VCF cutoff frequence will be dependend to the note key position relative to the defined breakpoint value.

uint8_t	VCFKeyboardTrackingBreakpoint
	See VCFKeyboardTracking (0 - 127).

curve_type_t	VelocityResponseCurve
	Defines a transformation curve to the incoming velocity values affecting amplitude (usually you don't have to interpret this parameter, use GetVelocityAttenuation() instead).

uint8_t	VelocityResponseDepth
	Dynamic range of velocity affecting amplitude (0 - 4) (usually you don't have to interpret this parameter, use GetVelocityAttenuation() instead).

uint8_t	VelocityResponseCurveScaling
	0 - 127 (usually you don't have to interpret this parameter, use GetVelocityAttenuation() instead).

curve_type_t	ReleaseVelocityResponseCurve
	Defines a transformation curve to the incoming release veloctiy values affecting envelope times.

uint8_t	ReleaseVelocityResponseDepth
	Dynamic range of release velocity affecting envelope time (0 - 4).

uint8_t	ReleaseTriggerDecay
	0 - 8

crossfade_t	Crossfade

bool	PitchTrack
	If true: sample will be pitched according to the key position (this will be disabled for drums for example).

dim_bypass_ctrl_t	DimensionBypass
	If defined, the MIDI controller can switch on/off the dimension in realtime.

int8_t	Pan
	Panorama / Balance (-64..0..63 <-> left..middle..right)

bool	SelfMask
	If true: high velocity notes will stop low velocity notes at the same note, with that you can save voices that wouldn't be audible anyway.

attenuation_ctrl_t	AttenuationController
	MIDI Controller which has influence on the volume level of the sample (or entire sample group).

bool	InvertAttenuationController
	Inverts the values coming from the defined Attenuation Controller.

uint8_t	AttenuationControllerThreshold
	0-127

uint8_t	ChannelOffset
	Audio output where the audio signal of the dimension region should be routed to (0 - 9).

bool	SustainDefeat
	If true: Sustain pedal will not hold a note.

bool	MSDecode
	Gigastudio flag: defines if Mid Side Recordings should be decoded.

uint16_t	SampleStartOffset
	Number of samples the sample start should be moved (0 - 2000).

double	SampleAttenuation
	Sample volume (calculated from DLS::Sampler::Gain)

uint8_t	DimensionUpperLimits [8]
	gig3: defines the upper limit of the dimension values for this dimension region. In case you wondered why this is defined on DimensionRegion level and not on Region level: the zone sizes (upper limits) of the velocity dimension can indeed differ in the individual dimension regions, depending on which zones of the other dimension types are currently selected. So this is exceptional for the velocity dimension only. All other dimension types have the same dimension zone sizes for every single DimensionRegion (of the sample Region).

eg_opt_t	EG1Options
	[gig extension]: Behavior options which should be used for envelope generator 1 (volume amplitude EG).

eg_opt_t	EG2Options
	[gig extension]: Behavior options which should be used for envelope generator 2 (filter cutoff EG).

sust_rel_trg_t	SustainReleaseTrigger
	[gig extension]: Whether a sustain pedal up event shall play release trigger sample.

bool	NoNoteOffReleaseTrigger
	[gig extension]: If `true` then don't play a release trigger sample on MIDI note-off events.

Protected Member Functions
	DimensionRegion (Region pParent, RIFF::List _3ewl)

	DimensionRegion (RIFF::List *_3ewl, const DimensionRegion &src)

void	CopyAssign (const DimensionRegion orig, const std::map< Sample , Sample * > *mSamples)
	Make a (semi) deep copy of the DimensionRegion object given by orig and assign it to this object.

void	serialize (Serialization::Archive *archive)

void	AddSampleLoop (sample_loop_t *pLoopDef)
	Adds a new sample loop with the provided loop definition.

void	DeleteSampleLoop (sample_loop_t *pLoopDef)
	Deletes an existing sample loop.

virtual void	DeleteChunks ()
	Remove all RIFF chunks associated with this Sampler object.

virtual void	CopyAssign (const Sampler *orig)
	Make a deep copy of the Sampler object given by orig and assign it to this object.

Protected Attributes
uint8_t *	VelocityTable
	For velocity dimensions with custom defined zone ranges only: used for fast converting from velocity MIDI value to dimension bit number.

uint8_t	UnityNote

int16_t	FineTune

int32_t	Gain

bool	NoSampleDepthTruncation

bool	NoSampleCompression

uint32_t	SampleLoops
	Reflects the number of sample loops.

sample_loop_t *	pSampleLoops
	Points to the beginning of a sample loop array, or is NULL if there are no loops defined.

RIFF::List *	pParentList

uint32_t	uiHeaderSize

uint32_t	SamplerOptions

Detailed Description

Encapsulates articulation informations of a dimension region.

This is the most important data object of the Gigasampler / GigaStudio format. A DimensionRegion provides the link to the sample to be played and all required articulation informations to be interpreted for playing back the sample and processing it appropriately by the sampler software. Every Region of a Gigasampler Instrument has at least one dimension region (exactly then when the Region has no dimension defined). Many Regions though provide more than one DimensionRegion, which reflect different playing "cases". For example a different sample might be played if a certain pedal is pressed down, or if the note was triggered with different velocity.

One instance of a DimensionRegion reflects exactly one particular case while playing an instrument (for instance "note between C3 and E3 was triggered AND note on velocity was between 20 and 42 AND modulation wheel controller is between 80 and 127). The DimensionRegion defines what to do under that one particular case, that is which sample to play back and how to play that sample back exactly and how to process it. So a DimensionRegion object is always linked to exactly one sample. It may however also link to no sample at all, for defining a "silence" case where nothing shall be played (for example when note on velocity was below 6). Note that a DimensionRegion object only defines "what to do", but it does not define "when to do it". To actually resolve which DimensionRegion to pick under which situation, you need to refer to the DimensionRegions' parent Region object. The Region object contains the necessary "Dimension" definitions, which in turn define which DimensionRegion is associated with which playing case exactly.

The Gigasampler/GigaStudio format defines 3 Envelope Generators and 3 Low Frequency Oscillators:

EG1 and LFO1, both controlling sample amplitude
EG2 and LFO2, both controlling filter cutoff frequency
EG3 and LFO3, both controlling sample pitch

Since the gig format was designed as extension to the DLS file format, this class is derived from the DLS::Sampler class. So also refer to DLS::Sampler for additional informations, class attributes and methods.

Definition at line 535 of file gig.h.

Constructor & Destructor Documentation

◆ DimensionRegion() [1/2]

gig::DimensionRegion::DimensionRegion	(	Region *	pParent,
		RIFF::List *	_3ewl
	)

protected

Definition at line 1496 of file gig.cpp.

◆ DimensionRegion() [2/2]

gig::DimensionRegion::DimensionRegion	(	RIFF::List *	_3ewl,
		const DimensionRegion &	src
	)

protected

Definition at line 1814 of file gig.cpp.

◆ ~DimensionRegion()

gig::DimensionRegion::~DimensionRegion ( )

protected

Definition at line 3102 of file gig.cpp.

Member Function Documentation

◆ AddSampleLoop()

void DLS::Sampler::AddSampleLoop ( sample_loop_t * pLoopDef )

inherited

Adds a new sample loop with the provided loop definition.

Parameters

pLoopDef - points to a loop definition that is to be copied

Definition at line 742 of file DLS.cpp.

References DLS::Sampler::pSampleLoops, DLS::Sampler::SampleLoops, and DLS::sample_loop_t::Size.

◆ CopyAssign() [1/3]

void gig::DimensionRegion::CopyAssign ( const DimensionRegion * orig )

virtual

Make a (semi) deep copy of the DimensionRegion object given by orig and assign it to this object.

Note that all sample pointers referenced by orig are simply copied as memory address. Thus the respective samples are shared, not duplicated!

Parameters

orig	- original DimensionRegion object to be copied from

Definition at line 1842 of file gig.cpp.

References CopyAssign().

Referenced by CopyAssign(), gig::Region::CopyAssign(), gig::Region::DeleteDimensionZone(), and gig::Region::SplitDimensionZone().

◆ CopyAssign() [2/3]

void gig::DimensionRegion::CopyAssign	(	const DimensionRegion *	orig,
		const std::map< Sample , Sample > *	mSamples
	)

protected

Make a (semi) deep copy of the DimensionRegion object given by orig and assign it to this object.

Parameters

orig	- original DimensionRegion object to be copied from
mSamples	- crosslink map between the foreign file's samples and this file's samples

Definition at line 1854 of file gig.cpp.

References pSample, DLS::Sampler::pSampleLoops, DLS::Sampler::SampleLoops, and VelocityTable.

◆ CopyAssign() [3/3]

void DLS::Sampler::CopyAssign ( const Sampler * orig )

virtualinherited

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

Parameters

orig	- original Sampler object to be copied from

Definition at line 788 of file DLS.cpp.

References DLS::Sampler::Gain, DLS::Sampler::pSampleLoops, and DLS::Sampler::SampleLoops.

Referenced by DLS::Region::CopyAssign().

◆ DeleteChunks()

void DLS::Sampler::DeleteChunks ( )

virtualinherited

Remove all RIFF chunks associated with this Sampler object.

At the moment Sampler::DeleteChunks() does nothing. It is recommended to call this method explicitly though from deriving classes's own overridden implementation of this method to avoid potential future compatiblity issues.

See Storage::DeleteChunks() for details.

Implements DLS::Storage.

Reimplemented in DLS::Region.

Definition at line 734 of file DLS.cpp.

Referenced by DLS::Region::DeleteChunks().

◆ DeleteSampleLoop()

void DLS::Sampler::DeleteSampleLoop ( sample_loop_t * pLoopDef )

inherited

Deletes an existing sample loop.

Parameters

pLoopDef - pointer to existing loop definition

Exceptions

Exception - if given loop definition does not exist

Definition at line 764 of file DLS.cpp.

References DLS::Sampler::pSampleLoops, and DLS::Sampler::SampleLoops.

◆ GetParent()

Region * gig::DimensionRegion::GetParent ( ) const

Definition at line 2450 of file gig.cpp.

◆ GetVelocityAttenuation()

double gig::DimensionRegion::GetVelocityAttenuation ( uint8_t MIDIKeyVelocity )

Returns the correct amplitude factor for the given MIDIKeyVelocity.

All involved parameters (VelocityResponseCurve, VelocityResponseDepth and VelocityResponseCurveScaling) involved are taken into account to calculate the amplitude factor. Use this method when a key was triggered to get the volume with which the sample should be played back.

Parameters

MIDIKeyVelocity MIDI velocity value of the triggered key (between 0 and 127)

Returns: amplitude factor (between 0.0 and 1.0)

Definition at line 3129 of file gig.cpp.

◆ GetVelocityCutoff()

double gig::DimensionRegion::GetVelocityCutoff ( uint8_t MIDIKeyVelocity )

Definition at line 3137 of file gig.cpp.

◆ GetVelocityRelease()

double gig::DimensionRegion::GetVelocityRelease ( uint8_t MIDIKeyVelocity )

Definition at line 3133 of file gig.cpp.

◆ serialize()

void gig::DimensionRegion::serialize ( Serialization::Archive * archive )

protected

Definition at line 1896 of file gig.cpp.

◆ SetGain()

void gig::DimensionRegion::SetGain ( int32_t gain )

virtual

Updates the respective member variable and updates SampleAttenuation which depends on this value.

Reimplemented from DLS::Sampler.

Definition at line 2000 of file gig.cpp.

References DLS::Sampler::Gain, and SampleAttenuation.