gig::Instrument Class Reference

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

`#include <gig.h>`

Inheritance diagram for gig::Instrument:

## Public Member Functions

Region * | GetRegionAt (size_t pos)
| Returns Region at supplied pos position within the region list of this instrument.
Region * | GetFirstRegion ()
| Returns the first Region of the instrument.
Region * | GetNextRegion ()
| Returns the next Region of the instrument.
Region * | AddRegion ()
void | DeleteRegion (Region *pRegion)
void | MoveTo (Instrument *dst)
| Move this instrument at the position before.
virtual void | UpdateChunks (progress_t *pProgress)
| Apply Instrument with all its Regions to the respective RIFF chunks.
virtual void | CopyAssign (const Instrument *orig)
| Make a (semi) deep copy of the Instrument object given by orig and assign it to this object.
Region * | GetRegion (unsigned int Key)
| Returns the appropriate Region for a triggered note.
MidiRule * | GetMidiRule (int i)
| Returns a MIDI rule of the instrument.
MidiRuleCtrlTrigger * | AddMidiRuleCtrlTrigger ()
| Adds the "controller trigger" MIDI rule to the instrument.
MidiRuleLegato * | AddMidiRuleLegato ()
| Adds the legato MIDI rule to the instrument.
MidiRuleAlternator * | AddMidiRuleAlternator ()
| Adds the alternator MIDI rule to the instrument.
void | DeleteMidiRule (int i)
| Deletes a MIDI rule from the instrument.
Script * | GetScriptOfSlot (size_t index)
| Get instrument script (gig format extension).
void | AddScriptSlot (Script *pScript, bool bypass=false)
| Add new instrument script slot (gig format extension).
void | SwapScriptSlots (size_t index1, size_t index2)
| Flip two script slots with each other (gig format extension).
void | RemoveScriptSlot (size_t index)
| Remove script slot.
void | RemoveScript (Script *pScript)
| Remove reference to given Script (gig format extension).
size_t | ScriptSlotCount () const
| Instrument's amount of script slots.
bool | IsScriptSlotBypassed (size_t index)
| Whether script execution shall be skipped.
void | SetScriptSlotBypassed (size_t index, bool bBypass)
| Defines whether execution shall be skipped.
bool | IsScriptPatchVariableSet (size_t slot, String variable)
| Checks whether a certain script 'patch' variable value is set.
std::map< String, String > | GetScriptPatchVariables (size_t slot)
| Get all overridden script 'patch' variables.
String | GetScriptPatchVariable (size_t slot, String variable)
| Get overridden initial value for 'patch' variable.
void | SetScriptPatchVariable (size_t slot, String variable, String value)
| Override initial value for 'patch' variable.
void | UnsetScriptPatchVariable (ssize_t slot=-1, String variable="")
| Drop overridden initial value(s) for 'patch' variable(s).
Resource * | GetParent ()
const Resource * | GetParent () const
size_t | CountRegions ()
| Returns the amount of regions of this instrument.

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

## Protected Types

typedef std::vector< Region * > | RegionList
typedef std::vector< Articulation * > | ArticulationList

## Protected Member Functions

| Instrument (File *pFile, RIFF::List *insList, progress_t *pProgress=NULL)
| ~Instrument ()
| Destructor.
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.
void | UpdateRegionKeyTable ()
void | LoadScripts ()
void | UpdateScriptFileOffsets ()
void | DeleteRegion (Region *pRegion)
virtual void | DeleteChunks ()
| Remove all RIFF chunks associated with this Instrument object.
virtual void | CopyAssign (const Instrument *orig)
| Make a (semi) deep copy of the Instrument object given by orig and assign it to this object.
virtual void | CopyAssign (const Resource *orig)
| Make a deep copy of the Resource object given by orig and assign it to this object.
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 ()
void | GenerateDLSID ()
| Generates a new DLSID for the resource.
Articulation * | GetArticulation (size_t pos)
| Returns Articulation at supplied pos position within the articulation list.
Articulation * | GetFirstArticulation ()
| Returns the first Articulation in the list of articulations.
Articulation * | GetNextArticulation ()
| Returns the next Articulation from the list of articulations.
void | LoadArticulations ()

## Static Protected Member Functions

static void | GenerateDLSID (dlsid_t *pDLSID)

## Protected Attributes

Region * | RegionKeyTable [128]
| fast lookup for the corresponding Region of a MIDI key
RIFF::List * | pCkInstrument
RegionList * | pRegions
RegionList::iterator | RegionsIterator
Resource * | pParent
RIFF::List * | pResourceList
RIFF::List * | pParentList
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 1266 of file gig.h.

