Adafruit_NeoPXL8HDR Class Reference

Adafruit_NeoPXL8HDR is a subclass of Adafruit_NeoPXL8 with additions for 16-bits-per-channel color, temporal dithering, frame blending and gamma correction. This requires inordinate RAM, and the frequent need for refreshing makes it best suited for multi-core chips (e.g. RP2040). More...

#include <Adafruit_NeoPXL8.h>

Inheritance diagram for Adafruit_NeoPXL8HDR:

Public Member Functions
	Adafruit_NeoPXL8HDR (uint16_t n, int8_t *p=NULL, neoPixelType t=NEO_GRB)
	NeoPXL8HDR constructor. Instantiates a new NeoPXL8HDR object (must follow with a begin() call to alloc buffers and init hardware). More...
bool	begin (bool blend=false, uint8_t bits=4, bool dbuf=false)
	Allocate buffers and initialize hardware for NeoPXL8 output. More...
void	setBrightness (uint8_t b)
	Set peak output brightness for all channels (RGB and W if present) to the same value. Existing gamma setting is unchanged. This is for compatibility with existing NeoPixel or NeoPXL8 sketches moved directly to NeoPXL8HDR. New code may prefer one of the other setBrightness() invocations, which provide 16-bit adjustment plus gamma correction. More...
void	setBrightness (uint16_t b, float y)
	Set peak output brightness for all channels (RGB and W if present) to the same value, and set gamma curve. More...
void	setBrightness (uint16_t r, uint16_t g, uint16_t b)
	Set peak output brightness for R, G, B channels independently. Existing gamma setting is unchanged. W brightness, if present, is unchanged. More...
void	setBrightness (uint16_t r, uint16_t g, uint16_t b, uint16_t w)
	Set peak output brightness for R, G, B, W channels independently. Existing gamma setting is unchanged. More...
void	setBrightness (uint16_t r, uint16_t g, uint16_t b, float y)
	Set peak output brightness for R, G, B channels independently, and set gamma curve. W brightness, if present, is unchanged. More...
void	setBrightness (uint16_t r, uint16_t g, uint16_t b, uint16_t w, float y)
	Set peak output brightness for R, G, B, W channels independently, and set gamma curve. More...
void	show (void)
	Provide new pixel data to the refresh handler (but does not actually refresh the strip - use refresh() for that).
void	refresh (void)
	Dither (and blend, if enabled) and issue new data to the NeoPixel strands.
void	stage (void) const
	Overload the stage() function from Adafruit_NeoPXL8. Does nothing in NeoPXL8HDR, provided for compatibility.
bool	canStage (void) const
	Overload the canStage() function from Adafruit_NeoPXL8. Does nothing in NeoPXL8HDR, provided for compatibility. More...
bool	canShow (void) const
	Overload the canShow() function from Adafruit_NeoPXL8. Does nothing in NeoPXL8HDR, provided for compatibility. More...
void	setPixelColor (uint16_t n, uint8_t r, uint8_t g, uint8_t b)
	Set a pixel's color using separate red, green and blue components. If using RGBW pixels, white will be set to 0. More...
void	setPixelColor (uint16_t n, uint8_t r, uint8_t g, uint8_t b, uint8_t w)
	Set a pixel's color using separate red, green, blue and white components (for RGBW NeoPixels). More...
void	setPixelColor (uint16_t n, uint32_t c)
	Set a pixel's color using a 32-bit 'packed' RGB or RGBW value. More...
void	set16 (uint16_t n, uint16_t r, uint16_t g, uint16_t b, uint16_t w=0)
	Set a pixel's color using a 16-bit R, G, B and optionally W values. More...
uint32_t	getPixelColor (uint16_t n) const
	Query the color of a previously-set pixel, reduced to 8-bit components. This is for compatibility with existing NeoPixel or NeoPXL8 sketches moved directly to NeoPXL8HDR. New code may prefer get16() instead, which returns the pristine true 16-bit value previously set. More...
void	get16 (uint16_t n, uint16_t *r, uint16_t *g, uint16_t *b, uint16_t *w=NULL) const
	Query the color of a previously-set pixel, returning the original 16-bit values. More...
