Efficient CPU Translucency Sorting with BSP Trees and Heuristics

CONTRIBUTING.md

@@ -11,7 +11,7 @@ with some minor changes, as described below.
     - If you are using more than three levels of indentation, you should likely consider restructuring your code.
     - Branches which are only exceptionally or very rarely taken should remain concise. When this is not possible,
       prefer breaking out to a new method (where it makes sense) as this helps the compiler better optimize the code.
-- Use `this` to qualify member and field access, as it avoids some ambiguity in certain contexts.
+- Use `this` to qualify method and field access, as it avoids some ambiguity in certain contexts.
 
 We also provide these code styles as [EditorConfig](https://editorconfig.org/) files, which most Java IDEs will
 automatically detect and make use of.
@@ -51,4 +51,4 @@ style guidelines.
 
 If you're adding new Mixin patches to the project, please ensure that you have created appropriate entries to disable
 them in the config file. Mixins should always be self-contained and grouped into "patch sets" which are easy to isolate,
-and where that is not possible, they should be placed into the "core" package.
+and where that is not possible, they should be placed into the "core" package.

build.gradle

@@ -80,6 +80,8 @@ dependencies {
     mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
     modImplementation "net.fabricmc:fabric-loader:${project.loader_version}"
 
+    modIncludeImplementation "com.lodborg:interval-tree:1.0.0"
+
     // Fabric API
     modIncludeImplementation(fabricApi.module("fabric-api-base", project.fabric_version))
     modIncludeImplementation(fabricApi.module("fabric-block-view-api-v2", project.fabric_version))

src/main/java/me/jellysquid/mods/sodium/client/gui/SodiumGameOptionPages.java

@@ -20,7 +20,6 @@
 import org.lwjgl.opengl.GL;
 import org.lwjgl.opengl.GLCapabilities;
 
-import javax.sound.sampled.BooleanControl;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -260,8 +259,7 @@ public static OptionPage performance() {
                         .setBinding((opts, value) -> opts.performance.alwaysDeferChunkUpdates = value, opts -> opts.performance.alwaysDeferChunkUpdates)
                         .setFlags(OptionFlag.REQUIRES_RENDERER_UPDATE)
                         .build())
-                .build()
-        );
+                .build());
 
         groups.add(OptionGroup.createBuilder()
                 .add(OptionImpl.createBuilder(boolean.class, sodiumOpts)
@@ -310,6 +308,17 @@ public static OptionPage performance() {
                         .build())
                 .build());
 
+        groups.add(OptionGroup.createBuilder()
+                .add(OptionImpl.createBuilder(SodiumGameOptions.SortBehavior.class, sodiumOpts)
+                        .setName(Text.translatable("sodium.options.sort_behavior.name"))
+                        .setTooltip(Text.translatable("sodium.options.sort_behavior.tooltip"))
+                        .setControl(option -> new CyclingControl<>(option, SodiumGameOptions.SortBehavior.class))
+                        .setBinding((opts, value) -> opts.performance.sortBehavior = value, opts -> opts.performance.sortBehavior)
+                        .setImpact(OptionImpact.MEDIUM)
+                        .setFlags(OptionFlag.REQUIRES_RENDERER_RELOAD)
+                        .build())
+                .build());
+
         return new OptionPage(Text.translatable("sodium.options.pages.performance"), ImmutableList.copyOf(groups));
     }
 

src/main/java/me/jellysquid/mods/sodium/client/gui/SodiumGameOptions.java

