VulkanMod

https://github.com/xcollateral/vulkanmod
Admin
VulkanMod is a Fabric mod that replaces Minecraft Java's OpenGL renderer with a modern Vulkan-based...
Tokens:81,200
Snippets:555
Trust Score:6.8
License:LGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: Programmatic Use

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/options.md

Example showing how to create and use an Option programmatically without a GUI.

```APIDOC
## Example: Programmatic Use

### Description
Demonstrates creating a RangeOption and applying a new value.

### Code

```java
Option<Integer> renderDistance = new RangeOption(
        Component.literal("Render distance"),
        2, 32, 1,
        value -> mcOptions.renderDistance().set(value),
        () -> mcOptions.renderDistance().get());

renderDistance.setNewValue(16);
renderDistance.apply(); // pushes 16 through the setter
if (renderDistance.isChanged()) { /* ... */ }
```
```

--------------------------------

### Example: getVersion() usage

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/initializer.md

Example usage of the getVersion() method, storing the returned version string in a local variable.

```java
// Example:
String version = net.vulkanmod.Initializer.getVersion();
```

--------------------------------

### trySetup

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Performs lazy pipeline setup for a render pass.

```APIDOC
## trySetup(VkRenderPass)

### Description
Performs lazy pipeline setup for the given render pass.

### Method
trySetup

### Signature
boolean trySetup(VkRenderPass renderPass)

### Parameters
- **renderPass** (VkRenderPass) - Required - The render pass to set up.

### Returns
- **boolean** - True if setup succeeded, false otherwise.
```

--------------------------------

### Example: offscreen color+8-bit depth target

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/framebuffer.md

Shows how to build a framebuffer with a color and depth attachment, create a render pass with a clear load op, and begin/end the render pass. The example uses a command buffer and memory stack, and assumes the necessary imports are present.

```java
// Example: offscreen color+8-bit depth target
import net.vulkanmod.vulkan.framebuffer.Framebuffer;
import net.vulkanmod.vulkan.framebuffer.RenderPass;

Framebuffer fb = Framebuffer.builder("off", 640, 480, 1, true).build();
RenderPass pass = RenderPass.builder(fb).setLoadOp(VK_ATTACHMENT_LOAD_OP_CLEAR).build();
fb.beginRenderPass(cmd, pass, stack);
// ... draws ...
pass.endRenderPass(cmd);
```

--------------------------------

### Config load/write example and RuntimeException handling

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/config.md

Example of loading and saving a config: load from a path, modify a field (frameQueueSize), then write. The second block shows failure handling: Gson parse errors surface as RuntimeException, which the game generally lets propagate at startup.

```java
import net.vulkanmod.config.Config;
import java.nio.file.Path;

Config config = Config.load(Path.of("/path/to/vulkanmod_settings.json"));
config.frameQueueSize = 4; // raise GPU queue
config.write();
```

```java
try {
    Config cfg = Config.load(Path.of("corrupt.json"));
} catch (RuntimeException e) {
    // e.g. JSON syntax error — the game generally lets these propagate at startup
    System.err.println("Failed to load config: " + e.getMessage());
}
```

--------------------------------

### Example: picking the graphics queue handles

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/device.md

Shows how to obtain the graphics queue and submit commands, returning a fence to wait on.

```java
// Example: picking the graphics queue handles
import net.vulkanmod.vulkan.device.DeviceManager;

net.vulkanmod.vulkan.queue.GraphicsQueue gq = DeviceManager.getGraphicsQueue();
long cb = gq.beginCommands();               // CommandPool.CommandBuffer
long fence = gq.submitCommands(cmdBuffer);  // wait for this fence
```

--------------------------------

### Platform-conditional code example

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/platform.md

Shows how to use Platform.isLinux() and Platform.isWayLand() to configure Wayland-specific behavior, and Platform.isGnome() to check the desktop environment.

```java
// Example: platform-conditional code
import net.vulkanmod.config.Platform;

if (Platform.isLinux() && Platform.isWayLand()) {
    // configure Wayland-specific behaviour
}
boolean underGnome = Platform.isGnome();
```

