### Install Vulkan Intel Driver on Arch Linux

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

Installs the Vulkan Intel driver for Intel GPUs on Arch Linux.

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

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

### Install Nvidia Drivers on Void Linux

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

Installs the Nvidia proprietary driver, including kernel and userspace modules, on Void Linux. A reboot is required after installation.

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

```bash
sudo reboot
```

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

### Install Mesa Vulkan Intel Driver on Void Linux

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

Installs the Mesa Vulkan Intel driver for Intel GPUs on Void Linux.

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

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

### Install Nvidia Proprietary Driver on Fedora

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

Installs the Nvidia proprietary driver and kernel modules using akmod-nvidia. A reboot is required after installation.

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

```bash
sudo reboot
```

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

### Install Nvidia Drivers on Debian/Ubuntu

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

Installs the Nvidia proprietary driver, including kernel and userspace modules, on Debian-based systems. A reboot is required after installation.

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

```bash
sudo reboot
```

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

### Install Experimental Nvidia Open-Source Driver on Arch Linux

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

Installs the experimental open-source Nvidia Vulkan driver (nvk) from the AUR on Arch Linux. This method does not require a reboot.

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

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

### Install RADV Vulkan Driver on Arch Linux

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

Installs the RADV Vulkan driver for AMD GPUs on Arch Linux.

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

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

### Install Mesa Vulkan Radeon Driver on Void Linux

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

Installs the Mesa Vulkan RADV driver for AMD GPUs on Void Linux.

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

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

### Install Mesa Vulkan Drivers on Debian/Ubuntu

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

Installs the open-source Mesa Vulkan drivers for AMD and Intel GPUs on Debian-based systems.

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

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

### Install Vulkan Drivers for AMD & Intel on Fedora

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

Installs the mesa-vulkan-drivers package, which provides Vulkan support for AMD and Intel GPUs.

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

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

### Renderer Frame Lifecycle Management

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Manages the per-frame rendering process, including swap chain creation, command buffer submission, and presentation. Handles swap chain recreation on resize or surface changes. Provides methods for binding pipelines, uploading UBOs, setting dynamic states, and managing debug sections. `initRenderer()` is for one-time setup, while `beginFrame()` and `endFrame()` orchestrate each frame.

```java
// net/vulkanmod/vulkan/Renderer.java

// One-time setup (called by MinecraftMixin after Vulkan.initVulkan):
Renderer.initRenderer();

// Per-frame lifecycle (driven by MinecraftMixin/GameRendererMixin):
Renderer renderer = Renderer.getInstance();

renderer.beginFrame();
// → waits in-flight fence for currentFrame
// → acquires next swap-chain image
// → begins main render pass / command buffer

// Bind a Vulkan graphics pipeline:
renderer.bindGraphicsPipeline(myGraphicsPipeline);

// Upload and bind UBOs for the current frame:
renderer.uploadAndBindUBOs(myGraphicsPipeline);

// Push per-draw constants:
renderer.pushConstants(myGraphicsPipeline);

// Dynamic state helpers:
Renderer.setViewport(0, 0, 1920, 1080);
Renderer.setScissor(0, 0, 1920, 1080);
Renderer.setDepthBias(0.0f, 0.0f);
Renderer.clearAttachments(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

renderer.endFrame();
// → ends render pass, submits command buffers, presents via vkQueuePresentKHR
// → advances currentFrame index

// Scheduling a swap-chain update (e.g., window resize, VSync toggle):
Renderer.scheduleSwapChainUpdate();

// Debug sections (only active when ENABLE_VALIDATION_LAYERS = true):
Renderer.pushDebugSection("TerrainPass");
// ... render terrain ...
Renderer.popPushDebugSection("EntityPass");
// ... render entities ...
Renderer.popDebugSection();

// Current frame index and in-flight frame count:
int frame  = Renderer.getCurrentFrame(); // 0 .. framesNum-1
int frames = Renderer.getFramesNum();    // equals config.frameQueueSize (2–5)
```

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

### Install Nvidia Proprietary Drivers on Arch Linux

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

Installs the Nvidia proprietary driver, including kernel and userspace modules, along with nvidia-settings and nvidia-utils on Arch Linux. A reboot is required.

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

```bash
sudo reboot
```

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

### Vulkan.setVsync(boolean)

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Controls the VSync setting for the swap chain. This signals the swap chain to change its present mode and schedules a recreation for the change to take effect at the start of the next frame. The swap chain is recreated lazily, so no immediate stall occurs.

```APIDOC
## `Vulkan.setVsync(boolean)` — VSync control

Signals the swap chain to change its present mode (FIFO vs. MAILBOX/IMMEDIATE) and schedules a swap-chain recreation so the change takes effect at the start of the next frame.

### Method Signature
`Vulkan.setVsync(boolean)`

### Parameters
* **boolean** - `true` to enable VSync (VK_PRESENT_MODE_FIFO_KHR), `false` to disable VSync (MAILBOX or IMMEDIATE if available).

### Request Example
```java
// net/vulkanmod/vulkan/Vulkan.java
Vulkan.setVsync(true);
Vulkan.setVsync(false);
```

### Notes
The swap chain is lazily recreated; no immediate stall occurs.
```

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

### Initialize Vulkan Context

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Boots the Vulkan instance, setting up the physical and logical devices, VMA allocator, command pool, and depth format. This is the primary call to bring the Vulkan context online. Debug labels can be set if validation layers are enabled.

