gig.h

/***************************************************************************
 *                                                                         *
 *   libgig - C++ cross-platform Gigasampler format file access library    *
 *                                                                         *
 *   Copyright (C) 2003-2021 by Christian Schoenebeck                      *
 *                              <cuse@users.sourceforge.net>               *
 *                                                                         *
 *   This library is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 *   This library is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU General Public License for more details.                          *
 *                                                                         *
 *   You should have received a copy of the GNU General Public License     *
 *   along with this library; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef __GIG_H__
#define __GIG_H__

#include "DLS.h"
#include <vector>
#include <array> // since C++11

#ifndef __has_feature
# define __has_feature(x) 0
#endif
#ifndef HAVE_RTTI
# if __GXX_RTTI || __has_feature(cxx_rtti) || _CPPRTTI
#  define HAVE_RTTI 1
# else
#  define HAVE_RTTI 0
# endif
#endif
#if HAVE_RTTI
# include <typeinfo>
#else
# warning No RTTI available!
#endif

#if WORDS_BIGENDIAN
# define LIST_TYPE_3PRG 0x33707267
# define LIST_TYPE_3EWL 0x3365776C
# define LIST_TYPE_3GRI 0x33677269
# define LIST_TYPE_3GNL 0x33676E6C
# define LIST_TYPE_3LS  0x334c5320 // own gig format extension
# define LIST_TYPE_RTIS 0x52544953 // own gig format extension
# define LIST_TYPE_3DNM 0x33646e6d
# define CHUNK_ID_3GIX  0x33676978
# define CHUNK_ID_3EWA  0x33657761
# define CHUNK_ID_3LNK  0x336C6E6B
# define CHUNK_ID_3EWG  0x33657767
# define CHUNK_ID_EWAV  0x65776176
# define CHUNK_ID_3GNM  0x33676E6D
# define CHUNK_ID_EINF  0x65696E66
# define CHUNK_ID_3CRC  0x33637263
# define CHUNK_ID_SCRI  0x53637269 // own gig format extension
# define CHUNK_ID_LSNM  0x4c534e4d // own gig format extension
# define CHUNK_ID_SCSL  0x5343534c // own gig format extension
# define CHUNK_ID_SCPV  0x53435056 // own gig format extension
# define CHUNK_ID_LSDE  0x4c534445 // own gig format extension
# define CHUNK_ID_3DDP  0x33646470
#else  // little endian
# define LIST_TYPE_3PRG 0x67727033
# define LIST_TYPE_3EWL 0x6C776533
# define LIST_TYPE_3GRI 0x69726733
# define LIST_TYPE_3GNL 0x6C6E6733
# define LIST_TYPE_3LS  0x20534c33 // own gig format extension
# define LIST_TYPE_RTIS 0x53495452 // own gig format extension
# define LIST_TYPE_3DNM 0x6d6e6433
# define CHUNK_ID_3GIX  0x78696733
# define CHUNK_ID_3EWA  0x61776533
# define CHUNK_ID_3LNK  0x6B6E6C33
# define CHUNK_ID_3EWG  0x67776533
# define CHUNK_ID_EWAV  0x76617765
# define CHUNK_ID_3GNM  0x6D6E6733
# define CHUNK_ID_EINF  0x666E6965
# define CHUNK_ID_3CRC  0x63726333
# define CHUNK_ID_SCRI  0x69726353 // own gig format extension
# define CHUNK_ID_LSNM  0x4d4e534c // own gig format extension
# define CHUNK_ID_SCSL  0x4c534353 // own gig format extension
# define CHUNK_ID_SCPV  0x56504353 // own gig format extension
# define CHUNK_ID_LSDE  0x4544534c // own gig format extension
# define CHUNK_ID_3DDP  0x70646433
#endif // WORDS_BIGENDIAN

#ifndef GIG_DECLARE_ENUM
# define GIG_DECLARE_ENUM(type, ...) enum type { __VA_ARGS__ }
#endif

// just symbol prototyping (since Serialization.h not included by default here)
namespace Serialization { class Archive; }

namespace gig {

    typedef std::string String;
    typedef RIFF::progress_t progress_t;
    typedef RIFF::file_offset_t file_offset_t;

    struct range_t {
        uint8_t low;  
        uint8_t high; 
    };

    struct buffer_t {
        void*         pStart;            
        file_offset_t Size;              
        file_offset_t NullExtensionSize; 
        buffer_t() {
            pStart            = NULL;
            Size              = 0;
            NullExtensionSize = 0;
        }
    };

    GIG_DECLARE_ENUM(loop_type_t,
        loop_type_normal        = 0x00000000,  
        loop_type_bidirectional = 0x00000001,  
        loop_type_backward      = 0x00000002   
    );

    GIG_DECLARE_ENUM(smpte_format_t,
        smpte_format_no_offset          = 0x00000000,  
        smpte_format_24_frames          = 0x00000018,  
        smpte_format_25_frames          = 0x00000019,  
        smpte_format_30_frames_dropping = 0x0000001D,  
        smpte_format_30_frames          = 0x0000001E   
    );

    GIG_DECLARE_ENUM(curve_type_t,
        curve_type_nonlinear = 0,          
        curve_type_linear    = 1,          
        curve_type_special   = 2,          
        curve_type_unknown   = 0xffffffff  
    );

    GIG_DECLARE_ENUM(lfo_wave_t,
        lfo_wave_sine     = 0,  
        lfo_wave_triangle = 1,  
        lfo_wave_saw      = 2,  
        lfo_wave_square   = 3,  
    );

    GIG_DECLARE_ENUM(dim_bypass_ctrl_t,
        dim_bypass_ctrl_none, 
        dim_bypass_ctrl_94,   
        dim_bypass_ctrl_95    
    );

    GIG_DECLARE_ENUM(lfo3_ctrl_t,
        lfo3_ctrl_internal            = 0x00, 
        lfo3_ctrl_modwheel            = 0x01, 
        lfo3_ctrl_aftertouch          = 0x02, 
        lfo3_ctrl_internal_modwheel   = 0x03, 
        lfo3_ctrl_internal_aftertouch = 0x04  
    );

    GIG_DECLARE_ENUM(lfo2_ctrl_t,
        lfo2_ctrl_internal            = 0x00, 
        lfo2_ctrl_modwheel            = 0x01, 
        lfo2_ctrl_foot                = 0x02, 
        lfo2_ctrl_internal_modwheel   = 0x03, 
        lfo2_ctrl_internal_foot       = 0x04  
    );

    GIG_DECLARE_ENUM(lfo1_ctrl_t,
        lfo1_ctrl_internal            = 0x00, 
        lfo1_ctrl_modwheel            = 0x01, 
        lfo1_ctrl_breath              = 0x02, 
        lfo1_ctrl_internal_modwheel   = 0x03, 
        lfo1_ctrl_internal_breath     = 0x04  
    );

    GIG_DECLARE_ENUM(vcf_cutoff_ctrl_t,
        vcf_cutoff_ctrl_none         = 0x00,  
        vcf_cutoff_ctrl_none2        = 0x01,  
        vcf_cutoff_ctrl_modwheel     = 0x81,  
        vcf_cutoff_ctrl_effect1      = 0x8c,  
        vcf_cutoff_ctrl_effect2      = 0x8d,  
        vcf_cutoff_ctrl_breath       = 0x82,  
        vcf_cutoff_ctrl_foot         = 0x84,  
        vcf_cutoff_ctrl_sustainpedal = 0xc0,  
        vcf_cutoff_ctrl_softpedal    = 0xc3,  
        vcf_cutoff_ctrl_genpurpose7  = 0xd2,  
        vcf_cutoff_ctrl_genpurpose8  = 0xd3,  
        vcf_cutoff_ctrl_aftertouch   = 0x80   
    );

    GIG_DECLARE_ENUM(vcf_res_ctrl_t,
        vcf_res_ctrl_none        = 0xffffffff,  
        vcf_res_ctrl_genpurpose3 = 0,           
        vcf_res_ctrl_genpurpose4 = 1,           
        vcf_res_ctrl_genpurpose5 = 2,           
        vcf_res_ctrl_genpurpose6 = 3            
    );

    struct leverage_ctrl_t {
        GIG_DECLARE_ENUM(type_t,
            type_none              = 0x00, 
            type_channelaftertouch = 0x2f, 
            type_velocity          = 0xff, 
            type_controlchange     = 0xfe  
        );

        type_t type;              
        uint   controller_number; 

        void serialize(Serialization::Archive* archive);
    };

    typedef leverage_ctrl_t attenuation_ctrl_t;

    typedef leverage_ctrl_t eg1_ctrl_t;

    typedef leverage_ctrl_t eg2_ctrl_t;

    GIG_DECLARE_ENUM(dimension_t,
        dimension_none              = 0x00, 
        dimension_samplechannel     = 0x80, 
        dimension_layer             = 0x81, 
        dimension_velocity          = 0x82, 
        dimension_channelaftertouch = 0x83, 
        dimension_releasetrigger    = 0x84, 
        dimension_keyboard          = 0x85, 
        dimension_roundrobin        = 0x86, 
        dimension_random            = 0x87, 
        dimension_smartmidi         = 0x88, 
        dimension_roundrobinkeyboard = 0x89, 
        dimension_modwheel          = 0x01, 
        dimension_breath            = 0x02, 
        dimension_foot              = 0x04, 
        dimension_portamentotime    = 0x05, 
        dimension_effect1           = 0x0c, 
        dimension_effect2           = 0x0d, 
        dimension_genpurpose1       = 0x10, 
        dimension_genpurpose2       = 0x11, 
        dimension_genpurpose3       = 0x12, 
        dimension_genpurpose4       = 0x13, 
        dimension_sustainpedal      = 0x40, 
        dimension_portamento        = 0x41, 
        dimension_sostenutopedal    = 0x42, 
        dimension_softpedal         = 0x43, 
        dimension_genpurpose5       = 0x30, 
        dimension_genpurpose6       = 0x31, 
        dimension_genpurpose7       = 0x32, 
        dimension_genpurpose8       = 0x33, 
        dimension_effect1depth      = 0x5b, 
        dimension_effect2depth      = 0x5c, 
        dimension_effect3depth      = 0x5d, 
        dimension_effect4depth      = 0x5e, 
        dimension_effect5depth      = 0x5f  
    );

    GIG_DECLARE_ENUM(split_type_t,
        split_type_normal,         
        split_type_bit             
    );

    struct dimension_def_t {
        dimension_t  dimension;  
        uint8_t      bits;       
        uint8_t      zones;      
        split_type_t split_type; 
        float        zone_size;  
    };

    GIG_DECLARE_ENUM(vcf_type_t,
        vcf_type_lowpass       = 0x00, 
        vcf_type_lowpassturbo  = 0xff, 
        vcf_type_bandpass      = 0x01, 
        vcf_type_highpass      = 0x02, 
        vcf_type_bandreject    = 0x03, 
        vcf_type_lowpass_1p    = 0x11, 
        vcf_type_lowpass_2p    = 0x12, 
        vcf_type_lowpass_4p    = 0x14, 
        vcf_type_lowpass_6p    = 0x16, 
        vcf_type_highpass_1p   = 0x21, 
        vcf_type_highpass_2p   = 0x22, 
        vcf_type_highpass_4p   = 0x24, 
        vcf_type_highpass_6p   = 0x26, 
        vcf_type_bandpass_2p   = 0x32, 
        vcf_type_bandreject_2p = 0x42  
    );

    struct crossfade_t {
        #if WORDS_BIGENDIAN
        uint8_t out_end;    
        uint8_t out_start;  
        uint8_t in_end;     
        uint8_t in_start;   
        #else // little endian
        uint8_t in_start;   
        uint8_t in_end;     
        uint8_t out_start;  
        uint8_t out_end;    
        #endif // WORDS_BIGENDIAN

        void serialize(Serialization::Archive* archive);
    };

    struct playback_state_t {
        file_offset_t position;          
        bool          reverse;           
        file_offset_t loop_cycles_left;  
    };

    struct eg_opt_t {
        bool AttackCancel;     
        bool AttackHoldCancel; 
        bool Decay1Cancel;     
        bool Decay2Cancel;     
        bool ReleaseCancel;    

        eg_opt_t();
        void serialize(Serialization::Archive* archive);
    };

    GIG_DECLARE_ENUM(sust_rel_trg_t,
        sust_rel_trg_none        = 0x00, 
        sust_rel_trg_maxvelocity = 0x01, 
        sust_rel_trg_keyvelocity = 0x02  
    );

    // just symbol prototyping
    class File;
    class Instrument;
    class Sample;
    class Region;
    class Group;
    class Script;
    class ScriptGroup;

    class DimensionRegion : protected DLS::Sampler {
        public:
            uint8_t            VelocityUpperLimit;            
            Sample*            pSample;                       
            // Sample Amplitude EG/LFO
            uint16_t           EG1PreAttack;                  
            double             EG1Attack;                     
            double             EG1Decay1;                     
            double             EG1Decay2;                     
            bool               EG1InfiniteSustain;            
            uint16_t           EG1Sustain;                    
            double             EG1Release;                    
            bool               EG1Hold;                       
            eg1_ctrl_t         EG1Controller;                 
            bool               EG1ControllerInvert;           
            uint8_t            EG1ControllerAttackInfluence;  
            uint8_t            EG1ControllerDecayInfluence;   
            uint8_t            EG1ControllerReleaseInfluence; 
            lfo_wave_t         LFO1WaveForm;                  
            double             LFO1Frequency;                 
            double             LFO1Phase;                     
            uint16_t           LFO1InternalDepth;             
            uint16_t           LFO1ControlDepth;              
            lfo1_ctrl_t        LFO1Controller;                
            bool               LFO1FlipPhase;                 
            bool               LFO1Sync;                      
            // Filter Cutoff Frequency EG/LFO
            uint16_t           EG2PreAttack;                  
            double             EG2Attack;                     
            double             EG2Decay1;                     
            double             EG2Decay2;                     
            bool               EG2InfiniteSustain;            
            uint16_t           EG2Sustain;                    
            double             EG2Release;                    
            eg2_ctrl_t         EG2Controller;                 
            bool               EG2ControllerInvert;           
            uint8_t            EG2ControllerAttackInfluence;  
            uint8_t            EG2ControllerDecayInfluence;   
            uint8_t            EG2ControllerReleaseInfluence; 
            lfo_wave_t         LFO2WaveForm;                  
            double             LFO2Frequency;                 
            double             LFO2Phase;                     
            uint16_t           LFO2InternalDepth;             
            uint16_t           LFO2ControlDepth;              
            lfo2_ctrl_t        LFO2Controller;                
            bool               LFO2FlipPhase;                 
            bool               LFO2Sync;                      
            // Sample Pitch EG/LFO
            double             EG3Attack;                     
            int16_t            EG3Depth;                      
            lfo_wave_t         LFO3WaveForm;                  
            double             LFO3Frequency;                 
            double             LFO3Phase;                     
            int16_t            LFO3InternalDepth;             
            int16_t            LFO3ControlDepth;              
            lfo3_ctrl_t        LFO3Controller;                
            bool               LFO3FlipPhase;                 
            bool               LFO3Sync;                      
            // Filter
            bool               VCFEnabled;                    
            vcf_type_t         VCFType;                       
            vcf_cutoff_ctrl_t  VCFCutoffController;           
            bool               VCFCutoffControllerInvert;     
            uint8_t            VCFCutoff;                     
            curve_type_t       VCFVelocityCurve;              
            uint8_t            VCFVelocityScale;              
            uint8_t            VCFVelocityDynamicRange;       
            uint8_t            VCFResonance;                  
            bool               VCFResonanceDynamic;           
            vcf_res_ctrl_t     VCFResonanceController;        
            bool               VCFKeyboardTracking;           
            uint8_t            VCFKeyboardTrackingBreakpoint; 
            // Key Velocity Transformations
            curve_type_t       VelocityResponseCurve;         
            uint8_t            VelocityResponseDepth;         
            uint8_t            VelocityResponseCurveScaling;  
            curve_type_t       ReleaseVelocityResponseCurve;  
            uint8_t            ReleaseVelocityResponseDepth;  
            uint8_t            ReleaseTriggerDecay;           
            // Mix / Layer
            crossfade_t        Crossfade;
            bool               PitchTrack;                    
            dim_bypass_ctrl_t  DimensionBypass;               
            int8_t             Pan;                           
            bool               SelfMask;                      
            attenuation_ctrl_t AttenuationController;         
            bool               InvertAttenuationController;   
            uint8_t            AttenuationControllerThreshold;
            uint8_t            ChannelOffset;                 
            bool               SustainDefeat;                 
            bool               MSDecode;                      
            uint16_t           SampleStartOffset;             
            double             SampleAttenuation;             
            uint8_t            DimensionUpperLimits[8];       
            eg_opt_t           EG1Options;                    
            eg_opt_t           EG2Options;                    
            sust_rel_trg_t     SustainReleaseTrigger;         
            bool               NoNoteOffReleaseTrigger;       

            // derived attributes from DLS::Sampler
            using DLS::Sampler::UnityNote;
            using DLS::Sampler::FineTune;
            using DLS::Sampler::Gain;
            using DLS::Sampler::SampleLoops;
            using DLS::Sampler::pSampleLoops;

            // own methods
            double GetVelocityAttenuation(uint8_t MIDIKeyVelocity);
            double GetVelocityRelease(uint8_t MIDIKeyVelocity);
            double GetVelocityCutoff(uint8_t MIDIKeyVelocity);
            void SetVelocityResponseCurve(curve_type_t curve);
            void SetVelocityResponseDepth(uint8_t depth);
            void SetVelocityResponseCurveScaling(uint8_t scaling);
            void SetReleaseVelocityResponseCurve(curve_type_t curve);
            void SetReleaseVelocityResponseDepth(uint8_t depth);
            void SetVCFCutoffController(vcf_cutoff_ctrl_t controller);
            void SetVCFVelocityCurve(curve_type_t curve);
            void SetVCFVelocityDynamicRange(uint8_t range);
            void SetVCFVelocityScale(uint8_t scaling);
            Region* GetParent() const;
            // derived methods
            using DLS::Sampler::AddSampleLoop;
            using DLS::Sampler::DeleteSampleLoop;
            // overridden methods
            virtual void SetGain(int32_t gain) OVERRIDE;
            virtual void UpdateChunks(progress_t* pProgress) OVERRIDE;
            virtual void CopyAssign(const DimensionRegion* orig);
        protected:
            uint8_t* VelocityTable; 
            DimensionRegion(Region* pParent, RIFF::List* _3ewl);
            DimensionRegion(RIFF::List* _3ewl, const DimensionRegion& src);
           ~DimensionRegion();
            void CopyAssign(const DimensionRegion* orig, const std::map<Sample*,Sample*>* mSamples);
            void serialize(Serialization::Archive* archive);
            friend class Region;
            friend class Serialization::Archive;
        private:
            typedef enum { 
                // official leverage controllers as they were defined in the original Gigasampler/GigaStudio format:
                _lev_ctrl_none              = 0x00,
                _lev_ctrl_modwheel          = 0x03, 
                _lev_ctrl_breath            = 0x05, 
                _lev_ctrl_foot              = 0x07, 
                _lev_ctrl_effect1           = 0x0d, 
                _lev_ctrl_effect2           = 0x0f, 
                _lev_ctrl_genpurpose1       = 0x11, 
                _lev_ctrl_genpurpose2       = 0x13, 
                _lev_ctrl_genpurpose3       = 0x15, 
                _lev_ctrl_genpurpose4       = 0x17, 
                _lev_ctrl_portamentotime    = 0x0b, 
                _lev_ctrl_sustainpedal      = 0x01, 
                _lev_ctrl_portamento        = 0x19, 
                _lev_ctrl_sostenutopedal    = 0x1b, 
                _lev_ctrl_softpedal         = 0x09, 
                _lev_ctrl_genpurpose5       = 0x1d, 
                _lev_ctrl_genpurpose6       = 0x1f, 
                _lev_ctrl_genpurpose7       = 0x21, 
                _lev_ctrl_genpurpose8       = 0x23, 
                _lev_ctrl_effect1depth      = 0x25, 
                _lev_ctrl_effect2depth      = 0x27, 
                _lev_ctrl_effect3depth      = 0x29, 
                _lev_ctrl_effect4depth      = 0x2b, 
                _lev_ctrl_effect5depth      = 0x2d, 
                _lev_ctrl_channelaftertouch = 0x2f, 
                _lev_ctrl_velocity          = 0xff, 

                // format extension (these controllers are so far only supported by LinuxSampler & gigedit) they will *NOT* work with Gigasampler/GigaStudio !
                // (the assigned values here are their official MIDI CC number plus the highest bit set):
                _lev_ctrl_CC3_EXT           = 0x83, 

                _lev_ctrl_CC6_EXT           = 0x86, 
                _lev_ctrl_CC7_EXT           = 0x87, 
                _lev_ctrl_CC8_EXT           = 0x88, 
                _lev_ctrl_CC9_EXT           = 0x89, 
                _lev_ctrl_CC10_EXT          = 0x8a, 
                _lev_ctrl_CC11_EXT          = 0x8b, 

                _lev_ctrl_CC14_EXT          = 0x8e, 
                _lev_ctrl_CC15_EXT          = 0x8f, 

                _lev_ctrl_CC20_EXT          = 0x94, 
                _lev_ctrl_CC21_EXT          = 0x95, 
                _lev_ctrl_CC22_EXT          = 0x96, 
                _lev_ctrl_CC23_EXT          = 0x97, 
                _lev_ctrl_CC24_EXT          = 0x98, 
                _lev_ctrl_CC25_EXT          = 0x99, 
                _lev_ctrl_CC26_EXT          = 0x9a, 
                _lev_ctrl_CC27_EXT          = 0x9b, 
                _lev_ctrl_CC28_EXT          = 0x9c, 
                _lev_ctrl_CC29_EXT          = 0x9d, 
                _lev_ctrl_CC30_EXT          = 0x9e, 
                _lev_ctrl_CC31_EXT          = 0x9f, 

                _lev_ctrl_CC68_EXT          = 0xc4, 
                _lev_ctrl_CC69_EXT          = 0xc5, 
                _lev_ctrl_CC70_EXT          = 0xc6, 
                _lev_ctrl_CC71_EXT          = 0xc7, 
                _lev_ctrl_CC72_EXT          = 0xc8, 
                _lev_ctrl_CC73_EXT          = 0xc9, 
                _lev_ctrl_CC74_EXT          = 0xca, 
                _lev_ctrl_CC75_EXT          = 0xcb, 
                _lev_ctrl_CC76_EXT          = 0xcc, 
                _lev_ctrl_CC77_EXT          = 0xcd, 
                _lev_ctrl_CC78_EXT          = 0xce, 
                _lev_ctrl_CC79_EXT          = 0xcf, 

                _lev_ctrl_CC84_EXT          = 0xd4, 
                _lev_ctrl_CC85_EXT          = 0xd5, 
                _lev_ctrl_CC86_EXT          = 0xd6, 
                _lev_ctrl_CC87_EXT          = 0xd7, 

                _lev_ctrl_CC89_EXT          = 0xd9, 
                _lev_ctrl_CC90_EXT          = 0xda, 

                _lev_ctrl_CC96_EXT          = 0xe0, 
                _lev_ctrl_CC97_EXT          = 0xe1, 

                _lev_ctrl_CC102_EXT         = 0xe6, 
                _lev_ctrl_CC103_EXT         = 0xe7, 
                _lev_ctrl_CC104_EXT         = 0xe8, 
                _lev_ctrl_CC105_EXT         = 0xe9, 
                _lev_ctrl_CC106_EXT         = 0xea, 
                _lev_ctrl_CC107_EXT         = 0xeb, 
                _lev_ctrl_CC108_EXT         = 0xec, 
                _lev_ctrl_CC109_EXT         = 0xed, 
                _lev_ctrl_CC110_EXT         = 0xee, 
                _lev_ctrl_CC111_EXT         = 0xef, 
                _lev_ctrl_CC112_EXT         = 0xf0, 
                _lev_ctrl_CC113_EXT         = 0xf1, 
                _lev_ctrl_CC114_EXT         = 0xf2, 
                _lev_ctrl_CC115_EXT         = 0xf3, 
                _lev_ctrl_CC116_EXT         = 0xf4, 
                _lev_ctrl_CC117_EXT         = 0xf5, 
                _lev_ctrl_CC118_EXT         = 0xf6, 
                _lev_ctrl_CC119_EXT         = 0xf7  
            } _lev_ctrl_t;
            typedef std::map<uint32_t, double*> VelocityTableMap;

            static size_t            Instances;                  
            static VelocityTableMap* pVelocityTables;            
            double*                  pVelocityAttenuationTable;  
            double*                  pVelocityReleaseTable;      
            double*                  pVelocityCutoffTable;       
            Region*                  pRegion;

            leverage_ctrl_t DecodeLeverageController(_lev_ctrl_t EncodedController);
            _lev_ctrl_t     EncodeLeverageController(leverage_ctrl_t DecodedController);
            double* GetReleaseVelocityTable(curve_type_t releaseVelocityResponseCurve, uint8_t releaseVelocityResponseDepth);
            double* GetCutoffVelocityTable(curve_type_t vcfVelocityCurve, uint8_t vcfVelocityDynamicRange, uint8_t vcfVelocityScale, vcf_cutoff_ctrl_t vcfCutoffController);
            double* GetVelocityTable(curve_type_t curveType, uint8_t depth, uint8_t scaling);
            double* CreateVelocityTable(curve_type_t curveType, uint8_t depth, uint8_t scaling);
            bool UsesAnyGigFormatExtension() const;
    };

    class Sample : public DLS::Sample {
        public:
            uint32_t       Manufacturer;      
            uint32_t       Product;           
            uint32_t       SamplePeriod;      
            uint32_t       MIDIUnityNote;     
            uint32_t       FineTune;          
            smpte_format_t SMPTEFormat;       
            uint32_t       SMPTEOffset;       
            uint32_t       Loops;             
            uint32_t       LoopID;            
            loop_type_t    LoopType;          
            uint32_t       LoopStart;         
            uint32_t       LoopEnd;           
            uint32_t       LoopSize;          
            uint32_t       LoopFraction;      
            uint32_t       LoopPlayCount;     
            bool           Compressed;        
            uint32_t       TruncatedBits;     
            bool           Dithered;          

            // own methods
            buffer_t      LoadSampleData();
            buffer_t      LoadSampleData(file_offset_t SampleCount);
            buffer_t      LoadSampleDataWithNullSamplesExtension(uint NullSamplesCount);
            buffer_t      LoadSampleDataWithNullSamplesExtension(file_offset_t SampleCount, uint NullSamplesCount);
            buffer_t      GetCache();
            // own static methods
            static buffer_t CreateDecompressionBuffer(file_offset_t MaxReadSize);
            static void     DestroyDecompressionBuffer(buffer_t& DecompressionBuffer);
            // overridden methods
            void          ReleaseSampleData();
            void          Resize(file_offset_t NewSize);
            file_offset_t SetPos(file_offset_t SampleCount, RIFF::stream_whence_t Whence = RIFF::stream_start);
            file_offset_t GetPos() const;
            file_offset_t Read(void* pBuffer, file_offset_t SampleCount, buffer_t* pExternalDecompressionBuffer = NULL);
            file_offset_t ReadAndLoop(void* pBuffer, file_offset_t SampleCount, playback_state_t* pPlaybackState, DimensionRegion* pDimRgn, buffer_t* pExternalDecompressionBuffer = NULL);
            file_offset_t Write(void* pBuffer, file_offset_t SampleCount);
            Group*        GetGroup() const;
            virtual void  UpdateChunks(progress_t* pProgress) OVERRIDE;
            void CopyAssignMeta(const Sample* orig);
            void CopyAssignWave(const Sample* orig);
            uint32_t GetWaveDataCRC32Checksum();
            bool VerifyWaveData(uint32_t* pActually = NULL);
        protected:
            static size_t        Instances;               
            static buffer_t      InternalDecompressionBuffer; 
            Group*               pGroup;                  
            file_offset_t        FrameOffset;             
            file_offset_t*       FrameTable;              
            file_offset_t        SamplePos;               
            file_offset_t        SamplesInLastFrame;      
            file_offset_t        WorstCaseFrameSize;      
            file_offset_t        SamplesPerFrame;         
            buffer_t             RAMCache;                
            unsigned long        FileNo;                  
            RIFF::Chunk*         pCk3gix;
            RIFF::Chunk*         pCkSmpl;
            uint32_t             crc;                     

            Sample(File* pFile, RIFF::List* waveList, file_offset_t WavePoolOffset, unsigned long fileNo = 0, int index = -1);
           ~Sample();
            uint32_t CalculateWaveDataChecksum();

            // Guess size (in bytes) of a compressed sample
            inline file_offset_t GuessSize(file_offset_t samples) {
                // 16 bit: assume all frames are compressed - 1 byte
                // per sample and 5 bytes header per 2048 samples

                // 24 bit: assume next best compression rate - 1.5
                // bytes per sample and 13 bytes header per 256
                // samples
                const file_offset_t size =
                    BitDepth == 24 ? samples + (samples >> 1) + (samples >> 8) * 13
                                   : samples + (samples >> 10) * 5;
                // Double for stereo and add one worst case sample
                // frame
                return (Channels == 2 ? size << 1 : size) + WorstCaseFrameSize;
            }

            // Worst case amount of sample points that can be read with the
            // given decompression buffer.
            inline file_offset_t WorstCaseMaxSamples(buffer_t* pDecompressionBuffer) {
                return (file_offset_t) ((float)pDecompressionBuffer->Size / (float)WorstCaseFrameSize * (float)SamplesPerFrame);
            }
        private:
            void ScanCompressedSample();
            friend class File;
            friend class Region;
            friend class Group; // allow to modify protected member pGroup
    };

    // TODO: <3dnl> list not used yet - not important though (just contains optional descriptions for the dimensions)
    class Region : public DLS::Region {
        public:
            unsigned int            Dimensions;               
            dimension_def_t         pDimensionDefinitions[8]; 
            uint32_t                DimensionRegions;         
            DimensionRegion*        pDimensionRegions[256];   
            unsigned int            Layers;                   

            // own methods
            DimensionRegion* GetDimensionRegionByValue(const uint DimValues[8]);
            DimensionRegion* GetDimensionRegionByBit(const uint8_t DimBits[8]);
            int              GetDimensionRegionIndexByValue(const uint DimValues[8]);
            Sample*          GetSample();
            void             AddDimension(dimension_def_t* pDimDef);
            void             DeleteDimension(dimension_def_t* pDimDef);
            dimension_def_t* GetDimensionDefinition(dimension_t type);
            void             DeleteDimensionZone(dimension_t type, int zone);
            void             SplitDimensionZone(dimension_t type, int zone);
            void             SetDimensionType(dimension_t oldType, dimension_t newType);
            // overridden methods
            virtual void     SetKeyRange(uint16_t Low, uint16_t High) OVERRIDE;
            virtual void     UpdateChunks(progress_t* pProgress) OVERRIDE;
            virtual void     CopyAssign(const Region* orig);
        protected:
            Region(Instrument* pInstrument, RIFF::List* rgnList);
            void LoadDimensionRegions(RIFF::List* rgn);
            void UpdateVelocityTable();
            Sample* GetSampleFromWavePool(unsigned int WavePoolTableIndex, progress_t* pProgress = NULL);
            void CopyAssign(const Region* orig, const std::map<Sample*,Sample*>* mSamples);
            DimensionRegion* GetDimensionRegionByBit(const std::map<dimension_t,int>& DimCase);
           ~Region();
            friend class Instrument;
        private:
            bool UsesAnyGigFormatExtension() const;
    };

    class MidiRule {
        public:
            virtual ~MidiRule() { }
        protected:
            virtual void UpdateChunks(uint8_t* pData) const = 0;
            friend class Instrument;
    };

    class MidiRuleCtrlTrigger : public MidiRule {
        public:
            uint8_t ControllerNumber;   
            uint8_t Triggers;           
            struct trigger_t {
                uint8_t TriggerPoint;   
                bool    Descending;     
                uint8_t VelSensitivity; 
                uint8_t Key;            
                bool    NoteOff;        
                uint8_t Velocity;       
                bool    OverridePedal;  
            } pTriggers[32];

        protected:
            MidiRuleCtrlTrigger(RIFF::Chunk* _3ewg);
            MidiRuleCtrlTrigger();
            void UpdateChunks(uint8_t* pData) const OVERRIDE;
            friend class Instrument;
    };

    class MidiRuleLegato : public MidiRule {
        public:
            uint8_t LegatoSamples;     
            bool BypassUseController;  
            uint8_t BypassKey;         
            uint8_t BypassController;  
            uint16_t ThresholdTime;    
            uint16_t ReleaseTime;      
            range_t KeyRange;          
            uint8_t ReleaseTriggerKey; 
            uint8_t AltSustain1Key;    
            uint8_t AltSustain2Key;    

        protected:
            MidiRuleLegato(RIFF::Chunk* _3ewg);
            MidiRuleLegato();
            void UpdateChunks(uint8_t* pData) const OVERRIDE;
            friend class Instrument;
    };

    class MidiRuleAlternator : public MidiRule {
        public:
            uint8_t Articulations;     
            String pArticulations[32]; 

            range_t PlayRange;         

            uint8_t Patterns;          
            struct pattern_t {
                String Name;           
                int Size;              
                const uint8_t& operator[](int i) const { 
                    return data[i];
                }
                uint8_t& operator[](int i) {
                    return data[i];
                }
            private:
                uint8_t data[32];
            } pPatterns[32];           

            typedef enum {
                selector_none,
                selector_key_switch,
                selector_controller
            } selector_t;
            selector_t Selector;       
            range_t KeySwitchRange;    
            uint8_t Controller;        

            bool Polyphonic;           
            bool Chained;              

        protected:
            MidiRuleAlternator(RIFF::Chunk* _3ewg);
            MidiRuleAlternator();
            void UpdateChunks(uint8_t* pData) const OVERRIDE;
            friend class Instrument;
    };

    class MidiRuleUnknown : public MidiRule {
        protected:
            MidiRuleUnknown() { }
            void UpdateChunks(uint8_t* pData) const OVERRIDE { }
            friend class Instrument;
    };

    class Script : protected DLS::Storage {
        public:
            enum Encoding_t {
                ENCODING_ASCII = 0 
            };
            enum Compression_t {
                COMPRESSION_NONE = 0 
            };
            enum Language_t {
                LANGUAGE_NKSP = 0 
            };

            String         Name;        
            Compression_t  Compression; 
            Encoding_t     Encoding;    
            Language_t     Language;    
            bool           Bypass;      
            uint8_t        Uuid[16];    

            String GetScriptAsText();
            void   SetScriptAsText(const String& text);
            void   SetGroup(ScriptGroup* pGroup);
            ScriptGroup* GetGroup() const;
            void   CopyAssign(const Script* orig);
        protected:
            Script(ScriptGroup* group, RIFF::Chunk* ckScri);
            virtual ~Script();
            void UpdateChunks(progress_t* pProgress) OVERRIDE;
            void DeleteChunks() OVERRIDE;
            void RemoveAllScriptReferences();
            void GenerateUuid();
            friend class ScriptGroup;
            friend class Instrument;
        private:
            ScriptGroup*          pGroup;
            RIFF::Chunk*          pChunk; 
            std::vector<uint8_t>  data;
            uint32_t              crc; 
    };

    class ScriptGroup : protected DLS::Storage {
        public:
            String   Name; 

            Script*  GetScript(size_t index);
            Script*  AddScript();
            void     DeleteScript(Script* pScript);
        protected:
            ScriptGroup(File* file, RIFF::List* lstRTIS);
            virtual ~ScriptGroup();
            void LoadScripts();
            virtual void UpdateChunks(progress_t* pProgress) OVERRIDE;
            virtual void DeleteChunks() OVERRIDE;
            friend class Script;
            friend class File;
        private:
            File*                pFile;
            RIFF::List*          pList; 
            std::vector<Script*>* pScripts;
    };

    class Instrument : protected DLS::Instrument {
        public:
            // derived attributes from DLS::Resource
            using DLS::Resource::pInfo;
            using DLS::Resource::pDLSID;
            // derived attributes from DLS::Instrument
            using DLS::Instrument::IsDrum;
            using DLS::Instrument::MIDIBank;
            using DLS::Instrument::MIDIBankCoarse;
            using DLS::Instrument::MIDIBankFine;
            using DLS::Instrument::MIDIProgram;
            using DLS::Instrument::Regions;
            // own attributes
            int32_t   Attenuation;       
            uint16_t  EffectSend;
            int16_t   FineTune;          
            uint16_t  PitchbendRange;    
            bool      PianoReleaseMode;
            range_t   DimensionKeyRange; 


            // derived methods
            using DLS::Resource::GetParent;
            using DLS::Instrument::CountRegions;
            // overridden methods
            Region*   GetRegionAt(size_t pos);
            Region*   GetFirstRegion() LIBGIG_DEPRECATED_API("Use GetRegionAt() instead.");
            Region*   GetNextRegion() LIBGIG_DEPRECATED_API("Use GetRegionAt() instead.");
            Region*   AddRegion();
            void      DeleteRegion(Region* pRegion);
            void      MoveTo(Instrument* dst);
            virtual void UpdateChunks(progress_t* pProgress) OVERRIDE;
            virtual void CopyAssign(const Instrument* orig);
            // own methods
            Region*   GetRegion(unsigned int Key);
            MidiRule* GetMidiRule(int i);
            MidiRuleCtrlTrigger* AddMidiRuleCtrlTrigger();
            MidiRuleLegato*      AddMidiRuleLegato();
            MidiRuleAlternator*  AddMidiRuleAlternator();
            void      DeleteMidiRule(int i);
            // real-time instrument script methods
            Script*   GetScriptOfSlot(size_t index);
            void      AddScriptSlot(Script* pScript, bool bypass = false);
            void      SwapScriptSlots(size_t index1, size_t index2);
            void      RemoveScriptSlot(size_t index);
            void      RemoveScript(Script* pScript);
            size_t    ScriptSlotCount() const;
            bool      IsScriptSlotBypassed(size_t index);
            void      SetScriptSlotBypassed(size_t index, bool bBypass);
            bool      IsScriptPatchVariableSet(size_t slot, String variable);
            std::map<String,String> GetScriptPatchVariables(size_t slot);
            String    GetScriptPatchVariable(size_t slot, String variable);
            void      SetScriptPatchVariable(size_t slot, String variable, String value);
            void      UnsetScriptPatchVariable(ssize_t slot = -1, String variable = "");
        protected:
            Region*   RegionKeyTable[128]; 

            Instrument(File* pFile, RIFF::List* insList, progress_t* pProgress = NULL);
           ~Instrument();
            void CopyAssign(const Instrument* orig, const std::map<Sample*,Sample*>* mSamples);
            void UpdateRegionKeyTable();
            void LoadScripts();
            void UpdateScriptFileOffsets();
            friend class File;
            friend class Region; // so Region can call UpdateRegionKeyTable()
        private:
            struct _ScriptPooolEntry {
                uint32_t fileOffset;
                bool     bypass;
            };
            struct _ScriptPooolRef {
                Script*  script;
                bool     bypass;
            };
            typedef std::array<uint8_t,16> _UUID;
            typedef std::map<String,String> _PatchVars;
            typedef std::map<size_t,_PatchVars> _VarsBySlot;
            typedef std::map<_UUID,_VarsBySlot> _VarsByScript;
            MidiRule** pMidiRules;
            std::vector<_ScriptPooolEntry> scriptPoolFileOffsets;
            std::vector<_ScriptPooolRef>* pScriptRefs;
            _VarsByScript scriptVars;

            _VarsByScript stripScriptVars();
            bool ReferencesScriptWithUuid(const _UUID& uuid);
            bool UsesAnyGigFormatExtension() const;
    };

    class Group : public DLS::Storage {
        public:
            String Name; 

            Sample* GetSample(size_t index);
            Sample* GetFirstSample() LIBGIG_DEPRECATED_API("Use GetSample() instead.");
            Sample* GetNextSample() LIBGIG_DEPRECATED_API("Use GetSample() instead.");
            void AddSample(Sample* pSample);
        protected:
            Group(File* file, RIFF::Chunk* ck3gnm);
            virtual ~Group();
            virtual void UpdateChunks(progress_t* pProgress) OVERRIDE;
            virtual void DeleteChunks() OVERRIDE;
            void MoveAll();
            friend class File;
        private:
            File*        pFile;
            RIFF::Chunk* pNameChunk; 
            size_t       SamplesIterator; 
    };

    class File : protected DLS::File {
        public:
            static const DLS::version_t VERSION_2;
            static const DLS::version_t VERSION_3;
            static const DLS::version_t VERSION_4;

            // derived attributes from DLS::Resource
            using DLS::Resource::pInfo;
            using DLS::Resource::pDLSID;
            // derived attributes from DLS::File
            using DLS::File::pVersion;
            using DLS::File::Instruments;

            // derived methods from DLS::Resource
            using DLS::Resource::GetParent;
            // derived methods from DLS::File
            using DLS::File::Save;
            using DLS::File::GetFileName;
            using DLS::File::SetFileName;
            using DLS::File::GetRiffFile;
            // overridden  methods
            File();
            File(RIFF::File* pRIFF);
            Sample*     GetFirstSample(progress_t* pProgress = NULL) LIBGIG_DEPRECATED_API("Use GetSample() instead.");
            Sample*     GetNextSample() LIBGIG_DEPRECATED_API("Use GetSample() instead.");
            Sample*     GetSample(size_t index, progress_t* pProgress = NULL);
            Sample*     AddSample();
            size_t      CountSamples();
            void        DeleteSample(Sample* pSample);
            Instrument* GetFirstInstrument() LIBGIG_DEPRECATED_API("Use GetInstrument() instead.");
            Instrument* GetNextInstrument() LIBGIG_DEPRECATED_API("Use GetInstrument() instead.");
            Instrument* GetInstrument(size_t index, progress_t* pProgress = NULL);
            Instrument* AddInstrument();
            Instrument* AddDuplicateInstrument(const Instrument* orig);
            size_t      CountInstruments();
            void        DeleteInstrument(Instrument* pInstrument);
            Group*      GetFirstGroup() LIBGIG_DEPRECATED_API("Use GetGroup() instead.");
            Group*      GetNextGroup() LIBGIG_DEPRECATED_API("Use GetGroup() instead.");
            Group*      GetGroup(size_t index);
            Group*      GetGroup(String name);
            Group*      AddGroup();
            void        DeleteGroup(Group* pGroup);
            void        DeleteGroupOnly(Group* pGroup);
            void        SetAutoLoad(bool b);
            bool        GetAutoLoad();
            void        AddContentOf(File* pFile);
            ScriptGroup* GetScriptGroup(size_t index);
            ScriptGroup* GetScriptGroup(const String& name);
            ScriptGroup* AddScriptGroup();
            void        DeleteScriptGroup(ScriptGroup* pGroup);
            virtual    ~File();
            virtual void UpdateChunks(progress_t* pProgress) OVERRIDE;
        protected:
            // overridden protected methods from DLS::File
            virtual void LoadSamples() OVERRIDE;
            virtual void LoadInstruments() OVERRIDE;
            virtual void LoadGroups();
            virtual void UpdateFileOffsets() OVERRIDE;
            // own protected methods
            virtual void LoadSamples(progress_t* pProgress);
            virtual void LoadInstruments(progress_t* pProgress);
            virtual void LoadScriptGroups();
            void SetSampleChecksum(Sample* pSample, uint32_t crc);
            uint32_t GetSampleChecksum(Sample* pSample);
            uint32_t GetSampleChecksumByIndex(int index);
            bool VerifySampleChecksumTable();
            bool RebuildSampleChecksumTable();
            int  GetWaveTableIndexOf(gig::Sample* pSample);
            friend class Region;
            friend class Sample;
            friend class Instrument;
            friend class Group; // so Group can access protected member pRIFF
            friend class ScriptGroup; // so ScriptGroup can access protected member pRIFF
        private:
            std::vector<Group*>*          pGroups;
            std::vector<Group*>::iterator GroupsIterator;
            bool                        bAutoLoad;
            std::vector<ScriptGroup*>*    pScriptGroups;

            bool UsesAnyGigFormatExtension() const;
    };

    class Exception : public DLS::Exception {
        public:
            Exception(String format, ...);
            Exception(String format, va_list arg);
            void PrintMessage();
        protected:
            Exception();
    };

#if HAVE_RTTI
    size_t enumCount(const std::type_info& type);
    const char* enumKey(const std::type_info& type, size_t value);
    bool        enumKey(const std::type_info& type, String key);
    const char** enumKeys(const std::type_info& type);
#endif // HAVE_RTTI
    size_t enumCount(String typeName);
    const char* enumKey(String typeName, size_t value);
    bool        enumKey(String typeName, String key);
    const char** enumKeys(String typeName);
    size_t enumValue(String key);

    String libraryName();
    String libraryVersion();

} // namespace gig

#endif // __GIG_H__