/[svn]/libgig/trunk/src/gig.h
ViewVC logotype

Diff of /libgig/trunk/src/gig.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2682 by schoenebeck, Mon Dec 29 16:25:51 2014 UTC revision 2699 by schoenebeck, Mon Jan 12 17:12:05 2015 UTC
# Line 2  Line 2 
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  *
# Line 65  Line 65 
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;
# Line 321  namespace gig { Line 321  namespace gig {
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:
# Line 573  namespace gig { Line 603  namespace gig {
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
# Line 587  namespace gig { Line 623  namespace gig {
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:
# Line 678  namespace gig { Line 718  namespace gig {
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:
# Line 728  namespace gig { Line 772  namespace gig {
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() { }
# Line 737  namespace gig { Line 822  namespace gig {
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.
# Line 759  namespace gig { Line 856  namespace gig {
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)
# Line 780  namespace gig { Line 896  namespace gig {
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
# Line 821  namespace gig { Line 948  namespace gig {
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() { }
# Line 838  namespace gig { Line 977  namespace gig {
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:
# Line 907  namespace gig { Line 1047  namespace gig {
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
# Line 979  namespace gig { Line 1133  namespace gig {
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.
# Line 1012  namespace gig { Line 1162  namespace gig {
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;

Legend:
Removed from v.2682  
changed lines
  Added in v.2699

  ViewVC Help
Powered by ViewVC