Add an occlusion culling benchmark sample

Measures what a CPU visibility pass costs over a thousand boxes, two ways and at
two ray widths, with the accuracy of each. No shading: this measures visibility.

The per-object pass runs at 0.16 ms and removes two thirds of the draw calls,
about 1% of a 16.6 ms frame. The visibility buffer is four times dearer, culls
less, and is far more accurate. Both numbers come with what they get wrong.

Three things this turned up that are worth having written down:

Packet width has to be asked of the device. rtcIntersect16/rtcOccluded16 may
only be called when RTC_DEVICE_PROPERTY_NATIVE_RAY16_SUPPORTED says so, and
calling them anyway is undefined behaviour: the first version of this sample used
16 and corrupted the heap, surfacing as a crash inside AlignedFree with no hint
of the real cause. The shipped binaries are AVX2, which tops out at 8.

Packets are not automatically faster. They lose the per-object early exit -- once
one sample proves a box visible the rest are wasted, but the lanes are already
committed -- and 9,000 rays with SIMD come out slower than 7,165 without. For the
visibility buffer, where every ray is needed anyway, they draw level.

The obvious per-object test is wrong. An occlusion ray stopping just short of a
sample point on the box has the box occlude itself, since the point sits on its
own surface. Asking what the ray hits first costs more and answers the question
actually being asked.

Accuracy is reported weighted by screen area, not by object count. In a grid this
dense most of what is technically visible is visible through a gap a pixel or two
wide, so a raw count of missed objects reads as alarming while the pass is fine:
163 boxes missed, 3% of the screen.

Author: jcant0n

.gitignore

@@ -4,3 +4,8 @@
 
 # Screenshot produced by the sample at runtime (docs/ holds the committed ones).
 HelloEmbree/screenshot.png
+
+# Images the sample writes at runtime (docs/ holds the committed ones).
+OcclusionCulling/scene.png
+OcclusionCulling/verdict.png
+OcclusionCulling/slice.png

Embree.sln

@@ -9,6 +9,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Evergine.Bindings.Embree",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HelloEmbree", "HelloEmbree\HelloEmbree.csproj", "{E4461EA5-FD21-4449-A493-7BF77E32C8D2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OcclusionCulling", "OcclusionCulling\OcclusionCulling.csproj", "{9D90D092-3E99-429C-8657-C4809D72375B}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -55,6 +57,18 @@ Global
 		{E4461EA5-FD21-4449-A493-7BF77E32C8D2}.Release|x64.Build.0 = Release|Any CPU
 		{E4461EA5-FD21-4449-A493-7BF77E32C8D2}.Release|x86.ActiveCfg = Release|Any CPU
 		{E4461EA5-FD21-4449-A493-7BF77E32C8D2}.Release|x86.Build.0 = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|x64.Build.0 = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Debug|x86.Build.0 = Debug|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|x64.ActiveCfg = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|x64.Build.0 = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|x86.ActiveCfg = Release|Any CPU
+		{9D90D092-3E99-429C-8657-C4809D72375B}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

OcclusionCulling/Camera.cs

@@ -0,0 +1,98 @@
+using System;
+using System.Numerics;
+
+namespace OcclusionCulling
+{
+	/// <summary>
+	/// A pinhole camera plus the six frustum planes derived from it.
+	/// </summary>
+	/// <remarks>
+	/// The AABB test is the same scalar six-plane centre/half-extent form Evergine's
+	/// <c>BoundingFrustum.Intersects(ref BoundingBox, out bool)</c> uses, reproduced here so the
+	/// sample stays free of engine dependencies and runs on every RID the binding ships.
+	/// </remarks>
+	internal sealed class Camera
+	{
+		private readonly Vector4[] planes = new Vector4[6];
+
+		public Camera(Vector3 position, Vector3 target, float fovDegrees, float aspect, float near, float far)
+		{
+			this.Position = position;
+			this.Forward = Vector3.Normalize(target - position);
+			this.Right = Vector3.Normalize(Vector3.Cross(this.Forward, Vector3.UnitY));
+			this.Up = Vector3.Cross(this.Right, this.Forward);
+
+			this.TanHalfFov = MathF.Tan(fovDegrees * MathF.PI / 180.0f * 0.5f);
+			this.Aspect = aspect;
+
+			var view = Matrix4x4.CreateLookAt(position, target, Vector3.UnitY);
+			var projection = Matrix4x4.CreatePerspectiveFieldOfView(
+				fovDegrees * MathF.PI / 180.0f, aspect, near, far);
+			this.ExtractPlanes(view * projection);
+		}
+
+		public Vector3 Position { get; }
+
+		public Vector3 Forward { get; }
+
+		public Vector3 Right { get; }
+
+		public Vector3 Up { get; }
+
+		public float TanHalfFov { get; }
+
+		public float Aspect { get; }
+
+		/// <summary>
+		/// Ray direction through a normalised screen position, both in [0, 1].
+		/// </summary>
+		public Vector3 RayDirection(float u, float v)
+		{
+			float x = ((u * 2.0f) - 1.0f) * this.TanHalfFov * this.Aspect;
+			float y = (1.0f - (v * 2.0f)) * this.TanHalfFov;
+			return Vector3.Normalize(this.Forward + (this.Right * x) + (this.Up * y));
+		}
+
+		/// <summary>
+		/// Tests an AABB against the six planes. Conservative: a box straddling a plane counts
+		/// as inside.
+		/// </summary>
+		public bool Intersects(in Vector3 min, in Vector3 max)
+		{
+			Vector3 centre = (min + max) * 0.5f;
+			Vector3 extent = (max - min) * 0.5f;
+
+			for (int i = 0; i < 6; i++)
+			{
+				Vector4 p = this.planes[i];
+				var normal = new Vector3(p.X, p.Y, p.Z);
+
+				float distance = Vector3.Dot(normal, centre) + p.W;
+				float radius = Vector3.Dot(Vector3.Abs(normal), extent);
+
+				if (distance + radius < 0.0f)
+				{
+					return false;
+				}
+			}
+
+			return true;
+		}
+
+		private void ExtractPlanes(Matrix4x4 m)
+		{
+			this.planes[0] = Normalize(new Vector4(m.M14 + m.M11, m.M24 + m.M21, m.M34 + m.M31, m.M44 + m.M41)); // left
+			this.planes[1] = Normalize(new Vector4(m.M14 - m.M11, m.M24 - m.M21, m.M34 - m.M31, m.M44 - m.M41)); // right
+			this.planes[2] = Normalize(new Vector4(m.M14 + m.M12, m.M24 + m.M22, m.M34 + m.M32, m.M44 + m.M42)); // bottom
+			this.planes[3] = Normalize(new Vector4(m.M14 - m.M12, m.M24 - m.M22, m.M34 - m.M32, m.M44 - m.M42)); // top
+			this.planes[4] = Normalize(new Vector4(m.M13, m.M23, m.M33, m.M43));                                 // near
+			this.planes[5] = Normalize(new Vector4(m.M14 - m.M13, m.M24 - m.M23, m.M34 - m.M33, m.M44 - m.M43)); // far
+		}
+
+		private static Vector4 Normalize(Vector4 plane)
+		{
+			float length = new Vector3(plane.X, plane.Y, plane.Z).Length();
+			return length > 0.0f ? plane / length : plane;
+		}
+	}
+}