uint16_t *	getPixels (void) const
	Get a pointer directly to the NeoPXL8HDR data buffer in RAM. Pixel data is unsigned 16-bit, always RGB (3 words/pixel) or RGBW (4 words/pixel) order; different NeoPixel hardware color orders are covered by the library and do not need to be handled in calling code. Nice. More...
uint32_t	getFPS (void) const
	Query overall display refresh rate in frames-per-second. This is only an estimate and requires a moment to stabilize; will initially be 0. It's really only helpful on RP2040 where the refresh loop runs full-tilt on its own core; on SAMD, refresh is handled with a fixed timer interrupt. More...
void	clear (void)
	Fill the whole NeoPixel strip with 0 / black / off. More...
Public Member Functions inherited from Adafruit_NeoPXL8
	Adafruit_NeoPXL8 (uint16_t n, int8_t *p=NULL, neoPixelType t=NEO_GRB)
	NeoPXL8 constructor. Instantiates a new NeoPXL8 object (must follow with a begin() call to alloc buffers and init hardware). More...
bool	begin (bool dbuf=false)
	Allocate buffers and initialize hardware for NeoPXL8 output. More...
void	show (void)
	Process and issue new data to the NeoPixel strands.
void	stage (void)
	Preprocess NeoPixel data into DMA-ready format, but do not issue to strands yet. Esoteric but potentially useful if aiming to have pixels refresh at precise intervals (since preprocessing is not deterministic) – e.g. 60 Hz – follow with a call to show() when the actual data transfer is to occur.
bool	canShow (void) const
	Poll whether last show() transfer has completed and library is idle. Of questionable utility, but provided for compatibility with similarly questionable function in the NeoPixel library. More...
bool	canStage (void) const
	Poll whether last show() data transfer has completed, but not necessarily the end-of-data latch. This is the earliest moment at which one can stage() the next frame of data. More...
void	setBrightness (uint8_t b)
	Set strip brightness for subsequent show() calls. Unlike the Adafruit_NeoPixel library, this function is non-destructive – original color values passed to setPixelColor() will always be accurately returned by getPixelColor(), even if brightness is adjusted. More...
uint8_t	getBrightness (void) const
	Query brightness value last assigned with setBrightness(). More...
void	setLatchTime (uint16_t us=300)
	Change the NeoPixel end-of-data latch period. Here be dragons. More...

Protected Member Functions
void	calc_gamma_table (void)
	Recalculate the tables used for gamma correction and temporal dithering. Used internally, not for user code. Invoked by the brightness/gamma-setting functions.

Protected Attributes
float	gfactor
	Gamma: 1.0=linear, 2.6=typ.
uint16_t *	pixel_buf [3] = {NULL, NULL, NULL}
	Buffer for NeoPXL8 staging.
uint16_t *	dither_table = NULL
	Temporal dithering lookup.
uint32_t	last_show_time = 0
	micros() @ last show()
uint32_t	avg_show_interval = 0
	Avergage uS between show()
uint32_t	fps = 0
	Estimated refreshes/second.
uint32_t	last_fps_time = 0
	micros() @ last estimate
uint16_t	g16 [4][256]
	Gamma look up table.
uint16_t	brightness_rgbw [4]
	Peak brightness/channel.
uint8_t	dither_bits
	bits for temporal dither
uint8_t	dither_index = 0
	Current dither_table pos.
uint8_t	stage_index = 0
	Ping-pong pixel_buf.
volatile bool	new_pixels = true
	show()/refresh() sync
Protected Attributes inherited from Adafruit_NeoPXL8
Adafruit_ZeroDMA	dma
	DMA object.
DmacDescriptor *	desc
	DMA descriptor pointer.
uint8_t *	allocAddr
	Allocated buffer into which dmaBuf points.
uint32_t *	alignedAddr [2]
	long-aligned ptrs into dmaBuf
int8_t	pins [8]
	Pin list for 8 NeoPixel strips.
uint8_t	bitmask [8]
	Pattern generator bitmask for each pin.