```java
// net/vulkanmod/vulkan/Vulkan.java

// Called internally by MinecraftMixin; shown here for understanding the sequence:
Vulkan.initVulkan(glfwWindowHandle);
// Internally performs in order:
//   createInstance()           → VkInstance with VK_API_VERSION_1_2
//   setupDebugMessenger()      → only if ENABLE_VALIDATION_LAYERS = true
//   createSurface(window)      → glfwCreateWindowSurface
//   DeviceManager.init(instance)
//   createVma()                → VmaAllocator
//   MemoryTypes.createMemoryTypes()
//   createCommandPool()
//   setupDepthFormat()

// After init, query the selected device:
Device dev = Vulkan.getDevice();
System.out.println(dev.deviceName);   // e.g. "NVIDIA GeForce RTX 4090"
System.out.println(dev.vkVersion);    // e.g. "1.3.260"
System.out.println(dev.driverVersion);

// Enable debug labels (valid only when ENABLE_VALIDATION_LAYERS = true):
try (MemoryStack stack = MemoryStack.stackPush()) {
    Vulkan.setDebugLabel(stack, VK_OBJECT_TYPE_IMAGE, imageHandle, "MainColorAttachment");
}

// Tear down the entire Vulkan context on shutdown:
Vulkan.cleanUp(); // waits idle, destroys pools, pipelines, allocator, device, instance
```

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

### DeviceManager.init

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Initializes the GPU selection process and creates the logical Vulkan device. It enumerates physical devices, filters for suitability, picks the best device, and configures queues and features.

```APIDOC
## `DeviceManager.init(VkInstance)` — GPU selection and logical device creation

Enumerates all physical devices, filters for suitability (required extensions, swap-chain support), picks the best one (discrete GPU preferred over integrated), creates the logical `VkDevice` with graphics / transfer / present / compute queues, and configures requested features (anisotropic filtering, multi-draw indirect, wide lines).

### Usage Example
```java
// net/vulkanmod/vulkan/device/DeviceManager.java
DeviceManager.init(instance);

// After init, inspect available devices:
for (Device d : DeviceManager.availableDevices) {
    System.out.printf("Device: %s  Vulkan: %s%n", d.deviceName, d.vkVersion);
}
System.out.println(DeviceManager.getAvailableDevicesInfo());

// Access queues:
GraphicsQueue gfx      = DeviceManager.getGraphicsQueue();
TransferQueue transfer = DeviceManager.getTransferQueue();
ComputeQueue  compute  = DeviceManager.getComputeQueue();

// Find the optimal depth format for the selected GPU:
int depthFmt = DeviceManager.findDepthFormat(true); // true = prefer 24-bit (better on NVIDIA)

// Tear down:
DeviceManager.destroy(); // destroys queues and logical device
```

### Output Example for `getAvailableDevicesInfo()`
```
  Device: NVIDIA GeForce RTX 4090
      Vulkan Version: 1.3.260
      All required extensions are supported
```

### Depth Format Return Values
Returns one of: `VK_FORMAT_D24_UNORM_S8_UINT`, `VK_FORMAT_X8_D24_UNORM_PACK32`, `VK_FORMAT_D32_SFLOAT`
```

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

### GLFW Platform Initialization

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Initializes GLFW with platform-specific hints based on the operating system and display server. This must be called before creating any windows or Vulkan surfaces.

```java
// net/vulkanmod/config/Platform.java
Platform.init();
// Logs: "Selecting Platform: WAYLAND" (or WIN32 / X11 / MACOS / ANDROID)

// Query helpers available anywhere after init():
boolean onWayland = Platform.isWayLand();   // true on Wayland desktop
boolean onWindows = Platform.isWindows();
boolean onMac     = Platform.isMacOS();
boolean isGnome   = Platform.isGnome();     // checks XDG_SESSION_DESKTOP / XDG_CURRENT_DESKTOP
```

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

### Initialize GPU Device and Queues

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Initializes the `DeviceManager` by enumerating and selecting a suitable physical GPU. It creates a logical `VkDevice` with necessary queues (graphics, transfer, compute) and configures features. The optimal depth format for the selected GPU can be found. Call `destroy()` to clean up.

```java
// net/vulkanmod/vulkan/device/DeviceManager.java
DeviceManager.init(instance);

// After init, inspect available devices:
for (Device d : DeviceManager.availableDevices) {
    System.out.printf("Device: %s  Vulkan: %s%n", d.deviceName, d.vkVersion);
}
System.out.println(DeviceManager.getAvailableDevicesInfo());
// Output example:
//   Device: NVIDIA GeForce RTX 4090
//       Vulkan Version: 1.3.260
//       All required extensions are supported

// Access queues:
GraphicsQueue gfx      = DeviceManager.getGraphicsQueue();
TransferQueue transfer = DeviceManager.getTransferQueue();
ComputeQueue  compute  = DeviceManager.getComputeQueue();

// Find the optimal depth format for the selected GPU:
int depthFmt = DeviceManager.findDepthFormat(true); // true = prefer 24-bit (better on NVIDIA)
// Returns one of: VK_FORMAT_D24_UNORM_S8_UINT, VK_FORMAT_X8_D24_UNORM_PACK32, VK_FORMAT_D32_SFLOAT

// Tear down:
DeviceManager.destroy(); // destroys queues and logical device
```

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

### Fabric Mod Entry Point

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

The `onInitializeClient` method is the main entry point for Fabric mods. It reads the mod version, initializes platform-specific settings, loads configuration, registers the custom renderer, and checks for updates.

```java
// net/vulkanmod/Initializer.java
// Triggered automatically by Fabric; no direct call needed.
// To read the running mod version anywhere in code:
String version = Initializer.getVersion(); // e.g. "0.6.5-dev"

// To access the loaded config object:
Config cfg = Initializer.CONFIG;
// cfg fields: advCulling, indirectDraw, entityCulling, frameQueueSize, device, ...
```

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