--------------------------------

### Arch Linux Nvidia Open-source Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the experimental nvk driver from the AUR git repository.

```bash
git clone https://aur.archlinux.org/vulkan-nouveau-git.git;
cd vulkan-nouveau-git;
makepkg -si;
```

--------------------------------

### Void Linux Intel Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the Intel Vulkan module on Void Linux.

```bash
sudo xbps-install -S mesa-vulkan-intel
```

--------------------------------

### Minimal registration example from another Fabric mod

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/config-api.md

Shows how to implement VkModSettingsFactory to register a settings page with a mod name, icon, option page, and apply callback. Uses the fluent builder methods.

```java
// Example: minimal registration from another Fabric mod
public class MyModSettings implements VkModSettingsFactory {
    @Override
    public ModSettingsEntry build(VkModSettingsEntryBuilder builder) {
        return builder.setModName(Component.literal("My Mod"))
                .setIcon(Identifier.fromNamespaceAndPath("mymod", "icon.png"))
                .withPage("Video")
                    .withOptionBlock("Quality")
                        .addOption(new SwitchOption(Component.literal("Extra quality"),
                                v -> MyConfig.extraQuality = v,
                                () -> MyConfig.extraQuality))
                        .finish()
                    .finish()
                .setOnApply(() -> MyConfig.save())
                .build();
    }
}
```

--------------------------------

### Arch Linux Intel Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the Intel Vulkan module on Arch-based systems.

```bash
sudo pacman -S vulkan-intel
```

--------------------------------

### CyclingOption example with WindowMode

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/options.md

Example usage of CyclingOption with WindowMode. Creates an option that cycles through WindowMode values, sets the config field on selection, and uses the current config value as the initial state. Calling nextValue() advances to the next candidate and apply() commits the change.

```java
// Example
CyclingOption<WindowMode> mode = new CyclingOption<>(Component.literal("Window mode"),
        WindowMode.values(),
        value -> config.windowMode = value.mode,
        () -> WindowMode.fromValue(config.windowMode));
mode.nextValue();                  // cycles to the next WindowMode
mode.apply();                      // commits it
```

--------------------------------

### Example: retrieving Vulkan pipeline handle via ExtendedRenderPipeline

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/interfaces.md

Shows how to obtain the Vulkan pipeline from a RenderPipeline instance using the ExtendedRenderPipeline.of helper, then retrieve its handle for binding in a command buffer. The null check guards against a missing pipeline.

```java
// Example: reaching the Vulkan pipeline behind a RenderPipeline
import net.vulkanmod.interfaces.shader.ExtendedRenderPipeline;

GraphicsPipeline vkPipeline = ExtendedRenderPipeline.of(renderPipeline).getPipeline();
if (vkPipeline != null) {
    long handle = vkPipeline.getHandle(state);
    // ... bind in a command buffer
}
```

--------------------------------

### One-off custom render pass with Renderer

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/renderer.md

Shows how to obtain the Renderer singleton and begin a custom render pass on a framebuffer, record draws, and end the pass. The example uses the beginRenderPass and endRenderPass methods.

```java
// Example: one-off custom pass
import net.vulkanmod.vulkan.Renderer;

Renderer r = Renderer.getInstance();
r.beginRenderPass(myRenderPass, myFramebuffer);
// ... record draws ...
r.endRenderPass();
```

--------------------------------

### RangeOption GUI-driven usage example

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/options.md

Example of creating a RangeOption for an FPS limit and setting its value from a scaled float. The comment notes that 0.5f maps to approximately 135, which rounds to 140.

```java
// Example: GUI-driven range usage
RangeOption fps = new RangeOption(Component.literal("FPS limit"), 10, 260, 10,
        value -> mcOptions.framerateLimit().set(value),
        () -> mcOptions.framerateLimit().get());
fps.setNewValueFromScaledFloat(0.5f); // ≈ 135 → rounded to 140
```