@@ -45,6 +45,25 @@ public static class PerformanceSettings {
         public boolean useFogOcclusion = true;
         public boolean useBlockFaceCulling = true;
         public boolean useNoErrorGLContext = true;
+
+        public SortBehavior sortBehavior = SortBehavior.DYNAMIC;
+    }
+
+    public enum SortBehavior implements TextProvider {
+        OFF("options.off"),
+        STATIC("options.clouds.fast"),
+        DYNAMIC("options.clouds.fancy");
+
+        private final Text name;
+
+        SortBehavior(String name) {
+            this.name = Text.translatable(name);
+        }
+
+        @Override
+        public Text getLocalizedName() {
+            return this.name;
+        }
     }
 
     public static class AdvancedSettings {

src/main/java/me/jellysquid/mods/sodium/client/model/quad/ModelQuad.java

@@ -5,7 +5,8 @@
 import static me.jellysquid.mods.sodium.client.util.ModelQuadUtil.*;
 
 /**
- * A simple implementation of the {@link ModelQuadViewMutable} interface which can provide an on-heap scratch area
+ * A simple implementation of the {@link ModelQuadViewMutable} interface which
+ * can provide an on-heap scratch area
  * for storing quad vertex data.
  */
 public class ModelQuad implements ModelQuadViewMutable {
@@ -15,6 +16,9 @@ public class ModelQuad implements ModelQuadViewMutable {
     private Sprite sprite;
     private int colorIdx;
     private int normal;
+    private int GFNINormX;
+    private int GFNINormY;
+    private int GFNINormZ;
 
     @Override
     public void setX(int idx, float x) {
@@ -120,4 +124,26 @@ public Sprite getSprite() {
     public int getNormal() {
         return this.normal;
     }
+
+    @Override
+    public int getGFNINormX() {
+        return this.GFNINormX;
+    }
+
+    @Override
+    public int getGFNINormY() {
+        return this.GFNINormY;
+    }
+
+    @Override
+    public int getGFNINormZ() {
+        return this.GFNINormZ;
+    }
+
+    @Override
+    public void setGFNINormal(int x, int y, int z) {
+        this.GFNINormX = x;
+        this.GFNINormY = y;
+        this.GFNINormZ = z;
+    }
 }

src/main/java/me/jellysquid/mods/sodium/client/model/quad/ModelQuadView.java

@@ -1,10 +1,13 @@
 package me.jellysquid.mods.sodium.client.model.quad;
 
 import me.jellysquid.mods.sodium.client.model.quad.properties.ModelQuadFlags;
+import me.jellysquid.mods.sodium.client.render.chunk.translucent_sorting.TranslucentSorting;
+import net.caffeinemc.mods.sodium.api.util.NormI8;
 import net.minecraft.client.texture.Sprite;
 
 /**
- * Provides a read-only view of a model quad. For mutable access to a model quad, see {@link ModelQuadViewMutable}.
+ * Provides a read-only view of a model quad. For mutable access to a model
+ * quad, see {@link ModelQuadViewMutable}.
  */
 public interface ModelQuadView {
     /**
@@ -38,7 +41,8 @@ public interface ModelQuadView {
     float getTexV(int idx);
 
     /**
-     * @return The integer bit flags containing the {@link ModelQuadFlags} for this quad
+     * @return The integer bit flags containing the {@link ModelQuadFlags} for this
+     *         quad
      */
     int getFlags();
 
@@ -57,6 +61,91 @@ public interface ModelQuadView {
      */
     int getNormal();
 
+    /**
+     * @return The x coordinate of the unit normal vector
+     */
+    int getGFNINormX();
+
+    /**
+     * @return The y coordinate of the unit normal vector
+     */
+    int getGFNINormY();
+
+    /**
+     * @return The z coordinate of the unit normal vector
+     */
+    int getGFNINormZ();
+
+    /**
+     * Sets an accurate normal vector for this quad. This is used for GFNI.
+     * 
+     * @param x The normal's x component
+     * @param y The normal's y component
+     * @param z The normal's z component
+     */
+    void setGFNINormal(int x, int y, int z);
+
+    default int calculateNormals(boolean calculateUnitNormal) {
+        final float x0 = getX(0);
+        final float y0 = getY(0);
+        final float z0 = getZ(0);
+
+        final float x1 = getX(1);
+        final float y1 = getY(1);
+        final float z1 = getZ(1);
+
+        final float x2 = getX(2);
+        final float y2 = getY(2);
+        final float z2 = getZ(2);
+
+        final float x3 = getX(3);
+        final float y3 = getY(3);
+        final float z3 = getZ(3);
+
+        final float dx0 = x2 - x0;
+        final float dy0 = y2 - y0;
+        final float dz0 = z2 - z0;
+        final float dx1 = x3 - x1;
+        final float dy1 = y3 - y1;
+        final float dz1 = z3 - z1;
+
+        float normX = dy0 * dz1 - dz0 * dy1;
+        float normY = dz0 * dx1 - dx0 * dz1;
+        float normZ = dx0 * dy1 - dy0 * dx1;
+
+        int packedNormal = -1;
+        if (calculateUnitNormal) {
+            // normalize by length for the packed normal
+            float length = (float) Math.sqrt(normX * normX + normY * normY + normZ * normZ);
+            if (length != 0.0 && length != 1.0) {
+                normX /= length;
+                normY /= length;
+                normZ /= length;
+            }
+
+            packedNormal = NormI8.pack(normX, normY, normZ);
+        }
+
+        // normalize onto the surface of a cube by dividing by the length of the longest
+        // component
+        float infNormLength = Math.max(Math.abs(normX), Math.max(Math.abs(normY), Math.abs(normZ)));
+        if (infNormLength != 0 && infNormLength != 1) {
+            normX /= infNormLength;
+            normY /= infNormLength;
+            normZ /= infNormLength;
+        }
+
+        // quantize the coordinates on the surface of the cube.
+        // in each axis the number of values is 2 * QUANTIZATION_FACTOR + 1.
+        // the total number of normals is the number of points on that cube's surface.
+        this.setGFNINormal(
+                (int) (normX * TranslucentSorting.QUANTIZATION_FACTOR),
+                (int) (normY * TranslucentSorting.QUANTIZATION_FACTOR),
+                (int) (normZ * TranslucentSorting.QUANTIZATION_FACTOR));
+
+        return packedNormal;
+    }
+
     default boolean hasColor() {
         return this.getColorIndex() != -1;
     }

src/main/java/me/jellysquid/mods/sodium/client/model/quad/properties/ModelQuadFacing.java

@@ -1,5 +1,8 @@
 package me.jellysquid.mods.sodium.client.model.quad.properties;
 
+import org.joml.Vector3f;
+import org.joml.Vector3fc;
+
 import net.minecraft.util.math.Direction;
 
 public enum ModelQuadFacing {
@@ -14,18 +17,31 @@ public enum ModelQuadFacing {
     public static final ModelQuadFacing[] VALUES = ModelQuadFacing.values();
 
     public static final int COUNT = VALUES.length;
+    public static final int DIRECTIONS = VALUES.length - 1;
 
     public static final int NONE = 0;
     public static final int ALL = (1 << COUNT) - 1;
 
+    public static final Vector3fc[] NORMALS = new Vector3fc[ModelQuadFacing.DIRECTIONS];
+
+    static {
+        for (int i = 0; i < ModelQuadFacing.DIRECTIONS; i++) {
+            NORMALS[i] = new Vector3f(ModelQuadFacing.VALUES[i].toDirection().getUnitVector());
+        }
+    }
+
+    public static final int OPPOSING_X = 1 << ModelQuadFacing.POS_X.ordinal() | 1 << ModelQuadFacing.NEG_X.ordinal();
+    public static final int OPPOSING_Y = 1 << ModelQuadFacing.POS_Y.ordinal() | 1 << ModelQuadFacing.NEG_Y.ordinal();
+    public static final int OPPOSING_Z = 1 << ModelQuadFacing.POS_Z.ordinal() | 1 << ModelQuadFacing.NEG_Z.ordinal();
+
     public static ModelQuadFacing fromDirection(Direction dir) {
         return switch (dir) {
-            case DOWN   -> NEG_Y;
-            case UP     -> POS_Y;
-            case NORTH  -> NEG_Z;
-            case SOUTH  -> POS_Z;
-            case WEST   -> NEG_X;
-            case EAST   -> POS_X;
+            case DOWN -> NEG_Y;
+            case UP -> POS_Y;
+            case NORTH -> NEG_Z;
+            case SOUTH -> POS_Z;
+            case WEST -> NEG_X;
+            case EAST -> POS_X;
         };
     }
 
@@ -40,4 +56,24 @@ public ModelQuadFacing getOpposite() {
             default -> UNASSIGNED;
         };
     }
+
+    public int getSign() {
+        return switch (this) {
+            case POS_Y, POS_X, POS_Z -> 1;
+            case NEG_Y, NEG_X, NEG_Z -> -1;
+            default -> 0;
+        };
+    }
+
+    public Direction toDirection() {
+        return switch (this) {
+            case POS_Y -> Direction.UP;
+            case NEG_Y -> Direction.DOWN;
+            case POS_X -> Direction.EAST;
+            case NEG_X -> Direction.WEST;
+            case POS_Z -> Direction.SOUTH;
+            case NEG_Z -> Direction.NORTH;
+            default -> Direction.UP;
+        };
+    }
 }