### Vulkan.initVulkan

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Initializes the Vulkan instance, debug messenger, window surface, physical and logical devices, VMA allocator, command pool, and depth format. This is the primary function to bring the Vulkan context online.

```APIDOC
## `Vulkan.initVulkan(long window)` — Vulkan instance bootstrap

Creates the `VkInstance`, optional debug messenger, window surface (via GLFW), picks and initialises the physical and logical device, creates the VMA allocator, and sets up the command pool and depth format. This is the single call that brings the entire Vulkan context online.

### Usage Example
```java
// net/vulkanmod/vulkan/Vulkan.java

// Called internally by MinecraftMixin; shown here for understanding the sequence:
Vulkan.initVulkan(glfwWindowHandle);

// After init, query the selected device:
Device dev = Vulkan.getDevice();
System.out.println(dev.deviceName);   // e.g. "NVIDIA GeForce RTX 4090"
System.out.println(dev.vkVersion);    // e.g. "1.3.260"
System.out.println(dev.driverVersion);

// Enable debug labels (valid only when ENABLE_VALIDATION_LAYERS = true):
try (MemoryStack stack = MemoryStack.stackPush()) {
    Vulkan.setDebugLabel(stack, VK_OBJECT_TYPE_IMAGE, imageHandle, "MainColorAttachment");
}

// Tear down the entire Vulkan context on shutdown:
Vulkan.cleanUp(); // waits idle, destroys pools, pipelines, allocator, device, instance
```

### Internal Sequence
```java
// Internally performs in order:
//   createInstance()           → VkInstance with VK_API_VERSION_1_2
//   setupDebugMessenger()      → only if ENABLE_VALIDATION_LAYERS = true
//   createSurface(window)      → glfwCreateWindowSurface
//   DeviceManager.init(instance)
//   createVma()                → VmaAllocator
//   MemoryTypes.createMemoryTypes()
//   createCommandPool()
//   setupDepthFormat()
```
```

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

### Create Vulkan Textures and Buffers with GpuDevice

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Demonstrates creating color, depth textures, texture views, and GPU buffers using the VkGpuDevice API. Ensure the GpuDevice is obtained from RenderSystem.

```java
VkGpuDevice gpuDevice = /* obtained from RenderSystem */;

// Create a 2D RGBA colour texture with mipmaps:
GpuTexture colorTex = gpuDevice.createTexture(
    () -> "MyColorTex",            // debug name supplier
    GpuTexture.USAGE_RENDER_TARGET | GpuTexture.USAGE_SAMPLER,
    TextureFormat.RGBA8,
    1280, 720,                     // width, height
    1,                             // array layers
    4                              // mip levels
);

// Create a depth texture:
GpuTexture depthTex = gpuDevice.createTexture(
    "MyDepthTex",
    GpuTexture.USAGE_DEPTH_STENCIL,
    TextureFormat.DEPTH32,
    1280, 720, 1, 1
);

// Create a texture view (e.g., subset of mip levels):
GpuTextureView view = gpuDevice.createTextureView(colorTex, 0, 2); // mips 0–1

// Create a GPU buffer (vertex / uniform data):
GpuBuffer vertexBuf = gpuDevice.createBuffer(
    () -> "TerrainVBO",
    GpuBuffer.USAGE_VERTEX,
    1024 * 1024 // bytes
);
```

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

### Compile and Manage Vulkan Render Pipelines

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Shows how to compile a render pipeline directly or precompile it with explicit shader source. Includes releasing the pipeline shader cache.

```java
// Compile a render pipeline (shader + state):
gpuDevice.compilePipeline(myRenderPipeline);
// or precompile with explicit shader source:
CompiledRenderPipeline compiled = gpuDevice.precompilePipeline(myRenderPipeline, null);

// Release pipeline shader cache on resource reload:
gpuDevice.clearPipelineCache();
gpuDevice.close();
```

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

### Options.getOptionPages

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves a list of all configuration option pages available in the settings menu.

```APIDOC
## `Options.getOptionPages()`

### Description
Returns a list of `OptionPage` objects, each representing a tab in the game's settings menu (Video, Graphics, Optimizations, Other). These pages contain categorized options that users can modify.

### Returns
- `List<OptionPage>` - A list defining the structure and content of the settings pages.

### Example
```java
List<OptionPage> pages = Options.getOptionPages();
// pages.get(0) → "Video"
// pages.get(1) → "Graphics"
// pages.get(2) → "Optimizations"
// pages.get(3) → "Other"
```
```

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

### Build Settings Page Model with Options API

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the list of option pages, each containing blocks of typed options. This structure is used by VOptionScreen to render the game's settings GUI.

```java
List<OptionPage> pages = Options.getOptionPages();
// pages.get(0) → "Video"         (window mode, resolution, refresh rate, FPS limit, VSync, GUI scale, gamma)
// pages.get(1) → "Graphics"      (render distance, graphics quality, particles, clouds, AO, mipmap)
// pages.get(2) → "Optimizations" (adv culling, entity culling, unique opaque layer, back-face culling, indirect draw)
// pages.get(3) → "Other"         (builder threads, frame queue size, texture animations, GPU selector)
```

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

### Apply Changed Options from Settings Pages

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Iterates through all defined option pages, blocks, and individual options to apply any changes made by the user. This should be called after user interaction with the settings screen.

