Documentation Center

Viz Engine Administrator Guide

Version 5.0 | Published December 20, 2022 ©

General Purpose I/O Commands

Viz Engine can send and receive frame accurate commands via General Purpose input/output (GPIO), provided the following requirements are met:

  • PCI or PCI Express Sealevel I/O device with eight, 16 or 32 digital inputs installed. Devices connected via Ethernet or USB cannot be used.

  • Viz Engine 3.3 (rev 8394) or later to receive commands.

  • Viz Engine 3.8.2 to send commands.

  • A Matrox X.mio-series video board is required for getting the actual field which is played out.

This section contains information on the following topics:

Input Functionality

Currently, there are five commands available which enable you to queue commands for execution when a pin on the Sealevel board shows a raising or falling edge. For every Pin, an arbitrary amount of commands can be queued for the raising and falling event. Every command can be armed with a counter which tells Viz Engine how often the command should be executed before it is removed from the queue. A counter of 0 tells Viz Engine that the command should never be removed from the queue.

The following diagram illustrates the Flow of the GPI signal from the sender until the consequences of the executed command are rendered into the correct position in the Matrox ringbuffer. As soon as a GPI sender changes the status of a pin, connected to the Sealevel device, the change is reflected in an internal register of the card. In Viz Engine, a thread polls this register every millisecond. As soon as a change is found it calculates the timestamp for when the command should be executed.

The thread looks for the pin command in the Command map and queues the command into the Timestamped commands queue. As the actual depth of the Matrox ringbuffer, known the render loop, checks every field if it is time to execute a command from the queue. This guarantees that the command is executed at the correct field, no matter how large or full the ringbuffer actually is.

Flow of the GPI signal

images/download/attachments/50615917/fac_favc_gpi.png

Output Functionality

Since version 3.8.2, Viz Engine is able to send external triggers via GPIO on systems with a supported Sealevel GPI/O card installed, using the GPO Command - Set. Depending on the GPI/O card configuration in the Sealevel driver, the first configured output channel could reside in a higher bank. For example, bank 2 -> first channel = 16.

Note: Only one channel can be sent at a time.

Commands

The following are the available GPIO commands:

Pin Command - Set

VIZ_COMMUNICATION*GPI_PIN_COMMAND SET ”<Command ID> <Command>” <PIN> <UP_DOWN> <COUNT>

Adds a command to the queue.

Example: VIZ_COMMUNICATION*GPI_PIN_COMMAND SET "-1 RENDERER*MAIN_LAYER*STAGE START" 0 1 0

  • <Command ID>: The command ID specifier.

  • <Command>: Command string which should be queued.

  • <PIN>: Input pin number (valid from 0-31) where the first Pin is 0.

  • <UP_DOWN>: 0 means the command should be executed on a falling edge, 1 means the command should be executed on a raising edge.

  • <COUNT>: Executes the command <Count> times. The command executes once per event and NOT <Count> times per event. A value lower or equal to 0 means that the command is never removed from the queue.

  • Remarks: After the GPI event occurs, the execution time of the command is calculated. The execution time is calculated in the following way: Ring_Buffer_Size*2+7+Delayed_Command_Bias. The <Delayed_Command_Bias> can be set in the Viz Config file.
    Therefore, Ring_Buffer_Size*2+7 is the minimum delay for GPI triggered commands.

Command - Clear

VIZ_COMMUNICATION*GPI_PIN_COMMAND CLEAR <PIN> <UP_DOWN>

Clears all commands from the queue.

  • <PIN>: Input Pin number (valid from 0-31) where the first Pin is 0.

  • <UP_DOWN>: 0 simulates a command executed on a falling edge, 1 simulates a command executed on a raising edge.

Information - Get

VIZ_COMMUNICATION*GPI_INFO GET

Sends information on the installed GPI device. If a valid device is present, the command returns the number of available GPI Banks. Therefore a value of 1 means that one bank (eight inputs) is available. If the command returns 0 no valid GPI device is present.

Pin Command - Test

VIZ_COMMUNICATION*GPI_PIN_COMMAND TEST <PIN> <UP_DOWN>

Sends all queued commands for the pin and signal to the Viz Engine. The counter for the commands is not decremented.

  • <PIN>: Input Pin number (valid from 0-31) where the first Pin is 0.

  • <UP_DOWN>: 0 means the command should be executed on a falling edge, 1 means the command should be executed on a raising edge.

Enable - Set

GLOBAL*GPI_ENABLE SET <1 or 0>

Enables or disables GPI commands for the Viz Engine. All functionality is available except of sending the commands on a GPI signal. If disabled, the command is shown in the console and a warning is shown, that GPI is disabled. The TEST command is working as usual, even if GPI is disabled.

  • 1 enables GPI execution

  • 0 disables GPI execution

GPO Command - Set

VIZ_COMMUNICATION*GPO_BIT SET <bit> <state>

Sets the specified output channel to either On or Off:

  • 1 is On.

  • 0 is Off.

The command can be sent directly via the Viz Engine command line, via an action keyframe, or DataPool plug-ins.

Example: send VIZ_COMMUNICATION*GPO_BIT SET 17 1

IMPORTANT! The bit count starts at 0.