2 |
* * |
* * |
3 |
* libgig - C++ cross-platform Gigasampler format file access library * |
* libgig - C++ cross-platform Gigasampler format file access library * |
4 |
* * |
* * |
5 |
* Copyright (C) 2003-2014 by Christian Schoenebeck * |
* Copyright (C) 2003-2015 by Christian Schoenebeck * |
6 |
* <cuse@users.sourceforge.net> * |
* <cuse@users.sourceforge.net> * |
7 |
* * |
* * |
8 |
* This library is free software; you can redistribute it and/or modify * |
* This library is free software; you can redistribute it and/or modify * |
65 |
# define CHUNK_ID_SCSL 0x4c534353 // own gig format extension |
# define CHUNK_ID_SCSL 0x4c534353 // own gig format extension |
66 |
#endif // WORDS_BIGENDIAN |
#endif // WORDS_BIGENDIAN |
67 |
|
|
68 |
/** Gigasampler specific classes and definitions */ |
/** Gigasampler/GigaStudio specific classes and definitions */ |
69 |
namespace gig { |
namespace gig { |
70 |
|
|
71 |
typedef std::string String; |
typedef std::string String; |
321 |
class Script; |
class Script; |
322 |
class ScriptGroup; |
class ScriptGroup; |
323 |
|
|
324 |
/** @brief Encapsulates articulation information of a dimension region. |
/** @brief Encapsulates articulation informations of a dimension region. |
325 |
* |
* |
326 |
* Every Gigasampler Instrument has at least one dimension region |
* This is the most important data object of the Gigasampler / GigaStudio |
327 |
* (exactly then when it has no dimension defined). |
* format. A DimensionRegion provides the link to the sample to be played |
328 |
|
* and all required articulation informations to be interpreted for playing |
329 |
|
* back the sample and processing it appropriately by the sampler software. |
330 |
|
* Every Region of a Gigasampler Instrument has at least one dimension |
331 |
|
* region (exactly then when the Region has no dimension defined). Many |
332 |
|
* Regions though provide more than one DimensionRegion, which reflect |
333 |
|
* different playing "cases". For example a different sample might be played |
334 |
|
* if a certain pedal is pressed down, or if the note was triggered with |
335 |
|
* different velocity. |
336 |
* |
* |
337 |
* Gigasampler provides three Envelope Generators and Low Frequency |
* One instance of a DimensionRegion reflects exactly one particular case |
338 |
* Oscillators: |
* while playing an instrument (for instance "note between C3 and E3 was |
339 |
|
* triggered AND note on velocity was between 20 and 42 AND modulation wheel |
340 |
|
* controller is between 80 and 127). The DimensionRegion defines what to do |
341 |
|
* under that one particular case, that is which sample to play back and how |
342 |
|
* to play that sample back exactly and how to process it. So a |
343 |
|
* DimensionRegion object is always linked to exactly one sample. It may |
344 |
|
* however also link to no sample at all, for defining a "silence" case |
345 |
|
* where nothing shall be played (for example when note on velocity was |
346 |
|
* below 6). |
347 |
|
* |
348 |
|
* Note that a DimensionRegion object only defines "what to do", but it does |
349 |
|
* not define "when to do it". To actually resolve which DimensionRegion to |
350 |
|
* pick under which situation, you need to refer to the DimensionRegions' |
351 |
|
* parent Region object. The Region object contains the necessary |
352 |
|
* "Dimension" definitions, which in turn define which DimensionRegion is |
353 |
|
* associated with which playing case exactly. |
354 |
|
* |
355 |
|
* The Gigasampler/GigaStudio format defines 3 Envelope Generators and 3 |
356 |
|
* Low Frequency Oscillators: |
357 |
* |
* |
358 |
* - EG1 and LFO1, both controlling sample amplitude |
* - EG1 and LFO1, both controlling sample amplitude |
359 |
* - EG2 and LFO2, both controlling filter cutoff frequency |
* - EG2 and LFO2, both controlling filter cutoff frequency |
360 |
* - EG3 and LFO3, both controlling sample pitch |
* - EG3 and LFO3, both controlling sample pitch |
361 |
|
* |
362 |
|
* Since the gig format was designed as extension to the DLS file format, |
363 |
|
* this class is derived from the DLS::Sampler class. So also refer to |
364 |
|
* DLS::Sampler for additional informations, class attributes and methods. |
365 |
*/ |
*/ |
366 |
class DimensionRegion : protected DLS::Sampler { |
class DimensionRegion : protected DLS::Sampler { |
367 |
public: |
public: |
603 |
double* CreateVelocityTable(curve_type_t curveType, uint8_t depth, uint8_t scaling); |
double* CreateVelocityTable(curve_type_t curveType, uint8_t depth, uint8_t scaling); |
604 |
}; |
}; |
605 |
|
|
606 |
/** @brief Encapsulates sample waves used for playback. |
/** @brief Encapsulates sample waves of Gigasampler/GigaStudio files used for playback. |
607 |
|
* |
608 |
|
* This class provides access to the actual audio sample data of a |
609 |
|
* Gigasampler/GigaStudio file. Along to the actual sample data, it also |
610 |
|
* provides access to the sample's meta informations like bit depth, |
611 |
|
* sample rate, encoding type, but also loop informations. The latter may be |
612 |
|
* used by instruments for resembling sounds with arbitary note lengths. |
613 |
* |
* |
614 |
* In case you created a new sample with File::AddSample(), you should |
* In case you created a new sample with File::AddSample(), you should |
615 |
* first update all attributes with the desired meta informations |
* first update all attributes with the desired meta informations |
623 |
* retrieved from the respective DimensionRegon instead from the Sample |
* retrieved from the respective DimensionRegon instead from the Sample |
624 |
* itself. This was made for allowing different loop definitions for the |
* itself. This was made for allowing different loop definitions for the |
625 |
* same sample under different conditions. |
* same sample under different conditions. |
626 |
|
* |
627 |
|
* Since the gig format was designed as extension to the DLS file format, |
628 |
|
* this class is derived from the DLS::Sample class. So also refer to |
629 |
|
* DLS::Sample for additional informations, class attributes and methods. |
630 |
*/ |
*/ |
631 |
class Sample : public DLS::Sample { |
class Sample : public DLS::Sample { |
632 |
public: |
public: |
718 |
}; |
}; |
719 |
|
|
720 |
// TODO: <3dnl> list not used yet - not important though (just contains optional descriptions for the dimensions) |
// TODO: <3dnl> list not used yet - not important though (just contains optional descriptions for the dimensions) |
721 |
/** @brief Defines Region information of an Instrument. |
/** @brief Defines Region information of a Gigasampler/GigaStudio instrument. |
722 |
* |
* |
723 |
* A Region reflects a consecutive area on the keyboard. The individual |
* A Region reflects a consecutive area (key range) on the keyboard. The |
724 |
* regions in the gig format may not overlap with other regions (of the same |
* individual regions in the gig format may not overlap with other regions |
725 |
* instrument). Further, in the gig format a Region is merely a container |
* (of the same instrument that is). Further, in the gig format a Region is |
726 |
* for DimensionRegions (a.k.a. "Cases"). The Region itself does not provide |
* merely a container for DimensionRegions (a.k.a. "Cases"). The Region |
727 |
* the sample mapping or articulation informations used, even though the |
* itself does not provide the sample mapping or articulation informations |
728 |
* data structures indeed provide such informations. The latter is however |
* used, even though the data structures of regions indeed provide such |
729 |
* just of historical nature, because the gig format was derived from the |
* informations. The latter is however just of historical nature, because |
730 |
* DLS format. |
* the gig file format was derived from the DLS file format. |
731 |
* |
* |
732 |
* Each Region consists of at least one or more DimensionRegions. The actual |
* Each Region consists of at least one or more DimensionRegions. The actual |
733 |
* amount of DimensionRegions depends on which kind of "dimensions" are |
* amount of DimensionRegions depends on which kind of "dimensions" are |
734 |
* defined for this region, and on the split / zone amount for each of those |
* defined for this region, and on the split / zone amount for each of those |
735 |
* dimensions. |
* dimensions. |
736 |
|
* |
737 |
|
* Since the gig format was designed as extension to the DLS file format, |
738 |
|
* this class is derived from the DLS::Region class. So also refer to |
739 |
|
* DLS::Region for additional informations, class attributes and methods. |
740 |
*/ |
*/ |
741 |
class Region : public DLS::Region { |
class Region : public DLS::Region { |
742 |
public: |
public: |
772 |
friend class Instrument; |
friend class Instrument; |
773 |
}; |
}; |
774 |
|
|
775 |
/** Abstract base class for all MIDI rules. */ |
/** @brief Abstract base class for all MIDI rules. |
776 |
|
* |
777 |
|
* Note: Instead of using MIDI rules, we recommend you using real-time |
778 |
|
* instrument scripts instead. Read about the reasons below. |
779 |
|
* |
780 |
|
* MIDI Rules (also called "iMIDI rules" or "intelligent MIDI rules") were |
781 |
|
* introduced with GigaStudio 4 as an attempt to increase the power of |
782 |
|
* potential user controls over sounds. At that point other samplers already |
783 |
|
* supported certain powerful user control features, which were not possible |
784 |
|
* with GigaStudio yet. For example triggering new notes by MIDI CC |
785 |
|
* controller. |
786 |
|
* |
787 |
|
* Such extended features however were usually implemented by other samplers |
788 |
|
* by requiring the sound designer to write an instrument script which the |
789 |
|
* designer would then bundle with the respective instrument file. Such |
790 |
|
* scripts are essentially text files, using a very specific programming |
791 |
|
* language for the purpose of controlling the sampler in real-time. Since |
792 |
|
* however musicians are not typically keen to writing such cumbersome |
793 |
|
* script files, the GigaStudio designers decided to implement such extended |
794 |
|
* features completely without instrument scripts. Instead they created a |
795 |
|
* set of rules, which could be defined and altered conveniently by mouse |
796 |
|
* clicks in GSt's instrument editor application. The downside of this |
797 |
|
* overall approach however, was that those MIDI rules were very limited in |
798 |
|
* practice. As sound designer you easily came across the possiblities such |
799 |
|
* MIDI rules were able to offer. |
800 |
|
* |
801 |
|
* Due to such severe use case constraints, support for MIDI rules is quite |
802 |
|
* limited in libgig. At the moment only the "Control Trigger", "Alternator" |
803 |
|
* and the "Legato" MIDI rules are supported by libgig. Consequently the |
804 |
|
* graphical instrument editor application gigedit just supports the |
805 |
|
* "Control Trigger" and "Legato" MIDI rules, and LinuxSampler even does not |
806 |
|
* support any MIDI rule type at all and LinuxSampler probably will not |
807 |
|
* support MIDI rules in future either. |
808 |
|
* |
809 |
|
* Instead of using MIDI rules, we introduced real-time instrument scripts |
810 |
|
* as extension to the original GigaStudio file format. This script based |
811 |
|
* solution is much more powerful than MIDI rules and is already supported |
812 |
|
* by libgig, gigedit and LinuxSampler. |
813 |
|
* |
814 |
|
* @deprecated Just provided for backward compatiblity, use Script for new |
815 |
|
* instruments instead. |
816 |
|
*/ |
817 |
class MidiRule { |
class MidiRule { |
818 |
public: |
public: |
819 |
virtual ~MidiRule() { } |
virtual ~MidiRule() { } |
822 |
friend class Instrument; |
friend class Instrument; |
823 |
}; |
}; |
824 |
|
|
825 |
/** MIDI rule for triggering notes by control change events. */ |
/** @brief MIDI rule for triggering notes by control change events. |
826 |
|
* |
827 |
|
* A "Control Trigger MIDI rule" allows to trigger new notes by sending MIDI |
828 |
|
* control change events to the sampler. |
829 |
|
* |
830 |
|
* Note: "Control Trigger" MIDI rules are only supported by gigedit, but not |
831 |
|
* by LinuxSampler. We recommend you using real-time instrument scripts |
832 |
|
* instead. Read more about the details and reasons for this in the |
833 |
|
* description of the MidiRule base class. |
834 |
|
* |
835 |
|
* @deprecated Just provided for backward compatiblity, use Script for new |
836 |
|
* instruments instead. See description of MidiRule for details. |
837 |
|
*/ |
838 |
class MidiRuleCtrlTrigger : public MidiRule { |
class MidiRuleCtrlTrigger : public MidiRule { |
839 |
public: |
public: |
840 |
uint8_t ControllerNumber; ///< MIDI controller number. |
uint8_t ControllerNumber; ///< MIDI controller number. |
856 |
friend class Instrument; |
friend class Instrument; |
857 |
}; |
}; |
858 |
|
|
859 |
/** MIDI rule for instruments with legato samples. */ |
/** @brief MIDI rule for instruments with legato samples. |
860 |
|
* |
861 |
|
* A "Legato MIDI rule" allows playing instruments resembling the legato |
862 |
|
* playing technique. In the past such legato articulations were tried to be |
863 |
|
* simulated by pitching the samples of the instrument. However since |
864 |
|
* usually a high amount of pitch is needed for legatos, this always sounded |
865 |
|
* very artificial and unrealistic. The "Legato MIDI rule" thus uses another |
866 |
|
* approach. Instead of pitching the samples, it allows the sound designer |
867 |
|
* to bundle separate, additional samples for the individual legato |
868 |
|
* situations and the legato rules defined which samples to be played in |
869 |
|
* which situation. |
870 |
|
* |
871 |
|
* Note: "Legato MIDI rules" are only supported by gigedit, but not |
872 |
|
* by LinuxSampler. We recommend you using real-time instrument scripts |
873 |
|
* instead. Read more about the details and reasons for this in the |
874 |
|
* description of the MidiRule base class. |
875 |
|
* |
876 |
|
* @deprecated Just provided for backward compatiblity, use Script for new |
877 |
|
* instruments instead. See description of MidiRule for details. |
878 |
|
*/ |
879 |
class MidiRuleLegato : public MidiRule { |
class MidiRuleLegato : public MidiRule { |
880 |
public: |
public: |
881 |
uint8_t LegatoSamples; ///< Number of legato samples per key in each direction (always 12) |
uint8_t LegatoSamples; ///< Number of legato samples per key in each direction (always 12) |
896 |
friend class Instrument; |
friend class Instrument; |
897 |
}; |
}; |
898 |
|
|
899 |
/** MIDI rule to automatically cycle through specified sequences of different articulations. The instrument must be using the smartmidi dimension. */ |
/** @brief MIDI rule to automatically cycle through specified sequences of different articulations. |
900 |
|
* |
901 |
|
* The instrument must be using the smartmidi dimension. |
902 |
|
* |
903 |
|
* Note: "Alternator" MIDI rules are neither supported by gigedit nor by |
904 |
|
* LinuxSampler. We recommend you using real-time instrument scripts |
905 |
|
* instead. Read more about the details and reasons for this in the |
906 |
|
* description of the MidiRule base class. |
907 |
|
* |
908 |
|
* @deprecated Just provided for backward compatiblity, use Script for new |
909 |
|
* instruments instead. See description of MidiRule for details. |
910 |
|
*/ |
911 |
class MidiRuleAlternator : public MidiRule { |
class MidiRuleAlternator : public MidiRule { |
912 |
public: |
public: |
913 |
uint8_t Articulations; ///< Number of articulations in the instrument |
uint8_t Articulations; ///< Number of articulations in the instrument |
948 |
friend class Instrument; |
friend class Instrument; |
949 |
}; |
}; |
950 |
|
|
951 |
/** A MIDI rule not yet implemented by libgig. */ |
/** @brief A MIDI rule not yet implemented by libgig. |
952 |
|
* |
953 |
|
* This class is currently used as a place holder by libgig for MIDI rule |
954 |
|
* types which are not supported by libgig yet. |
955 |
|
* |
956 |
|
* Note: Support for missing MIDI rule types are probably never added to |
957 |
|
* libgig. We recommend you using real-time instrument scripts instead. |
958 |
|
* Read more about the details and reasons for this in the description of |
959 |
|
* the MidiRule base class. |
960 |
|
* |
961 |
|
* @deprecated Just provided for backward compatiblity, use Script for new |
962 |
|
* instruments instead. See description of MidiRule for details. |
963 |
|
*/ |
964 |
class MidiRuleUnknown : public MidiRule { |
class MidiRuleUnknown : public MidiRule { |
965 |
protected: |
protected: |
966 |
MidiRuleUnknown() { } |
MidiRuleUnknown() { } |
977 |
* |
* |
978 |
* This is an extension of the GigaStudio format, thus a feature which was |
* This is an extension of the GigaStudio format, thus a feature which was |
979 |
* not available in the GigaStudio 4 software. It is currently only |
* not available in the GigaStudio 4 software. It is currently only |
980 |
* supported by LinuxSampler and gigedit. |
* supported by LinuxSampler and gigedit. Scripts will not load with the |
981 |
|
* original GigaStudio software. |
982 |
*/ |
*/ |
983 |
class Script { |
class Script { |
984 |
public: |
public: |
1047 |
std::list<Script*>* pScripts; |
std::list<Script*>* pScripts; |
1048 |
}; |
}; |
1049 |
|
|
1050 |
/** Provides all neccessary information for the synthesis of an <i>Instrument</i>. */ |
/** @brief Provides access to a Gigasampler/GigaStudio instrument. |
1051 |
|
* |
1052 |
|
* This class provides access to Gigasampler/GigaStudio instruments |
1053 |
|
* contained in .gig files. A gig instrument is merely a set of keyboard |
1054 |
|
* ranges (called Region), plus some additional global informations about |
1055 |
|
* the instrument. The major part of the actual instrument definition used |
1056 |
|
* for the synthesis of the instrument is contained in the respective Region |
1057 |
|
* object (or actually in the respective DimensionRegion object being, see |
1058 |
|
* description of Region for details). |
1059 |
|
* |
1060 |
|
* Since the gig format was designed as extension to the DLS file format, |
1061 |
|
* this class is derived from the DLS::Instrument class. So also refer to |
1062 |
|
* DLS::Instrument for additional informations, class attributes and |
1063 |
|
* methods. |
1064 |
|
*/ |
1065 |
class Instrument : protected DLS::Instrument { |
class Instrument : protected DLS::Instrument { |
1066 |
public: |
public: |
1067 |
// derived attributes from DLS::Resource |
// derived attributes from DLS::Resource |
1133 |
std::vector<_ScriptPooolRef>* pScriptRefs; |
std::vector<_ScriptPooolRef>* pScriptRefs; |
1134 |
}; |
}; |
1135 |
|
|
1136 |
/** @brief Group of Gigasampler objects |
/** @brief Group of Gigasampler samples |
1137 |
* |
* |
1138 |
* Groups help to organize a huge collection of Gigasampler objects. |
* Groups help to organize a huge collection of Gigasampler samples. |
1139 |
* Groups are not concerned at all for the synthesis, but they help |
* Groups are not concerned at all for the synthesis, but they help |
1140 |
* sound library developers when working on complex instruments with an |
* sound library developers when working on complex instruments with an |
1141 |
* instrument editor (as long as that instrument editor supports it ;-). |
* instrument editor (as long as that instrument editor supports it ;-). |
1142 |
* |
* |
|
* At the moment, it seems as only samples can be grouped together in |
|
|
* the Gigasampler format yet. If this is false in the meantime, please |
|
|
* tell us ! |
|
|
* |
|
1143 |
* A sample is always assigned to exactly one Group. This also means |
* A sample is always assigned to exactly one Group. This also means |
1144 |
* there is always at least one Group in a .gig file, no matter if you |
* there is always at least one Group in a .gig file, no matter if you |
1145 |
* created one yet or not. |
* created one yet or not. |
1162 |
RIFF::Chunk* pNameChunk; ///< '3gnm' chunk |
RIFF::Chunk* pNameChunk; ///< '3gnm' chunk |
1163 |
}; |
}; |
1164 |
|
|
1165 |
/** Parses Gigasampler files and provides abstract access to the data. */ |
/** @brief Provides convenient access to Gigasampler/GigaStudio .gig files. |
1166 |
|
* |
1167 |
|
* This is the entry class for accesing a Gigasampler/GigaStudio (.gig) file |
1168 |
|
* with libgig. It allows you to open existing .gig files, modifying them |
1169 |
|
* and saving them persistently either under the same file name or under a |
1170 |
|
* different location. |
1171 |
|
* |
1172 |
|
* A .gig file is merely a monolithic file. That means samples and the |
1173 |
|
* defintion of the virtual instruments are contained in the same file. A |
1174 |
|
* .gig file contains an arbitrary amount of samples, and an arbitrary |
1175 |
|
* amount of instruments which are referencing those samples. It is also |
1176 |
|
* possible to store samples in .gig files not being referenced by any |
1177 |
|
* instrument. This is not an error from the file format's point of view and |
1178 |
|
* it is actually often used in practice during the design phase of new gig |
1179 |
|
* instruments. |
1180 |
|
* |
1181 |
|
* So on toplevel of the gig file format you have: |
1182 |
|
* |
1183 |
|
* - A set of samples (see Sample). |
1184 |
|
* - A set of virtual instruments (see Instrument). |
1185 |
|
* |
1186 |
|
* And as extension to the original GigaStudio format, we added: |
1187 |
|
* |
1188 |
|
* - Real-time instrument scripts (see Script). |
1189 |
|
* |
1190 |
|
* Note that the latter however is only supported by libgig, gigedit and |
1191 |
|
* LinuxSampler. Scripts are not supported by the original GigaStudio |
1192 |
|
* software. |
1193 |
|
* |
1194 |
|
* All released Gigasampler/GigaStudio file format versions are supported |
1195 |
|
* (so from first Gigasampler version up to including GigaStudio 4). |
1196 |
|
* |
1197 |
|
* Since the gig format was designed as extension to the DLS file format, |
1198 |
|
* this class is derived from the DLS::File class. So also refer to |
1199 |
|
* DLS::File for additional informations, class attributes and methods. |
1200 |
|
*/ |
1201 |
class File : protected DLS::File { |
class File : protected DLS::File { |
1202 |
public: |
public: |
1203 |
static const DLS::version_t VERSION_2; |
static const DLS::version_t VERSION_2; |