Function elements (DDF-Syntax) DMXC3

Function elements (DDF-Syntax) DMXC3

Article describes DMXControl 3.2.3

Basic structure of DDFs Basic rules of DDF creation Table of Contents Part 1: Basics General introduction Basic structure Basic rules Part 2: Functions Intensity Position Color Matrix Radix Gobo Lens Blade Shifter Effect wheel Stage effects Free Functions Part 3: Procedures Functions Examples Part 4: Examples LED Spotlight 4-Light Bar Moving Head

In addition to the general structure in the DDFs for DMXControl 3, there are various elements within the function part that are (almost) always used in all functions. These can be found in two places:

• There are various additional attributes for all functions, hereinafter referred to as function attributes. Some of these function attributes are mandatory in order to fully define the used function.
• Many functions require various subordinate function elements. These function elements define the value range of a DMX channel more precisely or establish predefined dependencies.

Function attributes

Mandatory attributes

dmxchannel: DMX channel

The attribute dmxchannel, including the variations finedmxchannel, ultradmxchannel, and ultrafinedmxchannel, specifies the DMX channel on which the corresponding function is located. In most cases, a function only has an 8-bit resolution, which is why the attribute dmxchannel is only needed in many places.

The reason why up to four attributes are needed to specify the DMX channel is that only a total of 256 different values can be transmitted on each DMX channel. The values range from DMX value 0 to DMX value 255. This describes the classical resolution or accuracy of a DMX channel of 8 bits. To achieve fine resolutions with certain functions such as Pan, Tilt, or Dimmer, additional DMX channels are used to increase the resolution. In this case, a resolution with 16 bits is referred to, or the second DMX channel for the Pan function is called Pan fine.

DMXControl 3 currently supports resolutions for all functions up to 32 bits. For this purpose, four DMX channels are combined to represent the function in this resolution. The following designations are used in the DDFs for this purpose:

• dmxchannel for 8-bit resolution
• finedmxchannel for 16-bit resolution
• ultradmxchannel for 24-bit resolution
• ultrafinedmxchannel for 32-bit resolution

It should be noted that in the case of 32-bit resolution, all four DMX channels must be specified. It is not uncommon for the four DMX channels to be arranged in the assignment not directly one after the other. The following table shows the definition of the currently possible resolutions for a device function exemplarily using the function "Dimmer".

Case	Code example
Device function with 8-bit resolution	<dimmer dmxchannel="0" /> Dimmer on DMX channel 1
Device function with 16-bit resolution	<dimmer dmxchannel="0" finedmxchannel="1" /> Dimmer with 16-bit resolution on DMX channels 1 and 2
Device function with 24-bit resolution	<dimmer dmxchannel="0" finedmxchannel="1" ultradmxchannel="2" /> Dimmer with 24-bit resolution on DMX channels 1, 2, and 3
Device function with 32-bit resolution	<dimmer dmxchannel="0" finedmxchannel="1" ultradmxchannel="2" ultrafinedmxchannel="3" /> Dimmer with 32-bit resolution on DMX channels 1, 2, 3, and 4

Optional attributes

defaultval: Initial value or default value

Upon request, it is possible to specify for a selection of functions which value they should assume, deviating from the standard definition in DMXControl 3. This is done via the defaultval attribute. This attribute can be used for the following functions:

• Intensity
• Switch
• Colortemp
• Focus
• Iris
• Zoom
• Index
• Rotation
• Raw
• Rawrange
• Rawstep

The value for the defaultval attribute must always lie within the range which is usually specified below. If a function defaults to the standard definition for the value range, the value for defaultval must accordingly lie between 0 and 1 or between 0 and 100.

Case	Code example
Default value for brightness	<dimmer dmxchannel="0" defaultval="25"/> If the Dimmer (Intensity) is not addressed, the Hardware Abstraction Layer (HAL) now sets the value for the Dimmer contrary to the standard definition to 25%.
Custom value for color temperature	<colortemp dmxchannel="0" defaultval="5500"> <range mindmx="255" maxdmx="0" minval="2500" maxval="9500"/> </colortemp> Color temperature can be set from 9,500 K at DMX value 0 decreasing to 2,500 K at DMX value 255 on DMX channel 1. If the function is not used and no specific value is stored in a scene, etc., instead of the standard value of 6,500 K, a color temperature of 5,500 K is set.
User-defined controller	<raw dmxchannel="0" name="Auto / music speed" defaultval="25"> <range type="linear" mindmx="0" maxdmx="255" minval="0" maxval="100" /> </raw> The standard speed of the automatic programs should be 25%. When specifying the range from 0% at DMX value 0 to 100% at DMX value 255, a DMX value of 63 is output by defaultval.

Function elements

The available function elements are generally used whenever multiple functions are accommodated on one DMX channel. These can be various strobe modes such as linear, random. In the case of a color wheel or a gobo wheel, the various colors and gobos must be specified. But even with a shutter, there are already two functions directly, namely closed and open.

To store all this in the DDF, various function elements are available. They define that

• switching between different functions on one DMX channel (step).
• a function can be changed when a controller is moved within a certain range (range).
• to use a specific function, another DMX channel must be set to a predefined DMX value (supporthandler).

