Fabric Rendering API

src/main/java/net/fabricmc/fabric/api/client/model/fabric/DynamicModelBlockEntity.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2016, 2017, 2018 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.client.model.fabric;
+
+import net.minecraft.block.entity.BlockEntity;
+
+/**
+ * Interface for {@link BlockEntity}s which provide dynamic model state data.<p>
+ *
+ * Dynamic model state data is separate from BlockState, and will be
+ * cached during render chunk building on the main thread (safely) and accessible
+ * during chunk rendering on non-main threads.<p>
+ *
+ * For this reason, please ensure that all accesses to the passed model data are
+ * thread-safe. This can be achieved by, for example, passing a pre-generated
+ * immutable object, or ensuring all gets performed on the passed object are atomic
+ * and well-checked for unusual states.<p>
+ */
+@FunctionalInterface
+public interface DynamicModelBlockEntity {
+    /**
+     * @return The model state data provided by this block entity. Can be null.
+     */
+    Object getDynamicModelData();
+}

src/main/java/net/fabricmc/fabric/api/client/model/fabric/FabricBakedModel.java

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 2016, 2017, 2018 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.client.model.fabric;
+
+import java.util.Random;
+import java.util.function.Supplier;
+
+import net.minecraft.block.BlockState;
+import net.minecraft.client.render.block.BlockModelRenderer;
+import net.minecraft.client.render.model.BakedModel;
+import net.minecraft.item.ItemStack;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.world.ExtendedBlockView;
+
+/**
+ * Interface for baked models that output meshes with enhanced rendering features.
+ * Can also be used to generate or customize outputs based on world state instead of
+ * or in addition to block state when render chunks are rebuilt.<p>
+ * 
+ * Note for {@link Renderer} implementors: Fabric causes BakedModel to extend this
+ * interface with {@link #isVanilla()} == true and to produce standard vertex data. 
+ * This means any BakedModel instance can be safely cast to this interface without an instanceof check.
+ */
+public interface FabricBakedModel {
+    /**
+     * When true, signals renderer this producer is implemented through {@link BakedModel#getQuads(BlockState, net.minecraft.util.math.Direction, Random)}.
+     * Also means the model does not rely on any non-vanilla features. 
+     * Allows the renderer to optimize or route vanilla models through the unmodified vanilla pipeline if desired.<p>
+
+     * Fabric overrides to true for vanilla baked models.  
+     * Enhanced models that use this API should return false,
+     * otherwise the API will not recognize the model.<p>
+     */
+    boolean isVanillaAdapter(); 
+
+    /**
+     * This method will be called during chunk rebuilds to generate both the static and
+     * dynamic portions of a block model when the model implements this interface and
+     * {@link #isVanilla()} returns false. <p>
+     * 
+     * During chunk rebuild, this method will always be called exactly one time per block
+     * position, irrespective of which or how many faces or block render layers are included 
+     * in the model. Models must output all quads/meshes in a single pass.<p>
+     * 
+     * Also called to render block models outside of chunk rebuild or block entity rendering.
+     * Typically this happens when the block is being rendered as an entity, not as a block placed in the world.
+     * Currently this happens for falling blocks and blocks being pushed by a piston, but renderers
+     * should invoke this for all calls to {@link BlockModelRenderer#tesselate(ExtendedBlockView, BakedModel, BlockState, BlockPos, net.minecraft.client.render.BufferBuilder, boolean, Random, long)}
+     * that occur outside of chunk rebuilds to allow for features added by mods, unless 
+     * {@link #isVanilla()} returns true.<p>
+     * 
+     * Outside of chunk rebuilds, this method will be called every frame. Model implementations should 
+     * rely on pre-baked meshes as much as possible and keep transformation to a minimum.  The provided 
+     * block position may be the <em>nearest</em> block position and not actual. For this reason, neighbor
+     * state lookups are best avoided or will require special handling. Block entity lookups are 
+     * likely to fail and/or give meaningless results.<p>
+     * 
+     * In all cases, renderer will handle face occlusion and filter quads on faces obscured by 
+     * neighboring blocks (if appropriate).  Models only need to consider "sides" to the
+     * extent the model is driven by connection with neighbor blocks or other world state.<p>
+     * 
+     * Note: with {@link BakedModel#getQuads(BlockState, net.minecraft.util.math.Direction, Random)}, the random 
+     * parameter is normally initialized with the same seed prior to each face layer.
+     * Model authors should note this method is called only once per block, and call the provided
+     * Random supplier multiple times if re-seeding is necessary. For wrapped vanilla baked models, 
+     * it will probably be easier to use {@link RenderContext#fallbackModelConsumer()} which handles
+     * re-seeding per face automatically.<p>
+     * 
+     * @param Access to world state. Using {@link TerrainBlockView#getCachedRenderData(BlockPos)} to
+     * retrieve block entity state unless thread safety can be guaranteed.
+     * @param safeBlockEntityAccessor Thread-safe access to block entity data 
+     * @param state Block state for model being rendered.
+     * @param pos Position of block for model being rendered.
+     * @param randomSupplier  Random object seeded per vanilla conventions. Call multiple times to re-seed.
+     * The randomeSupplier will not be thread-safe. Do not cache or retain a reference.
+     * @param context Accepts model output.
+     */
+    void emitBlockQuads(TerrainBlockView blockView, BlockState state, BlockPos pos, Supplier<Random> randomSupplier, RenderContext context);
+
+    /**
+     * This method will be called during item rendering to generate both the static and
+     * dynamic portions of an item model when the model implements this interface and
+     * {@link #isVanilla()} returns false.<p>
+     * 
+     * Vanilla item rendering is normally very limited. It ignores lightmaps, vertex colors,
+     * and vertex normals. Renderers are expected to implement enhanced features for item 
+     * models. If a feature is impractical due to performance or other concerns, then the
+     * renderer must at least give acceptable visual results without the need for special-
+     * case handling in model implementations.<p>
+     * 
+     * Calls to this method will generally happen on the main client thread but nothing 
+     * prevents a mod or renderer from calling this method concurrently. Implementations 
+     * should not mutate the ItemStack parameter, and best practice will be to make the 
+     * method thread-safe.<p>
+     * 
+     * Implementing this method does NOT mitigate the need to implement a functional 
+     * {@link BakedModel#getItemPropertyOverrides()} method, because this method will be called 
+     * on the <em>result</em> of  {@link #getItemPropertyOverrides()}.  However, that 
+     * method can simply return the base model because the output from this method will
+     * be used for rendering.<p>
+     * 
+     * Renderer implementations should also use this method to obtain the quads used
+     * for item enchantment glint rendering.  This means models can put geometric variation
+     * logic here, instead of returning every possible shape from {@link #getItemPropertyOverrides()}
+     * as vanilla baked models.
+     */
+    void emitItemQuads(ItemStack stack, Supplier<Random> randomSupplier, RenderContext context);
+}