## Member Typedef Documentation

## ArticulationList

typedef std::vector<Articulation*> DLS::Articulator::ArticulationList

protected inherited

Definition at line 353 of file DLS.h.

## RegionList

typedef std::vector<Region*> DLS::Instrument::RegionList

protected inherited

Definition at line 543 of file DLS.h.

## Constructor & Destructor Documentation

## Instrument()

gig::Instrument::Instrument | ( | File * | pFile,
|  | RIFF::List * | insList,
|  | progress_t * | pProgress = NULL )

protected

Definition at line 4923 of file gig.cpp.

## ~Instrument()

gig::Instrument::~Instrument | ( |  | ) |

protected virtual

Destructor.

Frees all memory occupied by this instrument.

Reimplemented from DLS::Instrument.

Definition at line 5088 of file gig.cpp.

References ~Instrument().

Referenced by ~Instrument().

## Member Function Documentation

## AddMidiRuleAlternator()

MidiRuleAlternator * gig::Instrument::AddMidiRuleAlternator | ( |  | ) |

Adds the alternator MIDI rule to the instrument.

Returns
  the new MIDI rule

Definition at line 5482 of file gig.cpp.

References AddMidiRuleAlternator().

Referenced by AddMidiRuleAlternator().

## AddMidiRuleCtrlTrigger()

MidiRuleCtrlTrigger * gig::Instrument::AddMidiRuleCtrlTrigger | ( |  | ) |

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

Returns
  the new MIDI rule

Definition at line 5456 of file gig.cpp.

References AddMidiRuleCtrlTrigger().

Referenced by AddMidiRuleCtrlTrigger().

## AddMidiRuleLegato()

MidiRuleLegato * gig::Instrument::AddMidiRuleLegato | ( |  | ) |

Adds the legato MIDI rule to the instrument.

Returns
  the new MIDI rule

Definition at line 5469 of file gig.cpp.

References AddMidiRuleLegato().

Referenced by AddMidiRuleLegato().

## AddRegion()

Region * gig::Instrument::AddRegion | ( |  | ) |

Definition at line 5350 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 5586 of file gig.cpp.

References AddScriptSlot().

Referenced by AddScriptSlot().

## CopyAssign() [1/5]

void DLS::Articulator::CopyAssign | ( | const Articulator * | orig | ) |

virtual inherited

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.

Definition at line 306 of file DLS.cpp.

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

## CopyAssign() [2/5]

void DLS::Instrument::CopyAssign | ( | const Instrument * | orig | ) |

virtual inherited

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

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

## CopyAssign() [3/5]

void Resource::CopyAssign | ( | const Resource * | orig | ) |

virtual inherited

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

References pInfo, and Resource().

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

## CopyAssign() [4/5]

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 5978 of file gig.cpp.

References CopyAssign().

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

## CopyAssign() [5/5]

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 5990 of file gig.cpp.

References Attenuation, CopyAssign(), gig::Region::CopyAssign(), DimensionKeyRange, FineTune, GetRegionAt(), PitchbendRange, and Regions.

## CopyAssignCore()

void DLS::Instrument::CopyAssignCore | ( | const Instrument * | orig | ) |

protected inherited

Definition at line 1613 of file DLS.cpp.

## CountRegions()

size_t DLS::Instrument::CountRegions | ( |  | ) |

Returns the amount of regions of this instrument.

See also
  GetRegionAt()

Definition at line 533 of file DLS.cpp.

## DeleteChunks()

void DLS::Instrument::DeleteChunks | ( |  | ) |

virtual inherited

Remove all RIFF chunks associated with this Instrument object.

See Storage::DeleteChunks() for details.

Reimplemented from DLS::Resource.

Definition at line 1592 of file DLS.cpp.

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

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 5495 of file gig.cpp.

References DeleteMidiRule().

Referenced by DeleteMidiRule().

## DeleteRegion() [1/2]

void DLS::Instrument::DeleteRegion | ( | Region * | pRegion | ) |

inherited

Definition at line 1517 of file DLS.cpp.

## DeleteRegion() [2/2]

void gig::Instrument::DeleteRegion | ( | Region * | pRegion | ) |

Definition at line 5366 of file gig.cpp.

## GenerateDLSID() [1/2]

void Resource::GenerateDLSID | ( |  | ) |

inherited

