This is the software documentation for using Pixie Chroma functions on Arduino! For full example usage, see File > Examples > Pixie_Chroma inside Arduino!. More...

#include <pixie_chroma_internal.h>

Public Member Functions
	PixieChroma ()
	Construct a Pixie Chroma class object. More...

void	begin (const uint8_t data_pin, uint8_t pixies_x, uint8_t pixies_y)
	Initializes the display buffer, populates the XY coordinate table, defaults the display colors to green, loads the default CRGBPalette, initializes FastLED, and sets the default power budget. More...

void	begin_quad (uint8_t pixies_per_pin, uint8_t pixies_x, uint8_t pixies_y)
	Initializes the display buffer, populates the XY coordinate table, defaults the display colors to green, loads the default CRGBPalette, initializes FastLED for Quad Mode, and sets the default power budget. More...

void	set_color_animation (void(action)(PixieChroma , float))
	Accepts a preset Color Animation or custom function to use for the animation ISR. More...

void	set_color_animation_speed (float speed)
	Used to scale the animation speed of animation ISRs that can use pix.animation_speed() to scale their speeds or for other effects. More...

void	set_brightness (uint8_t level)
	Takes an 8-bit brightness value and passes it to FastLED internally, to provide global brightness control with temporal dithering. More...

void	set_frame_rate_target (uint16_t target)
	Sets the target frame rate for animation. This target frame rate is only used to calculate `delta` in custom/preset animation functions. More...

void	set_gamma_correction (bool enabled)
	Allows you to enable built-in automatic gamma correction, using a fast LUT in pixie_utility.h. (Not enabled by default) More...

void	set_justification (t_justification justification, int16_t row=-1)
	Sets the text justification globally, or by row. More...

void	set_line_wrap (bool enabled)
	Sets the line wrapping behavior. More...

void	set_max_power (float volts, uint16_t milliamps)
	Sets the maximum power budget in volts and milliamps. More...

void	set_palette (const uint8_t *pal)
	Accepts a const uint8_t (8-bit) array to generate a FastLED Gradient Palette at runtime: More...

void	set_palette (CRGBPalette16 pal)
	Accepts a FastLED CRGBPalette16 object to set the current color palette for animation. More...

void	set_scroll_type (t_scroll_type type)
	Sets the scroll behavior: More...

void	set_update_mode (t_update_mode mode, uint16_t FPS=60)
	Allows for automatic show() calls at a specified frames per second if AUTOMATIC is used. (uses Ticker.attach_ms() internally) More...

void	add_char (char chr, int16_t x_pos, int16_t y_pos)
	Internal function for rendering a single char to the mask buffer. More...

void	add_char (uint8_t bitmap_col_1, uint8_t bitmap_col_2, uint8_t bitmap_col_3, uint8_t bitmap_col_4, uint8_t bitmap_col_5, int16_t x_pos, int16_t y_pos)
	Internal function for rendering a single bitmap to the mask buffer. More...

