zoomvtools 2.0.0

Video motion vector analysis utilities in pure Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# UTIL KNOWLEDGE BASE

**Generated:** 2026-04-17

## OVERVIEW

Performance utility layer: typed function-pointer dispatch, pixel abstraction, cpudetect-backed CPU feature gating, math helpers. Hot-path primitives for SAD/SATD/luma/search.

## STRUCTURE

```
src/util/
├── block_functions.rs   # Function pointer aliases + BlockFunctions table
├── math.rs              # Math facade re-exports
├── math/                # Low-level math helpers, intrinsics glue
├── plane.rs             # Plane-oriented helpers for filters/search
├── tests.rs             # util-level tests
└── util.rs              # Module root: Pixel trait, get_dbg, cfg_select dispatch
```

## WHERE TO LOOK

| Task                      | Location                         | Notes                                   |
| ------------------------- | -------------------------------- | --------------------------------------- |
| SAD function selection    | `block_functions.rs`, `../sad/`  | `SadFn` typedef + kernel providers      |
| SATD function selection   | `block_functions.rs`, `../satd/` | `SatdFn` typedef + kernel providers     |
| Luma sum selection        | `block_functions.rs`, `../luma/` | `LumaSumFn` typedef + sum kernels       |
| Pixel trait + conversions | `util.rs`                        | Generic pixel API for `u8`/`u16`        |
| CPU feature detection     | dispatch callers (`../sad.rs`, `../satd.rs`, `../resize.rs`, `../reduce/*`, `../refine/*`, `../dct.rs`) | cpudetect::x86_64::* gates AVX2/AVX-512 entry points |
| Debug-checked indexing    | `util.rs`                        | `semisafe_get()` / `semisafe_get_mut()` |

## CONVENTIONS (UTIL-SPECIFIC)

- Function pointer aliases are canonical API: `SadFn`, `SatdFn`, `LumaSumFn`.
- `BlockFunctions` for per-block/per-format function pointers chosen once, reused in loops.
- Runtime dispatch: `#[cfg(feature = "simd")]` + cpudetect gate at boundary, not inside inner loops.
- `Pixel` trait is the generic seam for bit depth; helpers must support both `u8` and `u16`.
- Keep function signatures dispatch-friendly (plain pointers/strides/dims), avoid closure-based hot-path APIs.
- `semisafe_get()` / `semisafe_get_mut()` replace direct indexing: bounds-checked in debug, unchecked in release.

## ANTI-PATTERNS (UTIL)

| Pattern                                           | Status      | Replacement                                      |
| ------------------------------------------------- | ----------- | ------------------------------------------------ |
| Rechecking CPU features inside pixel/block loops  | FORBIDDEN   | Select function pointers once, call directly     |
| Branching on bit depth in hot loops               | WARN        | Route via `Pixel` + preselected function pointer |
| Allocating temporaries in per-block utility calls | WARN        | Reuse caller-owned scratch storage               |
| Ad-hoc dispatch tables local to callers           | DISCOURAGED | Centralize in `BlockFunctions`                   |