uint8_t *	dmaBuf [2] = {NULL, NULL}
	Buffer for pixel data + any extra.
uint16_t	brightness = 255
	Brightness (stored 1-256, not 0-255)
bool	staged
	If set, data is ready for DMA trigger.
uint16_t	latchtime = 300
	Pixel data latch time, microseconds.
uint8_t	dbuf_index = 0
	0/1 DMA buffer index

Detailed Description

Adafruit_NeoPXL8HDR is a subclass of Adafruit_NeoPXL8 with additions for 16-bits-per-channel color, temporal dithering, frame blending and gamma correction. This requires inordinate RAM, and the frequent need for refreshing makes it best suited for multi-core chips (e.g. RP2040).

Constructor & Destructor Documentation

Adafruit_NeoPXL8HDR()

Adafruit_NeoPXL8HDR::Adafruit_NeoPXL8HDR	(	uint16_t	n,
		int8_t *	p = NULL,
		neoPixelType	t = NEO_GRB
	)

NeoPXL8HDR constructor. Instantiates a new NeoPXL8HDR object (must follow with a begin() call to alloc buffers and init hardware).

Parameters

n	Length of each NeoPixel strand (total number of pixels will be 8X this).
p	Optional int8_t array of eight pin numbers for NeoPixel strands 0-7. There are specific hardware limitations as to which pins can be used, see the example sketch. If fewer than 8 outputs are needed, assign a value of -1 to the unused outputs, keeping in mind that this will always still use the same amount of memory as 8-way output. If unspecified (or if NULL is passed), a default 8-pin setup will be used (see example sketch). On RP2040, these are GP## numbers, not necessarily the digital pin numbers silkscreened on the board.
t	NeoPixel color data order, same as in Adafruit_NeoPixel library (optional, default is GRB).

Member Function Documentation

begin()

bool Adafruit_NeoPXL8HDR::begin	(	bool	blend = false,
		uint8_t	bits = 4,
		bool	dbuf = false
	)

Allocate buffers and initialize hardware for NeoPXL8 output.

Parameters

blend	If true, provide frame-to-frame blending via the refresh() function between show() calls (uses more RAM). If false (default), no blending. This is useful ONLY if sketch can devote time to many refresh() calls, e.g. on multicore RP2040.
bits	Number of bits for temporal dithering, 0-8. Higher values provide more intermediate shades but slower refresh; dither becomes more apparent. Default is 4, providing 12-bit effective range per channel.
dbuf	If true, 2X DMA buffers are allocated so that a frame can be NeoPXL8-staged while the prior is in mid-transfer. Might yield slightly improved frame rates in some cases, others just waste RAM. Currently ignored on SAMD.

Returns

true on successful alloc/init, false otherwise.

setBrightness() [1/6]

void Adafruit_NeoPXL8HDR::setBrightness

(

uint8_t

b

)

Set peak output brightness for all channels (RGB and W if present) to the same value. Existing gamma setting is unchanged. This is for compatibility with existing NeoPixel or NeoPXL8 sketches moved directly to NeoPXL8HDR. New code may prefer one of the other setBrightness() invocations, which provide 16-bit adjustment plus gamma correction.

Parameters

b	Brightness value, 0-255. This is the LEDs' maximum duty cycle and is not itself gamma-corrected.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades!

setBrightness() [2/6]

void Adafruit_NeoPXL8HDR::setBrightness	(	uint16_t	b,
		float	y
	)

Set peak output brightness for all channels (RGB and W if present) to the same value, and set gamma curve.

Parameters

b	Brightness value, 0-65535. This is the LEDs' maximum duty cycle and is not itself gamma-corrected.
y	Gamma exponent; 1.0 is linear, 2.6 is a typical correction factor for NeoPixels.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades! Note to future self: do NOT provide a default gamma value here, it MUST be specified, even if 1.0. This avoids ambiguity with the back-compatible setBrightness(uint8_t) above without weird explicit casts in user code.

setBrightness() [3/6]

void Adafruit_NeoPXL8HDR::setBrightness	(	uint16_t	r,
		uint16_t	g,
		uint16_t	b
	)