void	write (uint8_t bitmap_col_1, uint8_t bitmap_col_2, uint8_t bitmap_col_3, uint8_t bitmap_col_4, uint8_t bitmap_col_5, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a bitmap to a specified X and Y cursor position, taking five uint8_t as input for the column data. More...

void	write (char *message, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a char* string to a specified X and Y cursor position. More...

void	write (int16_t input, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a signed 16-bit integer to a specified X and Y cursor position. More...

void	write (uint16_t input, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes an unsigned 16-bit integer to a specified X and Y cursor position. More...

void	write (int32_t input, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a signed 32-bit integer to a specified X and Y cursor position. More...

void	write (uint32_t input, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes an unsigned 32-bit integer to a specified X and Y cursor position. More...

void	write (long unsigned int input, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes an unsigned 32-bit integer to a specified X and Y cursor position. ( Stupid ESP-specific type ) More...

void	write (float input, uint8_t places=2, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a single-precision floating point value to a specified X and Y cursor position, to a specified number of decimal places. More...

void	write (double input, uint8_t places=2, uint8_t x_pos=0, uint8_t y_pos=0)
	Writes a double-precision floating point value to a specified X and Y cursor position, to a specified number of decimal places. More...

void	write_pix (char *message, int16_t x_offset=0, int16_t y_offset=0)
	Internal function for rendering char* strings to the mask buffer. More...

void	write_pix (uint8_t bitmap_col_1, uint8_t bitmap_col_2, uint8_t bitmap_col_3, uint8_t bitmap_col_4, uint8_t bitmap_col_5, int16_t x_dest=0, int16_t y_dest=0)
	Internal function for rendering bitmaps to the mask buffer. More...

void	print (uint8_t bitmap_col_1, uint8_t bitmap_col_2, uint8_t bitmap_col_3, uint8_t bitmap_col_4, uint8_t bitmap_col_5)
	Prints a bitmap to the displays at the current cursor position, taking five uint8_t as input for the column data. More...

void	print (char chr)
	Prints a single char to the displays at the current cursor position. More...

void	print (char *message)
	Prints a char* string to the displays at the current cursor position. More...

void	print (int16_t input)
	Prints a signed 16-bit integer to the displays at the current cursor position. More...

void	print (uint16_t input)
	Prints an unsigned 16-bit integer to the displays at the current cursor position. More...

void	print (int32_t input)
	Prints a signed 32-bit integer to the displays at the current cursor position. More...

void	print (uint32_t input)
	Prints an unsigned 32-bit integer to the displays at the current cursor\ position. More...

void	print (long unsigned int input)
	Prints an unsigned 32-bit integer to the displays at the current cursor position. ( Dumb ESP-specific type ) More...

void	print (float input, uint8_t places=2)
	Prints a single-precision floating point value to the displays at the current cursor position, to a specified number of decimal places. More...

void	print (double input, uint8_t places=2)
	Prints a double-precision floating point value to the displays at the current cursor position, to a specified number of decimal places. More...

void	println (uint8_t bitmap_col_1, uint8_t bitmap_col_2, uint8_t bitmap_col_3, uint8_t bitmap_col_4, uint8_t bitmap_col_5)
	Prints a bitmap to the displays at the current cursor position, (taking five uint8_t as input for the column data) then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (char *message)
	Prints a char* string to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (int16_t input)
	Prints a signed 16-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (uint16_t input)
	Prints an unsigned 16-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (int32_t input)
	Prints a signed 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (uint32_t input)
	Prints an unsigned 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (long unsigned int input)
	Prints an unsigned 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. ( Stupid ESP-specific type ) More...

void	println (float input, uint8_t places=2)
	Prints a single-precision floating point value to the displays at the current cursor position (to a specified number of decimal places), then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

void	println (double input, uint8_t places=2)
	Prints a double-precision floating point value to the displays at the current cursor position (to a specified number of decimal places), then jumps to the next row in the Pixie display, similar to a newline '\n' character. More...

uint8_t	get_cursor_x ()
	Returns the cursor's X position. More...

int16_t	get_cursor_x_exact ()
	Returns the cursor's X position in exact pixel coordinates. More...

uint8_t	get_cursor_y ()
	Returns the cursor's Y position. More...

int16_t	get_cursor_y_exact ()
	Returns the cursor's Y position in exact pixel coordinates. More...

void	set_cursor (uint8_t x_position, uint8_t y_position=0)
	Sets the cursor position in a 2D context, in whole displays. More...

void	clear ()
	Clears (blackens) the current mask buffer and resets the cursor to 0,0. More...

void	free ()
	Unfreezes the current mask buffer in memory to allow showing updated text the next time show() is called. More...

void	hold ()
	Freezes the current mask buffer in memory to prevent showing unfinished text if show() automaticall fires during construction of the current display data. More...

void	show ()
	Processes 1D image data into truncated versions, sending them to the Pixie Chroma displays. More...

void	delay (uint32_t milliseconds)
	Custom delay() function from FastLED that allows automatic refreshing of the displays during a delay() call, allowing things like temporal dithering to continue to function properly while the microcontroller waits. More...

void	color (CRGB col)
	Sets the entire color buffer to a CRGB value. More...

void	color (CRGB col, uint8_t x, uint8_t y)
	Sets a specific display in the color buffer to a CRGB value. More...

void	color (CRGB col, int16_t x1, int16_t y1, int16_t x2, int16_t y2)
	Sets a rectangular area in the color buffer to a CRGB value. More...

void	print_color (CRGB col)
	All print() calls after a print_color() will be colored with this value. More...

CRGB	kelvin_to_rgb (uint16_t temperature)
	Approximates the conversion of a blackbody radiation temperature (i.e. 3500K) to a CRGB color object. More...

void	blur (fract8 blur_amount)
	Blurs the mask buffer in both axes by blur_amount. More...

void	blur_x (fract8 blur_amount)
	Blurs the mask buffer in the X axis by blur_amount. More...

void	blur_y (fract8 blur_amount)
	Blurs the mask buffer in the Y axis by blur_amount. More...

void	dim (uint8_t amount, bool reset_cursor=false)
	Darkens the mask buffer by an 8-bit amount. Optionally resets the cursor position. More...

void	color_blur (fract8 blur_amount)
	Blurs the color buffer in both axes by blur_amount. More...

void	color_blur_x (fract8 blur_amount)
	Blurs the color buffer in the X axis by blur_amount. More...

void	color_blur_y (fract8 blur_amount)
	Blurs the color buffer in the Y axis by blur_amount. More...

void	color_dim (uint8_t amount)
	Darkens the color buffer by an 8-bit amount. More...

void	draw_line_color (int16_t x1, int16_t y1, int16_t x2, int16_t y2, CRGB color)
	Draws a line in the color map using Bresenham's line algorithm. More...

void	draw_line_mask (int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t value=255)
	Draws a line in the mask buffer using Bresenham's line algorithm. More...

float	get_uv_x (int32_t x_pixel)
	Returns the X-axis UV coordinate for a given X-axis pixel position. More...

float	get_uv_y (int32_t y_pixel)
	Returns the Y-axis UV coordinate for a given Y-axis pixel position. More...

uint8_t	get_pixel_mask (int32_t x, int32_t y)
	Gets the mask value at a given pixel coordinate. More...

CRGB	get_pixel_color (int32_t x, int32_t y)
	Gets the RGB color value at a given pixel coordinate. More...

void	print_xy_table ()
	Prints the index table for the calculated XY map. Requires Serial.begin() first to function. More...

void	scroll_message (char *message, uint8_t row=0)
	Scrolls a message across the matrix by constructing it one character at a time in the dead-space outside the visible area and scrolling it in from the right. More...

void	set_pixel_mask (int32_t x, int32_t y, uint8_t value)
	Sets the mask value at a given pixel coordinate. More...

void	set_pixel_color (int32_t x, int32_t y, CRGB color)
	Sets the RGB color value at a given pixel coordinate. More...

void	shift_mask_x (int16_t amount, int16_t row=-1)
	Shifts the mask data by `amount` on the X axis. Useful for scrolling or justification! More...

void	shift_mask_y (int16_t amount)
	Shifts the mask data by `amount` on the Y axis. Useful for scrolling! More...

void	shift_color_map_x (int16_t amount, int16_t row=-1)
	Shifts the color_map data by `amount` on the X axis. Useful for scrolling or justification! More...

void	shift_color_map_y (int16_t amount)
	Shifts the color map data by `amount` on the Y axis. Useful for scrolling! More...

uint16_t	uv (float x, float y, bool wrap=false)
	This wrapper function returns the 1D color_map / mask index of a given OpenGL-style UV coordinate in the display matrix. More...

uint16_t	xy (int32_t x, int32_t y, bool wrap=false)
	This function returns the 1D color_map / mask index of a given 2D coordinate in the display matrix. More...

bool	unit_tests ()
	Developer use - automated unit testing of PixieChroma code. More...

Public Attributes
CRGB *	color_map
	Contains the entire color map, including "invisible" areas. More...

uint8_t *	mask
	Contains the entire mask, including "invisible" areas. More...

CRGBPalette16	current_palette
	The current FastLED CRGBPalette16 used for animations. More...

uint16_t	matrix_width
	Stores the final width of the matrix, including invisible pixels. More...

uint16_t	matrix_height
	Stores the final height of the matrix, including invisible pixels. More...

uint16_t	pixel_count
	Stores the total number of pixels, including invisible pixels. More...

uint16_t	led_count
	Stores the total number of physical LEDs, not including invisible pixels. This is calculated for you during begin() with an internal function, calc_xy(). More...

float	delta = 1.0
	Used by animation functions as a way of self-regulating speed if performance drops, similar to a game engine. More...

float	animation_speed = 1.0
	Used by animation functions to scale the apparent speed of animation. More...

float	frame_rate
	Allows the user to access a live frame rate calculation (1 frame latency) More...

Detailed Description

This is the software documentation for using Pixie Chroma functions on Arduino! For full example usage, see File > Examples > Pixie_Chroma inside Arduino!.

Definition at line 42 of file pixie_chroma_internal.h.

Constructor & Destructor Documentation

◆ PixieChroma()

PixieChroma::PixieChroma ( )

Construct a Pixie Chroma class object.

Used to initialize the PixieChroma library.

Example usage before setup() would be:

#include "Pixie_Chroma.h"
PixieChroma pix;

Because each of these functions are contained in the PixieChroma class object, you'll use them like this:

pix.print( "Hello!" );

Definition at line 36 of file pixie_chroma_internal.cpp.

Member Function Documentation

◆ begin()

void PixieChroma::begin	(	const uint8_t	data_pin,
		uint8_t	pixies_x,
		uint8_t	pixies_y
	)

Initializes the display buffer, populates the XY coordinate table, defaults the display colors to green, loads the default CRGBPalette, initializes FastLED, and sets the default power budget.

Pixie Chroma allows for multi-row displays, which are wired in western reading order (left to right, top to bottom) and their shape is defined here. For example, a 16-Pixie display with two rows of eight:

data_pin
   |
+--+-+   +----+   +----+   +----+   +----+   +----+   +----+   +----+
|  1 |-->|  2 |-->|  3 |-->|  4 |-->|  5 |-->|  6 |-->|  7 |-->|  8 | 
+----+   +----+   +----+   +----+   +----+   +----+   +----+   +--+-+
                                                                  |
   +--------------------------------------------------------------+
   |
+--+-+   +----+   +----+   +----+   +----+   +----+   +----+   +----+
|  9 |-->| 10 |-->| 11 |-->| 12 |-->| 13 |-->| 14 |-->| 15 |-->| 16 | 
+----+   +----+   +----+   +----+   +----+   +----+   +----+   +----+

The corresponding setup for this display layout would be:

#include "Pixie_Chroma.h"
PixieChroma pix;

#define DATA_PIN 5
#define PIXIES_X 8
#define PIXIES_Y 2

void setup() {
    pix.begin( DATA_PIN, PIXIES_X, PIXIES_Y );
}

For faster performance on large displays, see begin_quad().

Parameters

data_pin	GPIO pin to use for FastLED output
pixies_x	Number of Pixie PCBs in the X axis of your display
pixies_y	Number of Pixie PCBs in the Y axis of your display

Definition at line 84 of file pixie_chroma_internal.cpp.

◆ begin_quad()

void PixieChroma::begin_quad	(	uint8_t	pixies_per_pin,
		uint8_t	pixies_x,
		uint8_t	pixies_y
	)

Initializes the display buffer, populates the XY coordinate table, defaults the display colors to green, loads the default CRGBPalette, initializes FastLED for Quad Mode, and sets the default power budget.

This version of begin() is special, in that it will send your image data to the LEDs in 4 parallel streams to increase speed.

Unfortunately, this currently requires hard-coded pins to function due to FastLED limitations:

ESP32 / ESP8266:**

DATA_OUT_1: GPIO 12 / D6
DATA_OUT_2: GPIO 13 / D7
DATA_OUT_3: GPIO 14 / D5
DATA_OUT_4: GPIO 15 / D8

TEENSY 3.X:**
DATA_OUT_1: GPIO 2
DATA_OUT_2: GPIO 14
DATA_OUT_3: GPIO 7
DATA_OUT_4: GPIO 8

(If your microcontroller is not listed here, it does not (yet) support Quad Mode.)**

On each data line, you'll wire pixies_per_pin number of Pixie Chromas, with the final image being seamlessly spread across these four lines.

For example, if you have 16 Pixie Chromas (in two rows of eight) and have Quad Mode enabled, then each of the 4 data lines will have 4 Pixie Chromas like so:

DATA_OUT_1 GPIO
- Pixie 1
- Pixie 2
- Pixie 3
- Pixie 4
DATA_OUT_2 GPIO
- Pixie 5
- Pixie 6
- Pixie 7
- Pixie 8
DATA_OUT_3 GPIO
- Pixie 9
- Pixie 10
- Pixie 11
- Pixie 12
DATA_OUT_4 GPIO
- Pixie 13
- Pixie 14
- Pixie 15
- Pixie 16

The corresponding setup for this display layout would be:

#include "Pixie_Chroma.h"
PixieChroma pix;

#define PIXIES_PER_PIN 4
#define PIXIES_X       8
#define PIXIES_Y       2

void setup() {
    pix.begin_quad( PIXIES_PER_PIN, PIXIES_X, PIXIES_Y );
}

Then, with the displays physically arranged in western reading order (left to right, top to bottom) you're ready to begin!

DATA_OUT_1 --+                       DATA_OUT_2 ----+
             |                                      |
          +--+-+   +----+   +----+   +----+  ||  +--+-+   +----+   +----+   +----+
          |  1 |-->|  2 |-->|  3 |-->|  4 |  ||  |  5 |-->|  6 |-->|  7 |-->|  8 | 
          +----+   +----+   +----+   +----+  ||  +----+   +----+   +----+   +----+ 

DATA_OUT_3 --+                       DATA_OUT_4 ----+
             |                                      |
          +--+-+   +----+   +----+   +----+  ||  +--+-+   +----+   +----+   +----+
          |  9 |-->| 10 |-->| 11 |-->| 12 |  ||  | 13 |-->| 14 |-->| 15 |-->| 16 | 
          +----+   +----+   +----+   +----+  ||  +----+   +----+   +----+   +----+

Using begin_quad() to enable the Quad Mode driver will always send the 4 lines of data in parallel, saving on time per frame.

begin_quad() ideally should not be used with less than 4 Pixie Chromas, and with at least one on each line. Even if only two pins are physically used, all 4 pins are still occupied by Quad Mode.

Parameters

pixies_per_pin	Pixies per data pin
pixies_x	Number of Pixie PCBs in the X axis of your display
pixies_y	Number of Pixie PCBs in the Y axis of your display

Definition at line 213 of file pixie_chroma_internal.cpp.

◆ set_color_animation()

void PixieChroma::set_color_animation ( void(*)(PixieChroma *, float) action )

Accepts a preset Color Animation or custom function to use for the animation ISR.

For a list of predefined Color Animations, see pixie_animations.h.

Parameters

action Function to set as an animation ISR

Definition at line 287 of file pixie_chroma_internal.cpp.

◆ set_color_animation_speed()

void PixieChroma::set_color_animation_speed ( float speed )

Used to scale the animation speed of animation ISRs that can use pix.animation_speed() to scale their speeds or for other effects.

Parameters

speed Floating point value: 1.0 = 100%, 3.2 = 320%, 0.5 = 50%

Definition at line 307 of file pixie_chroma_internal.cpp.

◆ set_brightness()

void PixieChroma::set_brightness ( uint8_t level )

Takes an 8-bit brightness value and passes it to FastLED internally, to provide global brightness control with temporal dithering.

Parameters

level 8-bit global brightness value ( 0-255 )

Definition at line 319 of file pixie_chroma_internal.cpp.

◆ set_frame_rate_target()

void PixieChroma::set_frame_rate_target ( uint16_t target )

Sets the target frame rate for animation. This target frame rate is only used to calculate delta in custom/preset animation functions.

This does not change your real frame rate, or even govern it: it is left up to the user to use frequent show() calls or set_update_mode(AUTOMATIC). The "target frame rate" here is used to calculate delta for the animation functions, and should be set as close as possible to the rate at which you are expecting to call show().

This function is automatically called with a matching FPS when you use set_update_mode( AUTOMATIC, FPS ).

Parameters

target Target frame rate for animation.

Definition at line 341 of file pixie_chroma_internal.cpp.

◆ set_gamma_correction()

void PixieChroma::set_gamma_correction ( bool enabled )

Allows you to enable built-in automatic gamma correction, using a fast LUT in pixie_utility.h. (Not enabled by default)

Parameters

enabled Whether or not to apply gamma correction

Definition at line 353 of file pixie_chroma_internal.cpp.

◆ set_justification()

void PixieChroma::set_justification	(	t_justification	justification,
		int16_t	row = `-1`
	)

Sets the text justification globally, or by row.

Parameters

justification	Can be LEFT, CENTER, or RIGHT
row	Specifies the row to justify, or global justification if not specified.

Definition at line 366 of file pixie_chroma_internal.cpp.

◆ set_line_wrap()

void PixieChroma::set_line_wrap ( bool enabled )

Sets the line wrapping behavior.

set_line_wrap( true ); will automatically enter next line when the edge of the display is reached, and set_line_wrap( false ); will not.

Parameters

enabled Enable or disable auto line-wrapping

Definition at line 388 of file pixie_chroma_internal.cpp.

◆ set_max_power()

void PixieChroma::set_max_power	(	float	volts,
		uint16_t	milliamps
	)

Sets the maximum power budget in volts and milliamps.

Knowing the average power consumption of these LEDs at any given color, FastLED will automatically globally scale down the output values with temporal dithering to lower power usage until it is within the budget defined here. Defaults to 5.0V / 500mA to protect PC USB ports if the Pixies are not independently powered. ( 2000mA = 2A, 500mA = 0.5A, etc. )

Parameters

volts	Total LED power budget in volts. ( default: 5.0 )
milliamps	Total LED power budget in milliamps ( default 500 )

Definition at line 407 of file pixie_chroma_internal.cpp.

◆ set_palette() [1/2]

void PixieChroma::set_palette ( const uint8_t * pal )

Accepts a const uint8_t (8-bit) array to generate a FastLED Gradient Palette at runtime:

const uint8_t* my_gradient_palette[] = {

[INDEX], [R_VAL], [G_VAL], [B_VAL],

        0,        255,      0,        0, 
        127,      0,        255,      0, 
        255,      0,        0,        255, 
    };

On each line is the index of the color ( 0-255 ) to express the position in
the gradient this color occurs. So in the given example, it is a gradient
from red at 0, to green at 127, to blue at 255.

@param  pal  FastLED "Gradient Palette" array

Definition at line 432 of file pixie_chroma_internal.cpp.

◆ set_palette() [2/2]

void PixieChroma::set_palette ( CRGBPalette16 pal )

Accepts a FastLED CRGBPalette16 object to set the current color palette for animation.

Parameters

pal	FastLED CRGBPalette16 object to use

Definition at line 449 of file pixie_chroma_internal.cpp.

◆ set_scroll_type()

void PixieChroma::set_scroll_type ( t_scroll_type type )

Sets the scroll behavior:

INSTANT (No smooth animation, shift whole characters at a time)
SMOOTH (Smooth pixel scrolling)
SHIFT (Smooth pixel scrolling with stops at each whole display)

Parameters

scroll_type Can be INSTANT, SMOOTH, or SHIFT

Definition at line 469 of file pixie_chroma_internal.cpp.

◆ set_update_mode()

void PixieChroma::set_update_mode	(	t_update_mode	mode,
		uint16_t	FPS = `60`
	)

Allows for automatic show() calls at a specified frames per second if AUTOMATIC is used. (uses Ticker.attach_ms() internally)

This lets you use things like print() as infrequently as you'd like, since show() will automatically run in the background to keep the current animation function running smoothly.

Use in conjunction with hold() and free() to prevent show() calls during text/image construction, leading to unintended partial frames being shown. Be aware, hold() does not prevent animation / palette updates (only mask updates) so animations will still run smoothly during hold() times until free() is called and the mask is finally updated.

Parameters

mode	AUTOMATIC or MANUAL. AUTOMATIC will call show() at `FPS` using an ISR, MANUAL allows you call show() when you like.
FPS	Update this many times per second (Default: 60) Only applicable when mode is AUTOMATIC

Definition at line 509 of file pixie_chroma_internal.cpp.

◆ add_char() [1/2]

void PixieChroma::add_char	(	char	chr,
		int16_t	x_dest,
		int16_t	y_dest
	)

Internal function for rendering a single char to the mask buffer.

All other write() function overloads eventually end up casted to char* strings and passed to this function one character at a time for rendering.

Parameters

chr	char to render
x_dest	X pixel position of write
y_dest	Y pixel position of write

Definition at line 562 of file pixie_chroma_internal.cpp.

◆ add_char() [2/2]

void PixieChroma::add_char	(	uint8_t	bitmap_col_1,
		uint8_t	bitmap_col_2,
		uint8_t	bitmap_col_3,
		uint8_t	bitmap_col_4,
		uint8_t	bitmap_col_5,
		int16_t	x_dest,
		int16_t	y_dest
	)

Internal function for rendering a single bitmap to the mask buffer.

Parameters

bitmap_col_1	Column 1 data of this bitmap
bitmap_col_2	Column 2 data of this bitmap
bitmap_col_3	Column 3 data of this bitmap
bitmap_col_4	Column 4 data of this bitmap
bitmap_col_5	Column 5 data of this bitmap
x_dest	X pixel position of write
y_dest	Y pixel position of write

Definition at line 604 of file pixie_chroma_internal.cpp.

◆ write() [1/9]

void PixieChroma::write	(	uint8_t	bitmap_col_1,
		uint8_t	bitmap_col_2,
		uint8_t	bitmap_col_3,
		uint8_t	bitmap_col_4,
		uint8_t	bitmap_col_5,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a bitmap to a specified X and Y cursor position, taking five uint8_t as input for the column data.

Example:

pix.write( B00101111, B01001001, B01001001, B01001001, B00110001 );

    OR, WRITTEN VERTICALLY:

pix.write(   ,   ,   ,   ,   );
           1   1   1   1   1  LSB
           1   0   0   0   0
           1   0   0   0   0
           1   1   1   1   0
           0   0   0   0   1
           1   0   0   0   1
           0   1   1   1   0  
           0   0   0   0   0  MSB (unused)
           B   B   B   B   B

This writes a "5" to the display, seen above in the "1" bits of each column. The MSB (highest bit) is not used in bitmaps.

Parameters

bitmap_col_1	Column 1 data of this bitmap
bitmap_col_2	Column 2 data of this bitmap
bitmap_col_3	Column 3 data of this bitmap
bitmap_col_4	Column 4 data of this bitmap
bitmap_col_5	Column 5 data of this bitmap
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 694 of file pixie_chroma_internal.cpp.

◆ write() [2/9]

void PixieChroma::write	(	char *	message,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a char* string to a specified X and Y cursor position.

Parameters

message	char* string to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 707 of file pixie_chroma_internal.cpp.

◆ write() [3/9]

void PixieChroma::write	(	int16_t	input,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a signed 16-bit integer to a specified X and Y cursor position.

Parameters

input	Signed integer to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 724 of file pixie_chroma_internal.cpp.

◆ write() [4/9]

void PixieChroma::write	(	uint16_t	input,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes an unsigned 16-bit integer to a specified X and Y cursor position.

Parameters

input	Unsigned integer to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 744 of file pixie_chroma_internal.cpp.

◆ write() [5/9]

void PixieChroma::write	(	int32_t	input,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a signed 32-bit integer to a specified X and Y cursor position.

Parameters

input	Signed integer to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 764 of file pixie_chroma_internal.cpp.

◆ write() [6/9]

void PixieChroma::write	(	uint32_t	input,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes an unsigned 32-bit integer to a specified X and Y cursor position.

Parameters

input	Unsigned integer to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 784 of file pixie_chroma_internal.cpp.

◆ write() [7/9]

void PixieChroma::write	(	long unsigned int	input,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes an unsigned 32-bit integer to a specified X and Y cursor position. ( Stupid ESP-specific type )

Parameters

input	Unsigned integer to write
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 806 of file pixie_chroma_internal.cpp.

◆ write() [8/9]

void PixieChroma::write	(	float	input,
		uint8_t	places = `2`,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a single-precision floating point value to a specified X and Y cursor position, to a specified number of decimal places.

Parameters

input	Single-precision float to write
places	Number of decimal places to show [optional]
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 829 of file pixie_chroma_internal.cpp.

◆ write() [9/9]

void PixieChroma::write	(	double	input,
		uint8_t	places = `2`,
		uint8_t	x_pos = `0`,
		uint8_t	y_pos = `0`
	)

Writes a double-precision floating point value to a specified X and Y cursor position, to a specified number of decimal places.

Parameters

input	Double-precision float to write
places	Number of decimal places to show [optional]
x_pos	X cursor position of write [optional]
y_pos	Y cursor position of write [optional]

Definition at line 849 of file pixie_chroma_internal.cpp.

◆ write_pix() [1/2]

void PixieChroma::write_pix	(	char *	message,
		int16_t	x_dest = `0`,
		int16_t	y_dest = `0`
	)

Internal function for rendering char* strings to the mask buffer.

All other write() function overloads eventually end up casted to char* strings and passed to this function for rendering. This can also be used to write char* strings that are not aligned to whole display positions, such as during smooth scrolling.

Parameters

message	char* of text to render
x_dest	X pixel position of write [optional]
y_dest	Y pixel position of write [optional]

Definition at line 875 of file pixie_chroma_internal.cpp.

◆ write_pix() [2/2]

void PixieChroma::write_pix	(	uint8_t	bitmap_col_1,
		uint8_t	bitmap_col_2,
		uint8_t	bitmap_col_3,
		uint8_t	bitmap_col_4,
		uint8_t	bitmap_col_5,
		int16_t	x_dest = `0`,
		int16_t	y_dest = `0`
	)

Internal function for rendering bitmaps to the mask buffer.

This can also be used to write bitmaps that are not aligned to whole display positions, such as during smooth scrolling.

Parameters

bitmap_col_1	Column 1 data of this bitmap
bitmap_col_2	Column 2 data of this bitmap
bitmap_col_3	Column 3 data of this bitmap
bitmap_col_4	Column 4 data of this bitmap
bitmap_col_5	Column 5 data of this bitmap
x_dest	X pixel position of write [optional]
y_dest	Y pixel position of write [optional]

Definition at line 942 of file pixie_chroma_internal.cpp.

◆ print() [1/10]

void PixieChroma::print	(	uint8_t	bitmap_col_1,
		uint8_t	bitmap_col_2,
		uint8_t	bitmap_col_3,
		uint8_t	bitmap_col_4,
		uint8_t	bitmap_col_5
	)

Prints a bitmap to the displays at the current cursor position, taking five uint8_t as input for the column data.

Example:

pix.print( B00101111, B01001001, B01001001, B01001001, B00110001 );

    OR, WRITTEN VERTICALLY:

pix.print(    ,   ,   ,   ,    );
            1   1   1   1   1  LSB
            1   0   0   0   0
            1   0   0   0   0
            1   1   1   1   0
            0   0   0   0   1
            1   0   0   0   1
            0   1   1   1   0  
            0   0   0   0   0  MSB ( unused )
            B   B   B   B   B

This writes a "5" to the display, seen above in the "1" bits of each column. The MSB ( highest bit ) is not used in bitmaps.

Parameters

bitmap_col_1	Column 1 data of this bitmap
bitmap_col_2	Column 2 data of this bitmap
bitmap_col_3	Column 3 data of this bitmap
bitmap_col_4	Column 4 data of this bitmap
bitmap_col_5	Column 5 data of this bitmap

Definition at line 1005 of file pixie_chroma_internal.cpp.

◆ print() [2/10]

void PixieChroma::print ( char chr )

Prints a single char to the displays at the current cursor position.

Parameters

chr	char to print

Definition at line 1023 of file pixie_chroma_internal.cpp.

◆ print() [3/10]

void PixieChroma::print ( char * message )

Prints a char* string to the displays at the current cursor position.

The given string will be searched for "Shortcodes", which are special strings which will automatically be replaced with bitmap icons such as:

print("SMILEY FACE! [:SMILE:]");

A full list of Shortcodes can be found in pixie_shortcodes.h.

Parameters

message char* string to print

Definition at line 1064 of file pixie_chroma_internal.cpp.

◆ print() [4/10]

void PixieChroma::print ( int16_t input )

Prints a signed 16-bit integer to the displays at the current cursor position.

Parameters

input Signed integer to print

Definition at line 1096 of file pixie_chroma_internal.cpp.

◆ print() [5/10]

void PixieChroma::print ( uint16_t input )

Prints an unsigned 16-bit integer to the displays at the current cursor position.

Parameters

input Unsigned integer to print

Definition at line 1114 of file pixie_chroma_internal.cpp.

◆ print() [6/10]

void PixieChroma::print ( int32_t input )

Prints a signed 32-bit integer to the displays at the current cursor position.

Parameters

input Signed integer to print

Definition at line 1132 of file pixie_chroma_internal.cpp.

◆ print() [7/10]

void PixieChroma::print ( uint32_t input )

Prints an unsigned 32-bit integer to the displays at the current cursor\ position.

Parameters

input Unsigned integer to print

Definition at line 1150 of file pixie_chroma_internal.cpp.

◆ print() [8/10]

void PixieChroma::print ( long unsigned int input )

Prints an unsigned 32-bit integer to the displays at the current cursor position. ( Dumb ESP-specific type )

Parameters

input Unsigned integer to print

Definition at line 1169 of file pixie_chroma_internal.cpp.

◆ print() [9/10]

void PixieChroma::print	(	float	input,
		uint8_t	places = `2`
	)

Prints a single-precision floating point value to the displays at the current cursor position, to a specified number of decimal places.

Parameters

input	float to print
places	Number of decimal places to print [optional]

Definition at line 1189 of file pixie_chroma_internal.cpp.

◆ print() [10/10]

void PixieChroma::print	(	double	input,
		uint8_t	places = `2`
	)

Prints a double-precision floating point value to the displays at the current cursor position, to a specified number of decimal places.

Parameters

input	double to print
places	Number of decimal places to print [optional]

Definition at line 1206 of file pixie_chroma_internal.cpp.

◆ println() [1/9]

void PixieChroma::println	(	uint8_t	bitmap_col_1,
		uint8_t	bitmap_col_2,
		uint8_t	bitmap_col_3,
		uint8_t	bitmap_col_4,
		uint8_t	bitmap_col_5
	)

Prints a bitmap to the displays at the current cursor position, (taking five uint8_t as input for the column data) then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

bitmap_col_1	Column 1 data of this bitmap
bitmap_col_2	Column 2 data of this bitmap
bitmap_col_3	Column 3 data of this bitmap
bitmap_col_4	Column 4 data of this bitmap
bitmap_col_5	Column 5 data of this bitmap

Definition at line 1233 of file pixie_chroma_internal.cpp.

◆ println() [2/9]

void PixieChroma::println ( char * message )

Prints a char* string to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character.

The given string will be searched for "Shortcodes", which are special strings which will automatically be replaced with bitmap icons such as:

print("SMILEY FACE! [:SMILE:]");

A full list of Shortcodes can be found in pixie_shortcodes.h.

Parameters

message char* string to print

Definition at line 1254 of file pixie_chroma_internal.cpp.

◆ println() [3/9]

void PixieChroma::println ( int16_t input )

Prints a signed 16-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input Signed 16-bit integer to print

Definition at line 1268 of file pixie_chroma_internal.cpp.

◆ println() [4/9]

void PixieChroma::println ( uint16_t input )

Prints an unsigned 16-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input Unsigned 16-bit integer to print

Definition at line 1282 of file pixie_chroma_internal.cpp.

◆ println() [5/9]

void PixieChroma::println ( int32_t input )

Prints a signed 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input Signed 32-bit integer to print

Definition at line 1296 of file pixie_chroma_internal.cpp.

◆ println() [6/9]

void PixieChroma::println ( uint32_t input )

Prints an unsigned 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input Unsigned 32-bit integer to print

Definition at line 1310 of file pixie_chroma_internal.cpp.

◆ println() [7/9]

void PixieChroma::println ( long unsigned int input )

Prints an unsigned 32-bit integer to the displays at the current cursor position, then jumps to the next row in the Pixie display, similar to a newline '\n' character. ( Stupid ESP-specific type )

Parameters

input Unsigned 32-bit integer to print

Definition at line 1325 of file pixie_chroma_internal.cpp.

◆ println() [8/9]

void PixieChroma::println	(	float	input,
		uint8_t	places = `2`
	)

Prints a single-precision floating point value to the displays at the current cursor position (to a specified number of decimal places), then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input	float to print
places	Number of decimal places to print [optional]

Definition at line 1342 of file pixie_chroma_internal.cpp.

◆ println() [9/9]

void PixieChroma::println	(	double	input,
		uint8_t	places = `2`
	)

Prints a double-precision floating point value to the displays at the current cursor position (to a specified number of decimal places), then jumps to the next row in the Pixie display, similar to a newline '\n' character.

Parameters

input	double to print
places	Number of decimal places to print [optional]

Definition at line 1357 of file pixie_chroma_internal.cpp.

◆ get_cursor_x()

uint8_t PixieChroma::get_cursor_x ( )

Returns the cursor's X position.

Returns: The cursor's X position

Definition at line 1373 of file pixie_chroma_internal.cpp.

◆ get_cursor_x_exact()

int16_t PixieChroma::get_cursor_x_exact ( )

Returns the cursor's X position in exact pixel coordinates.

Returns: The cursor's X position in exact pixel coordinates

Definition at line 1384 of file pixie_chroma_internal.cpp.

◆ get_cursor_y()

uint8_t PixieChroma::get_cursor_y ( )

Returns the cursor's Y position.

Returns: The cursor's Y position

Definition at line 1395 of file pixie_chroma_internal.cpp.

◆ get_cursor_y_exact()

int16_t PixieChroma::get_cursor_y_exact ( )

Returns the cursor's Y position in exact pixel coordinates.

Returns: The cursor's Y position in exact pixel coordinates

Definition at line 1406 of file pixie_chroma_internal.cpp.

◆ set_cursor()

void PixieChroma::set_cursor	(	uint8_t	x_position,
		uint8_t	y_position = `0`
	)

Sets the cursor position in a 2D context, in whole displays.

Wherever the cursor is, is where the next call to print() or write() will originate. Position is counted from zero. Remember: each Pixie Chroma has two "displays" on it.

+-----------------+   +-----------------+   +-----------------+
|      + + +      |   |      + + +      |   |      + + +      |
|+-----+   +-----+|   |+-----+   +-----+|   |+-----+   +-----+|
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
|| 0,0 |   | 1,0 ||-->|| 2,0 |   | 3,0 ||-->|| 4,0 |   | 5,0 ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
|+-----+   +-----+|   |+-----+   +-----+|   |+-----+   +-----+|
|      + + +      |   |      + + +      |   |      + + +      |
+-----------------+   +-----------------+   +-----------------+
                                                   |
       +-------------------------------------------+
       |
       V
+-----------------+   +-----------------+   +-----------------+
|      + + +      |   |      + + +      |   |      + + +      |
|+-----+   +-----+|   |+-----+   +-----+|   |+-----+   +-----+|
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
|| 0,1 |   | 1,1 ||-->|| 2,1 |   | 3,1 ||-->|| 4,0 |   | 5,1 ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
||     |   |     ||   ||     |   |     ||   ||     |   |     ||
|+-----+   +-----+|   |+-----+   +-----+|   |+-----+   +-----+|
|      + + +      |   |      + + +      |   |      + + +      |
+-----------------+   +-----------------+   +-----------------+

For example:

set_cursor( 1,0 ) sets the cursor to the second display in the first row.

set_cursor( 3,1 ) sets the cursor to the fourth display in the second row.

Parameters

x_position	New cursor position on the X-axis, in whole displays
y_position	New cursor position on the Y-axis, in whole displays

Definition at line 1456 of file pixie_chroma_internal.cpp.

◆ clear()

void PixieChroma::clear ( )

Clears (blackens) the current mask buffer and resets the cursor to 0,0.

Definition at line 1471 of file pixie_chroma_internal.cpp.

◆ free()

void PixieChroma::free ( )

Unfreezes the current mask buffer in memory to allow showing updated text the next time show() is called.

Definition at line 1482 of file pixie_chroma_internal.cpp.

◆ hold()

void PixieChroma::hold ( )

Freezes the current mask buffer in memory to prevent showing unfinished text if show() automaticall fires during construction of the current display data.

Use free() to unfreeze.

Definition at line 1494 of file pixie_chroma_internal.cpp.

◆ show()

void PixieChroma::show ( )

Processes 1D image data into truncated versions, sending them to the Pixie Chroma displays.

FastLED.show() is called here!

Definition at line 1507 of file pixie_chroma_internal.cpp.

◆ delay()

void PixieChroma::delay ( uint32_t milliseconds )

Custom delay() function from FastLED that allows automatic refreshing of the displays during a delay() call, allowing things like temporal dithering to continue to function properly while the microcontroller waits.

Parameters

milliseconds Number of milliseconds to wait

Definition at line 1561 of file pixie_chroma_internal.cpp.

◆ color() [1/3]

void PixieChroma::color ( CRGB col )

Sets the entire color buffer to a CRGB value.

Example:

pix.color( CRGB( 0,255,255 ) );

This would set all displays to cyan, a mix of green and blue.

Parameters

col	FastLED CRGB color

Definition at line 1582 of file pixie_chroma_internal.cpp.

◆ color() [2/3]

void PixieChroma::color	(	CRGB	col,
		uint8_t	x,
		uint8_t	y
	)

Sets a specific display in the color buffer to a CRGB value.

Example:

pix.color( CRGB( 0,255,255 ), 1, 0 );

This would set the second display of the first row to cyan, a mix of green and blue.

Parameters

col	FastLED CRGB color
x	X coordinate of display
y	y coordinate of display

Definition at line 1604 of file pixie_chroma_internal.cpp.

◆ color() [3/3]

void PixieChroma::color	(	CRGB	col,
		int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2
	)

Sets a rectangular area in the color buffer to a CRGB value.

Example:

pix.color( CRGB( 0,255,255 ), 0, 0, 5, 5 );

This would set the first five columns and rows of the color buffer to cyan, a mix of green and blue.

Parameters

col	FastLED CRGB color
x1	Starting X coordinate of the rectangle
y1	Starting Y coordinate of the rectangle
x2	Ending X coordinate of the rectangle (inclusive)
y2	Ending Y coordinate of the rectangle (inclusive)

Definition at line 1638 of file pixie_chroma_internal.cpp.

◆ print_color()

void PixieChroma::print_color ( CRGB col )

All print() calls after a print_color() will be colored with this value.

print_color( CRGB::Red );
print("Hello "); // ..........Printed in red
print_color( CRGB::Green );
print("World!"); // ..........Printed in green

Parameters

col	FastLED CRGB color

Definition at line 1678 of file pixie_chroma_internal.cpp.

◆ kelvin_to_rgb()

CRGB PixieChroma::kelvin_to_rgb ( uint16_t temperature )

Approximates the conversion of a blackbody radiation temperature (i.e. 3500K) to a CRGB color object.

This can be used within other Pixie color functions like so:

pix.color(  kelvin_to_rgb(  3000  )  );

This would render a warm-white color. This measurement system is often used in household LED bulbs, with colors like:

2700K - Very Warm White
3500K - Warm White
5000K - White
7000K - Cool White

Parameters

temperature Blackbody radiation temperature in Kelvin

Returns: Approximate CRGB representation of the given temperature

Definition at line 1704 of file pixie_chroma_internal.cpp.

◆ blur()

void PixieChroma::blur ( fract8 blur_amount )

Blurs the mask buffer in both axes by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1752 of file pixie_chroma_internal.cpp.

◆ blur_x()

void PixieChroma::blur_x ( fract8 blur_amount )

Blurs the mask buffer in the X axis by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1764 of file pixie_chroma_internal.cpp.

◆ blur_y()

void PixieChroma::blur_y ( fract8 blur_amount )

Blurs the mask buffer in the Y axis by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1791 of file pixie_chroma_internal.cpp.

◆ dim()

void PixieChroma::dim	(	uint8_t	amount,
		bool	reset_cursor = `false`
	)

Darkens the mask buffer by an 8-bit amount. Optionally resets the cursor position.

Parameters

amount	8-bit amount to darken the mask
reset_cursor	Reset the cursor to 0,0 (Default: false)

Definition at line 1821 of file pixie_chroma_internal.cpp.

◆ color_blur()

void PixieChroma::color_blur ( fract8 blur_amount )

Blurs the color buffer in both axes by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1852 of file pixie_chroma_internal.cpp.

◆ color_blur_x()

void PixieChroma::color_blur_x ( fract8 blur_amount )

Blurs the color buffer in the X axis by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1864 of file pixie_chroma_internal.cpp.

◆ color_blur_y()

void PixieChroma::color_blur_y ( fract8 blur_amount )

Blurs the color buffer in the Y axis by blur_amount.

Parameters

blur_amount Amount to blur

Definition at line 1889 of file pixie_chroma_internal.cpp.

◆ color_dim()

void PixieChroma::color_dim ( uint8_t amount )

Darkens the color buffer by an 8-bit amount.

Parameters

amount 8-bit amount to darken the mask

Definition at line 1915 of file pixie_chroma_internal.cpp.

◆ draw_line_color()

void PixieChroma::draw_line_color	(	int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		CRGB	color
	)

Draws a line in the color map using Bresenham's line algorithm.

Parameters

x1	Starting X coordinate of the line
y1	Starting Y coordinate of the line
x2	Ending X coordinate of the line (inclusive)
y2	Ending Y coordinate of the line (inclusive)
color	CRGB color to draw

Definition at line 1935 of file pixie_chroma_internal.cpp.

◆ draw_line_mask()

void PixieChroma::draw_line_mask	(	int16_t	x1,
		int16_t	y1,
		int16_t	x2,
		int16_t	y2,
		uint8_t	value = `255`
	)

Draws a line in the mask buffer using Bresenham's line algorithm.

Parameters

x1	Starting X coordinate of the line
y1	Starting Y coordinate of the line
x2	Ending X coordinate of the line (inclusive)
y2	Ending Y coordinate of the line (inclusive)
value	8-bit mask value to draw (Default 255)

Definition at line 2017 of file pixie_chroma_internal.cpp.

◆ get_uv_x()

float PixieChroma::get_uv_x ( int32_t x_pixel )

Returns the X-axis UV coordinate for a given X-axis pixel position.

Parameters

x_pixel X-axis pixel position

Returns: X-axis UV coordinate

Definition at line 2096 of file pixie_chroma_internal.cpp.

◆ get_uv_y()

float PixieChroma::get_uv_y ( int32_t y_pixel )

Returns the Y-axis UV coordinate for a given Y-axis pixel position.

Parameters

y_pixel Y-axis pixel position

Returns: Y-axis UV coordinate

Definition at line 2108 of file pixie_chroma_internal.cpp.

◆ get_pixel_mask()

uint8_t PixieChroma::get_pixel_mask	(	int32_t	x,
		int32_t	y
	)

Gets the mask value at a given pixel coordinate.

Parameters

x	X pixel coordinate
y	Y pixel coordinate

Returns: Mask value

Definition at line 2122 of file pixie_chroma_internal.cpp.

◆ get_pixel_color()

CRGB PixieChroma::get_pixel_color	(	int32_t	x,
		int32_t	y
	)

Gets the RGB color value at a given pixel coordinate.

Parameters

x	X pixel coordinate
y	Y pixel coordinate

Returns: CRGB color

Definition at line 2135 of file pixie_chroma_internal.cpp.

◆ print_xy_table()

void PixieChroma::print_xy_table ( )

Prints the index table for the calculated XY map. Requires Serial.begin() first to function.

Useful for debugging, the index table (XY Map) can be printed over Serial. Each cell of the table denotes at what index that physical pixel location is inside of the 1D color_map / mask arrays. (The xy() function uses this table to translate real-world 2D coordinates to 1D indices.)

For example, here is the XY Table for a single Pixie:


70	71	72	73	74	75	76	77	78	79	80	81	82	83
84	85	86	87	88	89	90	91	92	93	94	95	96	97
98	0	1	2	3	4	99	100	35	36	37	38	39	101
102	5	6	7	8	9	103	104	40	41	42	43	44	105
106	10	11	12	13	14	107	108	45	46	47	48	49	109
110	15	16	17	18	19	111	112	50	51	52	53	54	113
114	20	21	22	23	24	115	116	55	56	57	58	59	117
118	25	26	27	28	29	119	120	60	61	62	63	64	121
122	30	31	32	33	34	123	124	65	66	67	68	69	125
126	127	128	129	130	131	132	133	134	135	136	137	138	139
140	141	142	143	144	145	146	147	148	149	150	151	152	153

BOLD = Visible Pixel
ITALIC = Invisible Pixel

Starting from 0 at the top-left with the first visible pixel, (of the first display in the XY Table) the index increases to 69, (the last visible pixel in the matrix) before starting to count invisible pixels at index 70 and up through 153.

With this example table setup, the first 70 indices of color_map / mask are visible pixels, and the remaining 84 are invisible. (Simulated margin between displays)

Definition at line 2180 of file pixie_chroma_internal.cpp.

◆ scroll_message()

void PixieChroma::scroll_message	(	char *	message,
		uint8_t	row = `0`
	)

Scrolls a message across the matrix by constructing it one character at a time in the dead-space outside the visible area and scrolling it in from the right.

Parameters

message	Message to scroll across the matrix
row	Row to scroll the message on (default 0)

Definition at line 2201 of file pixie_chroma_internal.cpp.

◆ set_pixel_mask()

void PixieChroma::set_pixel_mask	(	int32_t	x,
		int32_t	y,
		uint8_t	value
	)

Sets the mask value at a given pixel coordinate.

Parameters

x	X pixel coordinate
y	Y pixel coordinate
value	Mask value

Definition at line 2243 of file pixie_chroma_internal.cpp.

◆ set_pixel_color()

void PixieChroma::set_pixel_color	(	int32_t	x,
		int32_t	y,
		CRGB	color
	)

Sets the RGB color value at a given pixel coordinate.

Parameters

x	X pixel coordinate
y	Y pixel coordinate
color	CRGB color

Definition at line 2256 of file pixie_chroma_internal.cpp.

◆ shift_mask_x()

void PixieChroma::shift_mask_x	(	int16_t	amount,
		int16_t	row = `-1`
	)

Shifts the mask data by amount on the X axis. Useful for scrolling or justification!

Parameters

amount	Amount in whole-pixels to shift the mask data
row	If not the default (-1), shift only the specified row

Definition at line 2269 of file pixie_chroma_internal.cpp.

◆ shift_mask_y()

void PixieChroma::shift_mask_y ( int16_t amount )

Shifts the mask data by amount on the Y axis. Useful for scrolling!

Parameters

amount Amount in whole-pixels to shift the mask data

Definition at line 2317 of file pixie_chroma_internal.cpp.

◆ shift_color_map_x()

void PixieChroma::shift_color_map_x	(	int16_t	amount,
		int16_t	row = `-1`
	)

Shifts the color_map data by amount on the X axis. Useful for scrolling or justification!

Parameters

amount	Amount in whole-pixels to shift the color map data
row	If not the default (-1), shift only the specified row

Definition at line 2359 of file pixie_chroma_internal.cpp.

◆ shift_color_map_y()

void PixieChroma::shift_color_map_y ( int16_t amount )

Shifts the color map data by amount on the Y axis. Useful for scrolling!

Parameters

amount Amount in whole-pixels to shift the color map data

Definition at line 2408 of file pixie_chroma_internal.cpp.

◆ uv()

uint16_t PixieChroma::uv	(	float	x,
		float	y,
		bool	wrap = `false`
	)

This wrapper function returns the 1D color_map / mask index of a given OpenGL-style UV coordinate in the display matrix.

See xy(). UV Map:

+-------------------+
|0, 1           1, 1|
|                   |
|^                  |
|                   |
|0, 0     >     1, 0|
+-------------------+

Parameters

x	Floating-point UV X coordinate
y	Floating-point UV Y coordinate
wrap	Enable wrapping function [optional]

Returns: The 1D LED index of your UV coordinate

Definition at line 2463 of file pixie_chroma_internal.cpp.

◆ xy()

uint16_t PixieChroma::xy	(	int32_t	x,
		int32_t	y,
		bool	wrap = `false`
	)

This function returns the 1D color_map / mask index of a given 2D coordinate in the display matrix.

The XY Table is generated during begin() by an internal function, calc_xy(). Each cell of the table denotes at what index that physical pixel location is inside of the 1D color_map / mask arrays.

For example, here is the XY Table for a single Pixie:


70	71	72	73	74	75	76	77	78	79	80	81	82	83
84	85	86	87	88	89	90	91	92	93	94	95	96	97
98	0	1	2	3	4	99	100	35	36	37	38	39	101
102	5	6	7	8	9	103	104	40	41	42	43	44	105
106	10	11	12	13	14	107	108	45	46	47	48	49	109
110	15	16	17	18	19	111	112	50	51	52	53	54	113
114	20	21	22	23	24	115	116	55	56	57	58	59	117
118	25	26	27	28	29	119	120	60	61	62	63	64	121
122	30	31	32	33	34	123	124	65	66	67	68	69	125
126	127	128	129	130	131	132	133	134	135	136	137	138	139
140	141	142	143	144	145	146	147	148	149	150	151	152	153

BOLD = Visible Pixel
ITALIC = Invisible Pixel

With this example table, a given XY coordinate of (3, 4) would return 12. Thus, modifying the color_map or mask at index 12 would influence the pixel at the physical location of (3, 4).

Starting from 0 at the top-left with the first visible pixel, (of the first display in the XY Table) the index increases to 69, (the last visible pixel in the matrix) before starting to count invisible pixels at index 70 and up through 153.

With this example table setup, the first 70 indices of color_map / mask are visible pixels, and the remaining 84 are invisible. (Simulated margin between displays)

Optionally, the result of this function can be run through a wrapping function that allows coordinates out of range to wrap around to the opposite side of the 2D matrix.

If wrap is not enabled, any coordinates outside of the display matrix will be parsed to a 1D index that is completely unused and unseen.

Parameters

x	Signed 2D X coordinate
y	Signed 2D Y coordinate
wrap	Enable wrapping function [optional]

Returns: The 1D LED index of your 2D XY coordinate

Definition at line 2542 of file pixie_chroma_internal.cpp.

◆ unit_tests()

bool PixieChroma::unit_tests ( )

Developer use - automated unit testing of PixieChroma code.

Returns: Boolean test pass status

Definition at line 3034 of file pixie_chroma_internal.cpp.

Member Data Documentation

◆ color_map

CRGB* PixieChroma::color_map

Contains the entire color map, including "invisible" areas.

Note: Pixie Chroma uses "invisible" pixels acting as padding between displays, to allow for spatial consistency. (i.e. If a word starts to scroll off the left side of one display, it will enter an "invisible" margin before it arrives on the next display.

X = Visible
. = Invisible

. . . . . . . . . . . . . .
. . . . . . . . . . . . . .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. X X X X X . . X X X X X .
. . . . . . . . . . . . . .
. . . . . . . . . . . . . .

Definition at line 201 of file pixie_chroma_internal.h.

◆ mask

uint8_t* PixieChroma::mask

Contains the entire mask, including "invisible" areas.

The "mask" is used like a semi-transparent overlay over the color map. Imagine that you had a red piece of paper: if you took a marker and blacked out all areas of the paper except for a circle in the center, it would appear as if there was a red circle painted on a black paper. This is essentially what the mask here is doing: subtracting from the output of the color map, to show text or bitmaps.

Note: Pixie Chroma uses "invisible" pixels acting as padding between displays, to allow for spatial consistency. (i.e. If a word starts to scroll off the left side of one display, it will enter an "invisible" margin before it arrives on the next display. (See CRGB *color_map.)

Definition at line 220 of file pixie_chroma_internal.h.

◆ current_palette

CRGBPalette16 PixieChroma::current_palette

The current FastLED CRGBPalette16 used for animations.

Definition at line 226 of file pixie_chroma_internal.h.

◆ matrix_width

uint16_t PixieChroma::matrix_width

Stores the final width of the matrix, including invisible pixels.

Definition at line 232 of file pixie_chroma_internal.h.

◆ matrix_height

uint16_t PixieChroma::matrix_height

Stores the final height of the matrix, including invisible pixels.

Definition at line 238 of file pixie_chroma_internal.h.

◆ pixel_count

uint16_t PixieChroma::pixel_count

Stores the total number of pixels, including invisible pixels.

This is calculated for you with the display size given to begin().

Definition at line 246 of file pixie_chroma_internal.h.

◆ led_count

uint16_t PixieChroma::led_count

Stores the total number of physical LEDs, not including invisible pixels. This is calculated for you during begin() with an internal function, calc_xy().

Definition at line 253 of file pixie_chroma_internal.h.

◆ delta

float PixieChroma::delta = 1.0

Used by animation functions as a way of self-regulating speed if performance drops, similar to a game engine.

Definition at line 260 of file pixie_chroma_internal.h.

◆ animation_speed

float PixieChroma::animation_speed = 1.0

Used by animation functions to scale the apparent speed of animation.

Definition at line 266 of file pixie_chroma_internal.h.

◆ frame_rate

float PixieChroma::frame_rate

Allows the user to access a live frame rate calculation (1 frame latency)

Definition at line 272 of file pixie_chroma_internal.h.

The documentation for this class was generated from the following files:

src/pixie_chroma_internal.h
src/pixie_chroma_internal.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ PixieChroma()

Member Function Documentation

◆ begin()

◆ begin_quad()

◆ set_color_animation()

◆ set_color_animation_speed()

◆ set_brightness()

◆ set_frame_rate_target()

◆ set_gamma_correction()

◆ set_justification()

◆ set_line_wrap()

◆ set_max_power()

◆ set_palette() [1/2]

◆ set_palette() [2/2]

◆ set_scroll_type()

◆ set_update_mode()

◆ add_char() [1/2]

◆ add_char() [2/2]

◆ write() [1/9]

◆ write() [2/9]

◆ write() [3/9]

◆ write() [4/9]

◆ write() [5/9]

◆ write() [6/9]

◆ write() [7/9]

◆ write() [8/9]

◆ write() [9/9]

◆ write_pix() [1/2]

◆ write_pix() [2/2]

◆ print() [1/10]

◆ print() [2/10]

◆ print() [3/10]

◆ print() [4/10]

◆ print() [5/10]

◆ print() [6/10]

◆ print() [7/10]

◆ print() [8/10]

◆ print() [9/10]

◆ print() [10/10]

◆ println() [1/9]

◆ println() [2/9]

◆ println() [3/9]

◆ println() [4/9]

◆ println() [5/9]

◆ println() [6/9]

◆ println() [7/9]

◆ println() [8/9]

◆ println() [9/9]

◆ get_cursor_x()

◆ get_cursor_x_exact()

◆ get_cursor_y()

◆ get_cursor_y_exact()

◆ set_cursor()

◆ clear()

◆ free()

◆ hold()

◆ show()

◆ delay()

◆ color() [1/3]

◆ color() [2/3]

◆ color() [3/3]

◆ print_color()

◆ kelvin_to_rgb()

◆ blur()

◆ blur_x()

◆ blur_y()

◆ dim()

◆ color_blur()

◆ color_blur_x()

◆ color_blur_y()

◆ color_dim()

◆ draw_line_color()

◆ draw_line_mask()