name: libaom/av1/keep-encoder-only-code-in-encoder-directory description: Keep encoder/decoder logic, state (AV1_COMP, MACROBLOCK), definitions, and macros in av1/encoder/ or av1/decoder/, and never include pipeline headers in av1/common/ rubric: design severity: should_fix

Rule. Keep logic, state, definitions, and headers used exclusively by the encoder or decoder in dedicated pipeline directories and structs rather than in shared common files:

  1. File and Header Boundaries: Do not place encoder-only or decoder-only logic, helper functions, macros, constants, lookup tables, enums, structs, or experimental flags (such as rate control, first-pass analysis, search heuristics, RDO, or TPL) in av1/common/. Common files (av1/common/*) must never #include headers from av1/encoder/ or av1/decoder/.
  2. Codec- and Frame-Level State: Place encoder-only state and configuration parameters (such as motion search history, speed features, rate control) in AV1_COMP, AV1EncoderConfig, or ThreadData, and decoder-only state in AV1Decoder or AV1DecoderConfig, reserving AV1_COMMON (AV1Common) strictly for shared codec data.
  3. Block-Level State: Place encoder-only search, mode evaluation, and rate-distortion state in MACROBLOCK (macroblock, av1/encoder/block.h), reserving MACROBLOCKD (macroblockd, av1/common/blockd.h) strictly for state shared with or required by the decoder.
  4. Shared Code Consolidation: Pass encoder optimization parameters into shared workers via worker context structs (e.g., AV1CdefWorkerData). Consolidate logic shared by both encoder and decoder in av1/common/ using the av1_ prefix rather than duplicating implementations across pipelines.

Why. libaom supports standalone decoder-only and encoder-only builds while enforcing strict architectural separation of concerns. Placing encoder-only or decoder-only logic, macros, constants, lookup tables, or struct fields into shared locations (av1/common/, AV1_COMMON, MACROBLOCKD) introduces unwanted dependencies, pollutes shared interfaces, increases memory footprint for decoder instances, and bloats decoder-only binaries. Including encoder or decoder headers from av1/common/ breaks modularity and build isolation. Conversely, duplicating shared helpers across av1/encoder/ and av1/decoder/ creates maintenance overhead and risks logic divergence.

Examples

Bad:

// Anti-pattern 1: Including encoder or decoder headers in common files
// In av1/common/av1_common_int.h
#include "av1/decoder/decoder.h"
#include "av1/encoder/encoder.h"

// Anti-pattern 2: Placing encoder-only macros, enums, tables, or state in common
#define MAX_FIRSTPASS_ANALYSIS_FRAMES 150
typedef enum { ENCODER_SEARCH_FAST, ENCODER_SEARCH_ACCURATE } ENCODER_SEARCH_MODE;
static const uint16_t av1_derived_intra_tx_used_flag[INTRA_MODES] = { 0x0209, 0x0403 };

typedef struct AV1Common {
  FRAME_TYPE last_frame_type;  // Bad: encoder-only motion search state
} AV1Common;

// Anti-pattern 3: Placing encoder-only block search state in MACROBLOCKD
// In av1/common/blockd.h
typedef struct macroblockd {
  FRAME_CONTEXT *backup_tile_ctx;  // Bad: encoder-only RD search state
} MACROBLOCKD;

Good:

// Pattern 1: Common headers include only common dependencies
// In av1/common/av1_common_int.h
#include "aom/aom_codec.h"
#include "av1/common/enums.h"

// Pattern 2: Encoder-only macros, enums, tables, and state in av1/encoder/
// In av1/encoder/encoder.h or av1/encoder/firstpass.h
#define MAX_FIRSTPASS_ANALYSIS_FRAMES 150
typedef enum { ENCODER_SEARCH_FAST, ENCODER_SEARCH_ACCURATE } ENCODER_SEARCH_MODE;
static const uint16_t av1_derived_intra_tx_used_flag[INTRA_MODES] = { 0x0209, 0x0403 };

typedef struct AV1_COMP {
  FRAME_TYPE last_frame_type;  // Good: encoder search context
} AV1_COMP;

// Pattern 3: Encoder-only block search state in MACROBLOCK
// In av1/encoder/block.h
typedef struct macroblock {
  FRAME_CONTEXT *backup_tile_ctx;  // Good: encoder-only backup state
} MACROBLOCK;