```java
// Iterate and apply all changed options:
for (OptionPage page : pages) {
    for (OptionBlock block : page.getBlocks()) {
        for (Option<?> opt : block.getOptions()) {
            if (opt.isChanged()) {
                opt.apply();
            }
        }
    }
}
```

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

### Profile Rendering Performance with Profiler

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Utilizes a push/pop timer tree to measure rendering performance in nanoseconds, exposed as averaged milliseconds. The profiler is active when Profiler.ACTIVE is true and can be toggled in-game. Results are retrieved via getProfilerResults().

```java
// net/vulkanmod/render/profiling/Profiler.java

Profiler p = Profiler.getMainProfiler();

// Activate (normally toggled by keyboard shortcut):
Profiler.setActive(true);

p.start(); // begins a new measurement round

p.push("TerrainRender");
    // ... terrain rendering code ...
    p.push("OpaquePass");
        // ... opaque geometry ...
    p.pop();
    p.push("TranslucentPass");
        // ... translucent geometry ...
    p.pop();
p.pop();

p.end(); // or call p.round() to end + immediately start the next frame

// Retrieve averaged results:
Profiler.ProfilerResults results = p.getProfilerResults();
Profiler.Result main = results.getResult();
System.out.printf("%s: %.2f ms%n", main.name, main.value);

for (Profiler.Result partial : results.getPartialResults()) {
    System.out.printf("  %s: %.2f ms%n", partial.name, partial.value);
}
// Example output:
//   Main: 12.34 ms
//   TerrainRender: 8.10 ms
//   OpaquePass: 5.20 ms
//   TranslucentPass: 2.90 ms
```

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

### VkGpuDevice.compilePipeline

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Compiles a render pipeline, which includes shaders and rendering state.

```APIDOC
## `VkGpuDevice.compilePipeline(RenderPipeline pipeline)`

### Description
Compiles a given `RenderPipeline` object, making it ready for use in rendering operations. This typically involves compiling shaders and setting up render states.

### Parameters
- `pipeline` (RenderPipeline) - The render pipeline configuration to compile.

### Example
```java
gpuDevice.compilePipeline(myRenderPipeline);
```
```

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

### VkGpuDevice.precompilePipeline

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Precompiles a render pipeline with explicit shader source code.

```APIDOC
## `VkGpuDevice.precompilePipeline(RenderPipeline pipeline, ShaderSource shaderSource)`

### Description
Precompiles a render pipeline, optionally providing explicit shader source code. This can be used for more control over the compilation process.

### Parameters
- `pipeline` (RenderPipeline) - The render pipeline configuration.
- `shaderSource` (ShaderSource) - Optional explicit shader source code. If null, the pipeline's default shaders will be used.

### Returns
- `CompiledRenderPipeline` - The result of the precompilation.

### Example
```java
CompiledRenderPipeline compiled = gpuDevice.precompilePipeline(myRenderPipeline, null);
```
```

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

### VkGpuDevice.createTexture

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Creates a Vulkan texture compatible with Minecraft's rendering pipeline. It supports various usage flags, formats, dimensions, and mip levels.

```APIDOC
## `VkGpuDevice.createTexture(...)`

### Description
Creates a new GPU texture with specified properties. This method handles the conversion of Minecraft's `TextureFormat` to Vulkan formats and sets appropriate usage flags for rendering.

### Parameters
- `debugNameSupplier` (Supplier<String>) - A supplier for a debug name for the texture.
- `usage` (int) - Bitwise flags indicating the texture's intended usage (e.g., `GpuTexture.USAGE_RENDER_TARGET`, `GpuTexture.USAGE_SAMPLER`).
- `format` (TextureFormat) - The texture format (e.g., `TextureFormat.RGBA8`, `TextureFormat.DEPTH32`).
- `width` (int) - The width of the texture in pixels.
- `height` (int) - The height of the texture in pixels.
- `arrayLayers` (int) - The number of layers in the texture array.
- `mipLevels` (int) - The number of mipmap levels for the texture.

### Example
```java
GpuTexture colorTex = gpuDevice.createTexture(
    () -> "MyColorTex",
    GpuTexture.USAGE_RENDER_TARGET | GpuTexture.USAGE_SAMPLER,
    TextureFormat.RGBA8,
    1280, 720,
    1,
    4
);
```
```

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

### Configure Render Distance with RangeOption

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Defines a render distance setting with min, max, and step values. The new value is staged until apply() is called. Use setNewValueFromScaledFloat for midpoint settings.

```java
RangeOption renderDist = new RangeOption(
    Component.literal("Render Distance"),
    2, 32, 1,                                              // min, max, step
    value -> Component.literal(value + " chunks"),         // display translator
    value -> Minecraft.getInstance().options.renderDistance().set(value),  // setter
    () -> Minecraft.getInstance().options.renderDistance().get()           // getter
);
renderDist.setImpact(PerformanceImpact.HIGH);
renderDist.setNewValueFromScaledFloat(0.5f); // set to midpoint (17 chunks)
System.out.println(renderDist.getNewValue());  // 17
System.out.println(renderDist.isChanged());    // true if != current value
renderDist.apply();                            // calls setter
```

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

### VkGpuDevice.createTextureView

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Creates a texture view, allowing access to a subset of mip levels of an existing texture.

```APIDOC
## `VkGpuDevice.createTextureView(GpuTexture texture, int baseMipLevel, int mipLevels)`

### Description
Creates a view into an existing `GpuTexture`, specifying a base mipmap level and the number of mipmap levels to include in the view.

### Parameters
- `texture` (GpuTexture) - The parent texture to create a view from.
- `baseMipLevel` (int) - The starting mipmap level for the view.
- `mipLevels` (int) - The number of mipmap levels to include in the view.

### Example
```java
GpuTextureView view = gpuDevice.createTextureView(colorTex, 0, 2); // mips 0–1
```
```

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