--------------------------------

### Update badge example

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/platform.md

Shows how to use UpdateChecker.isUpdateAvailable() to conditionally draw an 'update available' indicator. Note that the check is asynchronous and may not be settled immediately after checkForUpdates().

```java
// Example: showing an update badge
import net.vulkanmod.config.UpdateChecker;

if (UpdateChecker.isUpdateAvailable()) {
    // draw "update available" indicator
}
```

--------------------------------

### Create, map, and unmap a CPU-side pixel buffer with VkGlBuffer

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/gl-emulation.md

Shows the typical usage of VkGlBuffer static methods to create a pixel unpack buffer, allocate data, map it for writing, and unmap it. The example uses GL_PIXEL_UNPACK_BUFFER and GL_STATIC_DRAW. Note that glMapBuffer returns the buffer's data rewound to 0, and glUnmapBuffer always returns true.

```java
// Example: create + map + unmap a CPU-side pixel buffer
int id = VkGlBuffer.glGenBuffers();
VkGlBuffer.glBindBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, id);
VkGlBuffer.glBufferData(GL32.GL_PIXEL_UNPACK_BUFFER, 4096, GL_STATIC_DRAW);
ByteBuffer mapped = VkGlBuffer.glMapBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, GL_READ_WRITE);
mapped.putFloat(...);
VkGlBuffer.glUnmapBuffer(id);
```

--------------------------------

### Void Linux AMD Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the RADV module for AMD GPUs on Void Linux.

```bash
sudo xbps-install -S mesa-vulkan-radeon
```

--------------------------------

### Arch Linux AMD Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the RADV module for AMD GPUs on Arch-based systems.

```bash
sudo pacman -S vulkan-radeon
```

--------------------------------

### setupUniforms

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Uploads and binds uniforms for a render pass.

```APIDOC
## setupUniforms(VkRenderPass)

### Description
Uploads and binds uniforms for the given render pass.

### Method
setupUniforms

### Signature
void setupUniforms(VkRenderPass renderPass)

### Parameters
- **renderPass** (VkRenderPass) - Required - The render pass.

### Returns
- **void** - This method does not return a value.
```

--------------------------------

### Fedora AMD and Intel Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the mesa vulkan drivers for both Intel and AMD GPUs on Fedora.

```bash
dnf install mesa-vulkan-drivers
```

--------------------------------

### Fedora Nvidia Proprietary Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the Nvidia akmod driver from RPM Fusion on Fedora, followed by a system reboot.

```bash
sudo dnf install akmod-nvidia
```

```bash
sudo reboot
```

--------------------------------

### Global state flow diagram

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/vulkan-core.md

ASCII diagram showing the initialization sequence from Initializer.onInitializeClient() through Platform.init(), Renderer.register(), and the Vulkan initialization steps at first frame.

```text
Initializer.onInitializeClient()
  └─ Platform.init()            (GLFW platform hint — platform.md)
  └─ Renderer.register(...)     (Fabric renderer — fabric-renderer.md)
  └─ ... later at first frame:
       VRenderSystem.initRenderer()
         └─ Vulkan.initVulkan(window)
              ├─ Instance.createInstance()
              ├─ Debug.setupDebugMessenger()
              ├─ createSurface()
              ├─ DeviceManager.init()      → device.md
              ├─ createVma()               → memory.md
              ├─ MemoryTypes.createMemoryTypes()
              └─ createCommandPool()       → queues.md
```

--------------------------------

### Config write() and load(Path) method signatures

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/config.md

Method signatures for writing and loading the config. write() serializes the current instance to CONFIG_PATH as pretty-printed JSON, creating the parent directory if missing and printing stack traces on IOException without throwing. load(Path) parses the file with Gson, keeping field defaults for missing keys, throws RuntimeException on read/parse failure, and creates a fresh Config with defaults and writes it if the file is missing.

```java
public void write()
```

```java
public static Config load(Path path)
```

--------------------------------

