libgig  4.2.0
gig::Instrument Class Reference

Provides access to a Gigasampler/GigaStudio instrument. More...

#include <gig.h>

Inheritance diagram for gig::Instrument:
DLS::Instrument DLS::Resource DLS::Articulator DLS::Storage DLS::Storage

Public Member Functions

RegionGetFirstRegion ()
 Returns the first Region of the instrument. More...
 
RegionGetNextRegion ()
 Returns the next Region of the instrument. More...
 
RegionAddRegion ()
 
void DeleteRegion (Region *pRegion)
 
void MoveTo (Instrument *dst)
 Move this instrument at the position before. More...
 
virtual void UpdateChunks (progress_t *pProgress)
 Apply Instrument with all its Regions to the respective RIFF chunks. More...
 
virtual void CopyAssign (const Instrument *orig)
 Make a (semi) deep copy of the Instrument object given by orig and assign it to this object. More...
 
RegionGetRegion (unsigned int Key)
 Returns the appropriate Region for a triggered note. More...
 
MidiRuleGetMidiRule (int i)
 Returns a MIDI rule of the instrument. More...
 
MidiRuleCtrlTriggerAddMidiRuleCtrlTrigger ()
 Adds the "controller trigger" MIDI rule to the instrument. More...
 
MidiRuleLegatoAddMidiRuleLegato ()
 Adds the legato MIDI rule to the instrument. More...
 
MidiRuleAlternatorAddMidiRuleAlternator ()
 Adds the alternator MIDI rule to the instrument. More...
 
void DeleteMidiRule (int i)
 Deletes a MIDI rule from the instrument. More...
 
ScriptGetScriptOfSlot (uint index)
 Get instrument script (gig format extension). More...
 
void AddScriptSlot (Script *pScript, bool bypass=false)
 Add new instrument script slot (gig format extension). More...
 
void SwapScriptSlots (uint index1, uint index2)
 Flip two script slots with each other (gig format extension). More...
 
void RemoveScriptSlot (uint index)
 Remove script slot. More...
 
void RemoveScript (Script *pScript)
 Remove reference to given Script (gig format extension). More...
 
uint ScriptSlotCount () const
 Instrument's amount of script slots. More...
 
bool IsScriptSlotBypassed (uint index)
 Whether script execution shall be skipped. More...
 
void SetScriptSlotBypassed (uint index, bool bBypass)
 Defines whether execution shall be skipped. More...
 

Public Attributes

int32_t Attenuation
 in dB
 
uint16_t EffectSend
 
int16_t FineTune
 in cents
 
uint16_t PitchbendRange
 Number of semitones pitchbend controller can pitch (default is 2).
 
bool PianoReleaseMode
 
range_t DimensionKeyRange
 0-127 (where 0 means C1 and 127 means G9)
 

Protected Types

typedef std::list< Region * > RegionList
 
typedef std::list< Articulation * > ArticulationList
 

Protected Member Functions

 Instrument (File *pFile, RIFF::List *insList, progress_t *pProgress=NULL)
 
 ~Instrument ()
 Destructor. More...
 
void CopyAssign (const Instrument *orig, const std::map< Sample *, Sample * > *mSamples)
 Make a (semi) deep copy of the Instrument object given by orig and assign it to this object. More...
 
void UpdateRegionKeyTable ()
 
void LoadScripts ()
 
void UpdateScriptFileOffsets ()
 
void DeleteRegion (Region *pRegion)
 
virtual void DeleteChunks ()
 Remove all RIFF chunks associated with this Instrument object. More...
 
virtual void CopyAssign (const Instrument *orig)
 Make a (semi) deep copy of the Instrument 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.
 
void CopyAssignCore (const Instrument *orig)
 
virtual void LoadRegions ()
 
ResourceGetParent ()
 
const ResourceGetParent () const
 
void GenerateDLSID ()
 Generates a new DLSID for the resource.
 
Articulation * GetFirstArticulation ()
 
Articulation * GetNextArticulation ()
 
void LoadArticulations ()
 

