[Migration Guide] v0.2.x -> v0.3.x

[Xaymar]

This is a migration guide for anyone that uses this SDK recreation. A lot has changed thanks to scanning thousands of available VST 1.x and 2.x plug-ins automatically instead of going through them manually.

Generic Changes

1. All type definitions via typedef and struct should now have the proper _t suffix attached.
2. enums that incorrectly had a plural name now have a singular name, i.e. FLAGS -> FLAG.
3. char[] buffer sizes are now in their own enum instead of #define and have been split by what they're for and their stated size is now correct.
4. The code should now be compliant with C99 standards and compile in all C and C++ compilers if included as a C header. If the C++ compiler does not support C headers the minimum C++ version is C++20 or most compilers with proprietary extensions enabled.

Effect Changes

1. The recreated SDK now has almost all categories deciphered into what they're most likely to be. This is respected by DAW software like Adobe Audition, FL Studio, etc. In some hosts this even changes how the host interacts with your effect.
2. The super rare container plug-in is now properly documented and supported, see VST_EFFECT_CATEGORY_CONTAINER for more information. Note that hosts may not actually support container plug-ins so it is not a safe option to use.
3. Effect flags were moved into their own enumeration named VST_EFFECT_FLAG
4. Discovered an alternative bypass functionality that many VST 2.3+ hosts implement that is enabled by returning VST_STATUS_TRUE from the VST_EFFECT_OPCODE_SUPPORTS query for bypass. This alternative mode requires the plug-in to handle the whole bypass code instead of having the host handle it. Could be useful for effects that require a constant feed of data or they regain their initial delay. See documentation for vst_effect_supports.bypass for more information.
5. Found a few hosts that implement the old VST 2.3 behavior instead of the new VST 2.4 behavior. These hosts expect us to implement VST_EFFECT_OPCODE_IDLE and have optional support for VST_EFFECT_PROCESS_BEGIN and VST_EFFECT_PROCESS_END. You can query the host for support using startStopProcess, see vst_host_supports.startStopProcess. I recommend an additional host version check when the plug-in is loaded to ensure that you are in a 2.4 or later host.
6. Added #defines for the actual default values that VST 1.x and 2.x expects your plug-in to default to as VST_DEFAULT_SAMPLE_RATE and VST_DEFUALT_BLOCK_SIZE. Hosts are not required to change the sample rate of your plug-in to match these defaults, but many of them do as a safety precaution.

Custom Editor Changes

1. vst_rect_t is now in the correct counter-clockwise order as defined by Steinberg instead of the same order as RECT from WinAPI. Adjust your code accordingly.
2. A lot of effect op-codes had their documentation improved or entirely replaced in order to improve the code.
3. For automatable parameters we must notify the host about changes using the new VST_HOST_OPCODE_AUTOMATE op-code. This expects the parameter index as well as a float representation of the value - even for integer parameters.
4. For all parameters we need to notify the host that the user has started or stopped editing a parameter in our user interface using VST_HOST_OPCODE_PARAM_START_EDIT and VST_HOST_OPCODE_PARAM_STOP_EDIT.
5. On Mac OS we can request that the host redraws the editor window using VST_HOST_OPCODE_EDITOR_UPDATE. Doesn't appear to be supported by all hosts as many just ignore it.

Parameter Changes

1. The final flag is now properly documented as VST_PARAMETER_FLAG_RAMPING. It allows the host to gradually increase/decrease the value of a parameter if it is automated instead of snapping to the target value immediately.
2. The float value representing a parameter is expected to be normalized inclusively between 0.0 and 1.0 in quite a lot of hosts. I'm not yet sure if this also affects integer parameters that are converted to floats.
3. A new op-code VST_EFFECT_OPCODE_PARAM_VALUE_FROM_STRING is added that allows the host to set a parameter from a string. This complements VST_EFFECT_OPCODE_PARAM_GET_VALUE which is used to do the opposite. The functions set_parameter and get_parameter appear to be only used for parameters that are automatable but not all hosts respect this and usually the functions have priority.

Program/Bank Changes

