D-Pro Python programming guide

Discuss D-Pro Python macro programming, and post any new macros here!
Dave Brown [admin]
Posts: 2123
Joined: Sat Sep 15, 2012 4:53 pm
Has thanked: 5 times
Been thanked: 17 times

D-Pro Python programming guide

Post by Dave Brown [admin] »

Overview

D-Pro FX scripts are written in Python language. To be specific, D-Pro runs Python version 2.6. All the usual Python system libraries, functions and programming constructs are available within a Python FX script. The user can add FX scripts to a cue or palette from the programmer window.

A script can modify certain aspects of the cue/palette such as channel levels and oscillator settings. However, It is important to realise that FX scripts do not run in realtime, and can not directly manipulate the DMX data being generated. Think instead of FX scripts as programming macros - shortcuts that let the user quickly set up the levels, colours, positions etc of a number of fixtures.

Python FX script files are stored in the "Macros" folder of the D-Pro installation folder...
  • OSX : /Library/Application Support/ENTTEC/D-Pro*/Macros
  • Windows : C:/Program Files (x86)/ENTTEC/D-Pro*/Macros
How scripts are called

So when is a Python FX script actually run? Answer - whenever a cue is loaded into, or modified within, the programmer window or cuelist window.

D-Pro silently "renders" cues into simple blocks of DMX data on demand, by sequentially going through the cue as defined in the programmer, setting the various channel levels and running the Python scripts to create the data block. This simple block of DMX data is then passed into the core D-Pro DMX engine, for transmission to USB hardware or Art-Net. So, Python scripts are never actually run within the core engine.

The Show Control window deserves special explanation. When Show Control is opened, D-Pro immediately renders every cue & cuelist, once only. Thus, the Python FX scripts are only called once, when the window is opened. During the actual show, Python is never called and the DMX engine is simply transmitting pre-rendered blocks of data to the outputs. This "pre-rendering" of cues & cuelists in advance means that in Show Control mode, D-Pro requires very little CPU power and is inherently more reliable. A good thing for show time!

Two phase script design

FX scripts can expose parameters for display in the "Effect Params" panel in the programmer. This lets you for example modify the FX speed in near-realtime. This is achieved via a "two phase" script design...
  • The first phase is run when the user loads the FX script into the programmer. Phase one of your script creates the parameters that you need (sliders, radio buttons, colour selectors) in the programmer window. The script then exits.
  • The second phase is called when the user modifies a parameter, or when D-Pro needs to render the cue for the DMX core engine. This phase is the body of the script, which modifies fixture attributes.
The function QueryParams returns true if the script is running phase one. Here's a simple example - phase one displays a "Speed" slider in the programmer, and phase two gets the speed value and does something with it (displays the speed in the D-Pro main window):

Code: Select all

if QueryParams(): 
   # Phase one. Displays a Speed param in the programmer
   AddParam("Speed", " sec", 0.0, 60.0, 1.0, True)
   QueryParamsComplete()
	
else:
   # Phase two. Get the value of our param and display it on the D-Pro main window
   theSpeed = GetParamVal("Speed")
   print 'speed selected = %f' % (theSpeed)	
All D-Pro FX scripts follow this two-phase design. At this point, I recommend you scan through the factory FX to get a feel for the sort of things you can create. A full reference list for the various functions now follows...

Functions for phase one/two control

QueryParams()
  • Returns true if the script should specify its parameters to the programmer (phase one) or false if the script should execute (phase two).
  • No params, no return value
  • For example usage, see any factory script and the above tutorial
QueryParamsComplete()
  • Must be called at the end of phase one before the script exits.
  • No params, no return value
  • For example usage, see any factory script and the above tutorial
Functions for slider params

AddParam(string name, string suffix, float min, float max, float defaultVal, bool logarithmic)
  • Adds a floating point slider to the programmer. (Only use in phase one)
  • name = the string displayed above the slider
  • suffix = the string appended to the slider value
  • min,mac = the range of the slider
  • defaultVal = the value that the slider is set to by default
  • logarithmic = if true, the slider will be scaled for finer control over the lower values. Good for time parameters with large ranges
  • No return value
  • For example usage, see the above tutorial
