Skip to content

Decompose the monolithic block/frame encode functions #25

Description

@audexdev

Summary

Block::Encoder::encode is a single ~525-line function (encoder.cpp:313-840) that performs predictor evaluation, residual-cost estimation, residual-mode selection, partition-order search, header serialization, residual bit-packing, and debug logging. The structure makes the encoder hard to test in isolation and hard to reason about, and it forces the same residual to be analyzed three times.

Affected areas

  • src/codec/block/encoder.cpp
  • src/codec/lac/encoder.cpp

Problem details

  • The emit routines (encode_rice_partition, encode_static_rice_partition, encode_bin_partition, encode_zr_partition, encoder.cpp:585-768) are lambdas defined inside encode, capturing bw / rice / best.residual by reference, so none of them can be unit-tested.
  • Mode-selection logic is open-coded in three separate places: whole-block (encoder.cpp:441-456), per-partition (encoder.cpp:498-522), and emit dispatch (encoder.cpp:810-816).
  • The same residual is walked three times — cost estimate (estimate_residual_costs, encoder.cpp:201-263, called at :340 and :501) and again at emit (:585-768) — and the estimate must match emit bit-for-bit by hand. (The repeated-analysis cost is also noted in Reduce peak memory and repeated analysis in encode/decode pipelines #15; this issue is about the structural decomposition that would make that fix testable.)
  • LAC::Encoder::encode (lac/encoder.cpp:216-457) similarly fuses stereo decision, per-block planning, threading, and bitstream assembly in one method.

Acceptance criteria

  • Predictor evaluation, residual-mode/partition selection ("plan"), and bit emission ("serialize") are separated into independently callable units.
  • Emit routines are free functions/methods that can be unit-tested without running the full block encoder.
  • A single shared cost/emit core (or a test) guarantees the estimate and the emitted size agree, eliminating estimate/emit drift.
  • No change to emitted bytes; existing fixtures still round-trip bit-perfectly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions