Documentation update

VoidXH · Sep 9, 2024 · 8e25779 · 8e25779
1 parent f69b565
commit 8e25779
Show file tree

Hide file tree

Showing 10 changed files with 84 additions and 25 deletions.
diff --git a/Cavern/Channels/ChannelPrototype.Consts.cs b/Cavern/Channels/ChannelPrototype.Consts.cs
@@ -71,7 +71,7 @@ public static readonly ChannelPrototype
             new Vector3(1, 0, .677419f), // WideRight
             new Vector3(-1, 1, -1), // TopRearLeft
             new Vector3(1, 1, -1), // TopRearRight
-            new Vector3(-1, 1, 0) // TopRearCenter
+            new Vector3(0, 1, -1) // TopRearCenter
         };
 
         /// <summary>

diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ These examples use the Cavern library to show how it works. The solution
 containing all sample projects is found at `CavernSamples/CavernSamples.sln`.
 The same build instructions apply as to the base project.
 
-Single-purpose sample codes are found under `docs/Code`.
+Single-purpose sample codes are found under `docs/Code samples`.
 
 ### Cavern for Unity
 Open the `CavernUnity DLL.sln` solution with Microsoft Visual Studio 2022.
@@ -191,8 +191,8 @@ component browser, under audio, and they will automatically add all their Unity
 dependencies.
 
 ## Development documents
-* [Documentations of specific use-cases](./docs)
-* [Scripting API](http://cavern.sbence.hu/cavern/doc.php?if=api/index) with descriptions of all public members for all public classes
+* [Knowledge base](./docs)
+* [API browser](http://cavern.sbence.hu/cavern/doc.php?if=api/index) with descriptions of all public members for all public classes
 * [Virtualizer repository](https://github.com/VoidXH/HRTF) which contains the raw IR measurements and detailed information about their use
 
 ## Disclaimers

diff --git a/docs/Cavern DCP channel order.md b/docs/Cavern DCP channel order.md
@@ -1,10 +1,14 @@
 # Cavern DCP channel order
-This is the recommended DCP channel ordering, and also the recommended wiring.
+This is the recommended DCP channel ordering, and also the recommended wiring
+for Digital Cinema Packages, the standard content delivery format for commercial
+theatres. This documentation is for DCP producing entities, not for home movies.
+
 Cavern DCPs only take advantage of currently or always unused channels, thus
 systems built for Cavern are perfectly backwards compatible, including 7.1,
 hearing/visually impaired tracks, and all sync signals. Cavern is using a 7.1.2
 bed only, with the Top Surround channels as Left/Right ceiling arrays. Cavern XL
-adds an additional Bottom Surround channel.
+adds an additional Bottom Surround channel array. Speakers that are part of the
+Bottom Surround array shall be placed into the stairs in the theatre room.
 
 | Channel | 5.1 | 7.1 SDDS | 7.1 DS | Auro 11.1 | Cavern | Cavern XL | Notes                                         |
 |--------:|:---:|:--------:|:------:|:---------:|:------:|:---------:|-----------------------------------------------|
@@ -24,22 +28,3 @@ adds an additional Bottom Surround channel.
 | 14      | ES  | ES       | ES     | ES        | ES     | ES        | External Sync Signal                          |
 | 15      | SL  | SL       | SL     | SL        | SL     | SL        | Sign Language Video                           |
 | 16      | -   | -        | -      | -         | -      | Bs        | Bottom Surround                               |
-
-# Channel angles
-For home and studios with a single speaker per channel, the recommended angles
-(+/- 10°) are:
-
-| Channel             | W / Y | H / X |
-|---------------------|:-----:|:-----:|
-| Front Left          | -30°  | 0°    |
-| Front Right         | 30°   | 0°    |
-| Front Center        | 0°    | 0°    |
-| Left Side Surround  | -110° | 0°    |
-| Right Side Surround | 110°  | 0°    |
-| Left Rear Surround  | -150° | 0°    |
-| Right Rear Surround | 150°  | 0°    |
-| Front Left Center   | -15°  | 0°    |
-| Front Right Center  | 15°   | 0°    |
-| Left Top Surround   | -70°  | -45°  |
-| Right Top Surround  | 70°   | -45°  |
-| Bottom Surround     | 0°    | 90°   |
diff --git a/docs/Channel placement guide.md b/docs/Channel placement guide.md
@@ -0,0 +1,67 @@
+# Channel placement guide for object-based audio
+Contrary to popular belief, speakers for object-based systems do not adhere to
+specific angles. By design, object-based renderers place objects relative to the
+room's walls, by the ratio between opposing walls. This happens because of the
+industry's chosen rendering method, called balance-based rendering.
+
+## How balance-based rendering works
+![Balance-based renderer](img/rnd_balance.png)
+Point object sources are rendered in a bounding speaker box by the ratio between
+them. This requires a channel layout to be symmetric, because not only there are
+front/rear, upper/lower channel pairs, but a left/right also has to be found to
+get all corners. When the pairs are found, the closer wall to the object will be
+louder. This is calculated on each axis, and the values corresponding to the
+corner of each speaker will be multiplied together to get the final gain.
+
+## What the true channel positions are
+Reverse-engineering object-based content with Cavern resulted in the following
+findings. Mixes rendered to the final channel layout contain a single,
+motionless object at the channel's exact position so they get rendered to that
+exact channel. This is only possible if the renderer chooses that position as
+an output channel, meaning these are the true channel possitions.
+
+<sub>These positions are also confirmed to be used by Dolby in Table B.10 of
+ETSI TS 103 420 V1.2.1, which is the description of E-AC-3 + JOC.</sub>
+
+Screen channels assume the screen spans perfectly from wall to wall. Because
+this is mostly not the case at home, and no content or renderer known as of 2024
+uses screen-anchored objects, it is inherent that the front left and right
+channels have to be placed on the sides of the screen.
+
+| Channel          | Euclidean coordinates | Y angle | X angle | Human-readable position                 |
+|------------------|-----------------------|---------|---------|-----------------------------------------|
+| Front Left       | -1, 0, 1              | -45°    | 0°      | Front wall, left side of the screen     |
+| Front Right      | 1, 0, 1               | 45°     | 0°      | Front wall, right side of the screen    |
+| Front Center     | 0, 0, 1               | 0°      | 0°      | Front wall, middle of the screen        |
+| Rear Left        | -1, 0, -1             | -135°   | 0°      | Rear left corner                        |
+| Rear Right       | 1, 0, -1              | 135°    | 0°      | Rear right corner                       |
+| Side Left        | -1, 0, 0              | -90°    | 0°      | Middle of the left wall                 |
+| Side Right       | 1, 0, 0               | 90°     | 0°      | Middle of the right wall                |
+| Wide Left        | -1, 0, 0.677419       | -55.89° | 0°      | Left wall, about 16% from the front     |
+| Wide Right       | 1, 0, 0.677419        | 55.89°  | 0°      | Right wall, about 16% from the front    |
+| Top Front Left   | -1, 1, 1              | -45°    | -45°    | Ceiling, perfectly above Front Left     |
+| Top Front Right  | 1, 1, 1               | 45°     | -45°    | Ceiling, perfectly above Front Right    |
+| Top Front Center | 0, 1, 1               | 0°      | -45°    | Center of the front wall/ceiling corner |
+| Top Rear Left    | -1, 1, -1             | -135°   | -45°    | Top rear left corner                    |
+| Top Rear Right   | 1, 1, -1              | 135°    | -45°    | Top rear right corner                   |
+| Top Rear Center  | 0, 1, -1              | 180°    | -45°    | Center of the rear wall/ceiling corner  |
+| Top Side Left    | -1, 1, 0              | -90°    | -45°    | Midway between TFL and TRL positions    |
+| Top Side Right   | 1, 1, 0               | 90°     | -45°    | Midway between TFR and TRR positions    |
+| God's Voice      | 0, 1, 0               | 0°      | -90°    | Middle of the ceiling                   |
+
+### Transforming the angles to specific rooms
+The angles shown in the table on the Y (horizontal) and X (vertical) axes are
+calculated from the center of the room, for a perfectly cubical room. The ideal
+listening position is not that, it's about 2/3 to the back, but the angles
+should stay, because these are not individual channels, but channel arrays. In a
+commercial cinema, all speakers on the left wall used to play the left surround
+channel's signal before object-based content appeared, giving all listeners the
+experience of left sounds coming exactly from the left. Because in modern home
+content, there are only two options on the side walls, side and wide speakers,
+this directionality shall be preserved.
+
+Knowing these, the most mathematically optimal way to get the actually mixed
+soundstage is using a laser pointer from the main listener's head pointing to
+the directions described here, and putting the speakers where they hit any wall
+or the ceiling. This conveys the exact object movements described in content
+rendered with Cavern, all other setups warp the space in a direction.
diff --git a/docs/Code/ADM creation.md → docs/Code samples/ADM creation.md b/docs/Code/ADM creation.md → docs/Code samples/ADM creation.md
diff --git a/docs/Adding Cavern to a Media Player.md → ...amples/Adding Cavern to a Media Player.md b/docs/Adding Cavern to a Media Player.md → ...amples/Adding Cavern to a Media Player.md
diff --git a/...mat definitions/Convolution Box Format.md → ...eam definitions/Convolution Box Format.md b/...mat definitions/Convolution Box Format.md → ...eam definitions/Convolution Box Format.md
diff --git a/...mat definitions/Limitless Audio Format.md → ...eam definitions/Limitless Audio Format.md b/...mat definitions/Limitless Audio Format.md → ...eam definitions/Limitless Audio Format.md
diff --git a/docs/Quality modes.md b/docs/Quality modes.md
@@ -0,0 +1,7 @@
+# Cavern quality modes
+| Quality  | Doppler/pitch | Resampling   | Object downmix | Angle precision | Asymmetric mixing |
+|----------|---------------|--------------|----------------|-----------------|-------------------|
+| Perfect  | High          | Catmull-Rom  | All channels   | Arcsine         | As-is             |
+| High     | High          | Linear       | All channels   | Arcsine         | Triangulated      |
+| Medium   | Low           | Nearest      | First channel  | Linear          | Triangulated      |
+| Low      | Disabled      | Nearest      | First channel  | Linear          | Triangulated      |
diff --git a/docs/img/rnd_balance.png b/docs/img/rnd_balance.png