vstpresetfile.h

Go to the documentation of this file.

//-----------------------------------------------------------------------------
// Project     : VST SDK
//
// Category    : Helpers
// Filename    : public.sdk/source/vst/vstpresetfile.h
// Created by  : Steinberg, 03/2006
// Description : VST 3 Preset File Format
//
//-----------------------------------------------------------------------------
// LICENSE
// (c) 2021, Steinberg Media Technologies GmbH, All Rights Reserved
//-----------------------------------------------------------------------------
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
// 
//   * Redistributions of source code must retain the above copyright notice, 
//     this list of conditions and the following disclaimer.
//   * Redistributions in binary form must reproduce the above copyright notice,
//     this list of conditions and the following disclaimer in the documentation 
//     and/or other materials provided with the distribution.
//   * Neither the name of the Steinberg Media Technologies nor the names of its
//     contributors may be used to endorse or promote products derived from this 
//     software without specific prior written permission.
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
// IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
// INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
// OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE  OF THIS SOFTWARE, EVEN IF ADVISED
// OF THE POSSIBILITY OF SUCH DAMAGE.
//-----------------------------------------------------------------------------
 
#pragma once
 
#include "pluginterfaces/vst/ivstcomponent.h"
#include "pluginterfaces/vst/ivsteditcontroller.h"
#include "pluginterfaces/vst/ivstunits.h"
 
#include "pluginterfaces/base/ibstream.h"
#include "base/source/fbuffer.h"
 
#include <cstdio>
#include <vector>
 
//------------------------------------------------------------------------
/* 
        VST 3 Preset File Format Definition
   ===================================
 
0   +---------------------------+
    | HEADER                    |
    | header id ('VST3')        |       4 Bytes
    | version                   |       4 Bytes (int32)
    | ASCII-encoded class id    |       32 Bytes 
 +--| offset to chunk list      |       8 Bytes (int64)
 |  +---------------------------+
 |  | DATA AREA                 |<-+
 |  | data of chunks 1..n       |  |
 |  ...                       ...  |
 |  |                           |  |
 +->+---------------------------+  |
    | CHUNK LIST                |  |
    | list id ('List')          |  |    4 Bytes
    | entry count               |  |    4 Bytes (int32)
    +---------------------------+  |
    |  1..n                     |  |
    |  +----------------------+ |  |
    |  | chunk id             | |  |    4 Bytes
    |  | offset to chunk data |----+    8 Bytes (int64)
    |  | size of chunk data   | |       8 Bytes (int64)
    |  +----------------------+ |
EOF +---------------------------+
*/
 
//------------------------------------------------------------------------
namespace Steinberg {
namespace Vst {
 
//------------------------------------------------------------------------
using ChunkID = char[4];
 
//------------------------------------------------------------------------
enum ChunkType
{
        kHeader,
        kComponentState,
        kControllerState,
        kProgramData,
        kMetaInfo,
        kChunkList,
        kNumPresetChunks
};
 
//------------------------------------------------------------------------
extern const ChunkID& getChunkID (ChunkType type);
 
//------------------------------------------------------------------------
inline bool isEqualID (const ChunkID id1, const ChunkID id2)
{
        return memcmp (id1, id2, sizeof (ChunkID)) == 0;
}
 
//------------------------------------------------------------------------
class PresetFile
{
public:
//------------------------------------------------------------------------
        PresetFile (IBStream* stream); 
        virtual ~PresetFile ();

        struct Entry
        {
                ChunkID id;
                TSize offset;
                TSize size;
        };
 
        IBStream* getStream () { return stream; }                       
 
        const FUID& getClassID () const { return classID; }     
        void setClassID (const FUID& uid) { classID = uid; }
 
        const Entry* getEntry (ChunkType which) const;          
        const Entry* getLastEntry () const;                                     
        int32 getEntryCount () const { return entryCount; }     
        const Entry& at (int32 index) const { return entries[index]; }  
        bool contains (ChunkType which) const { return getEntry (which) != nullptr; }   
 
        bool readChunkList ();          
        bool writeHeader ();            
        bool writeChunkList ();         

        bool readMetaInfo (char* xmlBuffer, int32& size);

        bool writeMetaInfo (const char* xmlBuffer, int32 size = -1, bool forceWriting = false); 
        bool prepareMetaInfoUpdate ();  

        bool writeChunk (const void* data, int32 size, ChunkType which = kComponentState);
 
        //-------------------------------------------------------------
        // for storing and restoring the whole plug-in state (component and controller states)
        bool seekToComponentState ();                                                   
        bool storeComponentState (IComponent* component);               
        bool storeComponentState (IBStream* componentStream);   
        bool restoreComponentState (IComponent* component);             
 
        bool seekToControllerState ();                                                  
        bool storeControllerState (IEditController* editController);
        bool storeControllerState (IBStream* editStream);                       
        bool restoreControllerState (IEditController* editController);
 
