Module gpuwav 

tc-gpu (stream magic TCG1): a GPU-decodable, random-access variant of the wavelet codec whose decode is integer only, so a CPU and a GPU decoder produce the same bytes.

Layout

• The field is cut into independent bricks (3D B³, 2D B² tiles), each with its own CDF 9/7 pyramid and its own entropy-coded lanes. A header index of brick sizes gives random access: a sub-box decodes only the bricks it touches.
• Values live on a fixed-point grid x ≈ v·2^e (v an i32); e is chosen so |x|/2^e ≤ 2^23 (the final i32 → f32 conversion is exact) and |x − mean|/2^e ≤ 2^20 (transform headroom inside i32).

Decode (integer only)

1. Coefficients. Each brick is coded in lanes independent rANS lanes (32-bit state, 16-bit words, 16-bit probabilities). Bands go coarse → fine; inside a band the lines along the fastest axis are split into passes by the parity of their (y, z) position (4 passes in 3D: (0,0) (1,1) (1,0) (0,1); 3 in 2D: y≡0 mod 4, y≡2 mod 4, odd y). A line conditions only on lines of earlier passes, coarser bands, and its own earlier samples, so every line of a pass decodes in parallel; lines of a pass are dealt round-robin to the lanes. Each lane owns its adaptive binary models (the hand model’s binarization: significance, adaptive-Golomb unary, low bits, sign) — adaptation is per lane, which is what keeps lanes independent.
2. Prediction. Per (level, orientation, pass) a 6-tap Q12 predictor over W, WW, Σfaces, Σdiagonals, Σ(±2 lines), parent, restricted to what the pass can see.
3. Dequantization in fixed point: c = ⌊|q|·m/2^s⌉ − ⌊δ·m/2^(s+9)⌉ with a per-band 31-bit step mantissa m.
4. Inverse CDF 9/7 lifting in i32 with Q24 constants and round-half-up products ⌊(a·k + 2^23)/2^24⌋ (a 32×32→64 multiply).
5. Max-abs corrections v += k·corr in the integer domain, then f32 = (v + mean) as f32 · 2^e — exact, since |v| < 2^24 and the scale is a normal power of two. Cells the grid still pushes past the bound are stored as raw f32 bits.

Structs

BandInfo

Per-band decode parameters.

BrickRef

A brick of a parsed stream.

DecSink

Decoder sink over a brick’s lanes.

Feats

Everything the coder derives for one coefficient.

GpuConfig

tc-gpu options.

GpuStats

Encoder statistics.

Parsed

A parsed stream header + brick index.

RansDec

Decoder of one lane.

RecSink

Encoder sink: records (cum, freq) per lane in decode order.

Shape

A brick shape and its pyramid.

Constants

ESC0

Escape (Elias-gamma unary) models.

LOW0

Low-bit models.

MAG0

Magnitude unary models.

MAGIC

Stream magic.

MINIT

Two-rate adaptive bit model packed in a u32 (fast in the low half).

NDL

Number of centroid offsets.

NKEY

Number of distinct predictor keys addressable.

NMODEL

Models per coefficient lane.

NOMODEL

Models of the outlier lane (count, gap, |k| gamma unaries).

NTAP

Number of predictor taps.

QL

Fixed-point shift of the lifting constants.

SGN0

Sign models.

SIG0

Model offsets inside one lane’s state.

VMAX

Largest magnitude allowed into the final i32 → f32 conversion.

Traits

Sink

A symbol sink/source for one brick: binary decisions at a probability, and raw bit chunks, per lane.

Functions

code_brick

Code (encode or decode) a brick’s coefficients q; adapt selects per-lane adaptive models (else the priors are static probabilities).

decode_box_bits

Decode the sub-box [lo, hi) (3D coordinates) with threads threads; returns f32 bits in box layout.

decode_box_parsed

decode_box_bits on an already parsed stream.

decode_brick_fix

Decode one brick to fixed-point values after corrections (brick-local layout) — the integer reference pipeline.

decode_f32

Decode a whole stream to f32 with threads threads.

dequant

Dequantize one value of band b.

encode_f32

Encode x (row-major f32, 1D–3D) as a tc-gpu stream.

encode_f32_mt

encode_f32 with threads worker threads (output bytes are identical for any thread count).

inverse_int

Inverse multi-level integer CDF 9/7 on a brick.

lift_consts

Inverse-lifting constants (Q24): 1/κ, κ, −δ, −γ, −β, −α.

mulsh

⌊(a·b + 2^(s−1)) / 2^s⌋, low 32 bits (the GPU emulates the 64-bit product).

npass_of

Pass count of a band.

parse

Parse a stream’s header and brick index.

pass_lattice

Lines of pass p form a lattice z ≡ rz (mod sz), y ≡ ry (mod sy) (band-relative): returns (rz, sz, ry, sy).

pass_of

Pass of band-relative line (zr, yr).

prior_table

The 64 prior probabilities P(1)·2^16 (logistic grid, step 0.28 in logit).

rans_encode

rANS-encode one lane (symbols in decode order) into 16-bit words.

to_f32_bits

f32 bits of fixed-point v at scale 2^e (exact: |v| < 2^24).