Defines Region information of a Gigasampler/GigaStudio instrument. More...

#include <gig.h>

Inheritance diagram for gig::Region:

Public Member Functions
DimensionRegion *	GetDimensionRegionByValue (const uint DimValues[8])
	Use this method in your audio engine to get the appropriate dimension region with it's articulation data for the current situation. More...

DimensionRegion *	GetDimensionRegionByBit (const uint8_t DimBits[8])
	Returns the appropriate DimensionRegion for the given dimension bit numbers (zone index). More...

int	GetDimensionRegionIndexByValue (const uint DimValues[8])

Sample *	GetSample ()
	Returns pointer address to the Sample referenced with this region. More...

void	AddDimension (dimension_def_t *pDimDef)
	Einstein would have dreamed of it - create a new dimension. More...

void	DeleteDimension (dimension_def_t *pDimDef)
	Delete an existing dimension. More...

dimension_def_t *	GetDimensionDefinition (dimension_t type)
	Searches in the current Region for a dimension of the given dimension type and returns the precise configuration of that dimension in this Region. More...

void	DeleteDimensionZone (dimension_t type, int zone)
	Delete one split zone of a dimension (decrement zone amount). More...

void	SplitDimensionZone (dimension_t type, int zone)
	Divide split zone of a dimension in two (increment zone amount). More...

void	SetDimensionType (dimension_t oldType, dimension_t newType)
	Change type of an existing dimension. More...

virtual void	SetKeyRange (uint16_t Low, uint16_t High)
	Modifies the key range of this Region and makes sure the respective chunks are in correct order. More...

virtual void	UpdateChunks (progress_t *pProgress)
	Apply Region settings and all its DimensionRegions to the respective RIFF chunks. More...

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

void	SetSample (Sample *pSample)
	Assign another sample to this Region. More...

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

virtual void	CopyAssign (const Region *orig)
	Make a (semi) deep copy of the Region 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...

virtual void	CopyAssign (const Articulator *orig)
	Not yet implemented in this version, since the .gig format does not need to copy DLS articulators and so far nobody used pure DLS instrument AFAIK.

virtual void	CopyAssign (const Sampler *orig)
	Make a deep copy of the Sampler 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.

Articulation *	GetArticulation (size_t pos)
	Returns Articulation at supplied pos position within the articulation list. More...

Articulation *	GetFirstArticulation ()
	Returns the first Articulation in the list of articulations. More...

Articulation *	GetNextArticulation ()
	Returns the next Articulation from the list of articulations. More...

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

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

virtual void	SetGain (int32_t gain)

Static Public Member Functions
static void	GenerateDLSID (dlsid_t *pDLSID)

Public Attributes
unsigned int	Dimensions
	Number of defined dimensions, do not alter!