        bool restoreComponentState (IEditController* editController);
 
        //--- ----------------------------------------------------------
        bool storeProgramData (IBStream* inStream, ProgramListID listID);
 
        //---when plug-in uses IProgramListData-----------------------
        bool storeProgramData (IProgramListData* programListData, ProgramListID programListID,
                               int32 programIndex);
        bool restoreProgramData (IProgramListData* programListData, ProgramListID* programListID = nullptr,
                                 int32 programIndex = 0);
 
        //---when plug-in uses IUnitData------------------------------
        bool storeProgramData (IUnitData* unitData, UnitID unitID);
        bool restoreProgramData (IUnitData* unitData, UnitID* unitID = nullptr);
 
        //--- ----------------------------------------------------------
        bool restoreProgramData (IUnitInfo* unitInfo, int32 unitProgramListID, int32 programIndex = -1);

        bool getUnitProgramListID (int32& unitProgramListID);
 
        //--- ---------------------------------------------------------------------
        static bool savePreset (IBStream* stream, const FUID& classID, IComponent* component,
                                IEditController* editController = nullptr,
                                const char* xmlBuffer = nullptr, int32 xmlSize = -1);
        static bool savePreset (IBStream* stream, const FUID& classID, IBStream* componentStream,
                                IBStream* editStream = nullptr, const char* xmlBuffer = nullptr,
                                int32 xmlSize = -1);

        static bool loadPreset (IBStream* stream, const FUID& classID, IComponent* component,
                                IEditController* editController = nullptr,
                                std::vector<FUID>* otherClassIDArray = nullptr);
//------------------------------------------------------------------------
protected:
        bool readID (ChunkID id);
        bool writeID (const ChunkID id);
        bool readEqualID (const ChunkID id);
        bool readSize (TSize& size);
        bool writeSize (TSize size);
        bool readInt32 (int32& value);
        bool writeInt32 (int32 value);
        bool seekTo (TSize offset);
        bool beginChunk (Entry& e, ChunkType which);
        bool endChunk (Entry& e);
 
        IBStream* stream;
        FUID classID;           
        enum { kMaxEntries = 128 };
        Entry entries[kMaxEntries];
        int32 entryCount;
};
 
//------------------------------------------------------------------------
class FileStream: public IBStream
{
public:
//------------------------------------------------------------------------
        static IBStream* open (const char* filename, const char* mode); 
 
        //---from FUnknown------------------
        DECLARE_FUNKNOWN_METHODS
 
        //---from IBStream------------------
        tresult PLUGIN_API read (void* buffer, int32 numBytes, int32* numBytesRead = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API write (void* buffer, int32 numBytes, int32* numBytesWritten = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API seek (int64 pos, int32 mode, int64* result = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API tell (int64* pos) SMTG_OVERRIDE;
 
//------------------------------------------------------------------------
protected:
        FileStream (FILE* file);
        virtual ~FileStream ();
 
        FILE* file;
};
 
//------------------------------------------------------------------------
class ReadOnlyBStream: public IBStream
{
public:
//------------------------------------------------------------------------
         ReadOnlyBStream (IBStream* sourceStream, TSize sourceOffset, TSize sectionSize);
         virtual ~ReadOnlyBStream ();
         
         //---from FUnknown------------------
         DECLARE_FUNKNOWN_METHODS
 
         //---from IBStream------------------
         tresult PLUGIN_API read (void* buffer, int32 numBytes, int32* numBytesRead = nullptr) SMTG_OVERRIDE;
         tresult PLUGIN_API write (void* buffer, int32 numBytes, int32* numBytesWritten = nullptr) SMTG_OVERRIDE;
         tresult PLUGIN_API seek (int64 pos, int32 mode, int64* result = nullptr) SMTG_OVERRIDE;
         tresult PLUGIN_API tell (int64* pos) SMTG_OVERRIDE;
 
//------------------------------------------------------------------------
protected:
         IBStream* sourceStream;
         TSize sourceOffset;
         TSize sectionSize;
         TSize seekPosition;
};
 
//------------------------------------------------------------------------
class BufferStream : public IBStream
{
public:
        BufferStream ();
        virtual ~BufferStream ();
 
        //---from FUnknown------------------
        DECLARE_FUNKNOWN_METHODS
 
        //---from IBStream------------------
        tresult PLUGIN_API read (void* buffer, int32 numBytes, int32* numBytesRead = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API write (void* buffer, int32 numBytes, int32* numBytesWritten = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API seek (int64 pos, int32 mode, int64* result = nullptr) SMTG_OVERRIDE;
        tresult PLUGIN_API tell (int64* pos) SMTG_OVERRIDE;
 
protected:
        Buffer mBuffer;
};
 
//------------------------------------------------------------------------
} // namespace Vst
} // namespace Steinberg