From b379be57ae16d508dd2215d1ab2cffc90c588799 Mon Sep 17 00:00:00 2001 From: Jozufozu Date: Mon, 6 Jan 2025 22:03:43 -0800 Subject: [PATCH] Make explicit the implicit - Add @apiNotes explaining that flywheel/ is prepended to each shader ResourceLocation's path - Document all InstanceType fields --- .../flywheel/api/instance/InstanceType.java | 37 +++++++++++++++++++ .../flywheel/api/material/CutoutShader.java | 6 +++ .../flywheel/api/material/FogShader.java | 6 +++ .../flywheel/api/material/LightShader.java | 6 +++ .../api/material/MaterialShaders.java | 9 +++++ 5 files changed, 64 insertions(+) diff --git a/common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceType.java b/common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceType.java index 1fd1c475e..fd5c726b1 100644 --- a/common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceType.java +++ b/common/src/api/java/dev/engine_room/flywheel/api/instance/InstanceType.java @@ -15,11 +15,48 @@ public interface InstanceType { */ I create(InstanceHandle handle); + /** + * The native memory layout of this instance type. + * + *

This layout determines what fields are made available to the instance type's shaders + * as well as determining how the fields are arranged in memory. + * + * @return The layout of this instance type. + */ Layout layout(); + /** + * The writer of this instance type. + * + *

The writer of an InstanceType is responsible for translating java instance objects + * into contiguous native memory. The instance writer must write to the given pointer + * according to the layout of this instance type. + * + *

It is undefined behavior to write outside the half closed range + * {@code [ptr, ptr + layout().byteSize())}. + * + * @return The writer for this instance type. + */ InstanceWriter writer(); + /** + *

The vertex shader of an InstanceType is responsible for transforming vertices from mesh + * space to world space in whatever way the instance type requires. + * + * @return The vertex shader for this instance type. + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation vertexShader(); + /** + * The cull shader of this instance type. + * + *

The cull shader of an InstanceType is responsible for transforming bounding spheres from mesh + * space to world space, such that a mesh contained by the input bounding sphere and transformed + * by the vertex shader would be contained by the output bounding sphere. + * + * @return The cull shader for this instance type. + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation cullShader(); } diff --git a/common/src/api/java/dev/engine_room/flywheel/api/material/CutoutShader.java b/common/src/api/java/dev/engine_room/flywheel/api/material/CutoutShader.java index b45cd5432..d98910cd5 100644 --- a/common/src/api/java/dev/engine_room/flywheel/api/material/CutoutShader.java +++ b/common/src/api/java/dev/engine_room/flywheel/api/material/CutoutShader.java @@ -2,6 +2,12 @@ package dev.engine_room.flywheel.api.material; import net.minecraft.resources.ResourceLocation; +/** + * A shader that decides what colors should be discarded in the fragment shader. + */ public interface CutoutShader { + /** + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation source(); } diff --git a/common/src/api/java/dev/engine_room/flywheel/api/material/FogShader.java b/common/src/api/java/dev/engine_room/flywheel/api/material/FogShader.java index 9242d6990..9a77a873a 100644 --- a/common/src/api/java/dev/engine_room/flywheel/api/material/FogShader.java +++ b/common/src/api/java/dev/engine_room/flywheel/api/material/FogShader.java @@ -2,6 +2,12 @@ package dev.engine_room.flywheel.api.material; import net.minecraft.resources.ResourceLocation; +/** + * A shader that controls the fog effect on a material. + */ public interface FogShader { + /** + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation source(); } diff --git a/common/src/api/java/dev/engine_room/flywheel/api/material/LightShader.java b/common/src/api/java/dev/engine_room/flywheel/api/material/LightShader.java index 683be4674..977d16764 100644 --- a/common/src/api/java/dev/engine_room/flywheel/api/material/LightShader.java +++ b/common/src/api/java/dev/engine_room/flywheel/api/material/LightShader.java @@ -2,6 +2,12 @@ package dev.engine_room.flywheel.api.material; import net.minecraft.resources.ResourceLocation; +/** + * A shader that controls the GPU-based light on a material. + */ public interface LightShader { + /** + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation source(); } diff --git a/common/src/api/java/dev/engine_room/flywheel/api/material/MaterialShaders.java b/common/src/api/java/dev/engine_room/flywheel/api/material/MaterialShaders.java index 4cc566e2e..bb8dc76ad 100644 --- a/common/src/api/java/dev/engine_room/flywheel/api/material/MaterialShaders.java +++ b/common/src/api/java/dev/engine_room/flywheel/api/material/MaterialShaders.java @@ -2,8 +2,17 @@ package dev.engine_room.flywheel.api.material; import net.minecraft.resources.ResourceLocation; +/** + * A vertex and fragment shader pair that can be attached to a material. + */ public interface MaterialShaders { + /** + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation vertexSource(); + /** + * @apiNote {@code flywheel/} is implicitly prepended to the {@link ResourceLocation}'s path. + */ ResourceLocation fragmentSource(); }