Basic structure (DDF-Syntax) DMXC3

From English DMXC-Wiki
Books.png Basic structure (DDF-Syntax) DMXC3 Article describes
DMXControl 3.2.3
Arrow back.png General introduction
Function elements Arrow forw.png
Table of Contents
Part 1: Basics
Part 2: Functions
Part 3: Procedures
Part 4: Examples


Basic structure of the DDF

The DDF for DMXControl 3 consists of four parts:

  • Basic information with fundamental information about the DDF itself, such as DDF version and image
  • Information with details about the device, manufacturer, author, and DMX mode
  • Functions with the functions of each DMX channel and their respective value ranges
  • Procedures for special device functions such as reset or turning lamps on or off
<?xml version="1.0" encoding="utf-8"?>
<device image="image.png" type="DMXDevice" dmxaddresscount="1" dmxcversion="3.2.3" ddfversion="1.0.0" subdevice="no">
  <information>
     ...
  </information>
  <functions>
     ...
  </functions>
  <procedures>
    ...
  </procedures>
</device>

In particular, the second part is important for the preparation of the DDF by the Graphical User Interface (GUI) to ensure that all controls such as the Device Control and the Control Panel are displayed correctly. Furthermore, the Hardware Abstraction Layer (HAL) relies on this information to store the set light moods in the Cues of a project.

Functional components

Basic information

The basic part of the DDF contains general information about the file and the device element. The device tag includes the following attributes:

Attribute Description Default Value Allowed Values Optional
image Image file of the DDF Not present File name of the image as a *.png file
type DMXDevice DMXDevice
General information about the DDF
dmxaddresscount Total number of DMX channels of the device Not present Whole numbers from 1 to 512 X
dmxcversion Required program version for using the DDF 3.0.0 3.0.2, 3.1.3, 3.2.0, and all future program versions
ddfversion Version of the DDF Not present 1.0.0, 1.1.0, 1.2.0, etc.
subdevice Additional device for an existing device, such as a color scroller for classic PAR fixtures no no or yes X
Control of the display in the Stage View
defaultdisplaystyle Default display mode in the Stage View preview custom, image, or preview X
defaultdisplaycolor Starting point of the light color of the device's lamp #ffffff Any HTML color (#000000 - #ffffff) X
Attributes for addressing RGB+ colors
whitechanneldefaultmode Behavior of how the white channel is addressed onlywhite none, addwhite, or onlywhite X
amberchanneldefaultmode Behavior of how the amber channel is addressed onlywhite none, add, or only X

The device element encapsulates all information of the DDF. Entries outside of the tag lead to errors when inserting the DDF into a project.

When entering the file name for the icon in the Stage View, only the file name including the file extension should be used. The path is not required.

Operation of additional LED colors

All additional LED colors such as white, amber, UV, etc., which are installed in addition to the RGB LEDs in the device, are not activated by default after adding the device to a project. In the properties of the device, accessible for example via the Stage View, under the entry Automix Mode, the behavior can be adjusted individually for each device, here using the example of the white LED:

  • None: No activation of the white LED (default setting)
  • Add white: All four LEDs at 100% for the color white
  • Only white: Only white LEDs at 100% for the color white

Device information

In the information part, all basic information about the device for which the DDF was created is stored. This information is also used to sort the new DDF in the Add Device dialog. All information is enclosed by the element <information> ... </information>.

Tag Description Optional
model Designation of the device according to the user manual
vendor Manufacturer of the device according to the predefined manufacturer list
author Author of the DDF
mode DMX
mode or channel assignment || X
electrical Electrical power consumption of the device X
comment Comment on the DDF or device X

Electrical power consumption

The electrical tag in the <information> block allows the optional specification of the electrical power consumption by the device. DMXControl 3 uses this information for Power Management to calculate the theoretical total power of the available power sources at the venue. There are two types of power consumption that DMXControl 3 works with:

  • Constant (static) power consumption
  • Dynamic power consumption

The constant (static) power consumption is defined via the static tag. The constant power consumption includes in particular moving heads or scanners with a discharge lamp as the light source. Here, the power consumption does not change, regardless of whether the shutter and dimmer of the device are open or not. The constant power consumption also includes the power consumption of the electronics itself when the device is switched on and ready for operation.

The dynamic power consumption corresponds to the value of the device's dimmer. This constellation is especially found in classic halogen fixtures connected to dimmer packs. In addition, DMXControl 3 can calculate the theoretical power consumption when dimming LED fixtures and moving heads, if the values are also maintained in the dimmer tag.

Variant Code
PAR fixtures with a 1,000 Watt lamp
<electrical>
  <dimmer>1000</dimmer>
</electrical>

Increasing power consumption of the device with a maximum of 1,000 Watts at full brightness (Dimmer 100%).

Moving head with discharge lamp
<electrical>
  <static>450</static>
</electrical>

Constant power consumption of the device of 450 Watts.

LED fixture
<electrical>
  <static>20</static>
  <dimmer>145</dimmer>
</electrical>

After switching on, the device has a constant power consumption of 20 Watts. The LEDs are off (Dimmer 0%). The LEDs have a power consumption of 145 Watts at full brightness. In total, the device has a power consumption of 165 Watts.

Functions

The function part contains the actual functions of the device, such as Pan and Tilt, Dimmer, Color Wheel, Strobe, etc. The possible function components in detail, including code examples, are listed in the Syntax. All information is enclosed by the element <functions> ... </functions>.

Sub-functions of a DMX channel

Each individual function of a DMX channel can be expanded by a sub-function. The most prominent example is the Gobo shake, which can be activated in addition to the currently selected Gobo. This function is usually located on the same DMX channel as the function for selecting the Gobo, but typically in a different value range.

Additional functions for a DMX channel

In addition to the sub-functions, there are additional functions. These can either be on the same DMX channel, such as continuous rotation of the color wheel in a moving head or scanner. In the case of Gobo rotation, the additional function is on a separate DMX channel. Here, the first DMX channel selects the Gobo and the second DMX channel determines how fast the Gobo should rotate and in which direction.

Procedures

Procedures are only used to activate rarely used functions on the device, which are usually not required for live operation. Especially moving heads or scanners typically have functions for performing a reset or turning the lamp on or off. All these functions are executed when a certain DMX value on the corresponding DMX channel is held for a certain time. Procedures cannot be stored in scenes and can be accessed either via