Static Protected Member Functions

static void GenerateDLSID (dlsid_t *pDLSID)
 

Protected Attributes

RegionRegionKeyTable [128]
 fast lookup for the corresponding Region of a MIDI key
 
bool IsDrum
 Indicates if the Instrument is a drum type, as they differ in the synthesis model of DLS from melodic instruments.
 
uint16_t MIDIBank
 Reflects combination of MIDIBankCoarse and MIDIBankFine (bank 1 - bank 16384). Do not change this value, it will not be saved! Change MIDIBankCoarse and MIDIBankFine instead (we might change that in future).
 
uint8_t MIDIBankCoarse
 Reflects the MIDI Bank number for MIDI Control Change 0 (bank 1 - 128).
 
uint8_t MIDIBankFine
 Reflects the MIDI Bank number for MIDI Control Change 32 (bank 1 - 128).
 
uint32_t MIDIProgram
 Specifies the MIDI Program Change Number this Instrument should be assigned to.
 
uint32_t Regions
 Reflects the number of Region defintions this Instrument has.
 
RIFF::ListpCkInstrument
 
RegionList * pRegions
 
RegionList::iterator RegionsIterator
 
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.
 
ResourcepParent
 
RIFF::ListpResourceList
 
RIFF::ListpParentList
 
ArticulationList * pArticulations
 
ArticulationList::iterator ArticulationsIterator
 

Detailed Description

Provides access to a Gigasampler/GigaStudio instrument.

This class provides access to Gigasampler/GigaStudio instruments contained in .gig files. A gig instrument is merely a set of keyboard ranges (called Region), plus some additional global informations about the instrument. The major part of the actual instrument definition used for the synthesis of the instrument is contained in the respective Region object (or actually in the respective DimensionRegion object being, see description of Region for details).

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

Definition at line 1209 of file gig.h.

Constructor & Destructor Documentation

◆ ~Instrument()

gig::Instrument::~Instrument ( )
protectedvirtual

Destructor.

Frees all memory occupied by this instrument.

Reimplemented from DLS::Instrument.

Definition at line 4845 of file gig.cpp.

Member Function Documentation

◆ AddMidiRuleAlternator()

MidiRuleAlternator * gig::Instrument::AddMidiRuleAlternator ( )

Adds the alternator MIDI rule to the instrument.

Returns
the new MIDI rule

Definition at line 5136 of file gig.cpp.

◆ AddMidiRuleCtrlTrigger()

MidiRuleCtrlTrigger * gig::Instrument::AddMidiRuleCtrlTrigger ( )

Adds the "controller trigger" MIDI rule to the instrument.

Returns
the new MIDI rule

Definition at line 5110 of file gig.cpp.

◆ AddMidiRuleLegato()

MidiRuleLegato * gig::Instrument::AddMidiRuleLegato ( )

Adds the legato MIDI rule to the instrument.

Returns
the new MIDI rule

Definition at line 5123 of file gig.cpp.

◆ AddScriptSlot()

void gig::Instrument::AddScriptSlot ( Script pScript,
bool  bypass = false 
)

Add new instrument script slot (gig format extension).

Add the given real-time instrument script reference to this instrument, which shall be executed by the sampler for for this instrument. The script will be added to the end of the script list of this instrument. The positions of the scripts in the Instrument's Script list are relevant, because they define in which order they shall be executed by the sampler. For this reason it is also legal to add the same script twice to an instrument, for example you might have a script called "MyFilter" which performs an event filter task, and you might have another script called "MyNoteTrigger" which triggers new notes, then you might for example have the following list of scripts on the instrument:

  1. Script "MyFilter"
  2. Script "MyNoteTrigger"
  3. Script "MyFilter"

Which would make sense, because the 2nd script launched new events, which you might need to filter as well.

There are two ways to disable / "bypass" scripts. You can either disable a script locally for the respective script slot on an instrument (i.e. by passing false to the 2nd argument of this method, or by calling SetScriptBypassed()). Or you can disable a script globally for all slots and all instruments by setting Script::Bypass.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
pScript- script that shall be executed for this instrument
bypass- if enabled, the sampler shall skip executing this script (in the respective list position)
See also
SetScriptBypassed()