dimension_def_t	pDimensionDefinitions [8]
	Defines the five (gig2) or eight (gig3) possible dimensions (the dimension's controller and number of bits/splits). Use AddDimension() and DeleteDimension() to create a new dimension or delete an existing one.

uint32_t	DimensionRegions
	Total number of DimensionRegions this Region contains, do not alter!

DimensionRegion *	pDimensionRegions [256]
	Pointer array to the 32 (gig2) or 256 (gig3) possible dimension regions (reflects NULL for dimension regions not in use). Avoid to access the array directly and better use GetDimensionRegionByValue() instead, but of course in some cases it makes sense to use the array (e.g. iterating through all DimensionRegions). Use AddDimension() and DeleteDimension() to create a new dimension or delete an existing one (which will create or delete the respective dimension region(s) automatically).

unsigned int	Layers
	Amount of defined layers (1 - 32). A value of 1 actually means no layering, a value > 1 means there is Layer dimension. The same information can of course also be obtained by accessing pDimensionDefinitions. Do not alter this value!

range_t	KeyRange

range_t	VelocityRange

uint16_t	KeyGroup

uint16_t	Layer

bool	SelfNonExclusive

bool	PhaseMaster

uint16_t	PhaseGroup

bool	MultiChannel

uint32_t	Channel

Info *	pInfo
	Points (in any case) to an Info object, providing additional, optional infos and comments.

dlsid_t *	pDLSID
	Points to a dlsid_t structure if the file provided a DLS ID else is NULL.

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.

Protected Types
typedef std::vector< Articulation * >	ArticulationList

Protected Member Functions
	Region (Instrument pInstrument, RIFF::List rgnList)

void	LoadDimensionRegions (RIFF::List *rgn)

void	UpdateVelocityTable ()

Sample *	GetSampleFromWavePool (unsigned int WavePoolTableIndex, progress_t *pProgress=NULL)

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

DimensionRegion *	GetDimensionRegionByBit (const std::map< dimension_t, int > &DimCase)

	~Region ()
	Destructor. More...

void	LoadArticulations ()

Protected Attributes
RIFF::List *	pCkRegion

uint32_t	WavePoolTableIndex

Sample *	pSample

uint16_t	FormatOptionFlags

uint16_t	WaveLinkOptionFlags

Resource *	pParent

RIFF::List *	pResourceList

RIFF::List *	pParentList

RIFF::List *	pParentList

ArticulationList *	pArticulations

ArticulationList::iterator	ArticulationsIterator

uint32_t	uiHeaderSize

uint32_t	SamplerOptions

Detailed Description

Defines Region information of a Gigasampler/GigaStudio instrument.

A Region reflects a consecutive area (key range) on the keyboard. The individual regions in the gig format may not overlap with other regions (of the same instrument that is). Further, in the gig format a Region is merely a container for DimensionRegions (a.k.a. "Cases"). The Region itself does not provide the sample mapping or articulation informations used, even though the data structures of regions indeed provide such informations. The latter is however just of historical nature, because the gig file format was derived from the DLS file format.

Each Region consists of at least one or more DimensionRegions. The actual amount of DimensionRegions depends on which kind of "dimensions" are defined for this region, and on the split / zone amount for each of those dimensions.

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

Definition at line 927 of file gig.h.

Constructor & Destructor Documentation

◆ ~Region()

gig::Region::~Region ( )

protectedvirtual

Destructor.

Intended to free up all memory occupied by this Region object. ATM this destructor implementation does nothing though.

Reimplemented from DLS::Region.

Definition at line 4160 of file gig.cpp.

Member Function Documentation

◆ AddDimension()

void gig::Region::AddDimension ( dimension_def_t * pDimDef )

Einstein would have dreamed of it - create a new dimension.

Creates a new dimension with the dimension definition given by pDimDef. The appropriate amount of DimensionRegions will be created. There is a hard limit of dimensions and total amount of "bits" all dimensions can have. This limit is dependant to what gig file format version this file refers to. The gig v2 (and lower) format has a dimension limit and total amount of bits limit of 5, whereas the gig v3 format has a limit of 8.

Parameters

pDimDef - defintion of the new dimension

Exceptions

gig::Exception	if dimension of the same type exists already
gig::Exception	if amount of dimensions or total amount of dimension bits limit is violated

Definition at line 3608 of file gig.cpp.

References RIFF::List::AddSubList(), gig::dimension_def_t::bits, gig::dimension_def_t::dimension, gig::dimension_layer, gig::dimension_samplechannel, RIFF::List::GetSubList(), RIFF::List::MoveSubChunk(), DLS::File::pVersion, gig::dimension_def_t::split_type, and gig::dimension_def_t::zones.

Referenced by DeleteDimensionZone(), and SplitDimensionZone().

◆ 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::sample_loop_t::Size.

◆ CopyAssign() [1/5]

void Resource::CopyAssign ( const Resource * orig )

virtualinherited

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

Parameters

orig	- original Resource object to be copied from

Definition at line 637 of file DLS.cpp.

References RIFF::List::GetSubChunk(), DLS::Resource::pInfo, RIFF::Chunk::Read(), RIFF::Chunk::ReadInt16(), RIFF::Chunk::ReadInt32(), RIFF::Chunk::ReadUint16(), RIFF::Chunk::ReadUint32(), and RIFF::Chunk::SetPos().

Referenced by DLS::Region::CopyAssign(), DLS::Sample::CopyAssignCore(), and DLS::Instrument::DeleteChunks().

◆ CopyAssign() [2/5]

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

◆ CopyAssign() [3/5]

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

virtualinherited

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

Note that the sample pointer referenced by orig is simply copied as memory address. Thus the respective sample is shared, not duplicated!

Parameters

orig	- original Region object to be copied from

Definition at line 1325 of file DLS.cpp.

References DLS::Articulator::CopyAssign(), DLS::Resource::CopyAssign(), DLS::Sampler::CopyAssign(), DLS::range_t::high, DLS::Region::KeyRange, and DLS::range_t::low.

Referenced by DLS::Instrument::CopyAssign(), and CopyAssign().

◆ CopyAssign() [4/5]

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

virtual

Make a (semi) deep copy of the Region 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 Region object to be copied from

Definition at line 4359 of file gig.cpp.

References DLS::Sample::CopyAssign().

Referenced by gig::Instrument::CopyAssign().

◆ CopyAssign() [5/5]

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

protected

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

Parameters

mSamples - crosslink map between the foreign file's samples and this file's samples

Definition at line 4370 of file gig.cpp.

References DLS::Region::CopyAssign(), Dimensions, RIFF::Chunk::GetPos(), RIFF::Chunk::GetSize(), Layers, pDimensionDefinitions, pDimensionRegions, gig::Sample::pGroup, RIFF::Chunk::Read(), RIFF::Chunk::ReadInt16(), RIFF::Chunk::ReadString(), RIFF::Chunk::ReadUint16(), RIFF::Chunk::ReadUint32(), RIFF::Chunk::ReadUint8(), and RIFF::Chunk::SetPos().

◆ DeleteChunks()

void DLS::Region::DeleteChunks ( )

virtualinherited

Remove all RIFF chunks associated with this Region object.

See Storage::DeleteChunks() for details.

Reimplemented from DLS::Articulator.

Definition at line 1184 of file DLS.cpp.

References DLS::Articulator::DeleteChunks(), DLS::Resource::DeleteChunks(), DLS::Sampler::DeleteChunks(), RIFF::List::DeleteSubChunk(), and DLS::File::GetSample().

Referenced by DeleteDimensionZone(), DLS::Instrument::GetNextRegion(), and SplitDimensionZone().

◆ DeleteDimension()

void gig::Region::DeleteDimension ( dimension_def_t * pDimDef )

Delete an existing dimension.

Deletes the dimension given by pDimDef and deletes all respective dimension regions, that is all dimension regions where the dimension's bit(s) part is greater than 0. In case of a 'sustain pedal' dimension for example this would delete all dimension regions for the case(s) where the sustain pedal is pressed down.

Parameters

pDimDef - dimension to delete

Exceptions

gig::Exception if given dimension cannot be found

Definition at line 3720 of file gig.cpp.

References RIFF::List::DeleteSubChunk(), gig::dimension_def_t::dimension, gig::dimension_layer, gig::dimension_none, gig::DimensionRegion::DimensionUpperLimits, and RIFF::List::GetSubList().

◆ DeleteDimensionZone()

void gig::Region::DeleteDimensionZone	(	dimension_t	type,
		int	zone
	)

Delete one split zone of a dimension (decrement zone amount).

Instead of deleting an entire dimensions, this method will only delete one particular split zone given by zone of the Region's dimension given by type. So this method will simply decrement the amount of zones by one of the dimension in question. To be able to do that, the respective dimension must exist on this Region and it must have at least 3 zones. All DimensionRegion objects associated with the zone will be deleted.

Parameters

type	- identifies the dimension where a zone shall be deleted
zone	- index of the dimension split zone that shall be deleted

Exceptions

gig::Exception if requested zone could not be deleted

Definition at line 3810 of file gig.cpp.

References AddDimension(), RIFF::List::AddSubList(), gig::dimension_def_t::bits, gig::DimensionRegion::CopyAssign(), DLS::Region::DeleteChunks(), gig::dimension_def_t::dimension, gig::dimension_none, Dimensions, gig::DimensionRegion::DimensionUpperLimits, RIFF::List::GetSubList(), pDimensionDefinitions, pDimensionRegions, gig::dimension_def_t::split_type, gig::split_type_normal, and gig::dimension_def_t::zones.

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

◆ GetArticulation()

Articulation * DLS::Articulator::GetArticulation ( size_t pos )

inherited

Returns Articulation at supplied pos position within the articulation list.

If supplied pos is out of bounds then NULL is returned.

Parameters

pos	- position of sought Articulation in articulation list

Returns: pointer address to requested articulation or NULL if pos is out of bounds

Definition at line 200 of file DLS.cpp.

◆ GetDimensionDefinition()

dimension_def_t * gig::Region::GetDimensionDefinition ( dimension_t type )

Searches in the current Region for a dimension of the given dimension type and returns the precise configuration of that dimension in this Region.

Parameters

type	- dimension type of the sought dimension

Returns: dimension definition or NULL if there is no dimension with sought type in this Region.

Definition at line 4153 of file gig.cpp.

◆ GetDimensionRegionByBit()

DimensionRegion * gig::Region::GetDimensionRegionByBit ( const uint8_t DimBits[8] )

Returns the appropriate DimensionRegion for the given dimension bit numbers (zone index).

You usually use GetDimensionRegionByValue instead of calling this method directly!

Parameters

DimBits Bit numbers for dimension 0 to 7

Returns: adress to the DimensionRegion for the given dimension bit numbers

See also: GetDimensionRegionByValue()

Definition at line 4293 of file gig.cpp.

Referenced by SetDimensionType(), and SplitDimensionZone().

◆ GetDimensionRegionByValue()

DimensionRegion * gig::Region::GetDimensionRegionByValue ( const uint DimValues[8] )

Use this method in your audio engine to get the appropriate dimension region with it's articulation data for the current situation.

Just call the method with the current MIDI controller values and you'll get the DimensionRegion with the appropriate articulation data for the current situation (for this Region of course only). To do that you'll first have to look which dimensions with which controllers and in which order are defined for this Region when you load the .gig file. Special cases are e.g. layer or channel dimensions where you just put in the index numbers instead of a MIDI controller value (means 0 for left channel, 1 for right channel or 0 for layer 0, 1 for layer 1, etc.).

Parameters

DimValues MIDI controller values (0-127) for dimension 0 to 7

Returns: adress to the DimensionRegion for the given situation

See also: pDimensionDefinitions; Dimensions

Definition at line 4184 of file gig.cpp.

References gig::dimension_velocity, gig::split_type_bit, gig::split_type_normal, and gig::DimensionRegion::VelocityTable.

◆ GetFirstArticulation()

Articulation * DLS::Articulator::GetFirstArticulation ( )

inherited

Returns the first Articulation in the list of articulations.

You have to call this method once before you can use GetNextArticulation().

Returns: pointer address to first Articulation or NULL if there is none

See also: GetNextArticulation()

Deprecated:: This method is not reentrant-safe, use GetArticulation() instead.

Definition at line 216 of file DLS.cpp.

◆ GetNextArticulation()

Articulation * DLS::Articulator::GetNextArticulation ( )

inherited

Returns the next Articulation from the list of articulations.

You have to call GetFirstArticulation() once before you can use this method. By calling this method multiple times it iterates through the available articulations.

Returns: pointer address to the next Articulation or NULL if end reached

See also: GetFirstArticulation()

Deprecated:: This method is not reentrant-safe, use GetArticulation() instead.

Definition at line 234 of file DLS.cpp.

References RIFF::List::GetListType(), RIFF::List::GetSubChunkAt(), and RIFF::List::GetSubList().

◆ GetSample()

Sample * gig::Region::GetSample ( )

Returns pointer address to the Sample referenced with this region.

This is the global Sample for the entire Region (not sure if this is actually used by the Gigasampler engine - I would only use the Sample referenced by the appropriate DimensionRegion instead of this sample).

Returns: address to Sample or NULL if there is no reference to a sample saved in the .gig file

Definition at line 4312 of file gig.cpp.

References RIFF::File::GetCurrentFileSize(), gig::File::GetSample(), and RIFF::File::IsNew().

◆ SetDimensionType()

void gig::Region::SetDimensionType	(	dimension_t	oldType,
		dimension_t	newType
	)

Change type of an existing dimension.

Alters the dimension type of a dimension already existing on this region. If there is currently no dimension on this Region with type oldType, then this call with throw an Exception. Likewise there are cases where the requested dimension type cannot be performed. For example if the new dimension type shall be gig::dimension_samplechannel, and the current dimension has more than 2 zones. In such cases an Exception is thrown as well.

Parameters

oldType	- identifies the existing dimension to be changed
newType	- to which dimension type it should be changed to

Exceptions

gig::Exception if requested change cannot be performed

Definition at line 4113 of file gig.cpp.

References gig::dimension_def_t::dimension, gig::dimension_samplechannel, GetDimensionRegionByBit(), gig::dimension_def_t::split_type, and gig::dimension_def_t::zones.

◆ SetKeyRange()

void gig::Region::SetKeyRange	(	uint16_t	Low,
		uint16_t	High
	)

virtual

Modifies the key range of this Region and makes sure the respective chunks are in correct order.

Parameters

Low	- lower end of key range
High	- upper end of key range

Reimplemented from DLS::Region.

Definition at line 3514 of file gig.cpp.

References gig::dimension_velocity, gig::DimensionRegion::DimensionUpperLimits, DLS::Region::SetKeyRange(), gig::DimensionRegion::VelocityTable, and gig::DimensionRegion::VelocityUpperLimit.

◆ SetSample()

void DLS::Region::SetSample ( Sample * pSample )

inherited

Assign another sample to this Region.

Parameters

pSample - sample to be assigned

Definition at line 1216 of file DLS.cpp.

◆ SplitDimensionZone()

void gig::Region::SplitDimensionZone	(	dimension_t	type,
		int	zone
	)

Divide split zone of a dimension in two (increment zone amount).

This will increment the amount of zones for the dimension (given by type) by one. It will do so by dividing the zone (given by zone) in the middle of its zone range in two. So the two zones resulting from the zone being splitted, will be an equivalent copy regarding all their articulation informations and sample reference. The two zones will only differ in their zone's upper limit (DimensionRegion::DimensionUpperLimits).

Parameters

type	- identifies the dimension where a zone shall be splitted
zone	- index of the dimension split zone that shall be splitted

Exceptions

gig::Exception if requested zone could not be splitted

Definition at line 3954 of file gig.cpp.

References AddDimension(), RIFF::List::AddSubList(), gig::dimension_def_t::bits, gig::DimensionRegion::CopyAssign(), DLS::Region::DeleteChunks(), gig::dimension_def_t::dimension, gig::dimension_none, Dimensions, gig::DimensionRegion::DimensionUpperLimits, GetDimensionRegionByBit(), RIFF::List::GetSubList(), pDimensionDefinitions, pDimensionRegions, gig::dimension_def_t::split_type, gig::split_type_normal, and gig::dimension_def_t::zones.

◆ UpdateChunks()

void gig::Region::UpdateChunks ( progress_t * pProgress )

virtual

Apply Region settings and all its DimensionRegions 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.

Parameters

pProgress - callback function for progress notification

Exceptions

gig::Exception if samples cannot be dereferenced

Reimplemented from DLS::Region.

Definition at line 3399 of file gig.cpp.

References RIFF::List::AddSubList(), RIFF::List::DeleteSubChunk(), gig::dimension_none, RIFF::List::GetListType(), RIFF::List::GetSubList(), RIFF::List::GetSubListAt(), RIFF::Chunk::LoadChunkData(), DLS::File::pVersion, and DLS::Region::UpdateChunks().

Member Data Documentation

◆ Gain

int32_t DLS::Sampler::Gain

inherited

Deprecated:: Don't alter directly, use SetGain() instead!

Definition at line 429 of file DLS.h.

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

◆ KeyRange

range_t DLS::Region::KeyRange

inherited

Deprecated:: Only read, don't write! Use SetKeyRange() instead.

Definition at line 495 of file DLS.h.

Referenced by DLS::Region::CopyAssign(), and gig::ScriptGroup::DeleteScript().

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

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Region()

Member Function Documentation

◆ AddDimension()

◆ AddSampleLoop()

◆ CopyAssign() [1/5]

◆ CopyAssign() [2/5]

◆ CopyAssign() [3/5]

◆ CopyAssign() [4/5]

◆ CopyAssign() [5/5]

◆ DeleteChunks()

◆ DeleteDimension()

◆ DeleteDimensionZone()

◆ DeleteSampleLoop()

◆ GetArticulation()

◆ GetDimensionDefinition()

◆ GetDimensionRegionByBit()

◆ GetDimensionRegionByValue()

◆ GetFirstArticulation()

◆ GetNextArticulation()

◆ GetSample()

◆ SetDimensionType()

◆ SetKeyRange()

◆ SetSample()

◆ SplitDimensionZone()

◆ UpdateChunks()

Member Data Documentation

◆ Gain

◆ KeyRange