WS2812_RMT Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Namespaces | Functions | Variables
ws2812_rmt_functions.hpp File Reference

The pure functions of the WS2812_RMT driver: colour scaling, gamma, pixel encoding, the waveform resolver, frame arithmetic and Validate(). More...

#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <span>
#include "ws2812_rmt_detail.hpp"
#include "ws2812_rmt_gamma.hpp"
#include "ws2812_rmt_types.hpp"

Go to the source code of this file.

Namespaces

namespace  ws2812_rmt
 The WS2812_RMT driver: everything it declares lives here; internals in detail.
 

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
 

Detailed Description

The pure functions of the WS2812_RMT driver: colour scaling, gamma, pixel encoding, the waveform resolver, frame arithmetic and Validate().

Everything here is constexpr, noexcept and free of state: it is tested exhaustively or against an independent oracle (tests/), and the driver class only calls it. No floating point, no allocation.