### Debian AMD and Intel Vulkan Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the mesa vulkan drivers for AMD and Intel GPUs on Debian-based systems.

```bash
sudo apt install mesa-vulkan-drivers
```

--------------------------------

### Void Linux Nvidia Proprietary Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the Nvidia DKMS kernel and userspace libraries on Void Linux, followed by a system reboot.

```bash
sudo xbps-install -S nvidia-dkms nvidia-libs
```

```bash
sudo reboot
```

--------------------------------

### Arch Linux Nvidia Proprietary Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the Nvidia DKMS kernel and userspace modules on Arch-based systems, followed by a system reboot.

```bash
sudo pacman -S nvidia-dkms nvidia-settings nvidia-utils
```

```bash
sudo reboot
```

--------------------------------

### DeviceManager.init

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/device.md

Initializes the device manager by picking a physical device and creating a logical device.

```APIDOC
## DeviceManager.init

### Description
Initializes the device manager by picking a physical device and creating a logical device.

### Method
static void init(VkInstance instance)

### Parameters
- **instance** (VkInstance) - Required - The Vulkan instance to use for device enumeration.

### Returns
void
```

--------------------------------

### Debian Nvidia Proprietary Driver Installation

Source: https://github.com/xcollateral/vulkanmod/wiki/Linux-installation

Install the DKMS kernel and userspace modules for Nvidia proprietary drivers on Debian-based systems, followed by a system reboot.

```bash
sudo apt install nvidia-driver-dkms firmware-misc-nonfree
```

```bash
sudo reboot
```

--------------------------------

### SamplerInfo.Builder

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/texture.md

Fluent builder for creating SamplerInfo instances with configurable parameters.

```APIDOC
## SamplerInfo.Builder

### Description
Fluent builder for creating SamplerInfo instances. Defaults: CLAMP_TO_EDGE/CLAMP_TO_EDGE address modes, LINEAR/LINEAR/LINEAR filters, maxLod=0, anisotropy off, compare off (VK_COMPARE_OP_ALWAYS), reductionMode=0.

### Static Factory
- `builder()` - Returns a new Builder instance.

### Methods

#### `Builder setAddressMode(int addressMode)`
Sets the same address mode for both U and V.

#### `Builder setFiltering(int minFilter, int magFilter, int mipmapMode)`
Sets the filter triplet (min, mag, mipmap).

#### `Builder setMaxLod(float maxLod)`
Sets the maximum LOD bound.

#### `Builder setAnisotropy(float maxAnisotropy)`
Enables anisotropy with the given maximum.

#### `Builder setCompare(boolean enable, int compareOp)`
Sets depth comparison settings.

#### `Builder setReductionMode(int reductionMode)`
Sets the reduction mode.

#### `SamplerInfo createSamplerInfo()`
Builds and returns the SamplerInfo instance.
```

--------------------------------

### GraphicsQueue.startRecording

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/queues.md

Opens a command buffer for frame recording.

```APIDOC
## GraphicsQueue.startRecording

### Description
Opens a command buffer for frame recording.

### Method
startRecording

### Signature
`void startRecording()`

### Parameters
None

### Returns
void
```

--------------------------------

### Example JSON config document shape

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/config.md

Example JSON document shape showing all persisted fields with their keys and default values. The videoMode object uses the nested VideoModeSet.VideoMode class, not the standalone record.

```json
{
  "videoMode":       { "width": 2560, "height": 1440, "bitDepth": 8, "refreshRate": 144 },
  "windowMode":      0,
  "advCulling":      2,
  "indirectDraw":    true,
  "uniqueOpaqueLayer": true,
  "entityCulling":   true,
  "device":          -1,
  "useWayland":      false,
  "ambientOcclusion": 1,
  "frameQueueSize":  2,
  "builderThreads":  0,
  "backFaceCulling": true,
  "textureAnimations": true
}
```

--------------------------------

### Vulkan.initVulkan(long window)

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/vulkan-core.md

Initializes the Vulkan instance, debug messenger, surface, device, depth format, VMA allocator, memory types, and command pool.