Definition at line 5240 of file gig.cpp.

◆ CopyAssign() [1/4]

void DLS::Instrument::CopyAssign ( const Instrument orig)
virtualinherited

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

Definition at line 1524 of file DLS.cpp.

References DLS::Region::CopyAssign(), and DLS::Instrument::Regions.

◆ CopyAssign() [2/4]

void gig::Instrument::CopyAssign ( const Instrument orig)
virtual

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

Definition at line 5373 of file gig.cpp.

Referenced by gig::File::AddContentOf(), and gig::File::AddDuplicateInstrument().

◆ CopyAssign() [3/4]

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

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

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

Definition at line 5385 of file gig.cpp.

References Attenuation, gig::Region::CopyAssign(), DimensionKeyRange, FineTune, GetFirstRegion(), PitchbendRange, and DLS::Instrument::Regions.

◆ CopyAssign() [4/4]

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 601 of file DLS.cpp.

References DLS::Info::CopyAssign(), and DLS::Resource::pInfo.

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

◆ DeleteChunks()

void DLS::Instrument::DeleteChunks ( )
virtualinherited

Remove all RIFF chunks associated with this Instrument object.

See Storage::DeleteChunks() for details.

Reimplemented from DLS::Articulator.

Definition at line 1481 of file DLS.cpp.

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

Referenced by DLS::File::DeleteInstrument(), and gig::File::DeleteInstrument().

◆ DeleteMidiRule()

void gig::Instrument::DeleteMidiRule ( int  i)

Deletes a MIDI rule from the instrument.

Parameters
i- MIDI rule number

Definition at line 5149 of file gig.cpp.

◆ GetFirstRegion()

Region * gig::Instrument::GetFirstRegion ( )

Returns the first Region of the instrument.

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

Returns
pointer address to first region or NULL if there is none
See also
GetNextRegion()

Definition at line 4993 of file gig.cpp.

Referenced by CopyAssign().

◆ GetMidiRule()

MidiRule * gig::Instrument::GetMidiRule ( int  i)

Returns a MIDI rule of the instrument.