Set peak output brightness for R, G, B channels independently. Existing gamma setting is unchanged. W brightness, if present, is unchanged.

Parameters

r	Red brightness value, 0-65535. This is the maximum duty cycle and is not itself gamma-corrected.
g	Green brightness value, 0-65535.
b	Blue brightness value, 0-65535.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades!

setBrightness() [4/6]

void Adafruit_NeoPXL8HDR::setBrightness	(	uint16_t	r,
		uint16_t	g,
		uint16_t	b,
		uint16_t	w
	)

Set peak output brightness for R, G, B, W channels independently. Existing gamma setting is unchanged.

Parameters

r	Red brightness value, 0-65535. This is the maximum duty cycle and is not itself gamma-corrected.
g	Green brightness value, 0-65535.
b	Blue brightness value, 0-65535.
w	White brightness value, 0-65535. Ignored if NeoPixel strips are RGB variety with no W.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades!

setBrightness() [5/6]

void Adafruit_NeoPXL8HDR::setBrightness	(	uint16_t	r,
		uint16_t	g,
		uint16_t	b,
		float	y
	)

Set peak output brightness for R, G, B channels independently, and set gamma curve. W brightness, if present, is unchanged.

Parameters

r	Red brightness value, 0-65535. This is the maximum duty cycle and is not itself gamma-corrected.
g	Green brightness value, 0-65535.
b	Blue brightness value, 0-65535.
y	Gamma exponent; 1.0 is linear, 2.6 is a typical correction factor for NeoPixels.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades!

setBrightness() [6/6]

void Adafruit_NeoPXL8HDR::setBrightness	(	uint16_t	r,
		uint16_t	g,
		uint16_t	b,
		uint16_t	w,
		float	y
	)

Set peak output brightness for R, G, B, W channels independently, and set gamma curve.

Parameters

r	Red brightness value, 0-65535. This is the maximum duty cycle and is not itself gamma-corrected.
g	Green brightness value, 0-65535.
b	Blue brightness value, 0-65535.
w	White brightness value, 0-65535. Ignored if NeoPixel strips are RGB variety with no W.
y	Gamma exponent; 1.0 is linear, 2.6 is a typical correction factor for NeoPixels.

Note

This is typically set once at program startup and is not intended as an animation effect in itself, partly because the top value is an duty cycle and not a gamma-corrected level. Also, pixels will likely flash if this is called on an active NeoPXL8HDR object, as gamma tables are rewritten while blending/dithering is occurring. Well-designed animation code should handle its own fades!

canStage()

bool Adafruit_NeoPXL8HDR::canStage ( void  ) const

inline

Overload the canStage() function from Adafruit_NeoPXL8. Does nothing in NeoPXL8HDR, provided for compatibility.

Returns

true always.

canShow()

bool Adafruit_NeoPXL8HDR::canShow ( void  ) const

inline

Overload the canShow() function from Adafruit_NeoPXL8. Does nothing in NeoPXL8HDR, provided for compatibility.

Returns

true always.

setPixelColor() [1/3]

void Adafruit_NeoPXL8HDR::setPixelColor	(	uint16_t	n,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b
	)

Set a pixel's color using separate red, green and blue components. If using RGBW pixels, white will be set to 0.

Parameters

n	Pixel index, starting from 0.
r	Red brightness, 0 = minimum (off), 255 = maximum.
g	Green brightness, 0 = minimum (off), 255 = maximum.
b	Blue brightness, 0 = minimum (off), 255 = maximum.

setPixelColor() [2/3]

void Adafruit_NeoPXL8HDR::setPixelColor	(	uint16_t	n,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b,
		uint8_t	w
	)

Set a pixel's color using separate red, green, blue and white components (for RGBW NeoPixels).

Parameters

n	Pixel index, starting from 0.
r	Red brightness, 0 = minimum (off), 255 = maximum.
g	Green brightness, 0 = minimum (off), 255 = maximum.
b	Blue brightness, 0 = minimum (off), 255 = maximum.
w	White brightness, 0 = minimum (off), 255 = maximum, ignored if using RGB pixels.