```APIDOC
## Vulkan.initVulkan(long window)

### Description
Full init sequence: Instance.createInstance() → Debug.setupDebugMessenger() → createSurface(window) → DeviceManager.init(Instance.instance) → setupDepthFormat() (DeviceManager.findDepthFormat(use24BitsDepthFormat)) → createVma() → MemoryTypes.createMemoryTypes() → createCommandPool().

### Method
static void initVulkan(long window)

### Parameters
- **window** (long) - Required - GLFW window handle.

### Example
```java
Vulkan.initVulkan(glfwWindow);
```
```

--------------------------------

### Read configuration after startup

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/initializer.md

Logs the device index from the mod's runtime configuration after startup. Uses the public static fields LOGGER and CONFIG exposed by net.vulkanmod.Initializer.

```java
// Example: reading the loaded configuration after startup
net.vulkanmod.Initializer.LOGGER.info("Device index = {}", net.vulkanmod.Initializer.CONFIG.device);
```

--------------------------------

### createFence

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Creates a GPU fence that can be awaited.

```APIDOC
## createFence()

### Description
Creates a GPU fence that can be awaited via close or awaitCompletion.

### Method
createFence

### Signature
GpuFence createFence()

### Parameters
None

### Returns
- **GpuFence** - The created fence.
```

--------------------------------

### MemoryManager getInstance

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/memory.md

Static method to get the singleton instance of MemoryManager.

```APIDOC
## MemoryManager.getInstance()

### Description
Returns the singleton instance of the MemoryManager.

### Method
`static MemoryManager getInstance()`

### Returns
- **MemoryManager** - The singleton instance.

```

--------------------------------

### VulkanImage Instance Methods

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/texture.md

Instance methods for VulkanImage, including upload, layout transitions, sampler attachment, and resource management.

```APIDOC
## VulkanImage Instance Methods

### Description
Instance methods for VulkanImage, including upload, layout transitions, sampler attachment, and resource management.

### Methods

#### Constructor
- **Signature**: `VulkanImage(String name, long id, int format, int mipLevels, int width, int height, int formatSize, int usage, long imageView)`
- **Description**: Direct construction.

#### uploadSubTextureAsync
- **Signatures**:
  - `void uploadSubTextureAsync(int mipLevel, int width, int height, int xOffset, int yOffset, int unpackSkipRows, int unpackSkipPixels, int unpackRowLength, ByteBuffer buffer)`
  - `void uploadSubTextureAsync(int mipLevel, int arrayLayer, ..., ByteBuffer)`
  - `void uploadSubTextureAsync(int mipLevel, int arrayLayer, ..., long srcPtr)`
- **Description**: Stages a region into the global staging buffer (or a temporary one when the upload exceeds the default) and records a vkCmdCopyBufferToImage; unpackRowLength/Row/Skip mirror GL pixel-store state. Temporary buffers are scheduleFree()-d.

#### readOnlyLayout
- **Signatures**:
  - `void readOnlyLayout()`
  - `void readOnlyLayout(MemoryStack stack, VkCommandBuffer commandBuffer)`
- **Description**: Transition to shader-read layout.

#### setSampler
- **Signature**: `void setSampler(long sampler)`
- **Description**: Attach sampler handle.

#### transitionImageLayout (instance)
- **Signature**: `void transitionImageLayout(MemoryStack stack, VkCommandBuffer commandBuffer, int newLayout)`
- **Description**: Layout transition.

#### transitionImageLayout (static)
- **Signature**: `static void transitionImageLayout(MemoryStack stack, VkCommandBuffer commandBuffer, VulkanImage image, int newLayout)`
- **Description**: Static variant of layout transition.

#### transitionLayout
- **Signatures**:
  - `static void transitionLayout(MemoryStack, VkCommandBuffer, VulkanImage, int oldLayout, int newLayout, int baseLevel, ...)`
  - Overload
- **Description**: Full transition with base mip level.

#### free / doFree
- **Signatures**: `void free()` / `void doFree()`
- **Description**: Schedule / immediate free (VMA + views).

#### getCurrentLayout / setCurrentLayout
- **Signatures**: `int getCurrentLayout()` / `void setCurrentLayout(int)`
- **Description**: Layout tracking.

#### getId / getAllocation / getImageView / getSampler
- **Signatures**: `long ...()`
- **Description**: Handles.

#### getImageView (overload)
- **Signature**: `long getImageView(int format)`
- **Description**: View for a format (cached per-format).

#### getLevelImageView
- **Signature**: `long getLevelImageView(int i)`
- **Description**: View of mip level i.

#### getLevelImageViews
- **Signature**: `long[] getLevelImageViews()`
- **Description**: Views for all levels.

#### getViewFormat / setViewFormat
- **Signatures**: `int getViewFormat()` / `void setViewFormat(int)`
- **Description**: Format used for views (SRGB/UNORM variants).

```

