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) 2023, 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 () const { 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 {0};
};
 
//------------------------------------------------------------------------
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