src/main/java/net/fabricmc/fabric/api/client/model/fabric/ForwardingBakedModel.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2016, 2017, 2018 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.client.model.fabric;
+
+import java.util.List;
+import java.util.Random;
+import java.util.function.Supplier;
+
+import net.fabricmc.fabric.impl.client.model.DamageModel;
+import net.minecraft.block.BlockState;
+import net.minecraft.client.render.model.BakedModel;
+import net.minecraft.client.render.model.BakedQuad;
+import net.minecraft.client.render.model.json.ModelItemPropertyOverrideList;
+import net.minecraft.client.render.model.json.ModelTransformation;
+import net.minecraft.client.texture.Sprite;
+import net.minecraft.item.ItemStack;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.util.math.Direction;
+
+/**
+ * Base class for specialized model implementations that need to wrap other baked models.
+ * Avoids boilerplate code for pass-through methods. For example usage see {@link DamageModel}.
+ */
+public abstract class ForwardingBakedModel implements BakedModel, FabricBakedModel {
+    /** implementations must set this somehow */
+    protected BakedModel wrapped;
+
+    @Override
+    public void emitBlockQuads(TerrainBlockView blockView, BlockState state, BlockPos pos, Supplier<Random> randomSupplier, RenderContext context) {
+        ((FabricBakedModel)wrapped).emitBlockQuads(blockView, state, pos, randomSupplier, context);
+    }
+
+    @Override
+    public boolean isVanillaAdapter() {
+        return ((FabricBakedModel)wrapped).isVanillaAdapter();
+    }
+
+    @Override
+    public void emitItemQuads(ItemStack stack, Supplier<Random> randomSupplier, RenderContext context) {
+        ((FabricBakedModel)wrapped).emitItemQuads(stack, randomSupplier, context);
+    }
+
+    @Override
+    public List<BakedQuad> getQuads(BlockState blockState, Direction face, Random rand) {
+        return wrapped.getQuads(blockState, face, rand);
+    }
+
+    @Override
+    public boolean useAmbientOcclusion() {
+        return wrapped.useAmbientOcclusion();
+    }
+
+    @Override
+    public boolean hasDepthInGui() {
+        return wrapped.hasDepthInGui();
+    }
+
+    @Override
+    public boolean isBuiltin() {
+        return wrapped.isBuiltin();
+    }
+
+    @Override
+    public Sprite getSprite() {
+        return wrapped.getSprite();
+    }
+
+    @Override
+    public ModelTransformation getTransformation() {
+        return wrapped.getTransformation();
+    }
+
+    @Override
+    public ModelItemPropertyOverrideList getItemPropertyOverrides() {
+        return wrapped.getItemPropertyOverrides();
+    }
+}

src/main/java/net/fabricmc/fabric/api/client/model/fabric/MaterialFinder.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2016, 2017, 2018 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.client.model.fabric;
+
+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();
+
+    /**
+     * 
+     * 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, brightness value provided via {@link VertexEditor#lightmap()}
+     * will be used as the minimum lightmap brightness.  Usually this is used to 
+     * implement full brightness but less-than-full brightness values are valid.
+     * False by default<p>
+     * 
+     * Note that color will still be modified by diffuse shading and ambient occlusion,
+     * by default.  Most of the time, you will want to disable those via {@link #disableAo(int, boolean)}
+     * and {@link #disableDiffuse(int, boolean)}.
+     */
+    MaterialFinder emissive(int spriteIndex, boolean isEmissive);
+}

src/main/java/net/fabricmc/fabric/api/client/model/fabric/Mesh.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2016, 2017, 2018 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.client.model.fabric;
+
+import java.util.function.Consumer;
+
+/**
+ * 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);
+}