--------------------------------

### RangeOption Methods

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/options.md

Methods of RangeOption including overrides and extra methods for getting and setting values with scaling.

```APIDOC
## RangeOption Methods

### Description
Methods available on RangeOption instances, including overrides and additional methods for normalized value handling.

### Methods

#### getName
- **Signature**: `Component getName()` (override)
- **Description**: Returns `name + ": " + newValue`.

#### getScaledValue
- **Signature**: `float getScaledValue()`
- **Description**: Returns the last computed normalized value `(value - min) / (max - min)`.

#### setNewValueFromScaledFloat
- **Signature**: `void setNewValueFromScaledFloat(float f)`
- **Description**: Lerps `f ∈ [0,1]` into `[min,max]`, rounds to `step`, and calls `setNewValue`.

#### setNewValue
- **Signature**: `void setNewValue(Integer newValue)` (override)
- **Description**: Sets the new value and recomputes `scaledNewValue`.

#### getScaledNewValue
- **Signature**: `float getScaledNewValue()`
- **Description**: Returns the current normalized value.

### Example
```java
// Example: GUI-driven range usage
RangeOption fps = new RangeOption(Component.literal("FPS limit"), 10, 260, 10,
        value -> mcOptions.framerateLimit().set(value),
        () -> mcOptions.framerateLimit().get());
fps.setNewValueFromScaledFloat(0.5f); // ≈ 135 → rounded to 140
```
```

--------------------------------

### Create and apply a sampler with min/max reduction using SamplerManager

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/texture.md

Builds a SamplerInfo with CLAMP_TO_EDGE addressing, linear filtering, max LOD 4.0, and MIN reduction mode, then retrieves a cached sampler via SamplerManager.getSampler and assigns it to an image. Requires the net.vulkanmod.vulkan.texture package and a valid image object.

```java
// Example: sampling with min/max reduction
import net.vulkanmod.vulkan.texture.*;

SamplerInfo info = SamplerInfo.builder()
        .setAddressMode(VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE)
        .setFiltering(VK_FILTER_LINEAR, VK_FILTER_LINEAR, VK_SAMPLER_MIPMAP_MODE_LINEAR)
        .setMaxLod(4.0f)
        .setReductionMode(VK_SAMPLER_REDUCTION_MODE_MIN)
        .createSamplerInfo();
long sampler = SamplerManager.getSampler(info);
image.setSampler(sampler);
```

--------------------------------

### SamplerInfo Constructors

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/texture.md

Creates a SamplerInfo instance with default or specified sampler parameters.