float GetParamVal(string name)
  • Retrieve the current setting of a slider in the programmer. (Only use in phase two)
  • name = the name of the parameter (as initially passed to AddParam function)
  • Returns the current slider value as a floating point number.
  • For example usage, see the above tutorial
Functions for RGB colour picker params

AddColourParam(string name, int r, int g, int b)
  • Adds an RGB colour picker to the programmer. (Only use in phase one)
  • name = the string displayed above the colour picker
  • r/g/b = the defaultvalues for the red/green/blue values, range 0-255.
  • No return value
  • For example usage, see the 'Colour Fan.py' factory script.
int GetColourParamRed(string name)
int GetColourParamGreen(string name)
int GetColourParamBlue(string name)
  • Retrieve the red, green & blue values of an RGB colour picker in the programmer. (Only use in phase two)
  • name = the name of the colour picker (as initially passed to AddColour Param function)
  • Returns the current red, green or blue value as a 0-255 integer.
  • For example usage, see the 'Colour Fan.py' factory script.
Functions for radio box & drop down menu params

AddSwitch2(string name, string l1, string l2, int defaultVal)
  • Displays a two-way radio box parameter. (Only use in phase one)
  • name = the label displayed above the radio box
  • l1/l2 = the names displayed on the radio buttons
  • defaultVal = which radio button is selected by default (0 or 1)
  • No return value
  • For example usage, see the 'Shutter Chase.py' factory script.
AddSwitch3(string name, string l1, string l2, string l3, int defaultVal)
  • Displays a three-way radio box parameter. (Only use in phase one)
  • name = the label displayed above the radio box
  • l1/l2/l3 = the names displayed on the radio buttons
  • defaultVal = which radio button is selected by default (0...2)
  • No return value
  • For example usage, see the 'Attribute Oscillator.py' factory script.
AddSwitch4(string name, string l1, string l2, string l3, string l4, int defaultVal)
  • Displays a four-way popup menu parameter. (Only use in phase one)
  • name = the label displayed above the menu
  • l1/l2/l3/l4 = the names displayed on the menu entries
  • defaultVal = which menu entry is selected by default (0...3)
  • No return value
  • For example usage, see the 'Shutter Chase.py' factory script.
AddSwitch5(string name, string l1, string l2, string l3, string l4, string l5, int defaultVal)
  • Displays a five-way popup menu parameter. (Only use in phase one)
  • name = the label displayed above the menu
  • l1/l2/l3/l4 = the names displayed on the menu entries
  • defaultVal = which menu entry is selected by default (0...4)
  • No return value
  • For example usage, see the 'Shutter Chase.py' factory script.
int GetSwitchVal(string name)
  • Retrieve the current setting of a switch parameter (radio box or drop-down menu). (Only use in phase two)
  • name = the name of the parameter (as initially passed to the AddSwitchX function)
  • Returns the current switch value as an integer.
  • For example usage, see the 'Shutter Chase.py' factory script.
Other functions for displaying params

AddAttributeMenu(string name, int defaultVal)
  • Displays a radio box (or popup menu depending on available space) containing all attributes available in the currently selected devices. (Only use in phase one)
  • name = the label displayed above the menu
  • defaultVal = which menu entry is selected by default (0...number of attributes-1)
  • No return value
  • For example usage, see the 'Attribute Oscillator.py' factory script.
AddAttributeMenu(string name, int defaultVal)
  • Displays a radio box (or popup menu depending on available space) containing all attributes available in the currently selected devices. (Only use in phase one)
  • name = the label displayed above the menu
  • defaultVal = which menu entry is selected by default (0...number of attributes-1)
  • No return value
  • For example usage, see the 'Attribute Oscillator.py' factory script.
int GetAttributeVal(string name)
  • Retrieve the current setting of an attribute parameter. (Only use in phase two)
  • name = the name of the parameter (as initially passed to the AddAttributeMenu function)
  • Returns the index number of the selected attribute (suitable for passing into e.g. SetAttributeVal)
  • For example usage, see the 'Attribute Fan.py' factory script.
Query functions

int GetNumSelDevices()
  • Returns the number of fixtures currently selected in the Device Browser.
  • No params
  • Returns the selected fixture count
  • For example usage, see the 'Colour Fan.py' factory script.
