# DCT KNOWLEDGE BASE
**Generated:** 2026-04-25
## OVERVIEW
DCT (Discrete Cosine Transform) via reusable `rustdct` row/column DCT-II planners. Used in motion search modes 3-4 for frequency-domain block matching.
## STRUCTURE
```
src/dct/
├── rust.rs # Scalar float_src_to_pixels conversion
├── avx2.rs # AVX2-accelerated float_src_to_pixels (95% faster on width >= 8)
├── tests.rs # DCT tests with expected_ac/expected_dc mathematical verification
└── dct.rs # Module root (not present - logic in src/dct.rs)
```
Module root: `src/dct.rs` (130 lines). Subdirectory contains only `rust.rs`, `avx2.rs`, `tests.rs`.
## WHERE TO LOOK
| DctHelper struct | `src/dct.rs` | Manages `rustdct` planners, reusable scratch buffers, float buffers, pixel conversion |
| bytes_2d() | `src/dct.rs:64` | Full DCT pipeline: pixels→float→row/column DCT-II→pixels |
| pixels_to_float_src | `src/dct.rs:78` | Plane-to-float conversion (scalar only) |
| transform_src_to_dct() | `src/dct.rs` | Reuses row/column planners plus scratch buffers; no per-call allocations |
| float_src_to_pixels | `src/dct.rs:94` | DCT coefficients back to pixels (has AVX2 path) |
| AVX2 conversion | `dct/avx2.rs` | 95% faster on width >= 8 |
| DCT tests | `dct/tests.rs` | Mathematical verification via expected_ac/expected_dc helpers plus raw coefficient reference checks |
## CONVENTIONS (DCT-SPECIFIC)
- `DctHelper::new()` plans one `rustdct::DctPlanner<f32>` DCT-II per axis and caches scratch buffers sized from `get_scratch_len()`.
- The forward transform is separable and unnormalized: rows are transformed first into `src_dct`, then columns are gathered into a reusable temporary buffer and transformed in place.
- `dct_shift` and `dct_shift0` control coefficient scaling based on block size (next power of 2 + 2).
- AVX2 accelerates only `float_src_to_pixels` (inverse transform output). Forward transform (`pixels_to_float_src`) remains scalar.
- Test verification uses mathematical DCT formula (`sqrt(2)/2` scaling, shift, clamp) plus direct raw-coefficient reference checks for square and rectangular blocks.
- Benchmarks cover 4x4 to 128x128 block sizes, 8/10/16 bpp.
## ANTI-PATTERNS
- Reallocating row/column scratch buffers or column gather storage per frame (cache them in `DctHelper`).
- Assuming AVX2 covers full DCT pipeline (only inverse transform output is accelerated).
- Incorrect `dct_shift`/`dct_shift0` calculation (must match next power of 2 logic).
- Reordering row/column passes or changing the unnormalized transform without updating raw-coefficient tests.