```APIDOC
## SamplerInfo Constructors

### Description
Creates a SamplerInfo instance with default or specified sampler parameters.

### Constructors

#### `public SamplerInfo()`
Default constructor: REPEAT/REPEAT address modes, NEAREST/NEAREST filters, MIPMAP_NEAREST mipmap mode, maxLod 0, no anisotropy, no compare, reductionMode -1.

#### `public SamplerInfo(int addressModeU, int addressModeV, int minFilter, int magFilter, int mipmapMode, float maxLod, boolean anisotropy, float maxAnisotropy, int reductionMode)`
Creates a sampler with the given address modes, filters, mipmap mode, max LOD, anisotropy settings, and reduction mode.

#### `public SamplerInfo(int addressModeU, int addressModeV, int minFilter, int magFilter, int mipmapMode, float maxLod, boolean anisotropy, float maxAnisotropy, boolean compare, int compareOp, int reductionMode)`
Creates a sampler with the given address modes, filters, mipmap mode, max LOD, anisotropy settings, depth compare settings, and reduction mode.

### Parameters
- `addressModeU` (int) - Required - VK_SAMPLER_ADDRESS_MODE_* value for U coordinate.
- `addressModeV` (int) - Required - VK_SAMPLER_ADDRESS_MODE_* value for V coordinate.
- `minFilter` (int) - Required - VK_FILTER_* value for minification filter.
- `magFilter` (int) - Required - VK_FILTER_* value for magnification filter.
- `mipmapMode` (int) - Required - VK_SAMPLER_MIPMAP_MODE_* value.
- `maxLod` (float) - Required - Maximum LOD (truncated to int).
- `anisotropy` (boolean) - Required - Enable anisotropy.
- `maxAnisotropy` (float) - Required - Maximum anisotropy (truncated to int).
- `compare` (boolean) - Required - Enable depth compare.
- `compareOp` (int) - Required - VK_COMPARE_OP_* value.
- `reductionMode` (int) - Required - VK_SAMPLER_REDUCTION_MODE_* value; -1 disables reduction.
```

--------------------------------

### Option<T> Methods

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/options.md

Methods available on Option<T> for setting and getting values, managing state, and applying changes.

```APIDOC
## Option<T> Methods

### Description
Methods to manipulate the option's value, set callbacks, and manage its active state.

### Methods

| Method | Signature | Returns | Description |
|--------|-----------|---------|-------------|
| setOnApply | Option<T> setOnApply(Consumer<T> onApply) | this | Replace apply setter |
| setValueSupplier | Option<T> setValueSupplier(Supplier<T> supplier) | this | Replace getter |
| setTranslator | Option<T> setTranslator(Function<T, Component> translator) | this | Set value translator |
| getTranslator | Function<T, Component> getTranslator() | — | Current translator |
| setTooltip | Option<T> setTooltip(Function<T, Component> tooltipTranslator) | this | Set tooltip translator |
| getImpact | PerformanceImpact getImpact() | — | Performance impact label |
| setImpact | Option<T> setImpact(PerformanceImpact impact) | this | Set impact; see types.md |
| setActive | Option<T> setActive(boolean active) | this | Activates/deactivates the underlying widget directly |
| getWidget | OptionWidget<?> getWidget() | cached widget | Lazily creates via createWidget() |
| setNewValue | void setNewValue(T t) | — | Sets pending value, fires onChange if set |
| updateActiveState | void updateActiveState() | — | Re-evaluates activationFn (defaults to active) and propagates to widget |
| getName | Component getName() | — | Display name |
| setOnChange | Option<T> setOnChange(Runnable runnable) | this | Fired on every setNewValue |
| setActivationFn | Option<T> setActivationFn(Supplier<Boolean> activationFn) | this | Dynamic enable/disable predicate |
| isChanged | boolean isChanged() | — | !newValue.equals(value) |
| apply | void apply() | — | Pushes newValue through onApply and commits it as value |
| resetValue | void resetValue() | — | setNewValue(value) (restores original pending value) |
| getNewValue | T getNewValue() | — | Pending value |
| getDisplayedValue | Component getDisplayedValue() | — | translator.apply(newValue) |
| getTooltip | Component getTooltip() | — | tooltipTranslator.apply(newValue) or null |
```

--------------------------------

### getImplementationInformation()

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Returns the driver/implementation information string.

```APIDOC
## Method: getImplementationInformation()

### Description
Returns a string describing the driver/implementation.

### Returns
- **String** - Implementation information
```