Generates a new DLSID for the resource.

Definition at line 604 of file DLS.cpp.

References GenerateDLSID(), and pDLSID.

Referenced by gig::File::AddInstrument(), GenerateDLSID(), gig::Script::GenerateUuid(), and DLS::File::UpdateChunks().

## GenerateDLSID() [2/2]

void Resource::GenerateDLSID | ( | dlsid_t * | pDLSID | ) |

static inherited

Definition at line 611 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.

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

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

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

Definition at line 5328 of file gig.cpp.

References GetFirstRegion().

Referenced by GetFirstRegion().

## 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 5447 of file gig.cpp.

References GetMidiRule().

Referenced by GetMidiRule().

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

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

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

Definition at line 5344 of file gig.cpp.

References GetNextRegion().

Referenced by GetNextRegion().

## GetParent() [1/2]

Resource * DLS::Resource::GetParent | ( |  | ) |

inline

Definition at line 409 of file DLS.h.

## GetParent() [2/2]

const Resource * DLS::Resource::GetParent | ( |  | ) | const

inline

Definition at line 410 of file DLS.h.

## GetRegion()

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

Returns the appropriate Region for a triggered note.

Parameters

  Key | MIDI 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 5292 of file gig.cpp.

References GetRegion(), and RegionKeyTable.

Referenced by GetRegion().

## GetRegionAt()

Region * gig::Instrument::GetRegionAt | ( | size_t | pos | ) |

Returns Region at supplied pos position within the region list of this instrument.

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

Parameters

  pos | - position of sought Region in region list

Returns
  pointer address to requested region or `NULL` if pos is out of bounds

See also
  CountRegions()

Definition at line 5313 of file gig.cpp.

References GetRegionAt().

Referenced by CopyAssign(), and GetRegionAt().

## GetScriptOfSlot()

