Skip to main content

LED API

Overview​

The LED system in Matrix OS is very powerful and handles different layer, self timed update, and cross fade animations.

For some LED API, you can specific an layer ID. If you don't specify a layer ID, the API will use 255, which means the top most layer.

After making changes on the layer, it will only take effect and render onto the device by using the Update()

However, you can make your changes take effect immediately by write to layer 0, which is the active buffer. Your changes will be rendered to the device immediately. (Unless you pause the update with PauseUpdate(true)) This is great for real time rendering for like light show, but it might cause flickering and tearing. Also it will not be able to persevere if you create a new layer unless you copy the layer 0 to a layer first.

The header file for this API is part of os/MatrixOS.h and the implementation is in os/system/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​

void SetBrightnessMultiplier(string partition_name, float multiplier);

Applies a multiplier to the brightness of a specific partition.

Parameters:

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

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​

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

Fills a specific partition with a specified color. If the partition does not exist, it will just do nothing.

Each device have different partition, please refer to the device documentation for more information. For Mystrix, it has 2 partitions, Gain and 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.

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 = crossfade_duration);

Creates a new layer, optionally with a crossfade effect.

Parameters:

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

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 = crossfade_duration);

Destroys a layer, optionally with a crossfade effect.

Parameters:

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

Returns:

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

MatrixOS::LED::Fade​

void Fade(uint16_t crossfade = crossfade_duration, [`Color`](./Types/Color/)* source_buffer = nullptr);

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

Parameters:

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

MatrixOS::LED::PauseUpdate​

void PauseUpdate(bool pause);

Pauses or resumes auto timed buffer updates to the LEDs.

(Note: This means active buffer to the device. Not from layer buffer to active buffer. You always need Update() to apply changes from layer buffer to active buffer)

Parameters:

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

Comments