Skip to main content

​
Overview

RGB Matrix is a specialized function for controlling LED fixtures arranged in a grid or matrix layout. It uses algorithms and scripts to generate pixel-based effects like text scrolling, animations, and geometric patterns across the fixture group.
RGB Matrix requires fixtures to be organized in a Fixture Group that defines their physical layout (rows/columns).

​
When to Use RGB Matrix

LED Walls

Control LED panels arranged in matrix configurations

Pixel Mapping

Display images and videos on LED fixtures

Text Display

Scroll text messages across LED arrays

Geometric Patterns

Generate animated patterns like waves, spirals, and gradients

​
Key Components

​
Fixture Group

​
fixtureGroupID
quint32
ID of the Fixture Group defining the matrix layout. Required for RGB Matrix operation.
The Fixture Group defines:
  • Grid dimensions (width × height)
  • Fixture positions in the grid
  • Head mapping for multi-head fixtures

​
Algorithm

RGB Matrix uses RGBAlgorithm objects to generate patterns: 
class RGBAlgorithm {
public:
    enum Type {
        Script,   // JavaScript-based algorithms
        Image,    // Static or animated images
        Audio     // Audio spectrum visualization
    };
};

​
Control Modes

RGB Matrix supports different output channel types: 
enum ControlMode {
    ControlModeRgb,      // RGB color channels
    ControlModeWhite,    // White channel only
    ControlModeAmber,    // Amber channel only
    ControlModeUV,       // UV channel only
    ControlModeDimmer,   // Dimmer channel
    ControlModeShutter   // Shutter channel
};

​
Mode Descriptions

1

RGB Mode

Outputs to red, green, and blue channels (or CMY channels)
2

White/Amber/UV Mode

Outputs grayscale values to specific color channels
3

Dimmer Mode

Controls intensity channels, treating the pattern as brightness
4

Shutter Mode

Controls shutter channels with grayscale values

​
Class Methods

The RGBMatrix class (rgbmatrix.h:95) provides:

​
Basic Setup

// Set fixture group
void setFixtureGroup(quint32 id);
quint32 fixtureGroup() const;

// Set algorithm
void setAlgorithm(RGBAlgorithm* algo);
RGBAlgorithm* algorithm() const;

// Control mode
void setControlMode(ControlMode mode);
ControlMode controlMode() const;

​
Color Management

// Set color at index (up to 5 colors)
void setColor(int i, QColor c);
QColor getColor(int i) const;
QVector<QColor> getColors() const;

// Update color transitions
void updateColorDelta();
Most algorithms support 1-2 colors. Some advanced scripts can use up to 5 colors for complex gradients.

​
Algorithm Properties

Many algorithms expose custom properties: 
// Set algorithm property
void setProperty(QString propName, QString value);

// Get property value
QString property(QString propName);
Common properties:
  • orientation - Pattern direction
  • offset - Pattern start position
  • text - Text to display (text scripts)
  • image - Image file path

​
Duration Control

// Set step duration (time per frame)
void setDuration(uint ms);

// Set total duration (auto-calculates step duration)
void setTotalDuration(quint32 msec);
quint32 totalDuration();

// Get algorithm step count
int stepsCount() const;

​
Preview

Generate preview of the effect: 
void previewMap(int step, RGBMatrixStep *handler);

​
The RGBMap Structure

Algorithms generate an RGBMap - a 2D array of RGB values: 
typedef QVector<QVector<uint>> RGBMap;
Structure: 
RGBMap[y][x] = RGB color (uint)
  where:
    y = row (0 to height-1)
    x = column (0 to width-1)
    color = 0xRRGGBB format

​
Step Handler

The RGBMatrixStep class manages animation: 
class RGBMatrixStep {
public:
    // Current step management
    void setCurrentStepIndex(int index);
    int currentStepIndex() const;
    
    // Color transitions
    void calculateColorDelta(QColor startColor, 
                             QColor endColor, 
                             RGBAlgorithm *algorithm);
    
    void updateStepColor(int step, 
                        QColor startColor, 
                        int stepsCount);
    
    // Step progression
    bool checkNextStep(Function::RunOrder order, 
                      QColor startColor, 
                      QColor endColor, 
                      int stepsNumber);
    
public:
    RGBMap m_map;  // Current frame data
};

​
Tempo Synchronization