### Control VSync with Vulkan.setVsync()

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Enable or disable VSync to control the swap chain's present mode. The swap chain is recreated lazily, so no immediate stall occurs.

```java
Vulkan.setVsync(true);
// enable VSync (VK_PRESENT_MODE_FIFO_KHR)
Vulkan.setVsync(false);
// disable VSync (MAILBOX or IMMEDIATE if available)
// The swap chain is lazily recreated; no immediate stall occurs.
```

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

### VkGpuDevice.getVersion

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the version string of the graphics API.

```APIDOC
## `VkGpuDevice.getVersion()`

### Description
Returns the version string of the underlying graphics API (e.g., Vulkan version).

### Returns
- `String` - The graphics API version.

### Example
```java
System.out.println(gpuDevice.getVersion()); // e.g., "1.3.260"
```
```

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

### JSON Settings Persistence

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Loads mod settings from a JSON file and persists changes. If the file doesn't exist, a default configuration is created and saved. All public fields in the `Config` object are serialized.

```java
// net/vulkanmod/config/Config.java
Path configPath = FabricLoader.getInstance()
        .getConfigDir()
        .resolve("vulkanmod_settings.json");

Config config = Config.load(configPath);

// Modify a setting programmatically:
config.advCulling    = 2;      // 1=aggressive, 2=normal, 3=conservative, 10=off
config.indirectDraw  = true;   // Vulkan multi-draw indirect
config.entityCulling = true;
config.frameQueueSize = 2;     // frames in flight (2–5)
config.device         = -1;    // -1 = auto-pick GPU

config.write(); // persists to disk

// Expected JSON output (vulkanmod_settings.json):
// {
//   "videoMode": { "width": 1920, "height": 1080, "refreshRate": 60 },
//   "windowMode": 0,
//   "advCulling": 2,
//   "indirectDraw": true,
//   "entityCulling": true,
//   "frameQueueSize": 2,
//   "device": -1,
//   ...
// }
```

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

### VkGpuDevice.close

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Releases all resources associated with the `VkGpuDevice`.

```APIDOC
## `VkGpuDevice.close()`

### Description
Releases all GPU resources managed by this `VkGpuDevice` instance. This should be called when the device is no longer needed to prevent memory leaks.

### Example
```java
gpuDevice.close();
```
```

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

### OpenGL Pixel-Buffer-Object Emulation with VkGlBuffer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Emulates GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER targets using off-heap ByteBuffers. Used for texture uploads and screenshot capture.

```java
// Allocate a pixel unpack buffer:
int bufId = VkGlBuffer.glGenBuffers();
VkGlBuffer.glBindBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, bufId);
VkGlBuffer.glBufferData(GL32.GL_PIXEL_UNPACK_BUFFER, 1024 * 1024 * 4L, GL15.GL_STREAM_DRAW);

// Map for writing:
ByteBuffer mapped = VkGlBuffer.glMapBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, GL15.GL_WRITE_ONLY);
// ... fill mapped buffer with pixel data ...
VkGlBuffer.glUnmapBuffer(GL32.GL_PIXEL_UNPACK_BUFFER);

// Obtain currently bound PBO (used internally for texture uploads):
VkGlBuffer unpackBuf = VkGlBuffer.getPixelUnpackBufferBound();

// Delete when done:
VkGlBuffer.glDeleteBuffers(bufId);
```

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

### Cycle through Advanced Culling options with CyclingOption

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Implements a cycling option for advanced culling settings. Values are cycled using nextValue() and prevValue(). The displayed value is translated using a switch statement.

```java
CyclingOption<Integer> advCulling = new CyclingOption<>(
    Component.literal("Advanced Culling"),
    new Integer[]{1, 2, 3, 10},
    value -> Initializer.CONFIG.advCulling = value,
    () -> Initializer.CONFIG.advCulling
);
advCulling.setTranslator(v -> Component.literal(switch (v) {
    case 1  -> "Aggressive";
    case 2  -> "Normal";
    case 3  -> "Conservative";
    case 10 -> "Off";
    default -> "Unknown";
}));
advCulling.nextValue();  // cycle forward
advCulling.prevValue();  // cycle back
System.out.println(advCulling.getDisplayedValue().getString()); // "Normal"
advCulling.apply();
```

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

### Query Vulkan Device Information

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves and prints various details about the Vulkan GPU device, such as backend name, version, renderer, maximum texture size, and uniform offset alignment.

```java
System.out.println(gpuDevice.getBackendName());          // "Vulkan"
System.out.println(gpuDevice.getVersion());              // "1.3.260"
System.out.println(gpuDevice.getRenderer());             // "NVIDIA GeForce RTX 4090"
System.out.println(gpuDevice.getMaxTextureSize());       // e.g. 32768
System.out.println(gpuDevice.getUniformOffsetAlignment()); // e.g. 256 (bytes)
```

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

### VkGpuDevice.getBackendName

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the name of the graphics backend being used.

```APIDOC
## `VkGpuDevice.getBackendName()`

### Description
Returns the name of the graphics API backend. For this implementation, it will return "Vulkan".

### Returns
- `String` - The name of the graphics backend.

### Example
```java
System.out.println(gpuDevice.getBackendName()); // "Vulkan"
```
```

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

### VkGpuDevice.createBuffer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Creates a GPU buffer for vertex or uniform data with a specified size.

