Light clean up

- Ensure section set returned by SectionTracker is Unmodifiable to avoid copy in LightUpdatedVisualStorage
- Do not recompute section set in ShaderLightVisualStorage if not dirty
- Fix BlockEntityStorage not clearing posLookup on recreation or invalidation
- Fix Storage.invalidate not clearing everything
- Inline TopLevelEmbeddedEnvironment and NestedEmbeddedEnvironment into AbstractEmbeddedEnvironment and rename to EmbeddedEnvironment
- Move some classes between packages
- Remove unused fields in EmbeddingUniforms
- Remove suffix on field names in BufferBindings
- Rename enqueueLightUpdateSection methods to onLightUpdate
- Rename SectionCollectorImpl to SectionTracker
- Rename classes, methods, fields, and parameters and edit javadoc and comments to match previously done renames, new renames, and other existing classes

common/src/api/java/dev/engine_room/flywheel/api/backend/Engine.java

@@ -62,13 +62,6 @@ public interface Engine {
 	 */
 	Vec3i renderOrigin();
 
-	/**
-	 * Free all resources associated with this engine.
-	 * <br>
-	 * This engine will not be used again after this method is called.
-	 */
-	void delete();
-
 	/**
 	 * Assign the set of sections that visuals have requested GPU light for.
 	 *
@@ -78,6 +71,13 @@ public interface Engine {
 	 */
 	void lightSections(LongSet sections);
 
+	/**
+	 * Free all resources associated with this engine.
+	 * <br>
+	 * This engine will not be used again after this method is called.
+	 */
+	void delete();
+
 	/**
 	 * A block to be rendered as a crumbling overlay.
 	 * @param progress The progress of the crumbling animation in the range [0, 10).

common/src/api/java/dev/engine_room/flywheel/api/visual/LightUpdatedVisual.java

@@ -9,16 +9,15 @@
  */
 public non-sealed interface LightUpdatedVisual extends SectionTrackedVisual {
 	/**
-	 * Called when a section this visual is contained in receives a light update.
+	 * Called when a section this visual is contained in receives a light update. It is not called
+	 * unconditionally after visual creation or {@link SectionCollector#sections}.
 	 *
 	 * <p>Even if multiple sections are updated at the same time, this method will only be called once.</p>
 	 *
 	 * <p>The implementation is free to parallelize calls to this method, as well as execute the plan
 	 * returned by {@link DynamicVisual#planFrame} simultaneously. It is safe to query/update light here,
 	 * but you must ensure proper synchronization if you want to mutate anything outside this visual or
 	 * anything that is also mutated within {@link DynamicVisual#planFrame}.</p>
-	 *
-	 * <p>This method not is invoked automatically after visual creation.</p>
 	 */
 	void updateLight(float partialTick);
 }

common/src/api/java/dev/engine_room/flywheel/api/visual/SectionTrackedVisual.java

@@ -6,15 +6,15 @@
 
 public sealed interface SectionTrackedVisual extends Visual permits ShaderLightVisual, LightUpdatedVisual {
 	/**
-	 * Set the section property object.
+	 * Set the section collector object.
 	 *
 	 * <p>This method is only called once, upon visual creation.
-	 * <br>If the property is assigned to in this method, the
+	 * <br>If the collector is invoked in this method, the
 	 * visual will immediately be tracked in the given sections.
 	 *
-	 * @param property The property.
+	 * @param collector The collector.
 	 */
-	void setSectionCollector(SectionCollector property);
+	void setSectionCollector(SectionCollector collector);
 
 	@ApiStatus.NonExtendable
 	interface SectionCollector {

common/src/api/java/dev/engine_room/flywheel/api/visual/Visual.java

@@ -6,6 +6,7 @@
  * @see DynamicVisual
  * @see TickableVisual
  * @see LightUpdatedVisual
+ * @see ShaderLightVisual
  */
 public interface Visual {
 	/**

common/src/backend/java/dev/engine_room/flywheel/backend/engine/embed/LightUpdateHolder.java → common/src/backend/java/dev/engine_room/flywheel/backend/LightUpdateHolder.java

@@ -1,7 +1,8 @@
-package dev.engine_room.flywheel.backend.engine.embed;
+package dev.engine_room.flywheel.backend;
 
 import dev.engine_room.flywheel.lib.util.LevelAttached;
 import it.unimi.dsi.fastutil.longs.LongArraySet;
+import it.unimi.dsi.fastutil.longs.LongOpenHashSet;
 import it.unimi.dsi.fastutil.longs.LongSet;
 import net.minecraft.world.level.LevelAccessor;
 
@@ -11,12 +12,15 @@
 public class LightUpdateHolder {
 	private static final LevelAttached<LightUpdateHolder> HOLDERS = new LevelAttached<>(level -> new LightUpdateHolder());
 
+	private final LongSet updatedSections = new LongOpenHashSet();
+
+	private LightUpdateHolder() {
+	}
+
 	public static LightUpdateHolder get(LevelAccessor level) {
 		return HOLDERS.get(level);
 	}
 
-	private final LongSet updatedSections = new LongArraySet();
-
 	public LongSet getAndClearUpdatedSections() {
 		if (updatedSections.isEmpty()) {
 			return LongSet.of();
@@ -30,7 +34,4 @@ public LongSet getAndClearUpdatedSections() {
 	public void add(long section) {
 		updatedSections.add(section);
 	}
-
-	private LightUpdateHolder() {
-	}
 }

common/src/backend/java/dev/engine_room/flywheel/backend/compile/component/SsboInstanceComponent.java

@@ -43,7 +43,7 @@ protected void generateUnpacking(GlslBuilder builder) {
 
 		fnBody.ret(GlslExpr.call(STRUCT_NAME, unpackArgs));
 
-		builder._addRaw("layout(std430, binding = " + BufferBindings.INSTANCE_BUFFER_BINDING + ") restrict readonly buffer InstanceBuffer {\n"
+		builder._addRaw("layout(std430, binding = " + BufferBindings.INSTANCE + ") restrict readonly buffer InstanceBuffer {\n"
 				+ "    uint _flw_instances[];\n"
 				+ "};");
 		builder.blankLine();

common/src/backend/java/dev/engine_room/flywheel/backend/engine/embed/Arena.java → common/src/backend/java/dev/engine_room/flywheel/backend/engine/Arena.java

@@ -1,4 +1,4 @@
-package dev.engine_room.flywheel.backend.engine.embed;
+package dev.engine_room.flywheel.backend.engine;
 
 import dev.engine_room.flywheel.lib.memory.MemoryBlock;
 import it.unimi.dsi.fastutil.ints.IntArrayList;

common/src/backend/java/dev/engine_room/flywheel/backend/engine/DrawManager.java

@@ -16,7 +16,6 @@
 import dev.engine_room.flywheel.api.model.Model;
 import dev.engine_room.flywheel.backend.FlwBackend;
 import dev.engine_room.flywheel.backend.engine.embed.Environment;
-import dev.engine_room.flywheel.backend.engine.embed.LightStorage;
 import dev.engine_room.flywheel.lib.util.Pair;
 import it.unimi.dsi.fastutil.ints.Int2ObjectArrayMap;
 import it.unimi.dsi.fastutil.ints.Int2ObjectMap;

common/src/backend/java/dev/engine_room/flywheel/backend/engine/EngineImpl.java

@@ -14,9 +14,9 @@
 import dev.engine_room.flywheel.api.task.TaskExecutor;
 import dev.engine_room.flywheel.api.visualization.VisualEmbedding;
 import dev.engine_room.flywheel.api.visualization.VisualizationContext;
+import dev.engine_room.flywheel.backend.engine.embed.EmbeddedEnvironment;
 import dev.engine_room.flywheel.backend.engine.embed.Environment;
-import dev.engine_room.flywheel.backend.engine.embed.LightStorage;
-import dev.engine_room.flywheel.backend.engine.embed.TopLevelEmbeddedEnvironment;
+import dev.engine_room.flywheel.backend.engine.embed.EnvironmentStorage;
 import dev.engine_room.flywheel.backend.engine.uniform.Uniforms;
 import dev.engine_room.flywheel.backend.gl.GlStateTracker;
 import dev.engine_room.flywheel.lib.task.Flag;
@@ -30,11 +30,11 @@
 import net.minecraft.world.phys.Vec3;
 
 public class EngineImpl implements Engine {
-	private final int sqrMaxOriginDistance;
 	private final DrawManager<? extends AbstractInstancer<?>> drawManager;
+	private final int sqrMaxOriginDistance;
+	private final Flag flushFlag = new NamedFlag("flushed");
 	private final EnvironmentStorage environmentStorage;
 	private final LightStorage lightStorage;
-	private final Flag flushFlag = new NamedFlag("flushed");
 
 	private BlockPos renderOrigin = BlockPos.ZERO;
 
@@ -45,6 +45,11 @@ public EngineImpl(LevelAccessor level, DrawManager<? extends AbstractInstancer<?
 		lightStorage = new LightStorage(level);
 	}
 
+	@Override
+	public VisualizationContext createVisualizationContext(RenderStage stage) {
+		return new VisualizationContextImpl(stage);
+	}
+
 	@Override
 	public Plan<RenderContext> createFramePlan() {
 		return lightStorage.createFramePlan()
@@ -69,11 +74,6 @@ public void renderCrumbling(TaskExecutor executor, RenderContext context, List<C
 		drawManager.renderCrumbling(crumblingBlocks);
 	}
 
-	@Override
-	public VisualizationContext createVisualizationContext(RenderStage stage) {
-		return new VisualizationContextImpl(stage);
-	}
-
 	@Override
 	public boolean updateRenderOrigin(Camera camera) {
 		Vec3 cameraPos = camera.getPosition();
@@ -97,14 +97,14 @@ public Vec3i renderOrigin() {
 	}
 
 	@Override
-	public void delete() {
-		drawManager.delete();
-		lightStorage.delete();
+	public void lightSections(LongSet sections) {
+		lightStorage.sections(sections);
 	}
 
 	@Override
-	public void lightSections(LongSet sections) {
-		lightStorage.sections(sections);
+	public void delete() {
+		drawManager.delete();
+		lightStorage.delete();
 	}
 
 	public <I extends Instance> Instancer<I> instancer(Environment environment, InstanceType<I> type, Model model, RenderStage stage) {
@@ -150,7 +150,7 @@ public Vec3i renderOrigin() {
 
 		@Override
 		public VisualEmbedding createEmbedding() {
-			var out = new TopLevelEmbeddedEnvironment(EngineImpl.this, stage);
+			var out = new EmbeddedEnvironment(EngineImpl.this, stage);
 			environmentStorage.track(out);
 			return out;
 		}

common/src/backend/java/dev/engine_room/flywheel/backend/engine/embed/LightLut.java → common/src/backend/java/dev/engine_room/flywheel/backend/engine/LightLut.java

@@ -1,4 +1,4 @@
-package dev.engine_room.flywheel.backend.engine.embed;
+package dev.engine_room.flywheel.backend.engine;
 
 import org.jetbrains.annotations.NotNull;
 
@@ -11,8 +11,8 @@
 import it.unimi.dsi.fastutil.objects.ReferenceArrayList;
 import net.minecraft.core.SectionPos;
 
-public class LightLut {
-	public static final LongComparator SECTION_X_THEN_Y_THEN_Z = (long a, long b) -> {
+public final class LightLut {
+	private static final LongComparator SECTION_X_THEN_Y_THEN_Z = (long a, long b) -> {
 		final var xComp = Integer.compare(SectionPos.x(a), SectionPos.x(b));
 		if (xComp != 0) {
 			return xComp;
@@ -24,6 +24,8 @@ public class LightLut {
 		return Integer.compare(SectionPos.z(a), SectionPos.z(b));
 	};
 
+	private LightLut() {
+	}
 
 	// Massive kudos to RogueLogix for figuring out this LUT scheme.
 	// TODO: switch to y x z or x z y ordering

common/src/backend/java/dev/engine_room/flywheel/backend/engine/embed/LightStorage.java → common/src/backend/java/dev/engine_room/flywheel/backend/engine/LightStorage.java

@@ -1,4 +1,4 @@
-package dev.engine_room.flywheel.backend.engine.embed;
+package dev.engine_room.flywheel.backend.engine;
 
 import java.util.BitSet;
 
@@ -7,6 +7,7 @@
 
 import dev.engine_room.flywheel.api.event.RenderContext;
 import dev.engine_room.flywheel.api.task.Plan;
+import dev.engine_room.flywheel.backend.LightUpdateHolder;
 import dev.engine_room.flywheel.backend.engine.indirect.StagingBuffer;
 import dev.engine_room.flywheel.backend.gl.buffer.GlBuffer;
 import dev.engine_room.flywheel.lib.task.SimplePlan;