diff --git a/README.en.md b/README.en.md index cd6af02..a6af5e8 100644 --- a/README.en.md +++ b/README.en.md @@ -143,11 +143,11 @@ downstream player recognises Dolby speaker positions on its own. `--speaker-layout` accepts only the eleven names in the table; anything else fails as an unknown layout. -Speaker rendering reads warp 0/1, trim and front/back balance from the OAMD metadata; the CLI -has no warp override, and warp 2/3 is reported as unsupported at render time. Trim and balance -apply to the 2.0, 3.1, 4.0, 5.1, 5.1.2, 5.1.4 and 7.1 layouts. Source trajectories and binaural -rendering do not pre-apply these controls; see [mathematics §12](docs/math.en.md) for the -parameters and evaluation order. +Speaker rendering reads warp, trim and front/back balance from the OAMD metadata; the CLI has no +warp override. Warp 0/1 render directly; warp 2/3 render to a 7.1.x intermediate layout first, +then fold back to 5.1.x with PLIIx or Standard (Lo/Ro) coefficients, and calibration always +follows the final target layout. Source trajectories and binaural rendering do not pre-apply +these controls; see [mathematics §12](docs/math.en.md) for the parameters and evaluation order. ## Library integration diff --git a/README.md b/README.md index f782e0e..84ae017 100644 --- a/README.md +++ b/README.md @@ -124,10 +124,10 @@ PCM 声道顺序严格按上表,不按掩码位序重排。播放器、ASIO、 `--speaker-layout` 只接受上表 11 个名字;其它名字按未知布局报错。 -扬声器渲染从 OAMD 元数据读取 warp 0/1、trim 和 front/back balance;命令行不提供 warp -覆盖,warp 2/3 在渲染时明确报错。trim 与 balance 只施加于 2.0、3.1、4.0、5.1、5.1.2、 -5.1.4 和 7.1 这七种布局。原始对象轨迹与双耳渲染不预先应用这些控制,参数与求值顺序见 -[数学说明 §12](docs/math.md)。 +扬声器渲染从 OAMD 元数据读取 warp、trim 和 front/back balance;命令行不提供 warp 覆盖。 +warp 0/1 直接渲染;warp 2/3 先渲染到 7.1.x 中间布局,再按 PLIIx 或 Standard(Lo/Ro) +折回 5.1.x,校准参数始终按最终目标布局选择。原始对象轨迹与双耳渲染不预处理这些控制, +参数与求值顺序见[数学说明 §12](docs/math.md)。 ## 库集成 diff --git a/docs/math.en.md b/docs/math.en.md index cac375b..64de2ae 100644 --- a/docs/math.en.md +++ b/docs/math.en.md @@ -454,8 +454,8 @@ v_{\mathrm{floor}}= $$ Warp 0 and other layouts use $v_{\mathrm{floor}}=v$. The height layer is not scaled. -An absent warp indication uses 0; no CLI override is provided. Modes 2/3 are -explicitly unsupported rather than mapped to 0/1. Balance follows this scaling. +An absent warp indication uses 0; no CLI override is provided. Modes 2/3 use +the intermediate layout and folding matrix in §12.5. Balance follows this scaling. ### 10.3 Height layer @@ -563,7 +563,7 @@ Warp, trim and balance controls are read from OAMD metadata: | Parameter | Value or unit | Behavior | |---|---|---| -| `warp_mode` | 0 / 1 | Selects the floor Y mapping in §10.2; modes 2/3 are unsupported and rejected | +| `warp_mode` | 0 / 1 / 2 / 3 | Direct rendering / floor Y scaling / PLIIx folding / Standard (Lo/Ro) folding | | `global_trim_mode` | 0 / 1 / 2 | Automatic / disabled / per-layout configuration; reserved value 3 is rejected | | $T_s$, $T_h$ | dB | Explicit surround and height trim, with positive values treated as zero | | $T_c$ | dB | Signed explicit centre trim | @@ -642,7 +642,7 @@ $1$ at the back wall; $x$ and $z$ are unchanged. ### 12.4 Where it is applied Let $B_z(y)$ denote the balance map of §12.3 and $W(y)$ the warp map of §10.2. -The ordinary point-object path keeps three coordinates: +Direct point rendering in warp modes 0/1 keeps three coordinates: $$ y_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y). @@ -664,6 +664,47 @@ Height and trim coordinates pass through balance alone. The trim scalar multiplies the object's entire panning vector before accumulation into output channels. LFE passes through. +### 12.5 Surround folding in warp modes 2/3 + +For a 5.1, 5.1.2 or 5.1.4 target, warp modes 2/3 first render objects to the +corresponding 7.1, 7.1.2 or 7.1.4 intermediate layout, then fold the rear +surrounds into the target surround pair. The 4.0 layout also adds a rear pair +without adding centre or LFE. Other existing layouts render directly. + +The intermediate layout changes speaker geometry and panning only. The trim +configuration, both balance layers and the maximum automatic position +compensation remain those of the final target. For example, 5.1.2 uses +configuration 4 and a maximum compensation of $-2.25$ dB even when its +intermediate layout is 7.1.2. With separate side and rear pairs in the +intermediate layout, floor Y is not doubled. Balance and per-object trim +are evaluated during intermediate rendering. + +For intermediate outputs $L_s,R_s,L_{rs},R_{rs}$ and target surrounds +$L'_s,R'_s$: + +$$ +L'_s=L_s+aL_{rs}+bR_{rs},\qquad +R'_s=R_s+bL_{rs}+aR_{rs}. +$$ + +| Mode | $a$ | $b$ | +|---|---|---| +| 2: PLIIx | $\sqrt{3}/2$ | $1/2$ | +| 3: Standard (Lo/Ro) | $1$ | $0$ | + +Both matrices add linear amplitudes without normalizing energy after the +fold. Shared front, height and LFE channels pass through to their matching +positions. The folded object gain vector enters the target-gain update and +ramp in §13 before object audio is accumulated. + +The complete order is: select calibration for the target layout → apply +balance and trim while panning in the intermediate layout → fold horizontal +surrounds → update gain ramps and mix. Per-object bypass disables balance +and trim while retaining layout selection and folding. These modes are +generic speaker-rendering controls; the publicly defined E-AC-3 JOC warp +values remain 0/1. Source trajectories, ADM and binaural do not bake in the +folded result. + ## 13. OAMD time alignment and gain ramps The coded position of an OAMD update is diff --git a/docs/math.md b/docs/math.md index beabbb3..04153e3 100644 --- a/docs/math.md +++ b/docs/math.md @@ -451,7 +451,7 @@ v_{\mathrm{floor}}= $$ `warp_mode=0` 或其他布局使用 $v_{\mathrm{floor}}=v$。高度层不做该缩放。 -未携带 warp 元数据时采用 0;命令行不提供覆盖选项。2/3 保留为未实现,报错而不回退。 +未携带 warp 元数据时采用 0;命令行不提供覆盖选项。warp 2/3 使用 §12.5 的中间布局与折叠矩阵。 有 front/back balance 时,先求这里的分支坐标,再应用 §12.3 的 balance。 ### 10.3 高度层 @@ -557,7 +557,7 @@ warp、trim 和 balance 均从 OAMD 元数据读取。各参数的取值与作 | 参数 | 取值或单位 | 行为 | |---|---|---| -| `warp_mode` | 0 / 1 | 选择 §10.2 的地面 Y 映射;2/3 暂不支持,遇到时明确报错 | +| `warp_mode` | 0 / 1 / 2 / 3 | 直接渲染 / 地面 Y 缩放 / PLIIx 折叠 / Standard(Lo/Ro)折叠 | | `global_trim_mode` | 0 / 1 / 2 | automatic / disabled / 按目标布局配置选择;3 为保留值,明确报错 | | $T_s$、$T_h$ | dB | 显式 surround、height trim 参数,正值按 0 处理 | | $T_c$ | dB | 显式 centre trim 参数,保留符号 | @@ -628,7 +628,7 @@ $$ ### 12.4 施加位置 记 §12.3 的高度混合 balance 映射为 $B_z(y)$,§10.2 的 warp 映射为 $W(y)$。 -普通点对象的实际分支顺序为 +warp 0/1 直接渲染点对象时,分支顺序为 $$ y_f=B_z(W(y)),\qquad y_h=B_z(y),\qquad y_t=B_z(y). @@ -642,11 +642,43 @@ $$ 因此可概括为 warp → balance → trim 与声像增益合成,但不能让所有阶段共用一个 已经 warp 的 Y。balance 仅在 explicit 且未逐对象 bypass 时启用;warp 不受 trim -状态或 trim bypass 控制。源坐标保持原值,ADM 与 binaural 不预烘焙此变换。 +状态或 trim bypass 控制。源坐标保持原值,ADM 与 binaural 不预处理此变换。 地面坐标依次经过 warp、balance,再用于地面声像;顶部坐标和 trim 求值坐标只经过 balance。trim 标量乘到该对象的整条声像增益向量后,再累加到输出声道。LFE 直接通过。 +### 12.5 warp 2/3 的环绕折叠 + +目标为 5.1、5.1.2 或 5.1.4 时,warp 2/3 先把对象渲染到对应的 7.1、7.1.2 或 +7.1.4 中间布局,再将后环绕折叠到目标的环绕对。4.0 同样先增加一对后环绕, +中间布局不增加 centre 或 LFE。其他现有布局直接渲染。 + +中间布局只改变扬声器几何与声像分配。Trim 配置、两层 Balance 和 Auto Trim 的 +最大位置补偿仍按最终目标布局选择。例如,5.1.2 使用配置 4,最大位置补偿为 +$-2.25$ dB,即使其中间布局是 7.1.2,也继续使用这些参数。中间布局已有独立 +side/rear 两对,地面 Y 不再乘 2;Balance 和逐对象 Trim 在中间渲染时求值。 + +设中间布局输出为 $L_s,R_s,L_{rs},R_{rs}$,最终目标的环绕输出为 $L'_s,R'_s$: + +$$ +L'_s=L_s+aL_{rs}+bR_{rs},\qquad +R'_s=R_s+bL_{rs}+aR_{rs}. +$$ + +| 模式 | $a$ | $b$ | +|---|---|---| +| 2:PLIIx | $\sqrt{3}/2$ | $1/2$ | +| 3:Standard(Lo/Ro) | $1$ | $0$ | + +两种矩阵都按线性幅度相加,不做折叠后的能量归一化。共同的前方、高度和 LFE +声道按对应位置直接通过。折叠后的对象增益向量进入 §13 的目标增益更新与斜坡, +然后累加对象音频。 + +完整顺序为:按目标布局选择校准参数 → 在中间布局应用 Balance、Trim 并计算声像 +增益 → 折叠水平环绕 → 更新增益斜坡与混音。逐对象 bypass 关闭 Balance 和 Trim, +但仍保留 warp 2/3 的布局选择与折叠。上述模式属于通用扬声器渲染控制;E-AC-3 JOC +公开定义的 warp 值仍为 0/1,源对象轨迹、ADM 和 binaural 不预处理折叠结果。 + ## 13. OAMD 时间对齐与增益斜坡 OAMD 更新的编码位置为 diff --git a/include/eac3joc_core.h b/include/eac3joc_core.h index 44c6d9b..b67560f 100644 --- a/include/eac3joc_core.h +++ b/include/eac3joc_core.h @@ -131,8 +131,11 @@ the three trim levels and the two front-back balances. trim_bypass is indexed by object slot (1..15); slot 0 carries the LFE and is unused. warp_mode 0 leaves the floor Y coordinate unchanged; mode 1 maps it through -clamp(2Y, 0, 1). warp modes 2 and 3 have no speaker implementation and are -rejected by the caller that builds this structure. +clamp(2Y, 0, 1). Modes 2 and 3 render the 5.1-family and 4.0 layouts through an +expanded surround layout (7.1-family, or a rear pair added to 4.0 without a +centre or LFE) and fold the rear pair into the target surround pair: mode 2 +uses the PLIIx coefficients (sqrt(3)/2 and 1/2), mode 3 the Standard (Lo/Ro) +coefficients (1 and 0). Layouts without a single surround pair render directly. trim_mode selects where the gain comes from: automatic applies the layout position compensation, disabled applies no trim, and explicit applies the diff --git a/src/speaker/speaker_renderer.cpp b/src/speaker/speaker_renderer.cpp index d1ce5f1..9ae1418 100644 --- a/src/speaker/speaker_renderer.cpp +++ b/src/speaker/speaker_renderer.cpp @@ -16,6 +16,7 @@ namespace ejoc::speaker { using speaker_tables::AxisGroup; using speaker_tables::LayoutGeometry; using speaker_tables::RegionGeometry; +using speaker_tables::SpeakerPoint; constexpr double kPi = 3.141592653589793238462643383279502884; constexpr double kQ15Scale = 32768.0; @@ -194,7 +195,8 @@ public: static_cast(standard); } attenuation_db_ = layout_attenuation_db(layout_->speaker_bitfield); - floor_y_exponent_ = floor_y_exponent(layout_->speaker_bitfield); + target_floor_y_exponent_ = floor_y_exponent(layout_->speaker_bitfield); + configure_surround_fold(); reset_state(); } @@ -268,6 +270,159 @@ public: } private: + // Warp 2/3 render the 5.1-family and 4.0 layouts through an expanded + // surround layout, then fold the rear pair into the target surround pair. + void configure_surround_fold() noexcept { + fold_layout_ = layout_; + fold_source_channels_ = layout_->channel_count; + fold_source_floor_y_exponent_ = target_floor_y_exponent_; + fold_available_ = false; + if (target_floor_y_exponent_ == 0) { + return; + } + const LayoutGeometry* source = nullptr; + switch (layout_->speaker_bitfield) { + case 15u: source = speaker_tables::find_layout(31u); break; + case 1039u: source = speaker_tables::find_layout(1055u); break; + case 2575u: source = speaker_tables::find_layout(2591u); break; + case 9u: + build_fold_source_40(); + source = &fold_layout_storage_; + break; + default: return; + } + if (source == nullptr || source->channel_count == 0) { + return; + } + fold_layout_ = source; + fold_source_channels_ = source->channel_count; + fold_source_floor_y_exponent_ = floor_y_exponent(source->speaker_bitfield); + build_fold_matrix(source->speaker_bitfield, layout_->speaker_bitfield); + fold_available_ = true; + } + + // 4.0 expands to six full-band speakers without adding centre or LFE. + void build_fold_source_40() noexcept { + const LayoutGeometry* base = speaker_tables::find_layout(31u); + if (base == nullptr) { + return; + } + LayoutGeometry& out = fold_layout_storage_; + out = *base; + out.speaker_bitfield = 25u; // 4.0's pair plus the rear pair + out.out_ch_config = 255u; + out.channel_count = 6; + for (std::size_t slot = 0; slot < out.standard_from_internal.size(); ++slot) { + out.standard_from_internal[slot] = static_cast(slot); + } + constexpr int kMapped[8] = {0, 1, -1, -1, 2, 3, 4, 5}; + for (RegionGeometry& region : out.regions) { + int index_map[speaker_tables::kMaxPoints]; + for (int& value : index_map) { + value = -1; + } + std::size_t kept = 0; + for (std::size_t point = 0; point < region.point_count; ++point) { + const int speaker = region.points[point].speaker_id; + const int mapped = speaker >= 0 && speaker < 8 ? kMapped[speaker] : -1; + if (mapped < 0) { + continue; + } + region.points[kept] = region.points[point]; + region.points[kept].speaker_id = static_cast(mapped); + index_map[point] = static_cast(kept); + ++kept; + } + for (std::size_t point = kept; point < region.point_count; ++point) { + region.points[point] = SpeakerPoint{}; + } + region.point_count = static_cast(kept); + filter_groups(region.axis0_groups, region.axis0_group_count, index_map); + filter_groups(region.axis1_groups, region.axis1_group_count, index_map); + } + } + + static void filter_groups(std::array& groups, + std::uint8_t& count, + const int (&index_map)[speaker_tables::kMaxPoints]) noexcept { + std::array filtered{}; + std::uint8_t kept_groups = 0; + for (std::size_t row = 0; row < count; ++row) { + AxisGroup group{}; + for (std::size_t index = 0; index < groups[row].size; ++index) { + const int mapped = index_map[groups[row].indices[index]]; + if (mapped < 0) { + continue; + } + group.indices[group.size++] = static_cast(mapped); + } + if (group.size != 0) { + filtered[kept_groups++] = group; + } + } + groups = filtered; + count = kept_groups; + } + + // Shared speakers pass through; speaker IDs 6/7 are the rear pair and fold + // into the same-side (and, for PLIIx, the cross-side) surround. + void build_fold_matrix(std::uint32_t source_bitfield, + std::uint32_t target_bitfield) noexcept { + int source_ids[64]; + int target_ids[64]; + std::size_t source_count = 0; + std::size_t target_count = 0; + const std::uint64_t source_mask = expand_speaker_bitfield(source_bitfield); + const std::uint64_t target_mask = expand_speaker_bitfield(target_bitfield); + for (int id = 0; id < 64; ++id) { + if (((source_mask >> id) & 1ULL) != 0u) { + source_ids[source_count++] = id; + } + if (((target_mask >> id) & 1ULL) != 0u) { + target_ids[target_count++] = id; + } + } + for (auto& row : fold_pl2x_) { + row.fill(0.0); + } + for (auto& row : fold_loro_) { + row.fill(0.0); + } + constexpr double kSqrt3Over2 = 0.86602540378443864676; + for (std::size_t column = 0; column < source_count; ++column) { + const int id = source_ids[column]; + const std::size_t direct = target_position(target_ids, target_count, id); + if (direct < kChannels) { + fold_pl2x_[direct][column] = 1.0; + fold_loro_[direct][column] = 1.0; + continue; + } + if (id != 6 && id != 7) { + continue; + } + const std::size_t same = target_position(target_ids, target_count, id - 2); + const std::size_t cross = target_position(target_ids, target_count, id == 6 ? 5 : 4); + if (same < kChannels) { + fold_pl2x_[same][column] = kSqrt3Over2; + fold_loro_[same][column] = 1.0; + } + if (cross < kChannels) { + fold_pl2x_[cross][column] = 0.5; + fold_loro_[cross][column] = 0.0; + } + } + } + + static std::size_t target_position(const int (&ids)[64], std::size_t count, + int id) noexcept { + for (std::size_t index = 0; index < count; ++index) { + if (ids[index] == id) { + return index; + } + } + return kChannels; + } + void reset_state() noexcept { for (auto& row : current_) row.fill(0.0); for (auto& row : target_) row.fill(0.0); @@ -292,8 +447,8 @@ private: fail("unknown speaker controls struct_version"); return false; } - if (controls->warp_mode > 1u) { - fail("speaker rendering implements warp modes 0/1 only"); + if (controls->warp_mode > 3u) { + fail("unknown speaker warp mode"); return false; } if (controls->trim_mode > EJOC_SPEAKER_TRIM_EXPLICIT) { @@ -370,11 +525,15 @@ private: const bool bypass_trim, ChannelGains& output) const noexcept { output.fill(0.0); - const auto& region = layout_->regions[region_index]; + const bool folding = fold_available_ && controls.warp_mode >= 2u; + const auto& region = (folding ? *fold_layout_ : *layout_).regions[region_index]; const double u = static_cast(position[0]) / kQ15Scale; const double v = static_cast(position[1]) / kQ15Scale; const double w = std::max(static_cast(position[2]) / kQ15Scale, 0.0); - const int shift = controls.warp_mode == 1u ? floor_y_exponent_ : 0; + const int shift = controls.warp_mode == 0u + ? 0 + : (folding ? fold_source_floor_y_exponent_ + : target_floor_y_exponent_); 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; @@ -416,8 +575,21 @@ private: gain *= joc::speaker::explicit_position_gain(controls, u, trim_v, w); } } + ChannelGains internal{}; for (std::size_t index = 0; index < region.point_count; ++index) { - output[region.points[index].speaker_id] = point[index] * gain; + internal[region.points[index].speaker_id] = point[index] * gain; + } + if (!folding) { + output = internal; + return; + } + const auto& matrix = controls.warp_mode == 2u ? fold_pl2x_ : fold_loro_; + for (std::size_t target = 0; target < layout_->channel_count; ++target) { + double sum = 0.0; + for (std::size_t source = 0; source < fold_source_channels_; ++source) { + sum += matrix[target][source] * internal[source]; + } + output[target] = sum; } } @@ -501,8 +673,15 @@ private: } const LayoutGeometry* layout_; + const LayoutGeometry* fold_layout_ = nullptr; + LayoutGeometry fold_layout_storage_{}; + bool fold_available_ = false; + std::uint8_t fold_source_channels_ = 0; + int fold_source_floor_y_exponent_ = 0; + std::array fold_pl2x_{}; + std::array fold_loro_{}; double attenuation_db_{}; - int floor_y_exponent_{}; + int target_floor_y_exponent_{}; ObjectChannelGains current_{}; ObjectChannelGains target_{}; ObjectChannelGains step_{}; diff --git a/src/speaker/speaker_trim.cpp b/src/speaker/speaker_trim.cpp index 2200eb6..7ce85db 100644 --- a/src/speaker/speaker_trim.cpp +++ b/src/speaker/speaker_trim.cpp @@ -52,11 +52,10 @@ Status parameters_from_oamd(const oamd::OamdTrim* trim, const LayoutInfo& layout 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 (controls.warp_mode > 3u) { + return Status::fail(JOC_ERR_INVALID_ARGUMENT, stage::kRender, + "speaker: invalid warp mode " + + std::to_string(controls.warp_mode)); } if (!layout.carries_trim) { controls.trim_mode = EJOC_SPEAKER_TRIM_DISABLED; diff --git a/src/speaker/speaker_trim.h b/src/speaker/speaker_trim.h index 32d982f..d932ea5 100644 --- a/src/speaker/speaker_trim.h +++ b/src/speaker/speaker_trim.h @@ -23,10 +23,11 @@ inline constexpr int kBalanceSteps = 16; // 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. +// Converts OAMD calibration to the speaker controls of one layout. Warp 0 +// renders directly, 1 scales the floor Y, and 2/3 render through an expanded +// surround layout before folding; the reserved global trim mode is 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); diff --git a/tests/test_core.cpp b/tests/test_core.cpp index bacd739..08e7b46 100644 --- a/tests/test_core.cpp +++ b/tests/test_core.cpp @@ -550,11 +550,15 @@ void test_speaker_trim_parameters() { trim.configs[1].centre = 1.5; trim.warp_mode = 2; - const joc::Status warp2 = joc::speaker::parameters_from_oamd(&trim, layout51, &controls); - CHECK(!warp2.ok()); - CHECK(warp2.code() == JOC_ERR_NOT_SUPPORTED); + CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok()); + CHECK(controls.warp_mode == 2); trim.warp_mode = 3; - CHECK(!joc::speaker::parameters_from_oamd(&trim, layout714, &controls).ok()); + CHECK(joc::speaker::parameters_from_oamd(&trim, layout714, &controls).ok()); + CHECK(controls.warp_mode == 3); + CHECK(controls.trim_mode == EJOC_SPEAKER_TRIM_DISABLED); + trim.warp_mode = 4; + CHECK(joc::speaker::parameters_from_oamd(&trim, layout51, &controls).code() == + JOC_ERR_INVALID_ARGUMENT); trim.warp_mode = 0; trim.global_trim_mode = 3; CHECK(!joc::speaker::parameters_from_oamd(&trim, layout51, &controls).ok()); @@ -641,8 +645,8 @@ void test_speaker_warp_and_trim() { CHECK(channel == 3 ? std::fabs(value - 0.25) <= 1e-15 : value == 0.0); } } - // Reserved warp modes are rejected before any rendering happens. - ejoc_speaker_controls reserved = speaker_controls(2, EJOC_SPEAKER_TRIM_DISABLED); + // Warp modes above the two-bit OAMD field are rejected. + ejoc_speaker_controls reserved = speaker_controls(4, EJOC_SPEAKER_TRIM_DISABLED); CHECK(ejoc_speaker_renderer_process(handle, input.data(), EJOC_SPEAKER_BLOCK_SAMPLES, 0, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, &reserved, output.data()) != 0); @@ -650,6 +654,116 @@ void test_speaker_warp_and_trim() { } } +// Warp 2/3 render the 5.1-family and 4.0 layouts through an expanded surround +// layout and fold the rear pair back; calibration stays on the target layout. +void test_speaker_surround_fold() { + joc::speaker::LayoutInfo layout20{}; + joc::speaker::LayoutInfo layout40{}; + joc::speaker::LayoutInfo layout51{}; + joc::speaker::LayoutInfo layout512{}; + joc::speaker::LayoutInfo layout514{}; + joc::speaker::LayoutInfo layout71{}; + CHECK(joc::speaker::layout_by_name("2.0", &layout20)); + CHECK(joc::speaker::layout_by_name("4.0", &layout40)); + CHECK(joc::speaker::layout_by_name("5.1", &layout51)); + CHECK(joc::speaker::layout_by_name("5.1.2", &layout512)); + CHECK(joc::speaker::layout_by_name("5.1.4", &layout514)); + CHECK(joc::speaker::layout_by_name("7.1", &layout71)); + + ejoc_speaker_controls pl2x{}; + CHECK(joc::speaker::parameters_from_oamd(nullptr, layout51, &pl2x).ok()); + pl2x.warp_mode = 2; + ejoc_speaker_controls loro = pl2x; + loro.warp_mode = 3; + + // PLIIx spreads the rear object into both surrounds; Lo/Ro keeps it on the + // same side. Nothing is normalized after the fold. + const std::vector pl2x_mid = {0, 0, 0, 0, 0.88868654605257746, + 0.13546740014942704}; + const std::vector loro_mid = {0, 0, 0, 0, 0.92498492652336017, 0}; + const std::vector pl2x_back = {0, 0, 0, 0, 0.93411653293116492, + 0.25030863131451864}; + const std::vector loro_back = {0, 0, 0, 0, 1.0011865285504298, 0}; + check_gains(speaker_gains(layout51, pl2x, 0, 20480, 0), pl2x_mid); + check_gains(speaker_gains(layout51, loro, 0, 20480, 0), loro_mid); + check_gains(speaker_gains(layout51, pl2x, 0, 24576, 0), pl2x_back); + check_gains(speaker_gains(layout51, loro, 0, 24576, 0), loro_back); + + // 4.0 adds a rear pair without adding centre or LFE. + const std::vector pl2x_40 = {0, 0, 0.93411653293116492, 0.25030863131451864}; + const std::vector loro_40 = {0, 0, 1.0011865285504298, 0}; + const std::vector loro_40_front = {0.85973646214220434, 0, + 0.35611450268596406, 0}; + check_gains(speaker_gains(layout40, pl2x, 0, 24576, 0), pl2x_40); + check_gains(speaker_gains(layout40, loro, 0, 24576, 0), loro_40); + check_gains(speaker_gains(layout40, loro, 0, 4096, 0), loro_40_front); + + // The height layer and the 5.1.4/5.1.2 geometry come from the 7.1 family. + const std::vector pl2x_512 = {0, 0, 0, 0, 0.64546952862797569, + 0.25210606107018951, 0.54573901433240524, 0}; + const std::vector loro_512 = {0, 0, 0, 0, 0.7130211440987243, 0, + 0.54573901433240524, 0}; + const std::vector pl2x_514 = {0, 0, 0, 0, 0.70368087041735738, + 0.27484211821501858, 0, 0, + 0.59495621031473322, 0}; + check_gains(speaker_gains(layout512, pl2x, 0, 28672, 16384), pl2x_512); + check_gains(speaker_gains(layout512, loro, 0, 28672, 16384), loro_512); + check_gains(speaker_gains(layout514, pl2x, 0, 28672, 16384), pl2x_514); + + // Calibration is selected for the final target, not the intermediate + // layout: an explicit surround trim on 5.1 applies before the fold. + ejoc_speaker_controls trimmed = pl2x; + trimmed.trim_mode = EJOC_SPEAKER_TRIM_EXPLICIT; + trimmed.surround_db = -6.0; + const std::vector pl2x_trim = {0, 0, 0, 0, 0.66130386161214494, + 0.17720494033407685}; + check_gains(speaker_gains(layout51, trimmed, 0, 24576, 0), pl2x_trim); + // Per-object bypass drops balance and trim but keeps the fold. + const std::vector pl2x_bypass = {0, 0, 0, 0, 1.319474673818108, + 0.35357033947489241}; + check_gains(speaker_gains(layout51, trimmed, 0, 24576, 0, true), pl2x_bypass); + + // Layouts with both surround pairs, or none, render directly. + ejoc_speaker_controls direct71{}; + CHECK(joc::speaker::parameters_from_oamd(nullptr, layout71, &direct71).ok()); + ejoc_speaker_controls pl2x71 = direct71; + pl2x71.warp_mode = 2; + check_gains(speaker_gains(layout71, pl2x71, 0, 24576, 0), + speaker_gains(layout71, direct71, 0, 24576, 0)); + ejoc_speaker_controls direct20{}; + CHECK(joc::speaker::parameters_from_oamd(nullptr, layout20, &direct20).ok()); + ejoc_speaker_controls pl2x20 = direct20; + pl2x20.warp_mode = 2; + check_gains(speaker_gains(layout20, pl2x20, 0, 24576, 0), + speaker_gains(layout20, direct20, 0, 24576, 0)); + + // LFE passes through the folded output untouched. + ejoc_speaker_renderer_handle handle = + ejoc_speaker_renderer_create(layout51.speaker_bitfield); + CHECK(handle != nullptr); + if (handle != nullptr) { + std::vector input(static_cast(EJOC_SPEAKER_BLOCK_SAMPLES) * + JOC_OUTPUT_CHANNELS, + 0.0f); + for (std::uint32_t sample = 0; sample < EJOC_SPEAKER_BLOCK_SAMPLES; ++sample) { + input[sample * JOC_OUTPUT_CHANNELS] = 0.25f; + } + std::vector output(static_cast(EJOC_SPEAKER_BLOCK_SAMPLES) * + layout51.channel_count, + 0.0); + CHECK(ejoc_speaker_renderer_process(handle, input.data(), EJOC_SPEAKER_BLOCK_SAMPLES, + 0, nullptr, nullptr, nullptr, nullptr, nullptr, + nullptr, &pl2x, output.data()) == 0); + for (std::uint32_t sample = 0; sample < EJOC_SPEAKER_BLOCK_SAMPLES; ++sample) { + for (std::uint32_t channel = 0; channel < layout51.channel_count; ++channel) { + const double value = output[sample * layout51.channel_count + channel]; + CHECK(channel == 3 ? std::fabs(value - 0.25) <= 1e-15 : value == 0.0); + } + } + ejoc_speaker_renderer_destroy(handle); + } +} + // The speaker step takes the OAMD trim element from each payload; a payload // without it keeps the previous controls. void test_speaker_step_trim_events() { @@ -708,6 +822,21 @@ void test_speaker_step_trim_events() { 0.094556249720175942, 0}; check_gains(gains, half_warp0); + // A warp 2 element renders through the expanded layout and folds. + update = joc::oamd::OamdUpdate{}; + update.slots[1].q2 = 24576; + update.has_trim = true; + update.trim.warp_mode = 2; + update.trim.global_trim_mode = 0; + update.trim.object_count = 16; + CHECK(joc::speaker::step(&step, frame, &update, &error).ok()); + for (std::uint32_t channel = 0; channel < step.layout.channel_count; ++channel) { + gains[channel] = step.output[read + channel]; + } + const std::vector fold_back = {0, 0, 0, 0, 0.93411653293116492, + 0.25030863131451864}; + check_gains(gains, fold_back); + ejoc_speaker_renderer_destroy(step.handle); } @@ -1366,6 +1495,7 @@ int main() { test_oamd_trim_parse(); test_speaker_trim_parameters(); test_speaker_warp_and_trim(); + test_speaker_surround_fold(); test_speaker_step_trim_events(); test_dbmd_and_axml_trim(); test_int24_packing();