--------------------------------

### Wrap Vulkan image as GpuTexture

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Shows how to wrap an existing Vulkan image as a GpuTexture and create a texture view, e.g. for use as a render-pass attachment. Requires a VkGpuDevice instance and a VulkanImage.

```java
// Example: wrapping an existing Vulkan image as a GpuTexture
import net.vulkanmod.render.engine.VkGpuDevice;
import net.vulkanmod.render.engine.VkGpuTexture;
import net.vulkanmod.vulkan.texture.VulkanImage;

VkGpuTexture tex = gpuDevice.gpuTextureFromVulkanImage(vulkanImage);
GpuTextureView view = gpuDevice.createTextureView(tex); // e.g. as a render-pass attachment
```

--------------------------------

### Catching ShaderCompileException in VkGpuDevice

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/errors.md

Example of catching ShaderCompileException during pipeline compilation. The engine logs a warning and continues, skipping the broken pipeline instead of crashing.

```java
try {
    // ... compile / convert shaders via SpirvShader.createFromSpirv(...)
} catch (ShaderCompileException e) {
    // report shader error; fall back to a default pipeline
    LOGGER.warn("Shader compile failed: {}", e.getMessage());
}
```

--------------------------------

### Vulkan.getDevice()

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/vulkan-core.md

Returns the wrapped device.

```APIDOC
## Vulkan.getDevice()

### Description
Returns the wrapped device (see device.md).

### Method
static Device getDevice()

### Returns
Device - Wrapped device.
```

--------------------------------

### colorMask / getColorMask

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/vrendersystem.md

Set or get the color write mask. colorMask writes the mask via PipelineState.ColorMask.getColorMask, and getColorMask returns the current mask as an integer.

```APIDOC
## colorMask / getColorMask

### Description
Set or get the color write mask. colorMask writes the mask via PipelineState.ColorMask.getColorMask, and getColorMask returns the current mask as an integer.

### Method
static void colorMask(boolean r, boolean g, boolean b, boolean a) / static int getColorMask()

### Parameters
- **r** (boolean) - Required - Red channel write enable.
- **g** (boolean) - Required - Green channel write enable.
- **b** (boolean) - Required - Blue channel write enable.
- **a** (boolean) - Required - Alpha channel write enable.

### Response
- **getColorMask** returns an integer representing the color mask state.
```

--------------------------------

### getRenderer() / getVendor() / getBackendName() / getVersion()

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/render-engine.md

Returns device identity strings.

```APIDOC
## Methods: getRenderer(), getVendor(), getBackendName(), getVersion()

### Description
Returns device identity strings for renderer, vendor, backend name, and version.

### Returns
- **String** - The respective identity string
```

--------------------------------

### loadConfig(Path) helper

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/initializer.md

Private helper that delegates to Config.load(Path) to load the mod's configuration from the given path. Used during onInitializeClient() to assign the CONFIG field.

```java
private static Config loadConfig(Path path) {
    return Config.load(path);
}
```

--------------------------------

### Guarded boot with Vulkan.initVulkan, checkResult, waitIdle, cleanUp

Source: https://github.com/xcollateral/vulkanmod/blob/dev/_autodocs/api-reference/vulkan-core.md

Shows the full lifecycle: initialize Vulkan with a GLFW window, check a Vulkan call result with a custom error message, wait for the device to idle, and clean up. The checkResult method throws a RuntimeException with the format "<errorMessage>: <VkResult.decode(result)>" when the result is not VK_SUCCESS.

```java
// Example: guarded boot
import net.vulkanmod.vulkan.Vulkan;

Vulkan.initVulkan(glfwWindow);
try {
    Vulkan.checkResult(vkSomeCall(...), "My call failed");
} catch (RuntimeException e) {
    // e.getMessage() = "My call failed: VK_ERROR_OUT_OF_DEVICE_MEMORY"
}
Vulkan.waitIdle();
Vulkan.cleanUp();
```
Tokens:
Raw