1. Added the VST_EFFECT_FLAG_CHUNKS flag to indicate support for saving and loading of banks and programs. Take a look at VST_EFFECT_OPCODE_SET_CHUNK_DATA and VST_EFFECT_OPCODE_GET_CHUNK_DATA for further information. A bank appears to be a collection of program data.
2. Added the op-codes VST_EFFECT_OPCODE_PROGRAM_SET_BEGIN and VST_EFFECT_OPCODE_PROGRAM_SET_END which are called by the host to notify the plug-in that the host is now loading a program. These have no parameters so it's likely for the currently selected program.
3. Added the op-code VST_EFFECT_OPCODE_PROGRAM_LOAD which is sent prior to the op-codes in (2), but it uses a yet unknown structured format.

Input/Output Changes

1. It is now possible to ask the host if it supports dynamic input/output changes via the VST_HOST_OPCODE_SUPPORTS query for acceptIOChanges. If it returns true from this we can emit VST_HOST_OPCODE_IO_MODIFIED after we adjust the num_inputs, num_outputs, num_programs and/or delay values in our effect. This behavior is only valid while we are currently idle so it can't be tied to anything that would be automatable. Depending on the host an idle plug-in is either receiving VST_EFFECT_OPCODE_IDLE or currently between the VST_EFFECT_OPCODE_PROCESS_END and VST_EFFECT_OPCODE_PROCESS_START group. See vst_host_supports.acceptIOChanges for more information.
2. Speaker properties now have placement definitions for the speakers using Azimuth, Altitude and Distance for proper mixing support. These appear to be ignored if the speaker is not of a custom type.
3. Additional valid speaker arrangements were found for 4.0, 5.0 and 7.1.
4. Fixed the definition for speaker types incorrectly claiming the Rear Surround speakers are Side speakers. Adjust your code accordingly to support proper 4.0/5.0/5.1 audio.
5. Figured out that the VST_EFFECT_OPCODE_INPUT_GETCHANNELNAME and VST_EFFECT_OPCODE_OUTPUT_GETCHANNELNAME actually point to a structure describing each input/output stream. Therefore a new structure was created called vst_stream_properties_t that should be used to describe each input/output stream that you support. Seems to be used by the host for num_inputs and num_outputs. The new op-codes are VST_EFFECT_OPCODE_INPUT_GET_PROPERTIES and VST_EFFECT_OPCODE_OUTPUT_GET_PROPERTIES.

[Xaymar]

Migration Guide v0.3.0 to v0.3.1

Generic Changes/Updates

• The project now has an online documentation available at https://github.xaymar.com/vst2sdk/
• Many hosts expect float Parameters to be normalized within 0.0 and 1.0, even when a custom editor is provided.

Effect Changes/Updates

• Figured out that some hosts treat plug-ins in different categories with varying behavior so make sure that your plug-in is in the correct category.
• Added missing default enum entries to VST_EFFECT_FLAG.
• Split the function pointer definition from the class into individual typedefs instead. Doesn't require a code change, it just looks nicer in doxygen.
• Added a newly discovered entry point for MacOS PowerPC support that was used from VST 2.3 onwards it seems.

Parameter Changes/Updates

• Fixed VST_EFFECT_OPCODE_PARAM_PROPERTIES being set to the wrong number. Don't code while sleepy.

Host Changes/Updates

• Added VST_HOST_OPCODE_PARAM_UPDATE to stick with the same naming scheme.
• vst_host_callback_t now also has the proper VST_FUNCTION_INTERFACE declaration.

Input/Output Changes

• Actual positions for Azimuth and Altitude were found and added to the documentation.

[Xaymar]

Migration Guide v0.3.1 to v0.3.2

• Fixed an incorrect definition in vst.hpp. Somehow clang++ was happy with it despite the type not existing.

[Xaymar]

Migration Guide v0.3.2 to v0.3.3

• Host Op-Codes are now using the correct index instead of being off by exactly 1. This was caused by my initial decimal to hex conversion being off by exactly that much...

[Xaymar]

Migration Guide v0.3.3 to v0.3.4

• I missed one of the op-codes that was offset by 1. VST_HOST_OPCODE_IO_MODIFIED should now work as expected.