NeilClack
da0b6ffd5e
ScrollerPage now resolves the active Block from ScheduleManager (reusing the existing stream-switch path), honoring dynamicAudio true/false and falling back to local selection for gaps, no schedule, or toggle off. Adds a 'Schedule' On/Off entry (default On) in System Settings persisted in config.yaml, and config plumbing (proclamation.schedule_enabled). All on-device schedule times remain 12h AM/PM.
186 lines
9.6 KiB
Plaintext
186 lines
9.6 KiB
Plaintext
#pragma once
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Fibonacci affine image scrambling (RadiantWave scroller text obfuscation)
|
|
//
|
|
// This module implements the Fibonacci affine transformation as a reversible
|
|
// image permutation. The RadiantWave scroller uses it to render proclamation
|
|
// text as scrambled glyphs: every code point's glyph is permuted by the map
|
|
// below so letterforms are destroyed and the text is never readable on screen,
|
|
// while the exact inverse recovers the original glyph given the same key.
|
|
//
|
|
// ---------------------------------------------------------------------------
|
|
// [Published: Williams 2007] -- concepts from the published research
|
|
//
|
|
// Ben Williams, "Some properties of digital image scrambling methods using
|
|
// Fibonacci numbers", MATH491 Summer Research Project 2006-2007, Department
|
|
// of Mathematics and Statistics, University of Canterbury, 2007 (mirrored in
|
|
// this repository as algorithm.md).
|
|
//
|
|
// Mathematical foundations:
|
|
// - The Fibonacci matrix (Definition 2.2) is
|
|
// F = [ 0 1 ]
|
|
// [ 1 1 ]
|
|
// so consecutive Fibonacci numbers satisfy u(n+1) = F.u(n). It squares to
|
|
// the Arnold matrix F^2 = [[1,1],[1,2]] (Remark 3).
|
|
// - The Fibonacci affine transformation (Definition 4.1) acts on the square
|
|
// grid Z_m^2 = {0..m-1}^2 with modular arithmetic (Section 3):
|
|
// T(x) = F.x + b (mod m), b in Z_m^2.
|
|
// - An affine map x -> A.x + b is a bijection of Z_m^2 iff gcd(det A, m) = 1
|
|
// (Theorem 3.1 / Corollary 3.2), and it is periodic under the same
|
|
// condition (Theorem 3.4).
|
|
// - det F = -1, which is coprime to every m. By Proposition 4.1 the
|
|
// Fibonacci affine transformation is therefore a permutation of Z_m^2 for
|
|
// EVERY modulus m: no constraint whatsoever on the grid size.
|
|
// - The paper decrypts by re-applying T until the period recurs. Section 5
|
|
// notes the period of F mod m can reach 6m, so that route is slow; the
|
|
// paper never uses the inverse transform.
|
|
//
|
|
// ---------------------------------------------------------------------------
|
|
// [Adapted beyond the paper] -- generalization from algorithm.md's appendix
|
|
// (lines 491-500)
|
|
//
|
|
// Two extensions turn the published square-only transform into an
|
|
// arbitrary-size scrambler with a fast, exact round trip:
|
|
//
|
|
// 1. Arbitrary image sizes. Any W x H image is embedded in a square canvas
|
|
// of side
|
|
// N = canvasSize(W, H) = max(W, H)
|
|
// and T acts on Z_N^2. Because det F = -1 is invertible for every N, no
|
|
// Fibonacci-number, power-of-two, or other size constraint applies. (The
|
|
// size restriction in the paper was specific to Zou's scaled transform,
|
|
// Definition 4.3, not to the plain Fibonacci affine map.)
|
|
//
|
|
// 2. Exact inverse instead of period iteration. Since
|
|
// F^-1 = [ -1 1 ]
|
|
// [ 1 0 ]
|
|
// exists for every modulus, decryption applies the inverse directly and
|
|
// costs exactly as many rounds as encryption -- not up to 6N applications
|
|
// of T. This also turns the key into (round count, offset sequence):
|
|
// scramble applies the per-round offsets b1..bt in order, and unscramble
|
|
// applies the inverse in reverse order.
|
|
//
|
|
// ---------------------------------------------------------------------------
|
|
// [This implementation] -- project-specific engineering decisions
|
|
//
|
|
// Gather-form permutation. Each round is a single gather pass:
|
|
// scramble: dst[y] = src[preimage(y)], preimage(y) = T^-1(y)
|
|
// unscramble: dst[y] = src[image(y)], image(y) = T(y)
|
|
// Every output pixel is produced from exactly one input pixel, so there are
|
|
// never holes or collisions, and the padding convention is filled directly
|
|
// where a preimage falls outside the source. (The paper describes the
|
|
// forward scatter -- source pixel at x moves to T(x); gather is the
|
|
// equivalent output-directed formulation.)
|
|
//
|
|
// Composition semantics. Scrambling applies the inverse maps in round order
|
|
// (T1^-1, T2^-1, ..., Tt^-1); unscrambling applies the forward maps in
|
|
// reverse order (Tt, ..., T1). The composition telescopes:
|
|
// T1^-1( T2^-1( ... Tt^-1( Tt( ... T2( T1(y) ) ... ) ) ... ) ) = y
|
|
// so the round trip is exact in exactly `rounds` passes, regardless of the
|
|
// transform's period. Padding is created in round 1 and then permuted like
|
|
// any other pixel; because the composition is a bijection, each W x H output
|
|
// position of the final reverse pass maps to a canvas position holding a real
|
|
// source pixel, so no padding value ever reaches the recovered W x H region.
|
|
// (Intermediate reverse passes do read padding pixels -- they move the full
|
|
// N x N canvas -- but they are routed out of the W x H output.)
|
|
//
|
|
// Key derivation. The key is the (seed, rounds) pair. Each round derives its
|
|
// offset vector b = (b0, b1) from `seed` via splitmix64 -- two consecutive
|
|
// pure-integer draws reduced mod N:
|
|
// b0 = splitmix64(seed) mod N, b1 = splitmix64(seed) mod N.
|
|
// Pure integer arithmetic makes the offsets bit-identical on every platform,
|
|
// so a compile-time seed produces identical scrambling everywhere. The
|
|
// scroller fixes the seed at compile time (kDefaultSeed), meaning the same
|
|
// glyph scrambles identically on every device and every run, and no key
|
|
// state is ever persisted or transmitted.
|
|
//
|
|
// Padding convention. During scramble the W x H source sits in the natural
|
|
// top-left embedding of the N x N canvas. Canvas positions whose preimage
|
|
// falls outside [0, W) x [0, H) are written as transparent black
|
|
// (0, 0, 0, 0), which is invisible on a black background.
|
|
// Because the map is a bijection, the W x H source pixels land on W x H
|
|
// distinct canvas positions, and the remaining N^2 - W*H positions are
|
|
// padding. unscramble() reads the whole N x N canvas and writes only the
|
|
// W x H region, reproducing the source exactly. Display uses the matching
|
|
// crop-window convention: render the top-left W x H sub-rectangle of the
|
|
// scrambled canvas.
|
|
//
|
|
// Whole pixels. Each RGBA8888 pixel, alpha included, is permuted as a unit,
|
|
// so a round trip preserves alpha exactly.
|
|
//
|
|
// In-place hazard / scratch. A gather pass is not safe in place: within one
|
|
// pass, dst[y] = src[p(y)] reads source position p(y) after an earlier write
|
|
// at that same position may have replaced it (whenever p(y) < y in iteration
|
|
// order). Every pass therefore reads and writes distinct buffers. Two
|
|
// ping-pong scratch buffers of N*N*4 bytes are reused across rounds, so read
|
|
// and write never alias while memory stays bounded.
|
|
//
|
|
// Numerics. All coordinate products are accumulated in int64_t and reduced
|
|
// mod N, which is exact for any N whose squares fit comfortably in int64_t
|
|
// (N <= 2^30). Rounds below 1 are clamped to 1; N == 1 (a 1x1 image) yields
|
|
// the identity map, which is correct. In practice N is the side of a glyph
|
|
// tile, at most a few hundred pixels.
|
|
//
|
|
// Format & portability. The module is SDL-free and pure C++17: it operates
|
|
// on tightly packed RGBA8888 pixels (4 bytes per pixel, row stride = width *
|
|
// 4) and keeps no state between calls. Any caller can adopt it; the scroller
|
|
// uses it per glyph (see scroller_page.cpp).
|
|
//
|
|
// Why CPU. Glyph tiles are tiny and every distinct code point's tile is
|
|
// scrambled at most once per font size and then cached, so the total cost is
|
|
// a one-time, amortized O(N^2 * rounds) integer permute per character. A GPU
|
|
// path would need per-texture compute passes or shader support that buys
|
|
// nothing here.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
#include <cstdint>
|
|
|
|
namespace radiantwave {
|
|
namespace scramble {
|
|
|
|
// Fixed compile-time seed so every device renders the same glyph scrambling.
|
|
// The value is splitmix64's golden-ratio constant; any constant would do, the
|
|
// requirement is only that it never changes across runs and platforms.
|
|
inline constexpr uint64_t kDefaultSeed = 0x9E3779B97F4A7C15ULL;
|
|
|
|
// Default round count. Each round applies the affine map once; more rounds mix
|
|
// pixels across a larger fraction of the canvas. Values below 1 are clamped to
|
|
// 1 by the API.
|
|
inline constexpr int kDefaultRounds = 4;
|
|
|
|
// Per-call configuration: how many rounds and which key (seed).
|
|
struct ScrambleConfig
|
|
{
|
|
int rounds = kDefaultRounds;
|
|
uint64_t seed = kDefaultSeed;
|
|
};
|
|
|
|
// Square canvas side N for a W x H image: N = max(W, H).
|
|
// Returns 0 when width or height is < 1 (the scramble/unscramble entry points
|
|
// reject N == 0).
|
|
int canvasSize(int width, int height);
|
|
|
|
// Scramble a W x H RGBA8888 image (tightly packed, stride = width * 4) into
|
|
// an N x N RGBA8888 canvas where N = canvasSize(width, height). `dst` must
|
|
// hold at least N*N*4 bytes. Out-of-canvas source coordinates are written as
|
|
// transparent black per the padding convention above. `src` and `dst` must not
|
|
// alias.
|
|
//
|
|
// Returns false (writing nothing to `dst`) when width/height < 1, when either
|
|
// pointer is null, or when N exceeds the int64-safe bound (2^30).
|
|
bool scramble(const uint8_t* src, uint8_t* dst, int width, int height,
|
|
const ScrambleConfig& config);
|
|
|
|
// Exact inverse of scramble(): reads the N x N RGBA8888 canvas (stride =
|
|
// N * 4) and writes back the top-left W x H RGBA8888 region (stride = width *
|
|
// 4). `dst` must hold at least W*H*4 bytes. Must be called with the same
|
|
// (width, height, config) as the matching scramble() -- the key is the same
|
|
// tuple. `src` and `dst` must not alias.
|
|
//
|
|
// Returns false under the same conditions as scramble().
|
|
bool unscramble(const uint8_t* src, uint8_t* dst, int width, int height,
|
|
const ScrambleConfig& config);
|
|
|
|
} // namespace scramble
|
|
} // namespace radiantwave
|