```APIDOC
## `VkGpuDevice.createBuffer(Supplier<String> debugNameSupplier, int usage, long bytes)`

### Description
Allocates a GPU buffer for storing vertex data, uniform data, or other types of GPU-accessible memory.

### Parameters
- `debugNameSupplier` (Supplier<String>) - A supplier for a debug name for the buffer.
- `usage` (int) - Bitwise flags indicating the buffer's intended usage (e.g., `GpuBuffer.USAGE_VERTEX`).
- `bytes` (long) - The size of the buffer in bytes.

### Example
```java
GpuBuffer vertexBuf = gpuDevice.createBuffer(
    () -> "TerrainVBO",
    GpuBuffer.USAGE_VERTEX,
    1024 * 1024 // bytes
);
```
```

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

### Integrate Vulkan Rendering with LevelRendererMixin

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

This Java code demonstrates how VulkanMod's LevelRendererMixin replaces vanilla chunk rendering methods. It delegates rendering tasks to WorldRenderer, including frustum culling, section layer rendering (SOLID, CUTOUT, TRANSLUCENT), block-entity rendering, and exposes chunk statistics.

```java
// net/vulkanmod/mixin/chunk/LevelRendererMixin.java
// (Applied automatically by the Mixin framework; shown for integration context.)

// The overwritten methods delegate to WorldRenderer:
WorldRenderer wr = WorldRenderer.getInstance();

// Set up frustum culling (replaces cullTerrain):
wr.setupRenderer(camera, frustum, false /*captureEnabled*/, spectator);

// Render a terrain layer:
wr.renderSectionLayer(TerrainRenderType.SOLID, camX, camY, camZ, modelView, projection);
wr.renderSectionLayer(TerrainRenderType.CUTOUT, camX, camY, camZ, modelView, projection);
wr.renderSectionLayer(TerrainRenderType.TRANSLUCENT, camX, camY, camZ, modelView, projection);

// Block-entity rendering:
wr.renderBlockEntities(poseStack, levelRenderState, submitNodeStorage, destructionProgress);

// Statistics (exposed to Minecraft's F3 debug screen):
System.out.println(wr.getChunkStatistics());   // e.g. "C: 256/4096 Ent: 3"
System.out.println(wr.getVisibleSectionsCount()); // number of visible sections
System.out.println(wr.hasRenderedAllSections());  // true when build queue is empty
```

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

### VkGpuDevice.getRenderer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the name of the GPU renderer.

```APIDOC
## `VkGpuDevice.getRenderer()`

### Description
Returns the name of the GPU model and vendor.

### Returns
- `String` - The renderer name.

### Example
```java
System.out.println(gpuDevice.getRenderer()); // e.g., "NVIDIA GeForce RTX 4090"
```
```

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

### VkGpuDevice.getUniformOffsetAlignment

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the required alignment in bytes for uniform buffer offsets.

```APIDOC
## `VkGpuDevice.getUniformOffsetAlignment()`

### Description
Returns the minimum required alignment in bytes for offsets when accessing uniform buffers.

### Returns
- `int` - The uniform offset alignment in bytes.

### Example
```java
System.out.println(gpuDevice.getUniformOffsetAlignment()); // e.g. 256 (bytes)
```
```

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

### VkGlBuffer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Emulates OpenGL pixel-buffer-objects (PBOs) for `GL_PIXEL_PACK_BUFFER` and `GL_PIXEL_UNPACK_BUFFER` targets using direct off-heap ByteBuffer allocations. This is used for texture uploads and screenshot capture.

```APIDOC
## `VkGlBuffer` — OpenGL pixel-buffer-object emulation

Emulates `GL_PIXEL_PACK_BUFFER` and `GL_PIXEL_UNPACK_BUFFER` targets on top of direct off-heap `ByteBuffer` allocations (via LWJGL `MemoryUtil`). Used by Minecraft's texture upload and screenshot capture paths.

### Methods

#### `glGenBuffers()`
Generates a buffer ID.

#### `glBindBuffer(target, buffer)`
Binds a buffer object.

* **target** (int) - The target to bind to (e.g., `GL32.GL_PIXEL_UNPACK_BUFFER`).
* **buffer** (int) - The buffer ID.

#### `glBufferData(target, size, usage)`
Allocates storage for the buffer object.

* **target** (int) - The target buffer type (e.g., `GL32.GL_PIXEL_UNPACK_BUFFER`).
* **size** (long) - The size of the buffer in bytes.
* **usage** (int) - The expected usage pattern (e.g., `GL15.GL_STREAM_DRAW`).

#### `glMapBuffer(target, access)`
Maps the buffer object's memory range into the client's address space.

* **target** (int) - The target buffer type (e.g., `GL32.GL_PIXEL_UNPACK_BUFFER`).
* **access** (int) - The access mode (e.g., `GL15.GL_WRITE_ONLY`).
* **Returns** (ByteBuffer) - A direct ByteBuffer representing the mapped memory.

#### `glUnmapBuffer(target)`
Unmaps the buffer object's memory range.

* **target** (int) - The target buffer type (e.g., `GL32.GL_PIXEL_UNPACK_BUFFER`).

#### `getPixelUnpackBufferBound()`
Retrieves the currently bound pixel unpack buffer. This is used internally for texture uploads.

* **Returns** (`VkGlBuffer`) - The currently bound pixel unpack buffer object.

#### `glDeleteBuffers(buffer)`
Deletes the specified buffer object.

* **buffer** (int) - The ID of the buffer to delete.

### Request Example
```java
// net/vulkanmod/gl/VkGlBuffer.java