setPixelColor() [3/3]

void Adafruit_NeoPXL8HDR::setPixelColor	(	uint16_t	n,
		uint32_t	c
	)

Set a pixel's color using a 32-bit 'packed' RGB or RGBW value.

Parameters

n	Pixel index, starting from 0.
c	32-bit color value. Most significant byte is white (for RGBW pixels) or ignored (for RGB pixels), next is red, then green, and least significant byte is blue.

set16()

void Adafruit_NeoPXL8HDR::set16	(	uint16_t	n,
		uint16_t	r,
		uint16_t	g,
		uint16_t	b,
		uint16_t	w = 0
	)

Set a pixel's color using a 16-bit R, G, B and optionally W values.

Parameters

n	Pixel index, starting from 0.
r	16-bit red component.
g	16-bit green component.
b	16-bit blue component.
w	16-bit white component (optional argument, RGBW strips only, ignored if RGB).

getPixelColor()

uint32_t Adafruit_NeoPXL8HDR::getPixelColor

(

uint16_t

n

)

const

Query the color of a previously-set pixel, reduced to 8-bit components. This is for compatibility with existing NeoPixel or NeoPXL8 sketches moved directly to NeoPXL8HDR. New code may prefer get16() instead, which returns the pristine true 16-bit value previously set.

Parameters

n	Index of pixel to read (0 = first).

Returns

'Packed' 32-bit RGB or WRGB value. Most significant byte is white (for RGBW pixels) or 0 (for RGB pixels), next is red, then green, and least significant byte is blue.

Note

Unlike the NeoPixel library, brightness scaling is not a destructive operation; the data stored is what was set. However, color components are reduced from 16 to 8 bits. "16-bit-aware" code should use get16() instead.

get16()

void Adafruit_NeoPXL8HDR::get16	(	uint16_t	n,
		uint16_t *	r,
		uint16_t *	g,
		uint16_t *	b,
		uint16_t *	w = NULL
	)		const

Query the color of a previously-set pixel, returning the original 16-bit values.

Parameters

n	Index of pixel to read (0 = first).
r	Pointer to unsigned 16-bit variable to hold red result, must be non-NULL, no check performed.
g	Pointer to unsigned 16-bit variable to hold green result, must be non-NULL, no check performed.
b	Pointer to unsigned 16-bit variable to hold blue result, must be non-NULL, no check performed.
w	Pointer to unsigned 16-bit variable to hold white result (if RGBW strip, else 0 if RGB), or NULL to ignore.

Note

Unlike the NeoPixel library, the value returned is always equal to the value previously set; brightness scaling is not a destructive operation with this library.

getPixels()

uint16_t* Adafruit_NeoPXL8HDR::getPixels ( void  ) const

inline

Get a pointer directly to the NeoPXL8HDR data buffer in RAM. Pixel data is unsigned 16-bit, always RGB (3 words/pixel) or RGBW (4 words/pixel) order; different NeoPixel hardware color orders are covered by the library and do not need to be handled in calling code. Nice.

Returns

Pointer to NeoPixel buffer (uint16_t* array).

Note

This is for high-performance applications where calling set16() or setPixelColor() on every single pixel would be too slow. There is no bounds checking on the array, creating tremendous potential for mayhem if one writes past the ends of the buffer. Great power, great responsibility and all that.

getFPS()

uint32_t Adafruit_NeoPXL8HDR::getFPS ( void  ) const

inline

Query overall display refresh rate in frames-per-second. This is only an estimate and requires a moment to stabilize; will initially be 0. It's really only helpful on RP2040 where the refresh loop runs full-tilt on its own core; on SAMD, refresh is handled with a fixed timer interrupt.

Returns

Integer frames (pixel refreshes) per second.

clear()

void Adafruit_NeoPXL8HDR::clear ( void  )

inline

Fill the whole NeoPixel strip with 0 / black / off.

Note

Overloaded from Adafruit_NeoPixel because stored different here.

---

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

• Adafruit_NeoPXL8.h
• Adafruit_NeoPXL8.cpp