Sync the kernel copy with the OAMD frame-level core

The kernel copy follows the new kernel. The renderer has a frame-level state
machine (normal, hold, hard cut and passthrough, the 8-plane passthrough, the
LFE clipgain ramp and interpolation when no previous state exists), the OAMD
parser carries the complete frame state (several blocks, more than 16 objects)
and the speaker renderer applies the metadata (gain and inactive flags,
zone/elevation, size, snap, divergence, ISF and bed distribution). oamd_math and
oamd_params are new modules, the ISF tables are compiled in now that the
upstream data/ directory is gone, and the binaural timeline accepts a complete
frame state. joc_core.h moves to ABI 6 (frame parameters and EMDF payload info
at v2, JOC_FRAME_STATUS_*, raw 5-bit offset_ts) and eac3joc_core.h to EJOC ABI 4
(EJOC_FRAME_STATUS_*, ejoc_frame_input v1, ejoc_renderer_render_frame,
EJOC_CORE_OUT_CHANNELS and EJOC_LFE_SLOT; the old ejoc_renderer_process stays).
joc_stream.h and joc_version.h are unchanged.

joc_kernel.vcxproj lists the two new translation units and the four new
headers. The component's layout table gains the kernel's 6.0 layout (L R Ls Rs
Lrs Rrs) after 9.1.6, and layout_table_test expects twelve layouts, so the list
the preferences page shows and the list the renderer accepts are the same
again. README, THIRD_PARTY_NOTICES and the CI comment pin the copy to commit
3f0d5e87fe41b90d9350528d2dca2ca82a637a3f; tag v1.2.0 points at the older
a276028 and is not the sync baseline.

Builds Release-Static|x64 and |Win32 with no errors. The offline test tools
build and pass on both architectures: layout_table_test reports 12 layouts, and
channel_swap_test, log_rotation_test and long_path_test pass. scan_crosscheck
agrees with the core on the upstream test material, and the render harness
delivers 7.1.4 speaker output and binaural output on both architectures, with
the speaker-path WAV byte-identical between them.

The core is still vendored under kernel/; building it from the upstream
checkout at build time is a separate change.
This commit is contained in:
TheM14 committed 2026-11-08 16:11:57 +08:00
1 parent 5b41868e94
commit defe9538fe
39 files changed
+6714 -616

No files matched your search