bool hasDimmer(int deviceNo)
  • Checks if the specified device has a dimmer attribute.
  • deviceNo = the index of the selected fixture (0... number of selected fixtures-1)
  • Returns true (device has dimmer attribute) or false (device has no dimmer attribute)
float GetAttributeVal(int deviceIdx, int attributeIdx)
  • Returns the current value of a specific attribute on a specific fixture.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • attributeIdx = the index of ther desired attribute (0...number of attributes in fixture-1)
  • Returns the attribute value as a floating point number
  • For example usage, see the 'Attribute Fan.py' factory script.
Modify functions

SetAttributeVal(int deviceIdx, int attIdx, float newVal)
  • Modifies the current value of a specific attribute on a specific fixture.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • attributeIdx = the index of ther desired attribute (0...number of attributes in fixture-1)
  • newVal = the new attribute value (floating point)
  • No return value
  • For example usage, see the 'Attribute Fan.py' factory script.
SetRgbColour(int deviceIdx, int r, int g, int b)
  • Modifies the red/green/blue attributes of a specific fixture.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • r/g/b = the new red/green/blue values (0...255)
  • No return value
  • For example usage, see the 'Colour Fan.py' factory script.
SetDimmer(int deviceIdx, float level)
  • Modifies the dimmer attribute of a specific fixture.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • r/g/b = the new dimmer level (floating point 0.0 ... 1.0)
  • No return value
SetPanTilt(int deviceIdx, float pan, float tilt)
  • Modifies the pan & tilt attributes of a specific fixture.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • pan/tilt = the new pan & tilt values (floating point 0.0 ... 1.0)
  • No return value
Oscillator functions

The core DMX engine within D-Pro (and the D-Pro standalone engine available for the Enttec Datagate Mk2) supports per-channel oscillators. These can be manipulated in a number of creative ways from a Python script to create dynamic cues & palettes that change over time - for example, colour chases & moving head patterns.

OscAttribute(int deviceIdx, int attributeIdx, int wv, float period, float ph, float amplitude, float pw)
  • Oscillates one attribute on a specific device
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • attributeIdx = the index of ther desired attribute (0...number of attributes in fixture-1)
  • wv = the oscillator waveform to use (0-4, representing sine/square/triangle/saw up/saw down)
  • period = the time for one compete oscillation (in seconds)
  • ph = the phase of this oscillator (0.0 - 1.0)
  • amp = the amplitude of the oscillator (0.0 - 1.0)
  • pw = the pulse width of the waveform. Only relevant for squarewave oscillators.
  • No return value
  • For example usage, see the 'Attribute Oscillator.py' factory script.
OscDimmer(int deviceIdx, int wv, float period, float ph, float amp, float pw)
  • Oscillates the dimmer attribute on a specific device
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • wv = the oscillator waveform to use (0-4, representing sine/square/triangle/saw up/saw down)
  • period = the time for one compete oscillation (in seconds)
  • ph = the phase of this oscillator (0.0 - 1.0)
  • amp = the amplitude of the oscillator (0.0 - 1.0)
  • pw = the pulse width of the waveform. Only relevant for squarewave oscillators.
  • No return value
  • For example usage, see the 'Shutter Chase.py' factory script.
OscPan(int deviceIdx, int wv, float period, float phase, float amplitude, float pulseWidth)
OscTilt(int deviceIdx, int wv, float period, float phase, float amplitude, float pulseWidth)
  • Oscillates the pan & tilt attributes on a specific device.
  • deviceIdx = the index of the selected fixture (0... number of selected fixtures-1)
  • wv = the oscillator waveform to use (0-4, representing sine/square/triangle/saw up/saw down)
  • period = the time for one compete oscillation (in seconds)
  • ph = the phase of this oscillator (0.0 - 1.0)
  • amp = the amplitude of the oscillator (0.0 - 1.0)
  • pw = the pulse width of the waveform. Only relevant for squarewave oscillators.
  • No return value
  • For example usage, see the 'Shapes/Circles.py' factory script.
Dave Brown - db audioware
Author of Show Buddy Setlist | Show Buddy Active | ArtNetMon