The list of MIDI rules, at least in gig v3, always contains at most two rules. The second rule can only be the DEF filter (which currently isn't supported by libgig).

Parameters
i- MIDI rule number
Returns
pointer address to MIDI rule number i or NULL if there is none

Definition at line 5101 of file gig.cpp.

◆ GetNextRegion()

Region * gig::Instrument::GetNextRegion ( )

Returns the next Region of the instrument.

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

Returns
pointer address to the next region or NULL if end reached
See also
GetFirstRegion()

Definition at line 5007 of file gig.cpp.

◆ GetRegion()

Region * gig::Instrument::GetRegion ( unsigned int  Key)

Returns the appropriate Region for a triggered note.

Parameters
KeyMIDI Key number of triggered note / key (0 - 127)
Returns
pointer adress to the appropriate Region or NULL if there there is no Region defined for the given Key

Definition at line 4975 of file gig.cpp.

References RegionKeyTable.

◆ GetScriptOfSlot()

Script * gig::Instrument::GetScriptOfSlot ( uint  index)

Get instrument script (gig format extension).

Returns the real-time instrument script of instrument script slot index.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
index- instrument script slot index
Returns
script or NULL if index is out of bounds

Definition at line 5199 of file gig.cpp.

◆ IsScriptSlotBypassed()

bool gig::Instrument::IsScriptSlotBypassed ( uint  index)

Whether script execution shall be skipped.

Defines locally for the Script reference slot in the Instrument's Script list, whether the script shall be skipped by the sampler regarding execution.

It is also possible to ignore exeuction of the script globally, for all slots and for all instruments by setting Script::Bypass.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
index- index of the script slot on this instrument
See also
Script::Bypass

Definition at line 5336 of file gig.cpp.

References ScriptSlotCount().

◆ MoveTo()

void gig::Instrument::MoveTo ( Instrument dst)

Move this instrument at the position before.

  • dst.

This method can be used to reorder the sequence of instruments in a .gig file. This might be helpful especially on large .gig files which contain a large number of instruments within the same .gig file. So grouping such instruments to similar ones, can help to keep track of them when working with such complex .gig files.

When calling this method, this instrument will be removed from in its current position in the instruments list and moved to the requested target position provided by

Parameters
dst.You may also pass NULL as argument to this method, in that case this intrument will be moved to the very end of the .gig file's instrument list.

You have to call Save() to make the order change persistent to the .gig file.

Currently this method is limited to moving the instrument within the same .gig file. Trying to move it to another .gig file by calling this method will throw an exception.

Parameters
dst- destination instrument at which this instrument will be moved to, or pass NULL for moving to end of list
Exceptions
gig::Exceptionif this instrument and target instrument are not part of the same file

Definition at line 5061 of file gig.cpp.

References RIFF::List::GetSubList(), and RIFF::List::MoveSubChunk().

◆ RemoveScript()

void gig::Instrument::RemoveScript ( Script pScript)

Remove reference to given Script (gig format extension).

This will remove all script slots on the instrument which are referencing the given script.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
pScript- script reference to remove from this instrument
See also
RemoveScriptSlot()

Definition at line 5293 of file gig.cpp.

◆ RemoveScriptSlot()

void gig::Instrument::RemoveScriptSlot ( uint  index)

Remove script slot.

Removes the script slot with the given slot index.

Parameters
index- index of script slot to remove

Definition at line 5275 of file gig.cpp.

◆ ScriptSlotCount()

uint gig::Instrument::ScriptSlotCount ( ) const

Instrument's amount of script slots.

This method returns the amount of script slots this instrument currently uses.

A script slot is a reference of a real-time instrument script to be executed by the sampler. The scripts will be executed by the sampler in sequence of the slots. One (same) script may be referenced multiple times in different slots.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.

Definition at line 5316 of file gig.cpp.

Referenced by IsScriptSlotBypassed(), SetScriptSlotBypassed(), and UpdateChunks().

◆ SetScriptSlotBypassed()

void gig::Instrument::SetScriptSlotBypassed ( uint  index,
bool  bBypass 
)

Defines whether execution shall be skipped.

You can call this method to define locally whether or whether not the given script slot shall be executed by the sampler.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
index- script slot index on this instrument
bBypass- if true, the script slot will be skipped by the sampler
See also
Script::Bypass

Definition at line 5356 of file gig.cpp.

References ScriptSlotCount().

◆ SwapScriptSlots()

void gig::Instrument::SwapScriptSlots ( uint  index1,
uint  index2 
)

Flip two script slots with each other (gig format extension).

Swaps the position of the two given scripts in the Instrument's Script list. The positions of the scripts in the Instrument's Script list are relevant, because they define in which order they shall be executed by the sampler.

Note
This is an own format extension which did not exist i.e. in the GigaStudio 4 software. It will currently only work with LinuxSampler and gigedit.
Parameters
index1- index of the first script slot to swap
index2- index of the second script slot to swap

Definition at line 5260 of file gig.cpp.

◆ UpdateChunks()

void gig::Instrument::UpdateChunks ( progress_t pProgress)
virtual

Apply Instrument with all its Regions 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::Exceptionif samples cannot be dereferenced

Reimplemented from DLS::Instrument.

Definition at line 4863 of file gig.cpp.

References RIFF::List::AddSubChunk(), RIFF::List::AddSubList(), Attenuation, RIFF::List::DeleteSubChunk(), DimensionKeyRange, FineTune, RIFF::List::GetSubChunk(), RIFF::List::GetSubList(), gig::range_t::high, RIFF::Chunk::LoadChunkData(), gig::range_t::low, PitchbendRange, DLS::File::pVersion, RIFF::Chunk::Resize(), ScriptSlotCount(), and DLS::Instrument::UpdateChunks().


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