Whether the mentioned function elements are needed depends on the respective function. If there is already a standard implementation directly in DMXControl 3, as is the case with the dimmer for example, the function elements can be completely omitted. If a function either has no standard implementation or one must deviate from it, the function elements step or range are used more or less mandatorily.

Function elements such as the supporthandler, however, are optional per se and therefore only used in certain application cases. Corresponding typical examples are listed for the respective functions.

Required function elements

step: Specification of individual steps

The step function element always consists of the actual step tag, the type attribute, and the attributes for the minimum DMX value mindmx and the maximum DMX value maxdmx for the step. The value for the type attribute always depends on the property of the DMX channel to be represented. The permissible values are specified when describing the respective function. It is important to know here that the HAL always takes the average value between mindmx and maxdmx. In relation to the following example, this would be the DMX value 227.

<step type="open" mindmx="200" maxdmx="255" />

range: Specification of an adjustable range

The range function element is structured similarly to the step function element. The most significant difference is the addition of the minval and maxval attributes. Here, for example, the following are specified:

• the minimum and maximum strobe frequency
• the minimum and maximum speed for gobo rotation
• the minimum and maximum beam angle of the zoom

The special feature here is that the DMX values are assigned to the speeds. This means that the minimum speed is entered for the DMX value where, for example, the gobo rotates slowest. The same applies to the maximum speed of the gobo. Therefore, it may happen that the minimum speed does not always automatically correspond to the low DMX value and the maximum speed to the highest DMX value. A code example can be found in the article Gobo Wheel. A clearer constellation, on the other hand, is shown in the following example for the strobe frequency, where the lowest DMX value 0 also outputs the lowest strobe frequency of 0.5 Hz.

<range type="linear" mindmx="0" maxdmx="255" minval="0.5" maxval="15" />

Optional function elements

supporthandler: Value-dependent control of DMX channels

Some devices have one or more functions that work according to the principle: "One selects the function on one DMX channel and controls the speed via a second DMX channel". An illustrative example here could be a gobo wheel with rotating gobos, which can also be indexed additionally. Here, three different functions are already present:

• Indexing of gobos
• Clockwise rotation
• Counterclockwise rotation

Via a first DMX channel, one selects one of the three functions, while the second DMX channel always works over its entire value range from 0 to 255 and determines the function such as

• specifying the indexing angle
• Rotation speed, from slow to fast clockwise
• Rotation speed, from slow to fast counterclockwise

To implement this scenario in a DDF for DMXControl 3, there is the so-called supporthandler. This always consists of two parts:

• specifying which DMX channel switches the function
• the addition to the definition where the actual value is set

In the case of the gobo wheel, the implementation for the function "Indexing of gobos" is built up as follows. The first part of the supporthandler is another line within the goboindex element, after it has been noted in the same context that this function is on DMX channel 3, so DMX channel 3 determines the actual value.

<goboindex dmxchannel="2">

This implementation corresponds to the normal implementation without the addition of the supporthandler. By specifying the line directly following

<support dmxchannel="1" name="goboindex" />

it is defined that the function switching takes place on DMX channel 2. The associated keyword is also goboindex, whereby any other value is also permissible here. Furthermore, the range for the function is specified again, as if one were working without the supporthandler. The line only differs in that for mindmx and maxdmx, the specified value range of the DMX channel that determines the value is used. Furthermore, the line is not closed with />, but left open.

<range range="360" mindmx="0" maxdmx="255" minval="0" maxval="360" >

In the following line, which is a subordinate element to the range element, it is specified on which

DMX value the DMX channel must be set to select the corresponding function, as soon as one uses the gobo indexing function, for example, in this example. In addition to the corresponding value range via the mindmx and maxdmx attributes, this line receives the second part of the supporthandler. This consists of the handler attribute and the keyword previously chosen. Here it is the keyword goboindex, which is deposited with the prefix support- as the value. With this, all definitions within this line are completed.

<step handler="support-goboindex" mindmx="0" maxdmx="15" />

The line specifying the DMX value for selecting the corresponding function must be added to every definition that requires a specific DMX value on the selection channel. In the case, for example, of gobo rotation, this means that this addition may need to be inserted three times: rotation clockwise, stop, rotation counterclockwise.

Subsequently, the remaining part for the implementation of gobo indexing is completed. In sum, the code snippet looks like this.

Case

Code example

Gobo Indexing

<gobowheel dmxchannel="0"> <goboindex dmxchannel="2"> <support dmxchannel="1" name="goboindex" /> <range range="360" mindmx="0" maxdmx="255" minval="0" maxval="360" > <step handler="support-goboindex" mindmx="0" maxdmx="15" /> </range> </goboindex> <step type="open" mindmx="0" maxdmx="15" caption="Open" /> <step type="gobo" mindmx="16" maxdmx="31" val="congostar.png" caption="Gobo 1" /> <step type="gobo" mindmx="32" maxdmx="47" val="sunburst.png" caption="Gobo 2" /> Gobo wheel on DMX channel 1, gobo indexing on DMX channel 3, selection of the "Gobo Indexing" mode via DMX channel 2: Activation of gobo indexing at a DMX value on DMX channel 2 between 0 and 15. Positioning / orientation of the gobo via DMX channel 3 at an angle between 0° at DMX value 0 and 360° at DMX value 255.

Further examples of using the supporthandler can be found in the articles on Color wheel and Gobo wheel.