-
Notifications
You must be signed in to change notification settings - Fork 32
Options
Options are Dplug's way to:
-
Introduce optional breaking behaviour outside of a major tag. Such an option is a "future option" and will start with
futureXXXXas a prefix. -
Maintain older behaviour after a breaking change, to ease transitions. Such an option is a "legacy option" and will start with
legacyXXXXas a prefix.
The vehicle for this is D version identifiers, that can be provided to DUB using "versions".
Example:
Put this line in your
dub.jsontop-level:"versions": ["futureMouseOver"],to get the new behaviour for mouse-over.
Configuration options are created as a last resort strategy. Every configuration option is breaking (either the UI or sessions), they exist to let you upgrade behaviour at your own pace, or to avoid breaking plug-in user sessions. This page is the reference to know what they are and if you need to take action.
If the project is using a very old Dplug, consider going through each Dplug majors one by one.
These options will be the default in the future. You can define the futureXXX version identifier to get the future behaviour in advance.
Name: futureVST3FolderWindows or legacyVST3FolderWindows
Goal: Follow the VST3 specification and best practices, and avoid single file VST3 binaries on Windows.
Introduced in: Dplug v14.4.0
Made default in: Not default yet.
What is breaking?
- This breaks user sessions and should only be enabled for new plug-ins (or a new major version).
- Installing such a plugin on-top of one without the option is undefined behaviour. There were no investigation as to which host may find the right plug-in, this is probably host-dependent.
- No effect for other OS.
Take-away: Enable this for new plug-ins and/or new major versions.
Update your dub recipe, and rebuild dplug-build on Windows to use futureVST3FolderWindows.
Name: futurePBREmissive or legacyPBREmissive
Goal: Avoid incorrect "white halos" in PBR UIs, have prettier glowing Emissive with a more modern look that allows more hues.
Introduced in: Dplug v14.1.6
Made default in: Not default yet.
What is breaking?
-
Linear Space Emissive: The Emissive pass will use blue noise and linear RGB samples to draw prettier glowing things. This is an improvement in visual quality in all cases.
However, highlights get more saturated than before. - Tone-mapping: Final colors above 1.0f will use a simple luma-based tonemapping to extend the dynamic range, which gives the graphics a more relaxed feeling. This can be tuned. Colors under 1.0f don't get affected.
- Diffuse mipmap above level 0 will be in fake-linear RGB (actually: squared sRGB) which gives Emissive highlights a more correct and saturated look instead of washing the colors out. So,
Mipmapcontract has changed, but normally you aren't usingdplug.graphics.mipmap.Mipmapyourself. - Nothing breaks if you're not using PBR (or Mipmaps).
Take-away: You can unlock superior PBR graphics that looks less dated, more relaxed, and more expressive. However, for existing UI it's not an automatic win and needs some kind of rework to avoid destroying a particular look.
In particular:
- the main issue is that your UI may be more saturated than it was, and look toyish.
- the larger potential highlights might need a larger value for
setUpdateMargin. As such, it is heavily recommended to check the new look with a large display.
Name: futureVST3MIDICC or legacyVST3MIDICC
Goal: Allow MIDI Pitch Bend, Channel Pressure, and Control Change in VST3 plugins that can receive MIDI, which is essential for synths.
Introduced in: Dplug v14
Made default in: Not default yet.
What is breaking?
Plug-in will expose 2080 fake parameters to the host, in order to support VST3 MIDI CC in the traditional way.
Yes, this is how everyone is doing it.
Adding parameters like that is a bit risky, also is changing the number of MIDI input channels from 1 to 16.
So this is considered BREAKING for user sessions, for lack of extensive testing.
Take-away: Enable this for new plug-ins not yet in the wild, that needs MIDI input. If a plugin doesn't have MIDI input, whereas or not this is enabled is indifferent.
Name: futureBinState or legacyBinState
Goal: Allows a plug-in to have an internal state, saved and restored by the host, beyond having Parameter. This is meant for sound samples, savetables, file paths, or arbitrary data in general. If BinState is used, the plugin must implement two new callbacks:
saveStaterestoreState
Those two callbacks respectively emit or parse an extra chunk of arbitrary binary state. This binary state must be plain old data, portable (defined endianness), and not contain pointers.
Introduced in: Dplug v14
Made default in: Not default yet.
What is breaking?
Plug-in with and without BinState are supposed to be incompatible.
Normally going with BinState should not break sessions made with a plugin without BinState, but this hasn't been tested very much. Once you begin to save extra chunks of data, you can't opt out of BinState.
Take-away: Read the documentation of Client.saveState and Client.loadState in client.d and be wary of concurrency. This is a treacherous API right now. Also look at the examples/distort to see how to use the new callbacks.
Name: futureMouseDrag or legacyMouseDrag
Goal: Currently, during a drag operation, you can still highlight other widgets. MouseDrag fixes a number of oddities concerning selection of widgets, and other widgets won't be highlightable while dragging.
Introduced in: Dplug v12
Made default in: Not default yet.
What is breaking?
A few oddities are fixed at once:
- During a mouse drag operation, the
isDraggedwidget receivesonMouseDragbut notonMouseMove(previously: it would receive both). - During a mouse drag operation, the
isMouseOverwidget is locked to be theisDraggedwidget. When the drag operation stop, another such widget is searched for. In other words: the mouse only leave a dragged widget when the drag is finished. Oftentimes, for correct display you might want to check if a widget isisMouseOverbut notisDragged. - Only the
isMouseOverwidget receivemouseMovecallbacks. (prevously: all widgets in the stack that contains the mouse).
Moreover, using this option breaks option legacyMouseOver.
Take-away: Check your UIs (drag everything) when upgrading to this option, or use legacyMouseDrag. Especially the more complex widgets are at risk of breaking. WARNING: this is quite tricky to test for, you should also try multiple instances and avoid futureMouseDrag until you get time for testing.
These options are now the default. But you can define the legacyXXX version identifier to get the previous behaviour.
Name: futureVST2Chunks or legacyVST2Chunks
Goal: Historically Dplug made the mistake of not using VST 2.4 chunks from the get go. Hosts save parameter values themselves.
Lack of chunks prevents saving arbitrary internal data in addition to parameters. Using chunks allows new types of plugins (samplers, convolution...) that required more data than provided by parameters. Fixing this does not improve the situation of parameters with regards to remapping, and it's not clear for removing/adding them. VST2Chunks does not yet introduce a new chunk format that would allow for internal custom state.
futureVST2Chunks enable VST2 chunks. legacyVST2Chunks leave them disabled, which is the original behaviour. Please use legacyVST2Chunks if you upgraded to Dplug v13, were not using futureVST2Chunks already, and do not provide a new major of your product.
Introduced in: Dplug v10
Made default in: Dplug v13
What is breaking?
- User sessions will break for the VST 2.4 format. This is VERY disrupting for the user, and you should not attempt to use chunks without providing an incompatible MAJOR version of your product.
-
WARNING When this option is enabled, and if you use host presets, you will need a
presetbanktool built with Dplug v12.7.1 or superior.
Name: futureZOrder or legacyZOrder
Goal: Precedently, widgets with identical z-order were ordered depending on their position in the children list. The first widget added being given preference. This is accidental, and contrary to what HTML and SVG do (subsequent elements are considered above).
futureZOrder fixes the Z order, but might be breaking . legacyZOrder leave the original, unintuitive equal Z order resolution.
Introduced in: Dplug v12
Made default in: Dplug v13
What is breaking?
- The new Z-order behaviour give preference to later widgets, reversing the scan order of children. It could break plugins unknowingly reliant on this bug.
Test your products by enabling the new behaviour, then check you can click on every widget correctly. Else uselegacyZOrderif you don't have time to test.
Name: futureMouseCursor or legacyMouseCursor (NEW Dplug_NoMouseCursor is an alias for legacyMouseCursor)
Goal: With the new mouse cursors, windowing will poll the mouse cursor required by graphics and will change it using OS calls. Previously, there were no mouse cursor change which is worse for the UX.
Introduced in: Dplug v9
Made default in: Dplug v10
What is breaking?
- Mouse cursor is now changing, and this needs to be checked on existing products. In doubt, use
legacyMouseCursor. - Widgets need to use the
UIElement.setCursorWhenDragged(MouseCursor cursor)andUIElement.setCursorWhenMouseOver(MouseCursor cursor)to have the proper cursor set in operation. Check the implementation ofdplug.gui.context.UIContext.getCurrentMouseCursor()to see the selection algorithm.
Name: futureAUHighResolutionParameters or legacyAUHighResolutionParameters
Goal: AUHighResolutionParameters enables kAudioUnitParameterFlag_IsHighResolution flag on AU plugins, which makes AU use higher resolution for parameters.
Introduced in: Dplug v9
Made default in: Dplug v10
What is breaking? AU wont check if kAudioUnitParameterFlag_IsHighResolution flag changed, so all existing automation will break. Use legacyAUHighResolutionParameters if you have existing products and don't want an incompatible version right now.
These options are the default, and the possibility to go legacy has been removed. If you really do need the former behaviour, use a former Dplug version.
Name: futureMouseOver or legacyMouseOver
Goal: MouseOver fixes occurence of several isMouseOver at once, which is confusing for users. The old behaviour is buggy (several widgets are seen as selectable at once), but fixing this can introduce priority bugs in the UI (ie. zOrder was secretly wrong) and it is really recommended to check UIs carefully.
Introduced in: Dplug v8
Made default in: Dplug v9
Choice removed in: Dplug v13
What is breaking? The fix force to be more correct with partially overlapping widgets, that do not disambiguate yet with contains and/or zOrder. If you don't, widget that were expecting to get isMouseOver might not get it because some incorrect, possibly invisible widget is overlapping them. The fix is usually to override contains for the invisible widget that takes isMouseOver for itself wrongly.
Take-away: Check your UIs when upgrading to Dplug v9, or use legacyMouseOver.
Name: futureBlinnPhong or legacyBlinnPhong
Goal: PassSpecularLight was using the Phong algorithm for specular highlight, but the Blinn-Phong algorithm is more commonly used, as it avoids a class of artifacts. The actual difference in graphics quality is very limited.
Introduced in: Dplug v9
Made default in: Dplug v10
Choice removed in: Dplug v13
What is breaking? Very small visual change in PBR plug-ins, on specular highlights. Small change in luminosity of the specular pass too.
Name: futurePBRNormals or legacyPBRNormals
Goal: PBRNormals enables a more accurate normal algorithm for PBR plug-ins, that use a modified RANSAC algorithm. This algorithm test 24 possible planes and weigth them depending on the number of neighbours they contain. To get the same performance, it's highly advised to have flat areas: there is an early exit if all neighbours of a pixel fall under the same plane. In Dplug v12, the slow RANSAC algorithm was replaced by a faster and better least-square plane-fitting method, which led to this options being removed.
Introduced in: Dplug v9
Made default in: Dplug v10
Choice removed in: Dplug v12
What is breaking? Small visual change in PBR plug-ins. Things will look a bit more schematic and detailed. Enable the use of rotating depth textures in PBR. This is also much slower if you have large PBR layer updates and the underlying surface isn't flat (Note: it is fast since v12).