Skip to main content
Version: Matrix OS 4.0 🚧

LED API

Overview​

The LED API draws to Matrix OS LED layers and then pushes those changes to the device.

Most drawing functions take an optional layer. The default value, 255, means the current top layer. After drawing to a non-active layer, call MatrixOS::LED::Update() to render it.

Layer 0 is the active buffer. Writes to layer 0 can appear immediately, unless updates are paused with PauseUpdate(true), but direct active-buffer rendering can flicker or tear during fast updates.

The header file for this API is part of OS/MatrixOS.h and the implementation is in OS/LED/LED.cpp.

MatrixOS::LED::NextBrightness​

void NextBrightness();

Cycles to the next predefined brightness level for the LEDs.

MatrixOS::LED::SetBrightness​

void SetBrightness(uint8_t brightness);

Sets the brightness level of the LEDs.

Parameters:

  • brightness (uint8_t): Brightness level (0-255).

MatrixOS::LED::SetBrightnessMultiplier​

bool SetBrightnessMultiplier(string partitionName, float multiplier);

Applies a multiplier to the brightness of a specific partition.

Parameters:

  • partitionName: Name of the LED partition.
  • multiplier (float): Multiplier value for brightness.

Returns:

  • bool: true if the partition was found and updated.

MatrixOS::LED::SetColor (by position)​

void SetColor(Point xy, Color color, uint8_t layer = 255);

Sets the color of an LED at the specified position.

Parameters:

  • xy (Point): The position of the LED.
  • color (Color): The color to set.
  • layer (uint8_t, optional): The layer to apply the color to. Defaults to 255 - the top layer.

MatrixOS::LED::SetColor (by ID)​

void SetColor(uint16_t ID, Color color, uint8_t layer = 255);

Sets the color of an LED by its ID.

Parameters:

  • ID (uint16_t): The ID of the LED.
  • color (Color): The color to set.
  • layer (uint8_t, optional): The layer to apply the color to. Defaults to 255.

MatrixOS::LED::Fill​

void Fill(Color color, uint8_t layer = 255);

Fills all LEDs with a specified color.

Parameters:

  • color (Color): The color to fill with.
  • layer (uint8_t, optional): The layer to apply the color to. Defaults to 255 - the top layer.

MatrixOS::LED::FillPartition​

bool FillPartition(string partition, Color color, uint8_t layer = 255);

Fills a specific partition with a specified color. If the partition does not exist, the function returns false.

Each device can expose different LED partitions. Current Mystrix-class devices expose Grid; devices with underglow also expose Underglow.

Parameters:

  • partition: Name of the partition to fill.
  • color (Color): The color to fill with.
  • layer (uint8_t, optional): The layer to apply the color to. Defaults to 255 - the top layer.

Returns:

  • bool: true if the partition was found or the partition name was empty.

MatrixOS::LED::Update​

void Update(uint8_t layer = 255);

Updates the display with a specific layer.

Parameters:

  • layer (uint8_t, optional): The layer to update. Defaults to 255 - the top layer.

MatrixOS::LED::CurrentLayer​

int8_t CurrentLayer();

Returns the currently active layer.

Returns:

  • int8_t: The ID of the current layer.

MatrixOS::LED::CreateLayer​

int8_t CreateLayer(uint16_t crossfade = crossfadeDuration);

Creates a new layer, optionally with a crossfade effect.

Parameters:

  • crossfade (uint16_t, optional): Duration of the crossfade in milliseconds. Defaults to crossfadeDuration.

Returns:

  • int8_t: The ID of the newly created layer, -1 if the layer could not be created.

MatrixOS::LED::CopyLayer​

void CopyLayer(uint8_t dest, uint8_t src);

Copies content from one layer to another.

Parameters:

  • dest (uint8_t): Destination layer ID.
  • src (uint8_t): Source layer ID.

MatrixOS::LED::DestroyLayer​

bool DestroyLayer(uint16_t crossfade = crossfadeDuration);

Destroys a layer, optionally with a crossfade effect.

Parameters:

  • crossfade (uint16_t, optional): Duration of the crossfade in milliseconds. Defaults to crossfadeDuration.

Returns:

  • bool: true if the layer was successfully destroyed, otherwise false.

MatrixOS::LED::Fade​

void Fade(uint16_t crossfade = crossfadeDuration, Color* sourceBuffer = nullptr);

Fades the LED for a specific duration. You can also specify a buffer to fade from.

Parameters:

  • crossfade (uint16_t, optional): Duration of the crossfade in milliseconds. Defaults to crossfadeDuration.
  • sourceBuffer (Color*, optional): A buffer of colors to fade from. Defaults to nullptr, which means the current framebuffer.

MatrixOS::LED::PauseUpdate​

void PauseUpdate(bool pause = true);

Pauses or resumes auto timed buffer updates to the LEDs.

PauseUpdate() pauses active-buffer output updates by default. It does not replace Update(): changes made to a non-active layer still need Update() before they are rendered.

Parameters:

  • pause (bool): true to pause auto updates, false to resume.

Comments