Formalize most public API (#253)

* Start on general API formalization

* More API improvements

- Add Engine#onLightUpdate; remove LightUpdateHolder and backend/ClientChunkCacheMixin
- Add Effect#level
- Add VisualizationHelper#queueAdd and #queueRemove for Effects
- Fix PartialModel not assigning bakedModel field when populating on init
- Fix PartialModel.ALL using weak keys instead of weak values
- Make Simple*Visualizer and corresponding inner Builder classes final
- Restore FlatLit#light overload that accepts block and sky light values separately
- Add AbstractBlockEntityVisual#relight overloads that accept Iterator and Iterable
- Reorganize classes in impl.vizualization

* TaskExecutor simplification

- Move TaskExecutor#sync* methods to TaskExecutorImpl
- Move Flag and RaisePlan to impl
- Remove TaskExecutor#scheduleForMainThread and #isMainThread methods
- Remove SyncedPlan
- Add Engine#setupRender
- Remove TaskExecutor parameters from Engine#render* methods
- Convert Engine$CrumblingBlock into an interface
- Unmark RenderContext as NonExtendable to allow fulfilling the purpose described in the doc of VisualizationManager#renderDispatcher

* Remove registry freeze callbacks

- Lazily initialize MaterialShaderIndices
- Rename MaterialShaders#*Shader to #*Source
- Move BackendImplemented to api.backend package

common/src/api/java/dev/engine_room/flywheel/api/event/RenderContext.java → common/src/api/java/dev/engine_room/flywheel/api/RenderContext.java

@@ -1,7 +1,6 @@
-package dev.engine_room.flywheel.api.event;
+package dev.engine_room.flywheel.api;
 
-import org.jetbrains.annotations.ApiStatus;
-import org.joml.Matrix4f;
+import org.joml.Matrix4fc;
 
 import com.mojang.blaze3d.vertex.PoseStack;
 
@@ -10,7 +9,6 @@
 import net.minecraft.client.renderer.LevelRenderer;
 import net.minecraft.client.renderer.RenderBuffers;
 
-@ApiStatus.NonExtendable
 public interface RenderContext {
 	LevelRenderer renderer();
 
@@ -20,9 +18,9 @@ public interface RenderContext {
 
 	PoseStack stack();
 
-	Matrix4f projection();
+	Matrix4fc projection();
 
-	Matrix4f viewProjection();
+	Matrix4fc viewProjection();
 
 	Camera camera();
 

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

@@ -1,13 +1,12 @@
 package dev.engine_room.flywheel.api.backend;
 
-import dev.engine_room.flywheel.api.BackendImplemented;
 import dev.engine_room.flywheel.api.internal.FlwApiLink;
 import dev.engine_room.flywheel.api.registry.IdRegistry;
 import net.minecraft.world.level.LevelAccessor;
 
 @BackendImplemented
 public interface Backend {
-	static IdRegistry<Backend> REGISTRY = FlwApiLink.INSTANCE.createIdRegistry();
+	IdRegistry<Backend> REGISTRY = FlwApiLink.INSTANCE.createIdRegistry();
 
 	/**
 	 * Create a new engine instance.

common/src/api/java/dev/engine_room/flywheel/api/BackendImplemented.java → common/src/api/java/dev/engine_room/flywheel/api/backend/BackendImplemented.java

@@ -1,4 +1,4 @@
-package dev.engine_room.flywheel.api;
+package dev.engine_room.flywheel.api.backend;
 
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;

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

@@ -9,19 +9,19 @@ private BackendManager() {
 	/**
 	 * Get the current backend.
 	 */
-	public static Backend getBackend() {
-		return FlwApiLink.INSTANCE.getBackend();
+	public static Backend currentBackend() {
+		return FlwApiLink.INSTANCE.getCurrentBackend();
 	}
 
 	public static boolean isBackendOn() {
 		return FlwApiLink.INSTANCE.isBackendOn();
 	}
 
-	public static Backend getOffBackend() {
+	public static Backend offBackend() {
 		return FlwApiLink.INSTANCE.getOffBackend();
 	}
 
-	public static Backend getDefaultBackend() {
+	public static Backend defaultBackend() {
 		return FlwApiLink.INSTANCE.getDefaultBackend();
 	}
 }

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

@@ -2,52 +2,43 @@
 
 import java.util.List;
 
-import dev.engine_room.flywheel.api.BackendImplemented;
-import dev.engine_room.flywheel.api.event.RenderContext;
-import dev.engine_room.flywheel.api.event.RenderStage;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Range;
+
+import dev.engine_room.flywheel.api.RenderContext;
 import dev.engine_room.flywheel.api.instance.Instance;
 import dev.engine_room.flywheel.api.task.Plan;
-import dev.engine_room.flywheel.api.task.TaskExecutor;
+import dev.engine_room.flywheel.api.visualization.VisualType;
 import dev.engine_room.flywheel.api.visualization.VisualizationContext;
 import it.unimi.dsi.fastutil.longs.LongSet;
 import net.minecraft.client.Camera;
 import net.minecraft.core.BlockPos;
+import net.minecraft.core.SectionPos;
 import net.minecraft.core.Vec3i;
+import net.minecraft.world.level.LightLayer;
 
 @BackendImplemented
 public interface Engine {
 	/**
-	 * Create a visualization context that will render to the given stage.
+	 * Create a visualization context that will be used to create visuals of the given type.
 	 *
-	 * @param stage The stage to render to.
+	 * @param visualType The type of visual.
 	 * @return A new visualization context.
 	 */
-	VisualizationContext createVisualizationContext(RenderStage stage);
+	VisualizationContext createVisualizationContext(VisualType visualType);
 
 	/**
-	 * Create a plan that will be executed every frame.
+	 * Create a plan that will start execution after the start of the level render and
+	 * finish execution before {@link #setupRender} is called.
+	 *
 	 * @return A new plan.
 	 */
 	Plan<RenderContext> createFramePlan();
 
 	/**
-	 * Render all instances necessary for the given stage.
-	 * @param executor The task executor running the frame plan.
-	 * @param context The render context for this frame.
-	 * @param stage The stage to render.
-	 */
-	void renderStage(TaskExecutor executor, RenderContext context, RenderStage stage);
-
-	/**
-	 * Render the given instances as a crumbling overlay.
-	 * <br>
-	 * This is guaranteed to be called between the first and last calls to {@link #renderStage} for the current frame.
-	 *
-	 * @param executor        The task executor running the frame plan.
-	 * @param context         The render context for this frame.
-	 * @param crumblingBlocks The instances to render. This list is never empty.
+	 * @return The current render origin.
 	 */
-	void renderCrumbling(TaskExecutor executor, RenderContext context, List<CrumblingBlock> crumblingBlocks);
+	Vec3i renderOrigin();
 
 	/**
 	 * Maintain the render origin to be within a certain distance from the camera in all directions,
@@ -57,11 +48,6 @@ public interface Engine {
 	 */
 	boolean updateRenderOrigin(Camera camera);
 
-	/**
-	 * @return The current render origin.
-	 */
-	Vec3i renderOrigin();
-
 	/**
 	 * Assign the set of sections that visuals have requested GPU light for.
 	 *
@@ -71,19 +57,70 @@ public interface Engine {
 	 */
 	void lightSections(LongSet sections);
 
+	void onLightUpdate(SectionPos sectionPos, LightLayer layer);
+
+	/**
+	 * Set up rendering for the current level render.
+	 *
+	 * <p>This method is guaranteed to be called after
+	 * {@linkplain #createFramePlan() the frame plan} has finished execution and before
+	 * {@link #render} and {@link #renderCrumbling} are called. This method is guaranteed to
+	 * be called on the render thread.
+	 *
+	 * @param context The context for the current level render.
+	 */
+	void setupRender(RenderContext context);
+
+	/**
+	 * Render all instances necessary for the given visual type.
+	 *
+	 * <p>This method is guaranteed to be called after {@link #setupRender} for the current
+	 * level render. This method is guaranteed to be called on the render thread.
+	 *
+	 * @param context The context for the current level render.
+	 * @param visualType The type of visual.
+	 */
+	void render(RenderContext context, VisualType visualType);
+
+	/**
+	 * Render the given instances as a crumbling overlay.
+	 *
+	 * <p>This method is guaranteed to be called after {@link #setupRender} for the current
+	 * level render. This method is guaranteed to be called on the render thread.
+	 *
+	 * @param context The context for the current level render.
+	 * @param crumblingBlocks The instances to render. This list is never empty.
+	 */
+	void renderCrumbling(RenderContext context, List<CrumblingBlock> crumblingBlocks);
+
 	/**
 	 * Free all resources associated with this engine.
-	 * <br>
-	 * This engine will not be used again after this method is called.
+	 *
+	 * <p>This engine will not be used again after this method is called.
+	 *
+	 * <p>This method is guaranteed to be called on the render thread.
 	 */
 	void delete();
 
 	/**
 	 * A block to be rendered as a crumbling overlay.
-	 * @param progress The progress of the crumbling animation in the range [0, 10).
-	 * @param pos The position of the block.
-	 * @param instances The instances associated with the BE at this position.
 	 */
-	record CrumblingBlock(int progress, BlockPos pos, List<Instance> instances) {
+	@ApiStatus.NonExtendable
+	interface CrumblingBlock {
+		/**
+		 * The position of the block.
+		 */
+		BlockPos pos();
+
+		/**
+		 * The progress of the crumbling animation in the range [0, 10).
+		 */
+		@Range(from = 0, to = 9)
+		int progress();
+
+		/**
+		 * The instances associated with the block entity visual at this position.
+		 */
+		List<Instance> instances();
 	}
 }

common/src/api/java/dev/engine_room/flywheel/api/instance/Instance.java

@@ -5,11 +5,11 @@ public interface Instance {
 
 	InstanceHandle handle();
 
-	default void delete() {
-		handle().setDeleted();
-	}
-
 	default void setChanged() {
 		handle().setChanged();
 	}
+
+	default void delete() {
+		handle().setDeleted();
+	}
 }

common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceHandle.java

@@ -1,6 +1,6 @@
 package dev.engine_room.flywheel.api.instance;
 
-import dev.engine_room.flywheel.api.BackendImplemented;
+import dev.engine_room.flywheel.api.backend.BackendImplemented;
 
 @BackendImplemented
 public interface InstanceHandle {

common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceType.java

@@ -11,7 +11,7 @@
  * @param <I> The java representation of the instance.
  */
 public interface InstanceType<I extends Instance> {
-	static Registry<InstanceType<?>> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
+	Registry<InstanceType<?>> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
 
 	/**
 	 * @param handle A handle that allows you to mark the instance as dirty or deleted.

common/src/api/java/dev/engine_room/flywheel/api/instance/Instancer.java

@@ -2,7 +2,7 @@
 
 import org.jetbrains.annotations.Nullable;
 
-import dev.engine_room.flywheel.api.BackendImplemented;
+import dev.engine_room.flywheel.api.backend.BackendImplemented;
 
 /**
  * An instancer is how you interact with an instanced model.
@@ -29,6 +29,17 @@ public interface Instancer<I extends Instance> {
 	 */
 	I createInstance();
 
+	/**
+	 * Populate arr with new instances of this model.
+	 *
+	 * @param arr An array to fill.
+	 */
+	default void createInstances(I[] arr) {
+		for (int i = 0; i < arr.length; i++) {
+			arr[i] = createInstance();
+		}
+	}
+
 	/**
 	 * Steal an instance from another instancer.
 	 * <br>
@@ -43,15 +54,4 @@ public interface Instancer<I extends Instance> {
 	 * @param instance The instance to steal.
 	 */
 	void stealInstance(@Nullable I instance);
-
-	/**
-	 * Populate arr with new instances of this model.
-	 *
-	 * @param arr An array to fill.
-	 */
-	default void createInstances(I[] arr) {
-		for (int i = 0; i < arr.length; i++) {
-			arr[i] = createInstance();
-		}
-	}
 }

common/src/api/java/dev/engine_room/flywheel/api/instance/InstancerProvider.java

@@ -1,6 +1,6 @@
 package dev.engine_room.flywheel.api.instance;
 
-import dev.engine_room.flywheel.api.BackendImplemented;
+import dev.engine_room.flywheel.api.backend.BackendImplemented;
 import dev.engine_room.flywheel.api.model.Model;
 
 @BackendImplemented

common/src/api/java/dev/engine_room/flywheel/api/internal/FlwApiLink.java

@@ -22,7 +22,7 @@ public interface FlwApiLink {
 
 	<T> IdRegistry<T> createIdRegistry();
 
-	Backend getBackend();
+	Backend getCurrentBackend();
 
 	boolean isBackendOn();
 

common/src/api/java/dev/engine_room/flywheel/api/material/CutoutShader.java

@@ -5,7 +5,7 @@
 import net.minecraft.resources.ResourceLocation;
 
 public interface CutoutShader {
-	static Registry<CutoutShader> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
+	Registry<CutoutShader> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
 
 	ResourceLocation source();
 }

common/src/api/java/dev/engine_room/flywheel/api/material/FogShader.java

@@ -5,7 +5,7 @@
 import net.minecraft.resources.ResourceLocation;
 
 public interface FogShader {
-	static Registry<FogShader> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
+	Registry<FogShader> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
 
 	ResourceLocation source();
 }

common/src/api/java/dev/engine_room/flywheel/api/material/MaterialShaders.java

@@ -5,9 +5,9 @@
 import net.minecraft.resources.ResourceLocation;
 
 public interface MaterialShaders {
-	static Registry<MaterialShaders> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
+	Registry<MaterialShaders> REGISTRY = FlwApiLink.INSTANCE.createRegistry();
 
-	ResourceLocation vertexShader();
+	ResourceLocation vertexSource();
 
-	ResourceLocation fragmentShader();
+	ResourceLocation fragmentSource();
 }

common/src/api/java/dev/engine_room/flywheel/api/model/Mesh.java

@@ -31,9 +31,4 @@ public interface Mesh {
 	 * @return A vec4 view.
 	 */
 	Vector4fc boundingSphere();
-
-	/**
-	 * Free this mesh's resources, memory, etc.
-	 */
-	void delete();
 }