[FabricMC#65] Renderer API + Indigo

fabric-renderer-api-v1/build.gradle

@@ -0,0 +1,6 @@
+archivesBaseName = "fabric-renderer-api-v1"
+version = getSubprojectVersion(project, "0.1.0")
+
+dependencies {
+	compile project(path: ':fabric-api-base', configuration: 'dev')
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/Renderer.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1;
+
+import net.fabricmc.fabric.api.renderer.v1.material.MaterialFinder;
+import net.fabricmc.fabric.api.renderer.v1.material.RenderMaterial;
+import net.fabricmc.fabric.api.renderer.v1.mesh.MeshBuilder;
+import net.minecraft.util.Identifier;
+
+/**
+ * Interface for rendering plug-ins that provide enhanced capabilities
+ * for model lighting, buffering and rendering. Such plug-ins implement the
+ * enhanced model rendering interfaces specified by the Fabric API.<p>
+ */
+public interface Renderer {
+    /**
+     * Obtain a new {@link MeshBuilder} instance used to create 
+     * baked models with enhanced features.<p>
+     * 
+     * Renderer does not retain a reference to returned instances and they should be re-used for 
+     * multiple models when possible to avoid memory allocation overhead.
+     */
+    MeshBuilder meshBuilder();
+
+    /**
+     * Obtain a new {@link MaterialFinder} instance used to retrieve
+     * standard {@link RenderMaterial} instances.<p>
+     * 
+     * Renderer does not retain a reference to returned instances and they should be re-used for 
+     * multiple materials when possible to avoid memory allocation overhead.
+     */
+    MaterialFinder materialFinder();
+
+    /**
+     * Return a material previously registered via {@link #registerMaterial(Identifier, RenderMaterial)}.
+     * Will return null if no material was found matching the given identifier.
+     */
+    RenderMaterial materialById(Identifier id);
+
+    /**
+     * Register a material for re-use by other mods or models within a mod.
+     * The registry does not persist registrations - mods must create and register 
+     * all materials at game initialization.<p>
+     * 
+     * Returns false if a material with the given identifier is already present,
+     * leaving the existing material intact.
+     */
+    boolean registerMaterial(Identifier id, RenderMaterial material);
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/RendererAccess.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1;
+
+import net.fabricmc.fabric.impl.renderer.RendererAccessImpl;
+
+/**
+ * Registration and access for rendering extensions.
+ */
+public interface RendererAccess {
+    RendererAccess INSTANCE = RendererAccessImpl.INSTANCE;
+
+    /**
+     * Rendering extension mods must implement {@link Renderer} and 
+     * call this method during initialization.<p>
+     * 
+     * Only one {@link Renderer} plug-in can be active in any game instance.
+     * If a second mod attempts to register this method will throw an UnsupportedOperationException.
+     */
+    void registerRenderer(Renderer plugin);
+
+    /**
+     * Access to the current {@link Renderer} for creating and retrieving model builders 
+     * and materials. Will return null if no render plug in is active.
+     */
+    Renderer getRenderer();
+
+    /**
+     * Performant test for {@link #getRenderer()} != null;
+     */
+    boolean hasRenderer();
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/material/MaterialFinder.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1.material;
+
+import net.fabricmc.fabric.api.renderer.v1.render.RenderContext;
+import net.fabricmc.fabric.api.renderer.v1.Renderer;
+import net.fabricmc.fabric.api.renderer.v1.mesh.QuadEmitter;
+import net.minecraft.block.Block;
+import net.minecraft.block.BlockRenderLayer;
+
+/**
+ * Finds standard {@link RenderMaterial} instances used to communicate
+ * quad rendering characteristics to a {@link RenderContext}.<p>
+ *
+ * Must be obtained via {@link Renderer#materialFinder()}.
+ */
+public interface MaterialFinder {
+    /**
+     * Returns the standard material encoding all
+     * of the current settings in this finder. The settings in
+     * this finder are not changed.<p>
+     * 
+     * Resulting instances can and should be re-used to prevent
+     * needless memory allocation. {@link Renderer} implementations
+     * may or may not cache standard material instances.
+     */
+    RenderMaterial find();
+
+    /**
+     * Resets this instance to default values. Values will match those
+     * in effect when an instance is newly obtained via {@link Renderer#materialFinder()}.
+     */
+    MaterialFinder clear();
+
+    /**
+     * 
+     * Reserved for future use.  Behavior for values > 1 is currently undefined.
+     */
+    MaterialFinder spriteDepth(int depth);
+
+    /**
+     * Defines how sprite pixels will be blended with the scene.
+     * Accepts {link @BlockRenderLayer} values and blending behavior
+     * will emulate the way that Minecraft renders each pass. But this does 
+     * NOT mean the sprite will be rendered in a specific render pass - some
+     * implementations may not use the standard Minecraft render passes.<p>
+     * 
+     * CAN be null and is null by default. A null value means the renderer
+     * will use {@link Block#getRenderLayer()} for the associate block, or
+     * {@link BlockRenderLayer#TRANSLUCENT} for item renders. (Normal Minecraft rendering)
+     */
+    MaterialFinder blendMode(int spriteIndex, BlockRenderLayer blendMode);
+
+    /**
+     * Vertex color(s) will be modified for quad color index unless disabled.<p>
+     */
+    MaterialFinder disableColorIndex(int spriteIndex, boolean disable);
+
+    /**
+     * Vertex color(s) will be modified for diffuse shading unless disabled.
+     */
+    MaterialFinder disableDiffuse(int spriteIndex, boolean disable);
+
+    /**
+     * Vertex color(s) will be modified for ambient occlusion unless disabled.
+     */
+    MaterialFinder disableAo(int spriteIndex, boolean disable);
+
+    /**
+     * When true, sprite texture and color will be rendered at full brightness.
+     * Lightmap values provided via {@link QuadEmitter#lightmap(int)} will be ignored.
+     * False by default<p>
+     * 
+     * This is the preferred method for emissive lighting effects.  Some renderers
+     * with advanced lighting models may not use block lightmaps and this method will
+     * allow per-sprite emissive lighting in future extensions that support overlay sprites.<p>
+     * 
+     * Note that color will still be modified by diffuse shading and ambient occlusion,
+     * unless disabled via {@link #disableAo(int, boolean)} and {@link #disableDiffuse(int, boolean)}.
+     */
+    MaterialFinder emissive(int spriteIndex, boolean isEmissive);
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/material/RenderMaterial.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1.material;
+
+import net.fabricmc.fabric.api.renderer.v1.Renderer;
+import net.fabricmc.fabric.api.renderer.v1.mesh.MeshBuilder;
+import net.fabricmc.fabric.api.renderer.v1.mesh.MutableQuadView;
+import net.minecraft.block.Block;
+import net.minecraft.util.Identifier;
+
+/**
+ * All model quads have an associated render material governing
+ * how the quad will be rendered.<p>
+ * 
+ * A material instance is always immutable and thread-safe.  References to a material 
+ * remain valid until the end of the current game session.<p>
+ * 
+ * Materials can be registered and shared between mods using {@link Renderer#registerMaterial(net.minecraft.util.Identifier, RenderMaterial)}.
+ * The registering mod is responsible for creating each registered material at startup.<p>
+ * 
+ * Materials are not required to know their registration identity, and two materials
+ * with the same attributes may or may not satisfy equality and identity tests. Model 
+ * implementations should never attempt to analyze materials or implement control logic based on them.
+ * They are only tokens for communicating quad attributes to the ModelRenderer.<p>
+ * 
+ * There are three classes of materials... <p>
+ * 
+ * <b>STANDARD MATERIALS</b><p>
+ * 
+ * Standard materials have "normal" rendering with control over lighting,
+ * color, and texture blending. In the default renderer, "normal" rendering
+ * emulates unmodified Minecraft. Other renderers may offer a different aesthetic.<p>
+ * 
+ * The number of standard materials is finite, but not necessarily small. 
+ * To find a standard material, use {@link Renderer#materialFinder()}.<p>
+ * 
+ * All renderer implementations should support standard materials.<p>
+ * 
+ * <b>SHADER MATERIALS</b><p>
+ * 
+ * Shader materials are standard materials with a vertex and fragment shader attached.
+ * The quad attributes for standard materials have standard vertex attribute bindings
+ * for cross-compatibility of shaders. Vertex colors will be modified (lit) by the 
+ * renderer before the vertex shader runs, unless lighting (AO and diffuse) has been
+ * disabled in the standard material.<p>
+ * 
+ * Shader materials do not have to implement any sort of "standard" render, and the quad
+ * vertex attributes can be re-purposed to fit the needs of the shader author.<p>
+ * 
+ * Shader materials are an optional {@link Renderer} feature.
+ * {@link Renderer#shaderManager()} will return null if shaders are unsupported.<p>
+ * 
+ * <b>SPECIAL MATERIALS</b><p>
+ * 
+ * Special materials are implemented directly by the Renderer implementation, typically
+ * with the aim of providing advanced/extended features. Such materials may offer additional
+ * vertex attributes via extensions to {@link MeshBuilder} and {@link MutableQuadView}.<p>
+ * 
+ * Special materials can be obtained using {@link Renderer#materialById(Identifier)}
+ * with a known identifier. Renderers may provide other means of access. Popular 
+ * special materials could be implemented by multiple renderers, however there is 
+ * no requirement that special materials be cross-compatible.
+ */
+public interface RenderMaterial {
+    /**
+     * This will be identical to the material that would be obtained by calling {@link MaterialFinder#find()}
+     * on a new, unaltered, {@link MaterialFinder} instance.  It is defined here for clarity and convenience.
+     * 
+     * Quads using this material use {@link Block#getRenderLayer()} of the associated block to determine texture blending, 
+     * honor block color index, are non-emissive, and apply both diffuse and ambient occlusion shading to vertex colors.<p>
+     * 
+     * All standard, non-fluid baked models are rendered using this material.
+     */
+    Identifier MATERIAL_STANDARD = new Identifier("fabric", "standard");
+
+    /**
+     * How many sprite color/uv coordinates are in the material. 
+     * Behavior for values > 1 is currently undefined.
+     * See {@link MaterialFinder#spriteDepth(int)}
+     */
+    int spriteDepth();
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/mesh/Mesh.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1.mesh;
+
+import java.util.function.Consumer;
+
+import net.fabricmc.fabric.api.renderer.v1.Renderer;
+
+/**
+ * A bundle of one or more {@link QuadView} instances encoded by the renderer,
+ * typically via {@link Renderer#meshBuilder()}.<p>
+ * 
+ * Similar in purpose to the List<BakedQuad> instances returned by BakedModel, but 
+ * affords the renderer the ability to optimize the format for performance
+ * and memory allocation.<p>
+ * 
+ * Only the renderer should implement or extend this interface.
+ */
+public interface Mesh {
+    /**
+     * Use to access all of the quads encoded in this mesh. The quad instances
+     * sent to the consumer will likely be threadlocal/reused and should never
+     * be retained by the consumer.
+     */
+    public void forEach(Consumer<QuadView> consumer);
+}

fabric-renderer-api-v1/src/main/java/net/fabricmc/fabric/api/renderer/v1/mesh/MeshBuilder.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.renderer.v1.mesh;
+
+import net.minecraft.client.render.BufferBuilder;
+
+/**
+ * Similar in purpose to {@link BufferBuilder} but simpler
+ * and not tied to NIO or any other specific implementation,
+ * plus designed to handle both static and dynamic building.<p>
+ * 
+ * Decouples models from the vertex format(s) used by
+ * ModelRenderer to allow compatibility across diverse implementations.<p>
+ */
+public interface MeshBuilder {
+    /**
+     * Returns the {@link QuadEmitter} used to append quad to this mesh. 
+     * Calling this method a second time invalidates any prior result.
+     * Do not retain references outside the context of building the mesh.
+     */
+    QuadEmitter getEmitter();
+
+    /**
+     * Returns a new {@link Mesh} instance containing all
+     * quads added to this builder and resets the builder to an empty state<p>
+     */
+    Mesh build();
+}