Capability types (#425)

The capability syntax is now much more versatile: Every capability defines a
type and some type-specific (machine readable) properties. This enables us to
write better export plugins, e.g. with information for 3D previews.

Author: fxedel

.eslintrc.json

@@ -31,7 +31,7 @@
     "consistent-return": "error",
     "curly": ["error", "all"],
     "dot-location": ["error", "property"],
-    "dot-notation": "error",
+    "dot-notation": ["error", { "allowPattern": "^if$" }],
     "eol-last": ["error", "always"],
     "eqeqeq": ["error", "always", { "null": "ignore" }],
     "func-call-spacing": "error",

docs/capability-types.md

@@ -76,14 +76,56 @@ All channels that are used in one or more modes are listed in `availableChannels
 
 A channel's `defaultValue` is the DMX value that this channel is set to without the user interacting (most often, this will be `0`, but e.g. for Pan and Tilt channels, other values make more sense). Likewise, `highlightValue` specifies the DMX value if a user *highlights* this channel (defaults to the maximum DMX value). This is not available in every software.
 
-`invert` is used to mark a descending value (e.g. Speed from fast to slow). If `constant` is `true`, the channel cannot be changed. Set `crossfade` to `true` if you want to allow smooth transitions between two DMX values being output by the software. This is e.g. not recommended for Gobo wheels, as there can be no *smooth* transition to another Gobo; the wheel will always rotate.
-
-`precedence` specifies to which value the channel should be set if there are two conflicting active cues containing this channel: *HTP* (Highest takes precedence) or *LTP* (Latest (change) takes precedence).
+If `constant` is `true`, the channel cannot be changed. `precedence` specifies to which value the channel should be set if there are two conflicting active cues containing this channel: *HTP* (Highest takes precedence) or *LTP* (Latest (change) takes precedence).
 
 
 #### Capabilities
 
-A channel can do different things depending on which range its DMX value currently is in. Those capabilities can be triggered manually in many programs, and the `menuClick` property defines how: `start` / `center` / `end` sets the channel's DMX value to the start / center / end of the range, respectively. `hidden` hides this capability from the trigger menu.
+A channel can do different things depending on which range its DMX value currently is in. Those ranges, that can be triggered manually in many programs, are called capabilities. Choose a `type` to declare which property of the fixture is changed by this capability, e.g. `ShutterOpen`, `Intensity` or `Pan`. Depending on the type, there exist more properties that further describe the capability, like the pan angle, the strobe rate or the gobo wheel index. Most of these are physical entities that require to be entered using specific units (like `"10.5Hz"` or `"100%"`). Some entities offer keywords to replace specific percentage values, e.g. Distance: `"near"` = `"1%"`, `"far"` = `"100%"`. See the [full list of units, entities and capability types with their properties](capability-types.md). Example:
+
+```js
+"availableChannels": {
+  "Shutter": {
+    "capabilities": [
+      {
+        "dmxRange": [0, 20],
+        "type": "ShutterStrobe",
+        "shutterEffect": "Closed",
+        "comment": "Blackout"
+      },
+      {
+        "dmxRange": [21, 255],
+        "type": "ShutterStrobe",
+        "shutterEffect": "Open"
+      }
+    ]
+  }
+}
+```
+
+If a channel consists of a single 0-255 capability, one should use the `capability` property (instead of `capabilities`), which only needs a single object instead of an array of objects. The `dmxRange` is implicit in this object (see example below).
+
+Capabilities may be _steps_, which means that the whole DMX range has the same effect (e.g. "Gobo 1"), or _proportional_, which means that the effect is increasing / decreasing from the start to the end of the DMX range (e.g. "Intensity 0-100%"). A proportional capability can define a start and an end value of its type-specific properties. Example:
+
+```js
+"availableChannels": {
+  "Pan": {
+    "capability": {
+      "type": "Pan",
+      "angleStart": "0deg",
+      "angleEnd": "530deg"
+
+      // DMX value 0 -> 0°
+      // DMX value 127 -> 264°
+      // DMX value 255 -> 530°
+    }
+  }
+}
+```
+
+Please note that some properties don't allow start/end values, for example `hold`.
+
+The `menuClick` property defines which DMX value to use if the whole capability is selected: `start` / `center` / `end` sets the channel's DMX value to the start / center / end of the range, respectively. `hidden` hides this capability from the trigger menu. This is one of those special features that are supported only by some lighting programs.
 
 
 #### Fine channels
@@ -173,9 +215,11 @@ To reuse similar channels for each pixel or pixel group (like "Red 1", Red&
 ```js
 "templateChannels": {
   "Red $pixelKey": {
-    "type": "Single Color",
-    "color": "Red",
-    "fineChannelAliases": ["Red $pixelkey fine"]
+    "fineChannelAliases": ["Red $pixelKey fine"],
+    "capability": {
+      "type": "ColorIntensity",
+      "color": "Red"
+    }
   }
 }
 ```