Fixtures - QLC+

Overview

A Fixture in QLC+ represents a physical lighting device with one or more controllable parameters (channels). Fixtures are the building blocks of your lighting setup, mapping DMX channels to real-world lighting equipment.

QLC+ includes an extensive library of fixture definitions for commercial lighting products, and supports creating custom definitions for specialized equipment.

Fixture Fundamentals

Core Properties

Every fixture instance has these essential properties:

class Fixture {
    quint32 m_id;           // Unique fixture ID
    QString m_name;         // Friendly name
    quint32 m_address;      // DMX address (0-511) + universe
    quint32 m_channels;     // Number of channels
    bool m_crossUniverse;   // Can span multiple universes
};

Universe and Address

The address property combines both universe and DMX channel:

Universe: Stored in highest 7 bits (supports 128 universes)
Address: Stored in lowest 9 bits (0-511)

// Set universe (0-based)
fixture->setUniverse(0);

// Set DMX address (0-511, displayed as 1-512 in UI)
fixture->setAddress(0);

// Get combined address
quint32 universeAddress = fixture->universeAddress();

Fixture Definitions

What is a Fixture Definition?

A fixture definition describes the capabilities and channel layout of a lighting device:

class QLCFixtureDef {
    QString manufacturer;    // e.g., "Chauvet"
    QString model;          // e.g., "Intimidator Spot 375Z IRC"
    FixtureType type;       // MovingHead, Scanner, Dimmer, etc.
    QList<QLCChannel*> channels;
    QList<QLCFixtureMode*> modes;
};

Fixture Types

QLC+ supports various fixture types:

Dimmer

Simple intensity control

Moving Head

Pan, tilt, and effects

Scanner

Mirror-based movement

LED Bar

Multi-pixel RGB/RGBW strips

Strobe

Flashing effects

Smoke/Hazer

Atmospheric effects

Channels and Capabilities

Channel Groups

Channels are organized by function:

enum ChannelGroup {
    Intensity,    // Dimmer, master intensity
    Colour,       // Color wheels, CMY, RGB
    Gobo,         // Gobo wheels
    Prism,        // Prism effects
    Shutter,      // Strobe, shutter
    Beam,         // Zoom, focus, iris
    Speed,        // Effect speed
    Pan,          // Horizontal position
    Tilt,         // Vertical position
    Maintenance   // Reset, lamp control
};

Channel Capabilities

Capabilities define what a channel does at different value ranges:

class QLCCapability {
    uchar m_min;           // Minimum DMX value (e.g., 0)
    uchar m_max;           // Maximum DMX value (e.g., 127)
    QString m_name;        // Description (e.g., "Red")
    CapabilityResource m_resource;  // Color, gobo image, etc.
};

Example: Color wheel channel

Range	Capability
0-9	Open (white)
10-19	Red
20-29	Blue
30-39	Green
40-127	Split colors
128-255	Rotation

Fixture Modes

Many fixtures support multiple operating modes:

class QLCFixtureMode {
    QString m_name;                  // e.g., "16-bit", "Basic", "Extended"
    QVector<QLCChannel*> m_channels; // Channels in this mode
    QList<QLCFixtureHead> m_heads;   // Heads (for multi-head fixtures)
    QLCPhysical m_physical;          // Physical dimensions, power, etc.
};

Why Multiple Modes?

Channel count: Basic mode (8 channels) vs Extended mode (20 channels)
Precision: 8-bit vs 16-bit control
Feature sets: Simple operation vs advanced effects

Always select the mode that matches your fixture’s configuration. Using the wrong mode will result in incorrect control.

Fixture Heads

For multi-head fixtures (LED bars, pixel tubes), each head is a controllable unit:

class QLCFixtureHead {
    QVector<quint32> m_channels;  // Channels controlled by this head
    
    // Get RGB channel numbers for this head
    QVector<quint32> rgbChannels() const;
    
    // Get pan/tilt channel numbers
    quint32 panChannel() const;
    quint32 tiltChannel() const;
};

Example: 4-head LED bar

Head 1: Channels 0-3 (RGBW)
Head 2: Channels 4-7 (RGBW)
Head 3: Channels 8-11 (RGBW)
Head 4: Channels 12-15 (RGBW)

Generic Fixtures

Generic Dimmer

For simple intensity control without a specific definition:

QLCFixtureDef *def = fixture->genericDimmerDef(4);  // 4 channels
QLCFixtureMode *mode = fixture->genericDimmerMode(def, 4);
fixture->setFixtureDefinition(def, mode);

Generic RGB Panel

For custom LED pixel arrays:

