Skip to content

Options

Jump to bottom
p0nce edited this page Oct 20, 2022 · 67 revisions

Options are Dplug's way to:

  1. Introduce optional breaking behaviour outside of a major tag. Such an option is a "future option" and will start with futureXXXX as a prefix.

  2. Maintain older behaviour after a breaking change, to ease transitions. Such an option is a "legacy option" and will start with legacyXXXX as 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.json top-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, 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.

Pending Dplug's Options

These options will be the default in the future. You can define the futureXXX version identifier to get the future behaviour in advance.

MouseDrag

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 isDragged widget receives onMouseDrag but not onMouseMove (previously: it would receive both).
  • During a mouse drag operation, the isMouseOver widget is locked to be the isDragged widget. 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.
  • Only the isMouseOver widget receive mouseMove callbacks. (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 try multiple instances and avoid futureMouseDrag until you get time for testing.

Accepted Dplug's Options

These options are now the default. But you can define the legacyXXX version identifier to get the previous behaviour.

VST2Chunks

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 presetbank tool built with Dplug v12.7.1 or superior.

ZOrder

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 use legacyZOrder if you don't have time to test.

MouseCursor

Name: futureMouseCursor or 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) and UIElement.setCursorWhenMouseOver(MouseCursor cursor) to have the proper cursor set in operation. Check the implementation of dplug.gui.context.UIContext.getCurrentMouseCursor() to see the selection algorithm.

AUHighResolutionParameters

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.

Removed Dplug options

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.

MouseOver

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.

BlinnPhong

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.

PBRNormals

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).

Clone this wiki locally