Script * gig::Instrument::GetScriptOfSlot | ( | size_t | 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 5545 of file gig.cpp.

References GetScriptOfSlot().

Referenced by GetScriptOfSlot(), GetScriptPatchVariables(), IsScriptPatchVariableSet(), SetScriptPatchVariable(), and UnsetScriptPatchVariable().

## GetScriptPatchVariable()

String gig::Instrument::GetScriptPatchVariable | ( | size_t | slot,
|  | String | variable )

Get overridden initial value for 'patch' variable.

Returns current initial value for the requested script variable being overridden by this instrument.

Remarks
  Real-time instrument scripts allow to declare special 'patch' variables, which essentially behave like regular variables of their data type, however their initial value may optionally be overridden on a per instrument basis. That allows to share scripts between instruments while still being able to fine tune certain aspects of the script for each instrument individually.

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

  slot | - script slot index of the variable to be retrieved
  variable | - name of the 'patch' variable in that script

Definition at line 5814 of file gig.cpp.

References GetScriptPatchVariable(), and GetScriptPatchVariables().

Referenced by GetScriptPatchVariable().

## GetScriptPatchVariables()

std::map< String, String > gig::Instrument::GetScriptPatchVariables | ( | size_t | slot | ) |

Get all overridden script 'patch' variables.

Returns map of key-value pairs reflecting all patch variables currently being overridden by this instrument for the given script `slot`, where key is the variable name and value is the hereby currently overridden value for that variable.

Remarks
  Real-time instrument scripts allow to declare special 'patch' variables, which essentially behave like regular variables of their data type, however their initial value may optionally be overridden on a per instrument basis. That allows to share scripts between instruments while still being able to fine tune certain aspects of the script for each instrument individually.

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

  slot | - script slot index of the variable to be retrieved

Definition at line 5782 of file gig.cpp.

References gig::_UUIDFromCArray(), GetScriptOfSlot(), GetScriptPatchVariables(), and gig::Script::Uuid.

Referenced by GetScriptPatchVariable(), and GetScriptPatchVariables().

## IsScriptPatchVariableSet()

bool gig::Instrument::IsScriptPatchVariableSet | ( | size_t | slot,
|  | String | variable )

Checks whether a certain script 'patch' variable value is set.

Returns `true` if the initial value for the requested script variable is currently overridden by this instrument.

Remarks
  Real-time instrument scripts allow to declare special 'patch' variables, which essentially behave like regular variables of their data type, however their initial value may optionally be overridden on a per instrument basis. That allows to share scripts between instruments while still being able to fine tune certain aspects of the script for each instrument individually.

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

  slot | - script slot index of the variable to be retrieved
  variable | - name of the 'patch' variable in that script

Definition at line 5748 of file gig.cpp.

References gig::_UUIDFromCArray(), GetScriptOfSlot(), IsScriptPatchVariableSet(), and gig::Script::Uuid.

Referenced by IsScriptPatchVariableSet().

## IsScriptSlotBypassed()

bool gig::Instrument::IsScriptSlotBypassed | ( | size_t | 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 5682 of file gig.cpp.

References IsScriptSlotBypassed(), and ScriptSlotCount().

Referenced by IsScriptSlotBypassed().

## LoadArticulations()

void DLS::Articulator::LoadArticulations | ( |  | ) |

protected inherited

Definition at line 240 of file DLS.cpp.

## LoadRegions()

void DLS::Instrument::LoadRegions | ( |  | ) |

protected virtual inherited

Definition at line 1474 of file DLS.cpp.

## LoadScripts()

void gig::Instrument::LoadScripts | ( |  | ) |

protected

Definition at line 5500 of file gig.cpp.

## 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::Exception | if this instrument and target instrument are not part of the same file, as well as on unexpected internal error

Definition at line 5401 of file gig.cpp.

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

Referenced by MoveTo().

## 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 5639 of file gig.cpp.

References RemoveScript().

Referenced by RemoveScript().

## RemoveScriptSlot()

void gig::Instrument::RemoveScriptSlot | ( | size_t | index | ) |

Remove script slot.

Removes the script slot with the given slot index.

Parameters

  index | - index of script slot to remove

Definition at line 5621 of file gig.cpp.

References RemoveScriptSlot().

Referenced by RemoveScriptSlot().

## ScriptSlotCount()

size_t 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 5662 of file gig.cpp.

References ScriptSlotCount().

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

## SetScriptPatchVariable()

void gig::Instrument::SetScriptPatchVariable | ( | size_t | slot,
|  | String | variable,
|  | String | value )

Override initial value for 'patch' variable.

Overrides initial value for the requested script variable for this instrument with the passed value.

Remarks
  Real-time instrument scripts allow to declare special 'patch' variables, which essentially behave like regular variables of their data type, however their initial value may optionally be overridden on a per instrument basis. That allows to share scripts between instruments while still being able to fine tune certain aspects of the script for each instrument individually.

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

  slot | - script slot index of the variable to be set
  variable | - name of the 'patch' variable in that script
  value | - overridden initial value for that script variable

Exceptions

  gig::Exception | if given script `slot` index is invalid or given `variable` name is empty

Definition at line 5841 of file gig.cpp.

References gig::_UUIDFromCArray(), GetScriptOfSlot(), SetScriptPatchVariable(), and gig::Script::Uuid.

Referenced by SetScriptPatchVariable().

## SetScriptSlotBypassed()

void gig::Instrument::SetScriptSlotBypassed | ( | size_t | 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 5702 of file gig.cpp.

References ScriptSlotCount(), and SetScriptSlotBypassed().

Referenced by SetScriptSlotBypassed().

## SwapScriptSlots()

void gig::Instrument::SwapScriptSlots | ( | size_t | index1,
|  | size_t | 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 5606 of file gig.cpp.

References SwapScriptSlots().

Referenced by SwapScriptSlots().

## UnsetScriptPatchVariable()

void gig::Instrument::UnsetScriptPatchVariable | ( | ssize_t | slot = -1,
|  | String | variable = "" )

Drop overridden initial value(s) for 'patch' variable(s).

Reverts initial value(s) for requested script variable(s) back to their default initial value(s) defined in the script itself.

Both arguments of this method are optional. The most obvious use case of this method would be passing a valid script `slot` index and a (non-emtpy string as) `variable` name to this method, which would cause that single variable to be unset for that specific script slot (on this `Instrument` level).

Not passing a value (or `-1` for `slot` and/or empty string for `variable`) means 'wildcard'. So accordingly absence of argument(s) will cause all variables and/or for all script slots being unset. Hence this method serves 2^2 = 4 possible use cases in total and accordingly covers 4 different behaviours in one method.

Remarks
  Real-time instrument scripts allow to declare special 'patch' variables, which essentially behave like regular variables of their data type, however their initial value may optionally be overridden on a per instrument basis. That allows to share scripts between instruments while still being able to fine tune certain aspects of the script for each instrument individually.

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

  slot | - script slot index of the variable to be unset
  variable | - name of the 'patch' variable in that script

Definition at line 5882 of file gig.cpp.

References gig::_UUIDFromCArray(), GetScriptOfSlot(), UnsetScriptPatchVariable(), and gig::Script::Uuid.

Referenced by UnsetScriptPatchVariable().

## 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::Exception | if samples cannot be dereferenced

Reimplemented from DLS::Instrument.

Definition at line 5106 of file gig.cpp.

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

Referenced by UpdateChunks().

## UpdateRegionKeyTable()

void gig::Instrument::UpdateRegionKeyTable | ( |  | ) |

protected

Definition at line 5074 of file gig.cpp.

## UpdateScriptFileOffsets()

void gig::Instrument::UpdateScriptFileOffsets | ( |  | ) |

protected

Definition at line 5264 of file gig.cpp.

## Member Data Documentation

## ArticulationsIterator

ArticulationList::iterator DLS::Articulator::ArticulationsIterator

protected inherited

Definition at line 356 of file DLS.h.

## Attenuation

int32_t gig::Instrument::Attenuation

in dB

Definition at line 1279 of file gig.h.

Referenced by CopyAssign(), and UpdateChunks().

## DimensionKeyRange

range_t gig::Instrument::DimensionKeyRange

0-127 (where 0 means C1 and 127 means G9)

Definition at line 1284 of file gig.h.

Referenced by CopyAssign(), and UpdateChunks().

## EffectSend

uint16_t gig::Instrument::EffectSend

Definition at line 1280 of file gig.h.

## FineTune

int16_t gig::Instrument::FineTune

in cents

Definition at line 1281 of file gig.h.

Referenced by CopyAssign(), and UpdateChunks().

## IsDrum

bool DLS::Instrument::IsDrum

Indicates if the Instrument is a drum type, as they differ in the synthesis model of DLS from melodic instruments.

Definition at line 526 of file DLS.h.

## MIDIBank

uint16_t DLS::Instrument::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).

Definition at line 527 of file DLS.h.

## MIDIBankCoarse

uint8_t DLS::Instrument::MIDIBankCoarse

Reflects the MIDI Bank number for MIDI Control Change 0 (bank 1 - 128).

Definition at line 528 of file DLS.h.

## MIDIBankFine

uint8_t DLS::Instrument::MIDIBankFine

Reflects the MIDI Bank number for MIDI Control Change 32 (bank 1 - 128).

Definition at line 529 of file DLS.h.

## MIDIProgram

uint32_t DLS::Instrument::MIDIProgram

Specifies the MIDI Program Change Number this Instrument should be assigned to.

Definition at line 530 of file DLS.h.

## pArticulations

ArticulationList* DLS::Articulator::pArticulations

protected inherited

Definition at line 355 of file DLS.h.

## pCkInstrument

RIFF::List* DLS::Instrument::pCkInstrument

protected inherited

Definition at line 549 of file DLS.h.

## pDLSID

dlsid_t* DLS::Resource::pDLSID

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

Definition at line 407 of file DLS.h.

## PianoReleaseMode

bool gig::Instrument::PianoReleaseMode

Definition at line 1283 of file gig.h.

## pInfo

Info* DLS::Resource::pInfo

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

Definition at line 406 of file DLS.h.

Referenced by gig::File::AddInstrument().

## PitchbendRange

uint16_t gig::Instrument::PitchbendRange

Number of semitones pitchbend controller can pitch (default is 2).

Definition at line 1282 of file gig.h.

Referenced by CopyAssign(), and UpdateChunks().

## pParent

Resource* DLS::Resource::pParent

protected inherited

Definition at line 417 of file DLS.h.

## pParentList

RIFF::List* DLS::Articulator::pParentList

protected inherited

Definition at line 354 of file DLS.h.

## pRegions

RegionList* DLS::Instrument::pRegions

protected inherited

Definition at line 550 of file DLS.h.

## pResourceList

RIFF::List* DLS::Resource::pResourceList

protected inherited

Definition at line 418 of file DLS.h.

## RegionKeyTable

Region* gig::Instrument::RegionKeyTable[128]

protected

fast lookup for the corresponding Region of a MIDI key

Definition at line 1321 of file gig.h.

Referenced by GetRegion().

## Regions

uint32_t DLS::Instrument::Regions

Reflects the number of Region defintions this Instrument has.

Definition at line 531 of file DLS.h.

Referenced by CopyAssign().

## RegionsIterator

RegionList::iterator DLS::Instrument::RegionsIterator

protected inherited

Definition at line 551 of file DLS.h.

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

- gig.h
- gig.cpp