// 10 pixels, RGB order, 8-bit
QLCFixtureDef *def = fixture->genericRGBPanelDef(10, RGB, false);
QLCFixtureMode *mode = fixture->genericRGBPanelMode(def, RGB, false, 100, 10);

Supported color orders: RGB, BGR, BRG, GBR, GRB, RBG, RGBW

Channel Behavior Customization

Exclude from Fade

Some channels shouldn’t fade (e.g., gobos, shutters):

fixture->setChannelCanFade(3, false);  // Channel 3 won't fade

Force HTP/LTP

Override default channel behavior:

QList<int> htpChannels = {0, 1};  // Force channels 0,1 to HTP
fixture->setForcedHTPChannels(htpChannels);

QList<int> ltpChannels = {2};     // Force channel 2 to LTP
fixture->setForcedLTPChannels(ltpChannels);

Channel Modifiers

Apply custom transformations to channel values:

ChannelModifier *modifier = new ChannelModifier();
modifier->setName("Invert");
modifier->addPoint(0, 255);
modifier->addPoint(255, 0);

fixture->setChannelModifier(5, modifier);  // Invert channel 5

Position Control

For moving heads and scanners:

// Pan/Tilt in degrees
QList<SceneValue> values = fixture->positionToValues(
    QLCChannel::Pan,   // Channel type
    180.0,             // Degrees
    false              // Absolute (not relative)
);

// Returns SceneValue for MSB and LSB channels
// Automatically handles 8-bit vs 16-bit control

Practical Example

// Create a fixture instance
Fixture *movingHead = new Fixture(doc);
movingHead->setName("Stage Left Mover");

// Set location in DMX space
movingHead->setUniverse(0);
movingHead->setAddress(0);  // Channels 1-20 in UI

// Load fixture definition
QLCFixtureDef *def = fixtureDefCache->fixtureDef("Chauvet", "Intimidator");
QLCFixtureMode *mode = def->mode("16-bit");  // 20 channels

if (def && mode) {
    movingHead->setFixtureDefinition(def, mode);
}

// Add to document
doc->addFixture(movingHead);

Working with Fixture Data

Query Fixture Information

// Get specific channel types
quint32 dimmerCh = fixture->channel(QLCChannel::Intensity);
QVector<quint32> rgbChs = fixture->rgbChannels(0);  // Head 0

// Get channel information
const QLCChannel *ch = fixture->channel(0);
qDebug() << ch->name() << ch->group();

// Check fixture type
if (fixture->type() == QLCFixtureDef::MovingHead) {
    // Handle pan/tilt
}

Monitor Fixture Values

// Store current DMX values
bool changed = fixture->setChannelValues(universeData);

if (changed) {
    // Read individual channel
    uchar value = fixture->channelValueAt(0);
    
    // Get all values
    QByteArray values = fixture->channelValues();
}

Best Practices

Use Fixture Definitions: Always prefer official definitions over generic dimmers
Plan Addressing: Leave gaps between fixtures for future expansion
Document Custom Fixtures: Create proper definitions for specialized equipment
Test Modes: Verify fixture modes match physical device settings
Group Logically: Organize fixtures by location or function

Universes - Understanding DMX universes and channel allocation
Functions - How to control fixtures with scenes and effects

Get Started

Core Concepts

Functions

Fixture Management

Virtual Console

Input/Output

Advanced Features

​Overview

​Fixture Fundamentals

​Core Properties

​Universe and Address

​Fixture Definitions

​What is a Fixture Definition?

​Fixture Types

Dimmer

Moving Head

Scanner

LED Bar

Strobe

Smoke/Hazer

​Channels and Capabilities

​Channel Groups

​Channel Capabilities

​Fixture Modes

​Why Multiple Modes?

​Fixture Heads

​Generic Fixtures

​Generic Dimmer

​Generic RGB Panel

​Channel Behavior Customization

​Exclude from Fade

​Force HTP/LTP

​Channel Modifiers

​Position Control

​Practical Example

​Working with Fixture Data

​Query Fixture Information

​Monitor Fixture Values

​Best Practices

​Related Concepts

Build docs developers (and LLMs) love

Overview

Fixture Fundamentals

Core Properties

Universe and Address

Fixture Definitions

What is a Fixture Definition?

Fixture Types

Channels and Capabilities

Channel Groups

Channel Capabilities

Fixture Modes

Why Multiple Modes?

Fixture Heads

Generic Fixtures

Generic Dimmer

Generic RGB Panel

Channel Behavior Customization

Exclude from Fade

Force HTP/LTP

Channel Modifiers

Position Control

Practical Example

Working with Fixture Data

Query Fixture Information

Monitor Fixture Values

Best Practices

Related Concepts