File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+101
View File
@@ -0,0 +1,101 @@
// Port of src/oamd_math.py: float32 equations for the metadata application path.
//
// The routines implement the fixed float32 equations for the size tables, ISF
// basis assembly, bed channel routing and the position-dependent compensation.
// The size tables are generated from the region geometry with grouped equal-power
// panning, an S448 weight and a power sum; every operation is evaluated in
// float32 in a fixed order so the coefficients are reproducible.
//
// The caller passes the parameter mappings from oamd_params; this module does
// not read files itself.
#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#include <vector>
#include "oamd/oamd_params.h"
#include "speaker/speaker_layout_lookup.h"
#include "speaker/speaker_layouts.h"
namespace joc::oamd {
// The specified 2**x approximation used by the compensation kernels.
float exp2_approx(float value);
// The specified x**power approximation; power is a float32.
float pow_approx(float value, float power);
// Stable float32 normalisation with the tiny-norm floor.
std::vector<float> norm(const std::vector<float>& vector);
// One boundary weight of the size kernel.
float boundary(int axis, int edge, float position, float t);
// Maps a scalar size in [0, 1] to t on the size curve.
float size_curve_value(double size);
// Size kernel response in region-speaker order (the region point order).
std::vector<float> size_kernel(const ::ejoc::speaker_tables::RegionGeometry& region,
const float position[3], float t, bool height);
// Size-kernel target vector in layout channel order.
std::vector<float> size_targets(const MetadataParams& meta,
const ::ejoc::speaker_tables::LayoutGeometry& layout,
int region_index, const double position[3],
double size, bool height);
// One assembled ISF basis matrix (row_count x layout output_count, row major).
struct IsfBasis {
int rows = 0;
int columns = 0;
std::vector<float> values;
float at(int row, int column) const {
return values[static_cast<std::size_t>(row) * static_cast<std::size_t>(columns) +
static_cast<std::size_t>(column)];
}
};
// Assembles one ISF basis matrix from the compressed base tables.
IsfBasis assemble_isf(const MetadataParams& meta, const char* layout_key, int isf_idx);
// Returns the per-basis ISF compensation gain.
float isf_compensation(const MetadataParams& meta, const char* layout_key, int isf_idx,
int row, bool disabled);
// Per-label bed redistribution weight, in the reference-position index space
// used by the layout descriptors.
float bed_weight(int label, std::uint32_t mask, int target_label);
// The five height-candidate flags for one input bed label.
std::array<int, 5> bed_candidates(int label, std::uint32_t mask,
const std::vector<int>& output_labels);
// Route and weights for one input bed label. route == -1 means the returned
// weights are the target; otherwise route is the reference position used to
// synthesise a point source.
struct BedDistribution {
int route = -1;
std::vector<float> weights;
};
// Derives the bed routing of one input bed label from the target layout.
BedDistribution bed_distribution(const ::joc::speaker::LayoutInfo& layout, int label,
std::uint32_t mask, bool distribute);
// Returns the Q15 reference position used by the bed fallback path.
void bed_reference_position(int index, int q15[3]);
// Returns the bed path compensation gain for one input bed label. ``mode`` is
// the trim mode (0 automatic, 1 disabled, 2 explicit) and ``levels`` holds the
// surround, height and centre levels in dB.
float bed_compensation(const ::joc::speaker::LayoutInfo& layout, int label, int mode,
bool bypass, const double levels[3]);
// Automatic attenuation of a target layout in dB.
float bed_attenuation_db(const ::joc::speaker::LayoutInfo& layout);
} // namespace joc::oamd
+108
View File
@@ -0,0 +1,108 @@
#include "oamd/oamd_params.h"
#include <cstddef>
#include <utility>
#include <vector>
#include "oamd/isf_tables.h"
namespace joc::oamd {
namespace {
namespace tables = isf_tables;
// Builds the renderer-facing view from the checked-in table header. There is no
// file I/O and no runtime parsing: the numbers are compiled in as static data.
MetadataParams build_params() {
MetadataParams params;
params.configs.reserve(tables::kConfigCount);
for (const tables::Config& source : tables::kConfigs) {
IsfConfig config;
for (std::size_t index = 0; index < config.counts.size(); ++index) {
config.counts[index] = source.counts[index];
}
const std::size_t rows = static_cast<std::size_t>(config.row_count());
config.primary_row_map.assign(source.primary_row_map, source.primary_row_map + rows);
config.secondary_row_map.assign(source.secondary_row_map,
source.secondary_row_map + rows);
const std::size_t coefficients = rows * static_cast<std::size_t>(tables::kMatrixColumns);
config.matrix.assign(source.matrix, source.matrix + coefficients);
params.configs.push_back(std::move(config));
}
params.layouts.reserve(tables::kLayoutCount);
for (const tables::Layout& source : tables::kLayouts) {
IsfLayout layout;
layout.output_count = source.output_count;
for (std::size_t index = 0; index < layout.selectors.size(); ++index) {
layout.selectors[index] = source.selectors[index];
}
layout.compensation_value = source.compensation_value;
layout.output_ids.assign(source.output_ids,
source.output_ids + tables::kOutputIdSlots);
params.layouts.emplace(source.key, std::move(layout));
}
const auto copy_groups = [](const tables::GroupRecord* records, int count,
std::vector<IsfGroupRecord>* out) {
out->reserve(static_cast<std::size_t>(count));
for (int index = 0; index < count; ++index) {
out->push_back(IsfGroupRecord{records[index].selector, records[index].begin,
records[index].end});
}
};
copy_groups(tables::kLayoutGroups.floor_a, tables::kLayoutGroups.floor_a_count,
&params.layout_groups.floor_a);
copy_groups(tables::kLayoutGroups.floor_b, tables::kLayoutGroups.floor_b_count,
&params.layout_groups.floor_b);
copy_groups(tables::kLayoutGroups.height, tables::kLayoutGroups.height_count,
&params.layout_groups.height);
copy_groups(tables::kLayoutGroups.additional, tables::kLayoutGroups.additional_count,
&params.layout_groups.additional);
params.paired_columns.assign(tables::kPairedColumns,
tables::kPairedColumns + tables::kPairedColumnCount);
return params;
}
const MetadataParams& loaded_params() {
static const MetadataParams params = build_params();
return params;
}
} // namespace
const std::vector<IsfGroupRecord>* IsfLayoutGroups::find(const char* name) const {
if (name == nullptr) {
return nullptr;
}
const std::string key(name);
if (key == "floor_a") {
return &floor_a;
}
if (key == "floor_b") {
return &floor_b;
}
if (key == "height") {
return &height;
}
if (key == "additional") {
return &additional;
}
return nullptr;
}
const IsfLayout* MetadataParams::layout(const char* key) const {
if (key == nullptr) {
return nullptr;
}
const auto found = layouts.find(key);
return found != layouts.end() ? &found->second : nullptr;
}
const MetadataParams* metadata_params() { return &loaded_params(); }
const char* metadata_params_error() { return ""; }
} // namespace joc::oamd
+82
View File
@@ -0,0 +1,82 @@
// Port of src/oamd_params.py: the static ISF lookup data of the metadata path.
//
// The numbers are compiled in as the generated header `oamd/isf_tables.h`:
// ISF base coefficients and layout descriptors, applied as lookup tables.
// The remaining values (gain, size, priority, position, delta and refinement
// tables) are computed in code; the size tables are generated from the region
// geometry at runtime, and bed routing is derived from the speaker layouts.
// The arrays are adapted once per process into the structures below; nothing
// reads a data file.
#pragma once
#include <array>
#include <cstdint>
#include <string>
#include <unordered_map>
#include <vector>
#include "foundation/status.h"
namespace joc::oamd {
// One ISF configuration: the compressed basis matrix and the two row maps
// that expand it to the layout output channels.
struct IsfConfig {
// mid, upper, lower, zenith, row_count (the reference's counts tuple).
std::array<int, 5> counts{};
std::vector<int> primary_row_map;
std::vector<int> secondary_row_map;
// row_count * 73 float32 coefficients, row major.
std::vector<float> matrix;
int row_count() const { return counts[4]; }
};
// One layout descriptor: how many output channels the basis has,
// the layout-group selectors and the automatic compensation value.
struct IsfLayout {
int output_count = 0;
std::array<int, 4> selectors{}; // floor_a, floor_b, height, additional
double compensation_value = 0.0;
// ISF channel id of each matrix output column, padded with zeros to 37.
std::vector<std::uint8_t> output_ids;
};
// One record of a layout group: selector id and the half-open column range
// [begin, end).
struct IsfGroupRecord {
int selector = 0;
int begin = 0;
int end = 0;
};
// The four layout groups of the ISF tables.
struct IsfLayoutGroups {
std::vector<IsfGroupRecord> floor_a;
std::vector<IsfGroupRecord> floor_b;
std::vector<IsfGroupRecord> height;
std::vector<IsfGroupRecord> additional;
const std::vector<IsfGroupRecord>* find(const char* name) const;
};
// The ISF lookup data in the shape the metadata renderer consumes.
struct MetadataParams {
std::vector<IsfConfig> configs;
std::unordered_map<std::string, IsfLayout> layouts;
IsfLayoutGroups layout_groups;
// One flag per matrix column: whether the column also contributes through
// the secondary row map.
std::vector<bool> paired_columns;
const IsfLayout* layout(const char* key) const;
};
// Returns the process-wide tables. They are compiled in, so the pointer is
// never null; ``metadata_params_error`` is kept for callers that log a load
// failure and always returns an empty string.
const MetadataParams* metadata_params();
const char* metadata_params_error();
} // namespace joc::oamd
File diff suppressed because it is too large. Load diff
+172 -11
View File
@@ -9,6 +9,34 @@
#include "foundation/status.h"
#include "joc_core.h"
namespace joc::joc {
// OAMD Table 12 的标准 bed 声道。LSB 顺序与声明顺序一致:L/R、C、LFE、
// Ls/Rs、Lrs/Rrs、TFL/TFR、TSL/TSR、TBL/TBR、LW/RW、LFE2。
// The enum values are the reference's BED_LABEL_INDEX - 1.
enum class BedChannel : std::uint8_t {
kLeft = 0,
kRight,
kCenter,
kLfe,
kLeftSurround,
kRightSurround,
kLeftRearSurround,
kRightRearSurround,
kTopFrontLeft,
kTopFrontRight,
kTopSideLeft,
kTopSideRight,
kTopBackLeft,
kTopBackRight,
kLeftWide,
kRightWide,
kLfe2,
kCount,
};
} // namespace joc::joc
namespace joc::oamd {
inline constexpr int kMaxSlots = 16;
@@ -17,8 +45,16 @@ inline constexpr int kAxes = 3;
inline constexpr int kNQ12 = 62;
inline constexpr int kNQ3 = 15;
inline constexpr int kQ15Scale = 32768;
// Largest ISF configuration of Table 11b (5.6.0.11). A frame cannot carry more
// objects than this through any of the standard programmes, but the parser does
// not reject a larger count: it only bounds the legacy 16-slot view.
inline constexpr int kMaxObjects = 30;
inline constexpr int kMaxBlocks = 8;
inline constexpr std::uint32_t kTrimElementId = 2;
inline constexpr std::uint32_t kObjectElementId = 1;
inline constexpr std::uint32_t kExtendedElementId = 5;
inline constexpr int kTrimConfigs = 9;
inline constexpr int kBedLabelCount = 17;
// One of the nine per-configuration trim records of the OAMD trim element.
// ``kAbsent`` means the configuration carries no data (the element only
@@ -50,6 +86,92 @@ struct OamdTrim {
bool disable_per_object[kMaxSlots] = {};
};
// OAMD object kind: the programme assigns objects to the bed, to an ISF
// configuration, or to the dynamic (positional) set, in that order.
enum class ObjectKind : std::uint8_t {
kBed = 0,
kIsf = 1,
kDynamic = 2,
};
// Render state of one object in one block (5.5.9 object_info_block).
struct ObjectRenderState {
bool not_active = false;
std::int32_t gain_q = 0; // integer gain, unity = 4096
std::int32_t priority_q = 0; // Q10 priority, 32767 = default
std::int32_t qx = 0; // Q15 room position, 0..32767
std::int32_t qy = 0; // Q15 room position, 0..32767
std::int32_t qz = 0; // signed Q15 elevation
std::uint8_t zone_idx = 0;
bool enable_elevation = true;
std::uint8_t size_mode = 0; // 0 none, 1 isotropic, 2 per-axis
std::uint16_t size_q[3] = {0, 0, 0}; // Q15 size per axis
bool snap = false;
std::uint16_t divergence_q = 0; // Q15 divergence width
};
struct ObjectBlockState {
ObjectRenderState render;
};
// One object of the frame: its kind and the state of every block.
struct ObjectElementState {
ObjectKind kind = ObjectKind::kDynamic;
std::vector<ObjectBlockState> blocks;
};
// Timing shared by every object of one block. ``block_offset_samples`` already
// includes the element's sample_offset, like the reference block dictionary.
struct BlockTiming {
std::uint32_t block_offset_samples = 0;
std::uint32_t ramp_duration_samples = 0;
};
// Program assignment (5.5.3) as consumed by the speaker renderer.
struct ProgramState {
bool dynamic_object_only = false;
bool lfe_present = false;
bool b_bed_chan_distribute = false;
// program_assignment() content_description flags.
bool content_reserved = false;
bool content_bed = false;
bool content_isf = false;
bool content_dynamic = false;
std::uint32_t num_bed_objects = 0;
std::uint32_t num_isf_objects = 0;
std::int32_t num_dynamic_objects = -1; // -1 when the frame declares none
std::uint32_t bed_mask = 0; // 17-bit non-standard bed mask
std::int32_t isf_idx = -1; // -1 when the frame declares none
// Declared bed labels in channel order, including LFE/LFE2. Index i is the
// label of object i for i < num_bed_objects.
std::vector<::joc::joc::BedChannel> bed_labels;
};
// One element whose parsed content ended past its declared size. The reference
// keeps parsing such elements and only records the difference.
struct ElementSizeMismatch {
std::uint32_t element_ordinal = 0;
std::uint32_t element_id = 0;
std::uint32_t declared_size_bytes = 0;
std::uint32_t declared_end_bit = 0;
std::uint32_t parsed_end_bit = 0;
};
// Full frame state (frame_state() in the reference): per-object per-block
// render state plus programme assignment, timing and trim.
struct FrameState {
std::uint32_t object_count = 0;
std::uint32_t block_count = 0;
std::uint32_t sample_offset = 0; // object_element sample offset
std::uint32_t ramp_duration_samples = 0; // block 0
std::vector<BlockTiming> blocks;
std::vector<ObjectElementState> objects;
ProgramState program;
bool has_trim = false;
OamdTrim trim;
std::vector<ElementSizeMismatch> size_mismatch;
};
// (the reference's None), i.e. hold the previous position.
struct SlotUpdate {
std::int16_t q1 = -1;
@@ -76,6 +198,12 @@ struct OamdUpdate {
// keeps whatever controls the caller already holds.
OamdTrim trim;
bool has_trim = false;
// Full per-object per-block state of this payload. ``has_frame_state`` is
// true whenever the parser produced it; the speaker metadata path and the
// binaural position timeline consume it, while the legacy slot fields above
// stay authoritative for ADM export and the point-renderer path.
bool has_frame_state = false;
FrameState frame_state;
};
class OamdState {
@@ -103,6 +231,23 @@ public:
std::int16_t q(int slot, int axis) const { return q_[slot][axis]; }
// Resolves one frame-state position block for one object. The legacy
// apply() entry above keeps the reference frame_update() view (16 slots,
// block 0); the binaural position timeline uses this entry so a frame may
// carry more objects and more blocks than that view can express. Callers
// skip inactive and non-dynamic objects themselves, exactly like the
// reference's frame_update() value construction.
void apply_render_state(int object_index, const ObjectRenderState& render) {
if (object_index < 0 || object_index >= kMaxObjects) {
return;
}
q_[object_index][0] = static_cast<std::int16_t>(render.qx);
q_[object_index][1] = static_cast<std::int16_t>(render.qy);
const std::int32_t elevation = render.enable_elevation ? render.qz : 0;
q_[object_index][2] =
static_cast<std::int16_t>(elevation > 0 ? elevation : 0);
}
// Objects 1..15 as q15 triples, the layout the speaker renderer consumes.
void object_positions_q15(std::uint16_t out[kObjects][kAxes]) const {
for (int object = 0; object < kObjects; ++object) {
@@ -113,25 +258,18 @@ public:
}
private:
std::int16_t q_[kMaxSlots][kAxes] = {};
std::int16_t q_[kMaxObjects][kAxes] = {};
};
// q_of(k, n) = min(32767, floor(32768 k / n + 0.5)), the reference's quantiser.
int q_of(int k, int n);
Status parse_id11(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out);
// Parses only the trim element of a payload. ``out`` receives the first trim
// element found; ``*present`` is false when the payload carries none. decode
// paths that need the OAMD calibration but no object state can use this
// without requiring an object element.
Status parse_trim(const std::uint8_t* payload, std::size_t payload_size, OamdTrim* out,
bool* present);
struct BedAssignment {
bool lfe_only = false;
bool standard = false;
std::uint32_t mask = 0;
std::uint32_t mask = 0; // 10-bit standard or 17-bit non-standard mask
// Declared channels in channel order; LFE is kept in place.
std::vector<::joc::joc::BedChannel> channels;
};
struct ParseTrace {
@@ -145,6 +283,26 @@ struct ParseTrace {
bool reserved_data_not_present = false;
};
// Legacy single-frame view (frame_update() in the reference): the 16-slot
// position update plus programme and trim. A payload carrying more than 16
// objects or more than one position block is rejected, exactly like the
// reference legacy entry point. The ADM export path keeps this view; the
// speaker and binaural renderers use parse_id11_state().
Status parse_id11(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out);
// Full frame_state() view: per-object per-block state, no 16-slot or
// single-block restriction. The legacy fields are filled as well whenever the
// frame fits them, so a caller can parse once and hand the same update to the
// renderers and to the ADM export path where its shape allows it.
Status parse_id11_state(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out);
// Parses only the trim element of a payload. ``out`` receives the first trim
// element found; ``*present`` is false when the payload carries none. decode
// paths that need the OAMD calibration but no object state can use this
// without requiring an object element.
Status parse_trim(const std::uint8_t* payload, std::size_t payload_size, OamdTrim* out,
bool* present);
Status parse_id11_verbose(const std::uint8_t* payload, std::size_t payload_size, OamdUpdate* out,
ParseTrace* trace);
@@ -153,4 +311,7 @@ Status parse_id11_verbose(const std::uint8_t* payload, std::size_t payload_size,
Status parse_id11_bed_assignments(const std::uint8_t* payload, std::size_t payload_size,
std::vector<BedAssignment>* out);
// 10-bit standard bed mask -> 17-bit non-standard bed mask (5.6.1.1.4).
std::uint32_t standard_bed_mask(std::uint32_t bed_mask);
} // namespace joc::oamd