RGB Matrix supports beat-synced animation: 
// Set tempo type (Time or Beats)
setTempoType(Function::Beats);

// Duration interpreted as beat count
setDuration(4);  // 4 beats per cycle
Beat timing:
  • Step advances on each beat
  • Step duration calculated from BPM
  • Supports beat-to-beat synchronization

​
Dimmer Control (Legacy)

// Enable/disable dimmer control
void setDimmerControl(bool dimmerControl);
bool dimmerControl() const;
Dimmer control is legacy. Use ControlModeDimmer instead for consistent behavior.

​
Color Conversion

RGB Matrix includes grayscale conversion: 
// Convert RGB to grayscale using BT.601 weights
static uchar rgbToGrey(uint col);
Formula: gray = 0.299*R + 0.587*G + 0.114*B

​
XML Structure

<Function Type="RGBMatrix" ID="10" Name="Text Scroller">
  <Speed FadeIn="0" FadeOut="0" Duration="50"/>
  <Direction>Forward</Direction>
  <RunOrder>Loop</RunOrder>
  <Algorithm Type="Script">Text</Algorithm>
  <Color Index="0">4278190335</Color>  <!-- RGB as uint -->
  <Color Index="1">4278255360</Color>
  <ControlMode>RGB</ControlMode>
  <FixtureGroup>0</FixtureGroup>
  <Property Name="text" Value="Hello World"/>
  <Property Name="font" Value="Arial"/>
  <Property Name="orientation" Value="Horizontal"/>
</Function>

​
Built-in Algorithms

Common RGB scripts include:

​
Text Effects

  • Text: Scrolling text display
  • Text (Centered): Centered text display

​
Geometric Patterns

  • Stripes: Horizontal or vertical stripes
  • Gradient: Color gradient fill
  • Plasma: Plasma effect
  • Radial: Radial gradient

​
Animations

  • Balls: Bouncing balls
  • Waves: Wave patterns
  • Spiral: Rotating spiral
  • Fireworks: Firework effect

​
Images

  • Image: Display static image
  • Animated: Play animated GIF

​
Best Practices

1

Proper Grid Setup

Ensure fixture group accurately represents physical layout
2

Appropriate Step Duration

Balance between smoothness (short duration) and performance (longer duration)
3

Test Color Modes

Verify control mode matches your fixture channels
4

Use Fade In for Smooth Start

Set fade in time to avoid jarring effect start
5

Optimize Algorithm Properties

Adjust algorithm settings for best visual result

​
Channel Mapping

RGB Matrix intelligently maps to fixture channels: 
// RGB fixtures
if (hasRGB) {
    red_channel = rgbToRed(color);
    green_channel = rgbToGreen(color);
    blue_channel = rgbToBlue(color);
}

// CMY fixtures (automatic conversion)
if (hasCMY) {
    cyan_channel = 255 - red;
    magenta_channel = 255 - green;
    yellow_channel = 255 - blue;
}

// Dimmer channels
if (dimmerControl) {
    master_dimmer = rgbToGrey(color);
    head_dimmer = (color > 0) ? 255 : 0;
}

​
Performance Considerations

  • Large matrices (>100 pixels) require more CPU
  • Complex algorithms (Plasma, Fireworks) are CPU-intensive
  • Image algorithms need file I/O
  • Fade in/out adds fader overhead per channel
Very high frame rates (duration < 20ms) may cause timing issues on slower systems. Test performance before using in production.

​
Attributes

RGB Matrix supports intensity adjustment: 
int adjustAttribute(qreal fraction, int attributeId);
Intensity affects:
  • RGB channel output levels
  • Dimmer channel values
  • Overall brightness

​
Blend Modes

RGB Matrix supports blend mode control: 
void setBlendMode(Universe::BlendMode mode);
Useful for:
  • Layering multiple matrices
  • Additive color mixing
  • Masking effects

​
Algorithm Mutex

Thread-safe algorithm access: 
QRecursiveMutex& algorithmMutex();
Use when:
  • Changing algorithms during runtime
  • Accessing algorithm from multiple threads
  • Modifying algorithm properties

​
See Also

  • EFX - Position-based effects
  • Scenes - Static fixture states
  • Shows - Timeline-based shows with RGB matrices

Build docs developers (and LLMs) love

Get started for freeTalk to us