drafts:rendering
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | |||
drafts:rendering [2023/09/13 19:12] – removed - external edit (Unknown date) 127.0.0.1 | drafts:rendering [2023/09/13 19:12] (current) – ↷ Page moved from documentation:rendering to drafts:rendering nebelnidas | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Rendering in Fabric (DRAFT) ====== | ||
+ | **IMPORTANT: | ||
+ | |||
+ | ===== Introduction ===== | ||
+ | ==== The Fabric Rendering API ==== | ||
+ | |||
+ | The Rendering API specifies interfaces and creates hooks for the implementation of a '' | ||
+ | |||
+ | * Enhanced block model rendering: emissive lighting, control over diffuse and ambient occlusions lighting, and multiple blend modes (solid, cutout, translucent) in the same model. | ||
+ | * Dynamic block models: Some or all of a block model can be generated or modified during chunk rebuild based on world state, with or without a BlockEntity. | ||
+ | * Enhanced item model rendering: Item models have similar options for enhanced appearance and model output can be dynamic based on ItemStack state. | ||
+ | |||
+ | The API is flexible so that '' | ||
+ | Some renderer implementations may focus on aesthetics and some may focus on performance, | ||
+ | |||
+ | This freedom is achieved through two key design decisions: | ||
+ | |||
+ | First, Fabric delegates most of the functionality to the '' | ||
+ | |||
+ | Second, the API specification hides vertex formats, vertex data structures, and other implementation details from models using the API - models are not expected to provide or manipulate raw vertex data. Instead, the API defines lightweight interfaces for obtaining materials and building/ | ||
+ | ==== Audience ==== | ||
+ | == Mod Developers == | ||
+ | Many mod authors will use a 3rd-party library to create or load models. | ||
+ | |||
+ | == Model Loader Developers == | ||
+ | The Fabric Rendering API was designed to be a suitable back-end for practically any type of model loader but does not specify or implement any model formats. Creating a model loader is a great way to contribute to Fabric development! If you want to create a model loader, you should review the entire API and all of the sections below. | ||
+ | |||
+ | == Model Library Developers == | ||
+ | The Rendering API provides only the most basic primitives for model creation. Creating a library for procedural model generation and transformation is another good way to contribute to Fabric development. If you want to create a model library, you'll need to review the entire API and all of the sections below. | ||
+ | |||
+ | **Caution: | ||
+ | |||
+ | == Renderer Developers == | ||
+ | The Rendering API is only as good as the available implementations. Creating and maintaining a new Renderer is likely to be a large and complex effort. | ||
+ | * What are you trying to achieve? | ||
+ | * Your renderer should support all the features defined in the core API. Do you understand the entire Rendering API and how it is used? | ||
+ | * Are there any API extensions you intend to support or introduce? | ||
+ | * Do you know how to write and debug Mixins? | ||
+ | * How will your renderer modify the Minecraft rendering pipeline? | ||
+ | * How will your approach avoid excessive memory allocation? | ||
+ | * How will you ensure thread-safety? | ||
+ | |||
+ | Still want to create a renderer? This wiki and the links below will help you get started. | ||
+ | ==== Getting Started ==== | ||
+ | |||
+ | You'll need to include the Fabric API in your development environment - the Rendering API is part of it. See [[tutorial: | ||
+ | |||
+ | Fabric is distributed with a default '' | ||
+ | |||
+ | If the features provided in the core API are sufficient, the default renderer is all you need. Players or pack makers may render your content with other render implementations to get better performance or a different look (ie. shader packs). | ||
+ | |||
+ | Only one Renderer implementation can be active in a game session. When a non-default '' | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | [...] | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | If two (non-default) implementations are present, Minecraft will crash during startup when the second implementation tries to register itself. | ||
+ | |||
+ | Some renderer implementations may offer an expanded feature set. If you create mods with a hard dependency on those features, be sure to state that clearly for anyone using your mod. In that case, your audience will be limited to players and pack makers who use renderers supporting those expanded features. | ||
+ | |||
+ | === Getting the Renderer Instance === | ||
+ | To use the features of this API, you'll need a reference to the '' | ||
+ | |||
+ | <code java> | ||
+ | RendererAccess.INSTANCE.getRenderer() | ||
+ | </ | ||
+ | |||
+ | It is safe to retain a reference to the '' | ||
+ | |||
+ | The renderer instance will be reliably non-null unless Fabric was somehow distributed without the default renderer or with the default renderer disabled. (This would not be normal.) If your mod depends on features defined in the API, then your mod should simply crash when no '' | ||
+ | |||
+ | ===== Materials ===== | ||
+ | |||
+ | Every quad sent through the rending API has an associated '' | ||
+ | |||
+ | ==== Obtaining Materials ==== | ||
+ | |||
+ | Use '' | ||
+ | |||
+ | **Tip:** Calling '' | ||
+ | |||
+ | Material instances are immutable and opaque once retrieved. Materials with identical properties may or //may not// pass == and .equals() tests. | ||
+ | |||
+ | ==== Named Materials ==== | ||
+ | Materials can be registered with a name-spaced identifier using '' | ||
+ | |||
+ | Named materials can also be used by '' | ||
+ | |||
+ | Named materials will not be present unless a mod/ | ||
+ | ==== Material Properties ==== | ||
+ | |||
+ | When selecting a material, you can choose from materials with the following attributes: | ||
+ | |||
+ | === Blend Mode === | ||
+ | * Allows the effect of multiple render layers in the same block/ | ||
+ | * Set via '' | ||
+ | * Accepts '' | ||
+ | * Does NOT necessarily mean the material actually renders in the given pass - only that it will appear to do so. (Some renderers may combine passes or do other optimizations. | ||
+ | * If null (the default) then terrain renders will use the value of '' | ||
+ | |||
+ | === Diffuse Shading On/Off === | ||
+ | * Controls color modification for diffuse lighting. | ||
+ | * On by default. | ||
+ | * Disable via '' | ||
+ | * In vanilla Minecraft this causes sides and bottoms of blocks to be darker, creating visual distinction. | ||
+ | * Renderer implementations may use a different diffuse lighting model but should still honor this setting. | ||
+ | |||
+ | |||
+ | === Ambient Occlusion Shading On/Off === | ||
+ | * Controls color modification for ambient occlusion lighting. | ||
+ | * On by default. | ||
+ | * Disable via '' | ||
+ | * In vanilla Minecraft this causes interior corners to be darker, creating visual distinction. | ||
+ | * Renderer implementations may use a different AO lighting model but should still honor this setting. | ||
+ | |||
+ | === Emissive Rendering On/Off === | ||
+ | * When enabled, causes quad to be rendered at full brightness. | ||
+ | * Disabled by default. | ||
+ | * Enable via '' | ||
+ | * Does not require a custom per-vertex light map and it is recommended you don't provide one. | ||
+ | * Diffuse and Ambient Occlusion shading //will// apply unless also disabled. | ||
+ | |||
+ | === Sprite Depth === | ||
+ | * Default value is 1 and 1 is the only value currently supported in the API. | ||
+ | * Values > 1 are reserved for future use and for use by extensions. | ||
+ | * Extensions can use this to accept multiple sprites on the same quad to create overlay effects. | ||
+ | |||
+ | |||
+ | === Color Index On/Off === | ||
+ | * Controls application of block color index to vertex colors. | ||
+ | * If block color index != -1 it will be applied by default. (Set using '' | ||
+ | * Use '' | ||
+ | * Generally only useful when an extension is active the supports a material sprite depth > 1, In that case it allows block color to apply only to specific sprite layers. | ||
+ | ===== Meshes ===== | ||
+ | |||
+ | ===== Render Contexts ===== | ||
+ | |||
+ | ===== Dynamic Rendering ===== | ||
+ | |||
+ | ===== How To ===== | ||
+ | * Static Models | ||
+ | * Compound Models | ||
+ | * Dynamic Models | ||
+ | * Emissive Rendering | ||
+ | * Transformation | ||
+ | * Selective Visibility | ||
+ | * Mirroring | ||
+ | * Wrapping | ||
+ | * Coloring | ||
+ | * Item Models | ||
+ | * Damage Models | ||
+ | * Moving Blocks | ||
+ | |||
+ | ===== Implementation Advice ===== | ||
+ | Rendertime Mesh Generation | ||
+ | |||
+ | Necessary Hooks | ||
+ | |||
+ | Optimization Opportunities | ||
+ | * Chunk Builds | ||
+ | * Low Allocation | ||
+ | * Compact Formats | ||
+ | * Hardware Transforms | ||
+ | |||
+ | ===== Future Direction ===== | ||
+ | * Batched BlockEntity Rendering | ||
+ | * Shaders | ||
+ | * Custom Materials | ||
+ | * Sprite Overlay Layers | ||
+ | * Fancy Lighting Models | ||
+ | |||
+ | ===== Links ===== | ||
+ | Implementations | ||
+ | * Indigo | ||
+ | * Canvas | ||
+ | |||
+ | Extensions | ||
+ | * FREx | ||
+ | |||
+ | Sample Usage | ||
+ | * RenderBender | ||
+ | |||
+ | Model Libraries | ||
+ | * Brocade | ||
+ | |||
+ | Model Loaders |