// Allocate a pixel unpack buffer:
int bufId = VkGlBuffer.glGenBuffers();
VkGlBuffer.glBindBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, bufId);
VkGlBuffer.glBufferData(GL32.GL_PIXEL_UNPACK_BUFFER, 1024 * 1024 * 4L, GL15.GL_STREAM_DRAW);

// Map for writing:
ByteBuffer mapped = VkGlBuffer.glMapBuffer(GL32.GL_PIXEL_UNPACK_BUFFER, GL15.GL_WRITE_ONLY);
// ... fill mapped buffer with pixel data ...
VkGlBuffer.glUnmapBuffer(GL32.GL_PIXEL_UNPACK_BUFFER);

// Obtain currently bound PBO (used internally for texture uploads):
VkGlBuffer unpackBuf = VkGlBuffer.getPixelUnpackBufferBound();

// Delete when done:
VkGlBuffer.glDeleteBuffers(bufId);
```
```

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

### Renderer Frame Lifecycle

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Manages the lifecycle of a rendered frame, including initialization, beginning and ending frame operations, and handling swap-chain updates. It orchestrates the creation of swap chains, command buffers, and synchronization objects.

```APIDOC
## `Renderer.initRenderer()` / `Renderer.beginFrame()` / `Renderer.endFrame()` — Frame lifecycle

`Renderer` is the central per-frame orchestrator. `initRenderer()` creates the swap chain, drawer, uniform infrastructure, command buffers, and semaphore/fence sync objects. Each rendered frame follows the pattern: `preInitFrame()` → `beginFrame()` → (render work) → `endFrame()`. The renderer automatically handles swap-chain recreation on resize or suboptimal surface.

### Usage Example
```java
// net/vulkanmod/vulkan/Renderer.java

// One-time setup (called by MinecraftMixin after Vulkan.initVulkan):
Renderer.initRenderer();

// Per-frame lifecycle (driven by MinecraftMixin/GameRendererMixin):
Renderer renderer = Renderer.getInstance();

renderer.beginFrame();
// → waits in-flight fence for currentFrame
// → acquires next swap-chain image
// → begins main render pass / command buffer

// Bind a Vulkan graphics pipeline:
renderer.bindGraphicsPipeline(myGraphicsPipeline);

// Upload and bind UBOs for the current frame:
renderer.uploadAndBindUBOs(myGraphicsPipeline);

// Push per-draw constants:
renderer.pushConstants(myGraphicsPipeline);

