View source for Basic structure (DDF-Syntax) DMXC3

{{Chaptertitle|Version=DMXControl 3.2.3}}

{{DMXC3_Manual-Navigation_DDF
|backLink = Introduction (DDF-Syntax) DMXC3
|backText = General introduction
|forwardLink = Function elements (DDF-Syntax) DMXC3
|forwardText = Function elements
}}


= 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

<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>

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

= Functional components =
== Basic information ==
The basic part of the DDF contains general information about the file and the <code>device</code> element. The <code>device</code> tag includes the following attributes:

{| class="wikitable toptextcells"
|- class="hintergrundfarbe6"
! Attribute !! Description !! Default Value !! Allowed Values !! Optional
|-
| style="width: 10em"| <code>image</code>
| style="width: 30em"| Image file of the DDF
| style="width: 10em"| Not present
| style="width: 20em"| File name of the image as a *.png file
| style="width: 10em"| 
|-
| <code>type</code>
|
| <code>DMXDevice</code>
| DMXDevice

{{DMXC3 Manual-Tablesection | S1 | 5 | General information about the DDF}}

| <code>dmxaddresscount</code>
| Total number of DMX channels of the device
| Not present
| Whole numbers from 1 to 512
| X
|-
| <code>dmxcversion</code>
| Required program version for using the DDF
| <code>3.0.0</code>
| <code>3.0.2</code>, <code>3.1.3</code>, <code>3.2.0</code>, and all future program versions
| 
|-
| <code>ddfversion</code>
| Version of the DDF
| Not present
| <code>1.0.0</code>, <code>1.1.0</code>, <code>1.2.0</code>, etc.
| 
|-
| <code>subdevice</code>
| Additional device for an existing device, such as a color scroller for classic PAR fixtures
| <code>no</code>
| <code>no</code> or <code>yes</code>
| X

{{DMXC3 Manual-Tablesection | S1 | 5 | Control of the display in the Stage View}}

| <code>defaultdisplaystyle</code>
| Default display mode in the Stage View
| <code>preview</code>
| <code>custom</code>, <code>image</code>, or <code>preview</code>
| X
|-
| <code>defaultdisplaycolor</code>
| Starting point of the light color of the device's lamp
| <code>#ffffff</code>
| Any HTML color (<code>#000000</code> - <code>#ffffff</code>)
| X

{{DMXC3 Manual-Tablesection | S1 | 5 | Attributes for addressing RGB+ colors}}

| <code>whitechanneldefaultmode</code>
| Behavior of how the white channel is addressed
| <code>onlywhite</code>
| <code>none</code>, <code>addwhite</code>, or <code>onlywhite</code>
| X
|-
| <code>amberchanneldefaultmode</code>
| Behavior of how the amber channel is addressed
| <code>onlywhite</code>
| <code>none</code>, <code>add</code>, or <code>only</code>
| X
|}

The <code>device</code> 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 {{Manual Windowcaption|[[Device Manager DMXC3|Add Device]]}} dialog. All information is enclosed by the element <code><information> ... </information></code>.

{| class="wikitable toptextcells"
|-
! Tag !! Description !! Optional
|-
| style="width: 10em" | <code>model</code> || style="width: 30em" | Designation of the device according to the user manual || style="width: 10em" | 
|-
| <code>vendor</code> || Manufacturer of the device according to the predefined manufacturer list || 
|-
| <code>author</code> || Author of the DDF || 
|-
| <code>mode</code> || DMX

 mode or channel assignment || X
|-
| <code>electrical</code>  || Electrical power consumption of the device || X
|-
| <code>comment</code> || Comment on the DDF or device || X
|}

=== Electrical power consumption ===
The <code>electrical</code> tag in the <code><information></code> block allows the optional specification of the electrical power consumption by the device. DMXControl 3 uses this information for {{Manual Windowcaption|[[Electricity_DMXC3|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 <code>static</code> 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 <code>dimmer</code> tag.

{| class="wikitable toptextcells"
|-
! Variant !! Code
|-
| style="width: 10em" | PAR fixtures with a 1,000 Watt lamp
| style="width: 60em" | <syntaxhighlight lang="xml">
<electrical>
  <dimmer>1000</dimmer>
</electrical>
</syntaxhighlight>
Increasing power consumption of the device with a maximum of 1,000 Watts at full brightness (Dimmer 100%).
|-
| Moving head with discharge lamp
| <syntaxhighlight lang="xml">
<electrical>
  <static>450</static>
</electrical>
</syntaxhighlight>
Constant power consumption of the device of 450 Watts.
|-
| LED fixture
| <syntaxhighlight lang="xml">
<electrical>
  <static>20</static>
  <dimmer>145</dimmer>
</electrical>
</syntaxhighlight>
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 <code><functions> ... </functions></code>.

=== 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
* the {{Manual Windowcaption|[[Stage View DMXC3|Stage View]]}} or
* the {{Manual Objectcaption|[[Procedure (Input Assignment) DMXC3|Procedure]]}} node in the {{Manual Windowcaption|[[Input Assignment DMXC3|Input Assignment]]}}.

[[de:Grundaufbau (DDF-Syntax) DMXC3]]
[[Category:DDF DMXControl 3]]