Sync the kernel copy with the OAMD warp and trim controls

The kernel copy follows the new kernel: the OAMD parser reads the trim
element, the speaker renderer applies warp, per-object trim and the
front-back balance, and the ADM writer carries them into the BWF metadata.
joc_kernel.vcxproj lists the new speaker_trim translation unit and header,
and the copied joc_version.h reports kernel 1.2.0 in the session log.

The component keeps its playback settings, its speaker layout table and
the side/rear channel swap; the stream interface is unchanged, so the
decoder wrapper needs no edit. A stream whose OAMD asks for warp 2/3 now
stops at the speaker renderer with JOC_ERR_NOT_SUPPORTED, as the reference
refuses it.

Builds Release-Static|x64 and |Win32. layout_table_test and channel_swap_test
still pass; the render harness renders a warp-1 stream and reports the
unimplemented mode for a warp-3 stream.
This commit is contained in:
TheM14 committed 2026-11-03 13:35:01 +08:00
1 parent 43b16687cc
commit d35f6abe7a
16 files changed
+824 -40

No files matched your search

+17 -11
View File
@@ -10,20 +10,23 @@ struct FrozenLayout {
const char* name;
std::uint32_t out_ch_config;
std::uint32_t speaker_bitfield;
std::uint32_t surround_channels;
std::uint32_t height_channels;
bool carries_trim;
};
constexpr FrozenLayout kLayouts[kLayoutCount] = {
{"2.0", 0, 1},
{"3.1", 3, 7},
{"4.0", 0xFF, 9},
{"5.1", 7, 15},
{"7.1", 11, 31},
{"5.1.2", 13, 1039},
{"5.1.4", 14, 2575},
{"7.1.2", 15, 1055},
{"7.1.4", 16, 2591},
{"9.1.4", 19, 2719},
{"9.1.6", 20, 3743},
{"2.0", 0, 1, 0, 0, true},
{"3.1", 3, 7, 0, 0, true},
{"4.0", 0xFF, 9, 2, 0, true},
{"5.1", 7, 15, 2, 0, true},
{"7.1", 11, 31, 4, 0, true},
{"5.1.2", 13, 1039, 2, 2, true},
{"5.1.4", 14, 2575, 2, 4, true},
{"7.1.2", 15, 1055, 4, 2, false},
{"7.1.4", 16, 2591, 4, 4, false},
{"9.1.4", 19, 2719, 4, 4, false},
{"9.1.6", 20, 3743, 4, 6, false},
};
void fill(const FrozenLayout& source, LayoutInfo* out) {
@@ -31,6 +34,9 @@ void fill(const FrozenLayout& source, LayoutInfo* out) {
out->out_ch_config = source.out_ch_config;
out->speaker_bitfield = source.speaker_bitfield;
out->channel_count = ejoc_speaker_layout_channel_count(source.speaker_bitfield);
out->surround_channels = source.surround_channels;
out->height_channels = source.height_channels;
out->carries_trim = source.carries_trim;
}
} // namespace
@@ -15,6 +15,13 @@ struct LayoutInfo {
std::uint32_t out_ch_config = 0;
std::uint32_t speaker_bitfield = 0;
std::uint32_t channel_count = 0;
// Ls/Rs/Lrs/Rrs and Ltf/Rtf/Ltr/Rtr/Ltm/Rtm, the labels the OAMD trim
// configuration index counts.
std::uint32_t surround_channels = 0;
std::uint32_t height_channels = 0;
// One of the seven layouts that carry OAMD trim and front-back balance
// semantics; wider layouts leave the programme untrimmed.
bool carries_trim = false;
};
// All eleven layouts in the reference's order (2.0, 3.1, 4.0, 5.1, 7.1, 5.1.2,
+89 -12
View File
@@ -1,5 +1,6 @@
#define EJOC_BUILD_DLL
#include "eac3joc_core.h"
#include "speaker/speaker_trim.h"
#include "speaker_layouts.h"
#include <algorithm>
@@ -216,6 +217,7 @@ public:
const std::uint8_t* region_indices,
const std::uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output) noexcept {
error_[0] = '\0';
if (!input || !output) {
@@ -227,11 +229,21 @@ public:
if (metadata_count && (!metadata_offsets || !ramp_durations || !positions_q15)) {
return fail("metadata arrays are null while metadata_count is nonzero");
}
if (!validate_controls(controls)) {
return -1;
}
if (!validate_metadata(sample_count, metadata_count, metadata_offsets,
positions_q15, region_indices, object_gains)) {
return -1;
}
// A caller that passes no controls gets warp 0, no trim and no balance.
ejoc_speaker_controls fallback{};
fallback.struct_size = sizeof(fallback);
fallback.struct_version = EJOC_SPEAKER_CONTROLS_VERSION;
fallback.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
const ejoc_speaker_controls& active = controls != nullptr ? *controls : fallback;
std::fill(output, output + static_cast<std::size_t>(sample_count) * layout_->channel_count, 0.0);
const bool has_lfe = (layout_->speaker_bitfield & 0x4u) != 0;
const std::size_t total_blocks = sample_count / kBlock;
@@ -239,14 +251,14 @@ public:
for (std::size_t block = 0; block < total_blocks; ++block) {
while (event < metadata_count && aligned_block(metadata_offsets[event]) == block) {
apply_event(event, ramp_durations, positions_q15, region_indices,
height_enabled, object_gains);
height_enabled, object_gains, active);
++event;
}
mix_block(input, output, block, has_lfe);
}
while (event < metadata_count && aligned_block(metadata_offsets[event]) == total_blocks) {
apply_event(event, ramp_durations, positions_q15, region_indices,
height_enabled, object_gains);
height_enabled, object_gains, active);
++event;
}
if (event != metadata_count) {
@@ -268,6 +280,42 @@ private:
return -1;
}
bool validate_controls(const ejoc_speaker_controls* controls) noexcept {
if (controls == nullptr) {
return true;
}
if (controls->struct_size != sizeof(ejoc_speaker_controls)) {
fail("speaker controls struct_size mismatch");
return false;
}
if (controls->struct_version != EJOC_SPEAKER_CONTROLS_VERSION) {
fail("unknown speaker controls struct_version");
return false;
}
if (controls->warp_mode > 1u) {
fail("speaker rendering implements warp modes 0/1 only");
return false;
}
if (controls->trim_mode > EJOC_SPEAKER_TRIM_EXPLICIT) {
fail("unknown speaker trim mode");
return false;
}
for (const double level :
{controls->centre_db, controls->surround_db, controls->height_db}) {
if (!std::isfinite(level)) {
fail("trim level is not finite");
return false;
}
}
for (const double balance : {controls->listener_balance, controls->overhead_balance}) {
if (!std::isfinite(balance) || balance < -1.0 || balance > 1.0) {
fail("balance is not finite or outside [-1, 1]");
return false;
}
}
return true;
}
bool validate_metadata(const std::uint32_t sample_count,
const std::uint32_t metadata_count,
const std::uint32_t* metadata_offsets,
@@ -318,13 +366,28 @@ private:
const std::uint8_t region_index,
const bool enable_height,
const double object_gain,
const ejoc_speaker_controls& controls,
const bool bypass_trim,
ChannelGains& output) const noexcept {
output.fill(0.0);
const auto& region = layout_->regions[region_index];
const double u = static_cast<double>(position[0]) / kQ15Scale;
const double v = static_cast<double>(position[1]) / kQ15Scale;
const double w = static_cast<double>(position[2]) / kQ15Scale;
const double floor_v = clamp(std::ldexp(v, floor_y_exponent_), 0.0, 1.0);
const double w = std::max(static_cast<double>(position[2]) / kQ15Scale, 0.0);
const int shift = controls.warp_mode == 1u ? floor_y_exponent_ : 0;
double floor_v = clamp(std::ldexp(v, shift), 0.0, 1.0);
double top_v = clamp(v, 0.0, 1.0);
double trim_v = v;
if (controls.trim_mode == EJOC_SPEAKER_TRIM_EXPLICIT && !bypass_trim) {
// Warp feeds the floor coordinate only: the height and trim
// coordinates see the balance map on the original Y.
floor_v = joc::speaker::apply_balance(floor_v, w, controls.listener_balance,
controls.overhead_balance);
top_v = joc::speaker::apply_balance(top_v, w, controls.listener_balance,
controls.overhead_balance);
trim_v = joc::speaker::apply_balance(v, w, controls.listener_balance,
controls.overhead_balance);
}
PointGains floor{};
plane_gains(region, region.axis0_groups, region.axis0_group_count,
u, floor_v, region.mode, floor);
@@ -332,7 +395,7 @@ private:
if (region.mode == 3) {
PointGains height{};
plane_gains(region, region.axis1_groups, region.axis1_group_count,
u, v, 3, height);
u, top_v, 3, height);
const double z = enable_height ? clamp(w, 0.0, kQ15Max) : 0.0;
if (z >= kQ15Max) {
point = height;
@@ -345,21 +408,33 @@ private:
}
}
}
const double y_term = clamp(v / 0.6, 0.0, 1.0);
const double z_term = clamp((w - 0.2) / 0.8, 0.0, 1.0);
const double amount = clamp(y_term + z_term, 0.0, 1.0);
const double gain = std::pow(10.0, attenuation_db_ * amount / 20.0) * object_gain;
double gain = object_gain;
if (!bypass_trim) {
if (controls.trim_mode == EJOC_SPEAKER_TRIM_AUTOMATIC) {
gain *= position_gain(trim_v, w);
} else if (controls.trim_mode == EJOC_SPEAKER_TRIM_EXPLICIT) {
gain *= joc::speaker::explicit_position_gain(controls, u, trim_v, w);
}
}
for (std::size_t index = 0; index < region.point_count; ++index) {
output[region.points[index].speaker_id] = point[index] * gain;
}
}
double position_gain(const double v, const double w) const noexcept {
const double y_term = clamp(v / 0.6, 0.0, 1.0);
const double z_term = clamp((w - 0.2) / 0.8, 0.0, 1.0);
const double amount = clamp(y_term + z_term, 0.0, 1.0);
return std::pow(10.0, attenuation_db_ * amount / 20.0);
}
void apply_event(const std::size_t event,
const std::uint32_t* ramp_durations,
const std::uint16_t* positions_q15,
const std::uint8_t* region_indices,
const std::uint8_t* height_enabled,
const double* object_gains) noexcept {
const double* object_gains,
const ejoc_speaker_controls& controls) noexcept {
const std::uint32_t blocks = ramp_blocks(ramp_durations[event]);
for (std::size_t object = 0; object < kObjects; ++object) {
const std::size_t object_event = event * kObjects + object;
@@ -367,8 +442,9 @@ private:
const std::uint8_t region = region_indices ? region_indices[object_event] : 0;
const bool height = !height_enabled || height_enabled[object_event] != 0;
const double object_gain = object_gains ? object_gains[object_event] : 1.0;
const bool bypass = controls.trim_bypass[object + 1] != 0u;
ChannelGains next{};
render_point(position, region, height, object_gain, next);
render_point(position, region, height, object_gain, controls, bypass, next);
for (std::size_t channel = 0; channel < layout_->channel_count; ++channel) {
const double difference = next[channel] - current_[object][channel];
target_[object][channel] = next[channel];
@@ -482,6 +558,7 @@ int EJOC_CALL ejoc_speaker_renderer_process(
const uint8_t* region_indices,
const uint8_t* height_enabled,
const double* object_gains,
const ejoc_speaker_controls* controls,
double* output_interleaved) {
if (!handle) {
return -1;
@@ -489,7 +566,7 @@ int EJOC_CALL ejoc_speaker_renderer_process(
return static_cast<ejoc::speaker::Renderer*>(handle)->process(
objects16_interleaved, sample_count, metadata_count,
metadata_offsets, ramp_durations, positions_q15,
region_indices, height_enabled, object_gains, output_interleaved);
region_indices, height_enabled, object_gains, controls, output_interleaved);
}
} // extern "C"
+22 -1
View File
@@ -26,8 +26,29 @@ Status step(SpeakerStep* context, const std::vector<float>& objects16_planar,
static_cast<std::size_t>(JOC_FRAME_SAMPLES) * context->layout.channel_count, 0.0);
context->last_had_payload = update != nullptr;
if (!context->controls_ready) {
const Status status =
parameters_from_oamd(nullptr, context->layout, &context->controls);
if (!status.ok()) {
if (error != nullptr) {
*error = status.message();
}
return status;
}
context->controls_ready = true;
}
std::uint32_t ramp = 0;
if (update != nullptr) {
if (update->has_trim) {
const Status status = parameters_from_oamd(&update->trim, context->layout,
&context->controls);
if (!status.ok()) {
if (error != nullptr) {
*error = status.message();
}
return status;
}
}
context->state.apply(*update);
ramp = update->ramp_duration_samples;
context->last_block_offset = update->block_offset_samples;
@@ -53,7 +74,7 @@ Status step(SpeakerStep* context, const std::vector<float>& objects16_planar,
context->handle, context->interleaved.data(), JOC_FRAME_SAMPLES, event_count,
event_count != 0u ? &offset : nullptr, event_count != 0u ? &ramp : nullptr,
event_count != 0u ? &positions[0][0] : nullptr, nullptr, nullptr, nullptr,
context->output.data());
&context->controls, context->output.data());
if (result != 0) {
const char* message = ejoc_speaker_renderer_last_error(context->handle);
const std::string text =
+5
View File
@@ -9,6 +9,7 @@
#include "foundation/status.h"
#include "oamd/oamd_parser.h"
#include "speaker/speaker_layout_lookup.h"
#include "speaker/speaker_trim.h"
namespace joc::speaker {
@@ -23,6 +24,10 @@ struct SpeakerStep {
std::uint32_t last_ramp_duration = 0;
std::uint32_t last_object_count = 0;
bool last_had_payload = false;
// OAMD speaker controls. A payload carrying the trim element replaces
// them; a payload without it keeps the previous set.
ejoc_speaker_controls controls{};
bool controls_ready = false;
// bed 声道是固定通道:OAMD 不给位置,方位由声明的 bed 布局给出。这里存
// 对象槽 → Q15 方位;bed_override 为 false 的槽仍按 OAMD 坐标声像。
std::uint16_t bed_positions[oamd::kObjects][oamd::kAxes] = {};
+155
View File
@@ -0,0 +1,155 @@
#include "speaker/speaker_trim.h"
#include <algorithm>
#include <cmath>
#include <string>
#include "foundation/py_num.h"
namespace joc::speaker {
namespace {
int height_class(std::uint32_t count) {
if (count == 0u) {
return 0;
}
if (count == 2u) {
return 1;
}
return 2;
}
int floor_class(std::uint32_t count) {
if (count == 0u) {
return 0;
}
if (count == 2u || count == 3u) {
return 1;
}
return 2;
}
} // namespace
int trim_config_index(const LayoutInfo& layout) {
return floor_class(layout.surround_channels) + 3 * height_class(layout.height_channels);
}
Status parameters_from_oamd(const oamd::OamdTrim* trim, const LayoutInfo& layout,
ejoc_speaker_controls* out) {
if (out == nullptr) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"null speaker controls");
}
ejoc_speaker_controls controls{};
controls.struct_size = sizeof(controls);
controls.struct_version = EJOC_SPEAKER_CONTROLS_VERSION;
controls.trim_mode = EJOC_SPEAKER_TRIM_AUTOMATIC;
if (trim != nullptr) {
controls.warp_mode = trim->warp_mode;
for (int slot = 0; slot < oamd::kMaxSlots; ++slot) {
controls.trim_bypass[slot] = trim->disable_per_object[slot] ? 1u : 0u;
}
}
if (controls.warp_mode > 1u) {
return Status::fail(JOC_ERR_NOT_SUPPORTED, stage::kRender,
"speaker: warp_mode_not_implemented: speaker rendering "
"implements warp modes 0/1; warp mode " +
std::to_string(controls.warp_mode) + " is reserved");
}
if (!layout.carries_trim) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
const std::uint32_t mode = trim != nullptr ? trim->global_trim_mode : 0u;
if (mode == 1u) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
if (mode > 2u) {
return Status::fail(JOC_ERR_NOT_SUPPORTED, stage::kRender,
"speaker: trim_mode_not_implemented: OAMD global trim mode " +
std::to_string(mode) + " is reserved");
}
if (mode == 2u) {
const oamd::TrimConfig& record = trim->configs[trim_config_index(layout)];
if (record.kind == oamd::TrimConfigKind::kDefault ||
record.kind == oamd::TrimConfigKind::kAbsent) {
*out = controls;
return Status::success();
}
if (record.kind == oamd::TrimConfigKind::kDisabled) {
controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED;
*out = controls;
return Status::success();
}
if (!std::isfinite(record.centre) || !std::isfinite(record.surround) ||
!std::isfinite(record.height)) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"speaker: trim levels must be finite");
}
for (const double balance : {record.balance_listener, record.balance_overhead}) {
if (!std::isfinite(balance) || balance < -1.0 || balance > 1.0) {
return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender,
"speaker: balance must be finite and in [-1,1]");
}
}
// Surround and height are attenuation-only; the centre level keeps its
// sign.
controls.trim_mode = EJOC_SPEAKER_TRIM_EXPLICIT;
controls.centre_db = record.centre;
controls.surround_db = std::min(record.surround, 0.0);
controls.height_db = std::min(record.height, 0.0);
controls.listener_balance = record.balance_listener;
controls.overhead_balance = record.balance_overhead;
}
*out = controls;
return Status::success();
}
double front_back_balance(double position, double balance) {
const long long steps =
pynum::py_round(std::fabs(balance) * static_cast<double>(kBalanceSteps));
if (steps == 0) {
return position;
}
const double slope = static_cast<double>(steps) / 18.0;
if (position <= kBalanceWall || position >= 1.0 - kBalanceWall) {
return position;
}
if (position < 0.5) {
return balance > 0.0 ? (1.0 + slope) * position - kBalanceWall * slope
: (1.0 - slope) * position + kBalanceWall * slope;
}
return balance > 0.0
? (1.0 - slope) * (position - 0.5) + 0.5 + 0.45 * slope
: (1.0 + slope) * (position - 0.5) + 0.5 - 0.45 * slope;
}
double apply_balance(double position, double height, double listener, double overhead) {
if (listener == 0.0 && overhead == 0.0) {
return position;
}
const double low = front_back_balance(position, listener);
const double high = front_back_balance(position, overhead);
return (1.0 - height) * low + height * high;
}
double explicit_position_gain(const ejoc_speaker_controls& controls, double x, double y,
double z) {
const double surround = std::min(std::max(2.0 * y, 0.0), 1.0) * (1.0 - z);
const double centre = 1.0 - std::min(
std::max(10.0 * std::max(std::max(std::fabs(z) - kBalanceWall,
y - kBalanceWall),
std::fabs(x - 0.5) - kBalanceWall),
0.0),
1.0);
const double db = surround * std::min(controls.surround_db, 0.0) +
z * std::min(controls.height_db, 0.0) + centre * controls.centre_db;
return std::pow(10.0, db / 20.0);
}
} // namespace joc::speaker
+49
View File
@@ -0,0 +1,49 @@
// Port of src/trim_balance.py.
#pragma once
#include <cstdint>
#include "eac3joc_core.h"
#include "foundation/status.h"
#include "oamd/oamd_parser.h"
#include "speaker/speaker_layout_lookup.h"
namespace joc::speaker {
// Front-back balance keeps a 5 percent wall band at each end unmapped.
inline constexpr double kBalanceWall = 0.05;
// bal3d_y is coded on a 1/16 grid, so a balance is quantised to that grid.
inline constexpr int kBalanceSteps = 16;
// Trim configuration a layout selects, from its surround and height counts:
//
// cfg = kappa_f(surrounds) + 3 * kappa_h(heights)
// kappa_f: 0 -> 0, 2..3 -> 1, otherwise 2
// kappa_h: 0 -> 0, 2 -> 1, otherwise 2
int trim_config_index(const LayoutInfo& layout);
// Converts OAMD calibration to the speaker controls of one layout. Warp modes
// 2/3 and the reserved global trim mode are reported as unsupported. A null
// trim selects warp 0 and automatic trim, or disabled trim for a layout that
// carries no trim semantics.
Status parameters_from_oamd(const oamd::OamdTrim* trim, const LayoutInfo& layout,
ejoc_speaker_controls* out);
// Reparameterises a front-back coordinate in [0, 1] by ``balance``: 0 is the
// front wall and 1 the back wall, and the two wall bands pass through
// unchanged.
double front_back_balance(double position, double balance);
// Blends the listener-plane and overhead balance by height: 0 at the listener
// plane, 1 at the top layer.
double apply_balance(double position, double height, double listener, double overhead);
// Position-dependent object trim at the balanced original Y. Surround fades
// in with Y and out towards Z=1, height fades in with Z, and the centre trim is
// local to the front-centre region. The scalar multiplies the object's whole
// panning vector before accumulation.
double explicit_position_gain(const ejoc_speaker_controls& controls, double x, double y,
double z);
} // namespace joc::speaker