// Dynamic state helpers:
Renderer.setViewport(0, 0, 1920, 1080);
Renderer.setScissor(0, 0, 1920, 1080);
Renderer.setDepthBias(0.0f, 0.0f);
Renderer.clearAttachments(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

renderer.endFrame();
// → ends render pass, submits command buffers, presents via vkQueuePresentKHR
// → advances currentFrame index

// Scheduling a swap-chain update (e.g., window resize, VSync toggle):
Renderer.scheduleSwapChainUpdate();

// Debug sections (only active when ENABLE_VALIDATION_LAYERS = true):
Renderer.pushDebugSection("TerrainPass");
// ... render terrain ...
Renderer.popPushDebugSection("EntityPass");
// ... render entities ...
Renderer.popDebugSection();

// Current frame index and in-flight frame count:
int frame  = Renderer.getCurrentFrame(); // 0 .. framesNum-1
int frames = Renderer.getFramesNum();    // equals config.frameQueueSize (2–5)
```
```

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

### VkGlFramebuffer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Provides OpenGL-to-Vulkan framebuffer translation, intercepting standard OpenGL framebuffer functions and mapping them to Vulkan objects. It automatically sets up an inverted Vulkan viewport when a non-zero framebuffer is bound.

```APIDOC
## `VkGlFramebuffer` — OpenGL-to-Vulkan framebuffer translation

Intercepts `glGenFramebuffers`, `glBindFramebuffer`, `glFramebufferTexture2D`, etc. and maps them to Vulkan `Framebuffer` + `RenderPass` objects. When a non-zero framebuffer is bound, `Renderer.beginRenderPass` is called automatically, setting up an inverted Vulkan viewport to compensate for Vulkan's top-left origin.

### Methods

#### `genFramebufferId()`
Generates a new framebuffer ID.

#### `framebufferTexture2D(target, attachment, textarget, texture, level)`
Attaches a color texture to the framebuffer.

* **target** (int) - e.g., `GL30.GL_FRAMEBUFFER`
* **attachment** (int) - e.g., `GL30.GL_COLOR_ATTACHMENT0`
* **textarget** (int) - e.g., `GL11.GL_TEXTURE_2D`
* **texture** (int) - The ID of the texture to attach (must be a `VkGlTexture`).
* **level** (int) - Mip level, usually 0.

#### `bindFramebuffer(target, framebuffer)`
Binds the specified framebuffer. This triggers `Renderer.beginRenderPass` internally.

* **target** (int) - e.g., `GL30.GL_FRAMEBUFFER`
* **framebuffer** (int) - The ID of the framebuffer to bind. Use `0` to return to the default swap-chain render pass.

#### `glBlitFramebuffer(srcX0, srcY0, srcX1, srcY1, dstX0, dstY0, dstX1, dstY1, mask, filter)`
Blits content from one framebuffer to another.

* **srcX0, srcY0, srcX1, srcY1** (int) - Source rectangle coordinates.
* **dstX0, dstY0, dstX1, dstY1** (int) - Destination rectangle coordinates.
* **mask** (int) - Bitmask of buffers to blit (e.g., `GL11.GL_COLOR_BUFFER_BIT`).
* **filter** (int) - Blitting filter (e.g., `GL11.GL_NEAREST`).

#### `glCheckFramebufferStatus(target)`
Checks the completion status of the framebuffer. Always returns `GL_FRAMEBUFFER_COMPLETE`.

* **target** (int) - e.g., `GL30.GL_FRAMEBUFFER`
* **Returns** (int) - Status code, expected to be `GL_FRAMEBUFFER_COMPLETE`.

#### `deleteFramebuffer(framebuffer)`
Deletes the specified framebuffer.

* **framebuffer** (int) - The ID of the framebuffer to delete.

### Request Example
```java
// net/vulkanmod/gl/VkGlFramebuffer.java  (used via GL30 mixin intercepts)

// Generate a framebuffer ID:
int fbId = VkGlFramebuffer.genFramebufferId();

// Attach a colour texture (texture must already exist as VkGlTexture):
VkGlFramebuffer.framebufferTexture2D(
    GL30.GL_FRAMEBUFFER,
    GL30.GL_COLOR_ATTACHMENT0,
    GL11.GL_TEXTURE_2D,
    colourTexId,
    0 // mip level
);

// Bind for drawing — triggers Renderer.beginRenderPass internally:
VkGlFramebuffer.bindFramebuffer(GL30.GL_FRAMEBUFFER, fbId);

// Blit from one framebuffer to another:
VkGlFramebuffer.glBlitFramebuffer(
    0, 0, srcWidth, srcHeight,
    0, 0, dstWidth, dstHeight,
    GL11.GL_COLOR_BUFFER_BIT, GL11.GL_NEAREST
);

// Return to the default (main) swap-chain render pass:
VkGlFramebuffer.bindFramebuffer(GL30.GL_FRAMEBUFFER, 0);

// Check completion status (always returns GL_FRAMEBUFFER_COMPLETE):
int status = VkGlFramebuffer.glCheckFramebufferStatus(GL30.GL_FRAMEBUFFER);

// Clean up:
VkGlFramebuffer.deleteFramebuffer(fbId);
```
```

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

### Toggle Entity Culling with SwitchOption

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

A simple boolean toggle for entity culling. The new value is set using setNewValue() and applied with apply().

```java
SwitchOption entityCulling = new SwitchOption(
    Component.literal("Entity Culling"),
    v -> Initializer.CONFIG.entityCulling = v,
    () -> Initializer.CONFIG.entityCulling
);
entityCulling.setNewValue(false);
entityCulling.apply();
```

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

### Check for Modrinth Updates Asynchronously

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Initiates an asynchronous check for mod updates on Modrinth. The result can be polled safely from the render thread using isUpdateAvailable(). Pre-release versions are skipped.

```java
// net/vulkanmod/config/UpdateChecker.java

// Called once during mod init:
UpdateChecker.checkForUpdates();
// Runs on a CompletableFuture thread; logs "Update available!" if a newer stable
// release exists on Modrinth for the current Minecraft version.

// Poll the result (safe to call from the render thread):
if (UpdateChecker.isUpdateAvailable()) {
    // Show in-game notification
}

// Request URL built internally:
// https://api.modrinth.com/v2/project/vulkanmod/version
//   ?include_changelog=false&game_versions=["1.21.10"]
```

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

### VkGpuDevice.getMaxTextureSize

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Retrieves the maximum texture dimension (width or height) supported by the GPU.

```APIDOC
## `VkGpuDevice.getMaxTextureSize()`

### Description
Returns the maximum size (width or height) for a texture that the GPU can handle.

### Returns
- `int` - The maximum texture dimension.

### Example
```java
System.out.println(gpuDevice.getMaxTextureSize()); // e.g. 32768
```
```

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

### OpenGL-to-Vulkan Framebuffer Translation with VkGlFramebuffer

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Intercepts OpenGL framebuffer calls and maps them to Vulkan objects. Automatically sets up an inverted Vulkan viewport when a non-zero framebuffer is bound.

```java
// Generate a framebuffer ID:
int fbId = VkGlFramebuffer.genFramebufferId();

// Attach a colour texture (texture must already exist as VkGlTexture):
VkGlFramebuffer.framebufferTexture2D(
    GL30.GL_FRAMEBUFFER,
    GL30.GL_COLOR_ATTACHMENT0,
    GL11.GL_TEXTURE_2D,
    colourTexId,
    0 // mip level
);

// Bind for drawing — triggers Renderer.beginRenderPass internally:
VkGlFramebuffer.bindFramebuffer(GL30.GL_FRAMEBUFFER, fbId);

// Blit from one framebuffer to another:
VkGlFramebuffer.glBlitFramebuffer(
    0, 0, srcWidth, srcHeight,
    0, 0, dstWidth, dstHeight,
    GL11.GL_COLOR_BUFFER_BIT, GL11.GL_NEAREST
);

// Return to the default (main) swap-chain render pass:
VkGlFramebuffer.bindFramebuffer(GL30.GL_FRAMEBUFFER, 0);

// Check completion status (always returns GL_FRAMEBUFFER_COMPLETE):
int status = VkGlFramebuffer.glCheckFramebufferStatus(GL30.GL_FRAMEBUFFER);

// Clean up:
VkGlFramebuffer.deleteFramebuffer(fbId);
```

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

### VkGpuDevice.clearPipelineCache

Source: https://context7.com/xcollateral/vulkanmod/llms.txt

Clears the cache for compiled render pipelines, typically done during resource reloads.

```APIDOC
## `VkGpuDevice.clearPipelineCache()`

### Description
Clears the internal cache of compiled render pipelines. This is useful when resources are reloaded to ensure that old pipeline states do not interfere with new ones.

### Example
```java
gpuDevice.clearPipelineCache();
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.