|
WS2812_RMT Driver 0.1.0
API reference
|
Colour maths, encoding, the waveform resolver and frame arithmetic. More...
Functions | |
| constexpr uint8_t | ws2812_rmt::Scale8 (uint8_t v, uint8_t b) noexcept |
round(v * b / 255), halves up: exact at b = 255 (identity) and b = 0 (zero), monotone in both arguments, at most half a least significant bit of error. (The old truncating form differed by at most one.) | |
| constexpr uint8_t | ws2812_rmt::ApplyGamma (uint8_t v, Gamma gamma) noexcept |
| The transfer curve of a channel value. | |
| constexpr uint8_t | ws2812_rmt::ChannelOf (const Colour &colour, Channel channel) noexcept |
| One channel of a colour. | |
| constexpr uint8_t | ws2812_rmt::WireValue (uint8_t v, uint8_t brightness, Gamma gamma) noexcept |
| The wire value of a channel: gamma first, then brightness (linear dimming of the corrected value). | |
| constexpr bool | ws2812_rmt::IsValidOrder (const ColourOrder &order) noexcept |
Whether order is usable: a count of 3 (distinct channels among R, G, B) or 4 (all four). | |
| constexpr size_t | ws2812_rmt::EncodePixel (const Colour &colour, const ColourOrder &order, uint8_t brightness, Gamma gamma, std::span< uint8_t > out) noexcept |
| Encode one pixel into wire order. | |
| constexpr size_t | ws2812_rmt::EncodeFrame (std::span< const Colour > pixels, const ColourOrder &order, uint8_t brightness, Gamma gamma, std::span< uint8_t > out) noexcept |
| Encode a whole strip, pixel 0 first. | |
| constexpr size_t | ws2812_rmt::DecodeWire (std::span< const uint8_t > wire, const ColourOrder &order, std::span< Colour > out) noexcept |
The inverse of EncodeFrame() at brightness 255 and no gamma, for models and tests. | |
| constexpr Colour | ws2812_rmt::ExtractWhite (const Colour &colour) noexcept |
| Move the common part of red, green and blue into the white channel, for an RGBW strip that should show an RGB colour with the white die. Never applied implicitly. | |
| constexpr Colour | ws2812_rmt::Wheel (uint8_t position) noexcept |
| A colour wheel: red to green to blue to red in three segments of 85 steps. | |
| constexpr uint64_t | ws2812_rmt::NsToTicks (uint64_t ns, uint64_t hz) noexcept |
round(ns * hz / 1e9), halves up, in 64 bits (ns and hz below 2^32 cannot overflow). | |
| constexpr Result< Waveform > | ws2812_rmt::ResolveWaveform (const Timing &timing, uint32_t resolution_hz, uint32_t reset_us) noexcept |
| Turn a timing into ticks at the port's real tick rate. | |
| constexpr uint64_t | ws2812_rmt::TicksToNs (uint64_t ticks, uint32_t resolution_hz) noexcept |
| Convert ticks back to nanoseconds, rounding up (frame arithmetic, never a window check). | |
| constexpr bool | ws2812_rmt::WaveformInWindow (Variant variant, const Waveform &wave) noexcept |
| The windows check of a waveform against a named profile, in exact integer arithmetic: the mixed-chain and compatibility helper (is this waveform legal for that variant). | |
| constexpr uint64_t | ws2812_rmt::FrameBits (size_t pixels, uint8_t channels) noexcept |
| The number of bits in a frame. | |
| constexpr uint64_t | ws2812_rmt::FrameTimeNs (size_t pixels, uint8_t channels, const Waveform &wave) noexcept |
| Worst-case time of a frame: every bit a one (or a zero, whichever is longer), plus the reset. | |
| constexpr uint32_t | ws2812_rmt::MaxRefreshHz (size_t pixels, uint8_t channels, const Waveform &wave) noexcept |
| The refresh rate the frame time allows. | |
| constexpr size_t | ws2812_rmt::MaxPixelsAtRate (uint32_t rate_hz, uint8_t channels, const Waveform &wave) noexcept |
The longest strip that still refreshes at rate_hz. | |
| constexpr Result< uint32_t > | ws2812_rmt::ResolveRmtRate (uint32_t source_hz, uint32_t requested_hz, uint32_t tolerance_ppm=1000U) noexcept |
The tick rate an ESP32 RMT channel really runs at, computed as ESP-IDF v5.5 does (rmt_common.c): the channel divider is rounded to the nearest integer, (clock + request / 2) / request, so the real rate can be above or below the request. On the targets with a group prescaler (all but the ESP32 and ESP32-S2) the group prescaler is the first from 1 up that brings that divider into 1 to 256; on the ESP32 and ESP32-S2 the divider is the rounded one directly, which gives the same rate whenever it is at most 256 (every request above source_hz / 256). | |
| constexpr uint32_t | ws2812_rmt::MinLogicHighMv (Variant variant, uint32_t vdd_mv) noexcept |
| The lowest logic-high level the part's DIN accepts at a supply voltage, from the part's electrical table (informational: the driver cannot see the supply; docs/hardware.md). | |
| constexpr Timing | ws2812_rmt::TimingOf (const Config &config) noexcept |
| The timing a configuration selects. | |
| constexpr ColourOrder | ws2812_rmt::OrderOf (const Config &config) noexcept |
| The wire order a configuration selects. | |
| constexpr Result< void > | ws2812_rmt::Validate (const Config &config, size_t capacity) noexcept |
Check a configuration against a strip capacity without touching hardware. Pure and constexpr, so a fixed configuration can be proved with static_assert. | |
Variables | |
| constexpr uint64_t | ws2812_rmt::kNsPerSecond = 1'000'000'000ULL |
| Nanoseconds in a second, for the integer tick arithmetic. | |
| constexpr uint32_t | ws2812_rmt::kRmtMaxPrescale = 256 |
Colour maths, encoding, the waveform resolver and frame arithmetic.
|
constexprnoexcept |
The transfer curve of a channel value.
| v | The value. |
| gamma | The curve. |
v for Gamma::None, the table entry for Gamma::Gamma22.
|
constexprnoexcept |
One channel of a colour.
| colour | The colour. |
| channel | The channel. |
|
constexprnoexcept |
The inverse of EncodeFrame() at brightness 255 and no gamma, for models and tests.
| wire | Bytes in wire order. |
| order | The wire order. |
| out | Receives one colour per complete pixel of wire; unused channels stay 0. |
order is invalid.
|
constexprnoexcept |
Encode a whole strip, pixel 0 first.
| pixels | The logical colours. |
| order | The wire order. |
| brightness | Linear dimming. |
| gamma | The curve. |
| out | Receives pixels.size() x order.count bytes. |
order is invalid or out is too small (nothing is written).
|
constexprnoexcept |
Encode one pixel into wire order.
| colour | The logical colour; w is ignored for a three-channel order. |
| order | The wire order. |
| brightness | Linear dimming. |
| gamma | The curve. |
| out | Receives order.count bytes. |
order is invalid or out is too small (nothing is written). Move the common part of red, green and blue into the white channel, for an RGBW strip that should show an RGB colour with the white die. Never applied implicitly.
| colour | An RGB colour (w is replaced). |
w = min(r, g, b), subtracted from the other three.
|
constexprnoexcept |
The number of bits in a frame.
| pixels | Pixels. |
| channels | Channels per pixel (3 or 4). |
pixels x channels x 8.
|
constexprnoexcept |
Worst-case time of a frame: every bit a one (or a zero, whichever is longer), plus the reset.
| pixels | Pixels. |
| channels | Channels per pixel. |
| wave | The waveform. |
|
constexprnoexcept |
Whether order is usable: a count of 3 (distinct channels among R, G, B) or 4 (all four).
| order | The order. |
|
constexprnoexcept |
The longest strip that still refreshes at rate_hz.
| rate_hz | Frames per second, non-zero. |
| channels | Channels per pixel. |
| wave | The waveform. |
|
constexprnoexcept |
The refresh rate the frame time allows.
| pixels | Pixels. |
| channels | Channels per pixel. |
| wave | The waveform. |
|
constexprnoexcept |
The lowest logic-high level the part's DIN accepts at a supply voltage, from the part's electrical table (informational: the driver cannot see the supply; docs/hardware.md).
| variant | The variant; Custom returns the generic 0.7 x VDD. |
| vdd_mv | The supply in millivolts. |
kMaxSupplyMv counts as kMaxSupplyMv.
|
constexprnoexcept |
round(ns * hz / 1e9), halves up, in 64 bits (ns and hz below 2^32 cannot overflow).
| ns | A duration in nanoseconds. |
| hz | A tick rate. |
|
constexprnoexcept |
The wire order a configuration selects.
| config | The configuration. |
config.order unless use_default_order is set, then the variant's default.
|
constexprnoexcept |
The tick rate an ESP32 RMT channel really runs at, computed as ESP-IDF v5.5 does (rmt_common.c): the channel divider is rounded to the nearest integer, (clock + request / 2) / request, so the real rate can be above or below the request. On the targets with a group prescaler (all but the ESP32 and ESP32-S2) the group prescaler is the first from 1 up that brings that divider into 1 to 256; on the ESP32 and ESP32-S2 the divider is the rounded one directly, which gives the same rate whenever it is at most 256 (every request above source_hz / 256).
| source_hz | The source clock in hertz. |
| requested_hz | The tick rate asked for. |
| tolerance_ppm | The largest deviation accepted, in parts per million. |
TimingUnreachable when a rate is 0, no divider reaches the request, or the real rate is more than tolerance_ppm from the request.
|
constexprnoexcept |
Turn a timing into ticks at the port's real tick rate.
Each of the four durations gets the tick count nearest its nominal that lies inside its window (windows inclusive); a bit period below period_min_ns is repaired by lengthening the low, and a period above period_max_ns or an empty window is TimingUnreachable. The reset is reset_us (0: the minimum plus kResetMarginUs), never at or below the minimum, which is a strict bound.
| timing | A valid timing (see Config::custom). |
| resolution_hz | The tick rate the port reported, 1 to kMaxResolutionHz. |
| reset_us | The reset low time, 0 for the default, at most kMaxResetUs. |
TimingUnreachable when no tick count fits (or the arguments are out of range).
|
constexprnoexcept |
round(v * b / 255), halves up: exact at b = 255 (identity) and b = 0 (zero), monotone in both arguments, at most half a least significant bit of error. (The old truncating form differed by at most one.)
| v | The channel value. |
| b | The brightness. |
|
constexprnoexcept |
Convert ticks back to nanoseconds, rounding up (frame arithmetic, never a window check).
| ticks | A tick count. |
| resolution_hz | The tick rate, non-zero. |
ceil(ticks * 1e9 / hz); 0 when resolution_hz is 0. The timing a configuration selects.
| config | The configuration. |
config.custom for Custom, the profile otherwise.
|
constexprnoexcept |
Check a configuration against a strip capacity without touching hardware. Pure and constexpr, so a fixed configuration can be proved with static_assert.
Rejected: an unknown variant or gamma; a custom timing on a named variant, or an inconsistent one on Custom; an order that is invalid, does not match the variant's channel count, or is missing on Custom; a reset_us that is not above the variant's minimum or above kMaxResetUs; a pixel count above the capacity or a capacity of 0 or above kMaxPixels; a settle or slack above its maximum.
| config | The configuration. |
| capacity | The pixel capacity of the driver object. |
Ok or InvalidArgument.
|
constexprnoexcept |
The windows check of a waveform against a named profile, in exact integer arithmetic: the mixed-chain and compatibility helper (is this waveform legal for that variant).
| variant | A named variant; Custom has no profile and returns false. |
| wave | The waveform. |
|
constexprnoexcept |
A colour wheel: red to green to blue to red in three segments of 85 steps.
| position | 0 to 255. |
|
constexprnoexcept |
The wire value of a channel: gamma first, then brightness (linear dimming of the corrected value).
| v | The logical value. |
| brightness | Linear dimming. |
| gamma | The curve. |
Scale8(ApplyGamma(v, gamma), brightness).
|
inlineconstexpr |
The largest group and channel prescaler of the ESP32 RMT (ESP-IDF v5.5, RMT_LL_GROUP_CLOCK_MAX_INTEGER_PRESCALE and RMT_LL_CHANNEL_CLOCK_MAX_PRESCALE).