Preallocate texture VRAM, move files around

src/engine/DeviceAllocation.zig

@@ -0,0 +1,53 @@
+const std = @import("std");
+const DeviceAllocation = @This();
+
+const ctx = @import("../AppContext.zig");
+const vk = @import("vulkan");
+
+device_memory: vk.DeviceMemory,
+memory_type_index: u32,
+allocated: usize,
+capacity: usize,
+
+pub fn deinit(self: *DeviceAllocation) void {
+    const engine = ctx.engine;
+
+    engine.freeMemory(self.device_memory);
+    self.* = undefined;
+}
+
+pub fn bindBuffer(self: *DeviceAllocation, buffer: vk.Buffer) !void {
+    const engine = ctx.engine;
+
+    const memory_requirements = engine.getBufferMemoryRequirements(buffer);
+    const is_type = memory_requirements.memory_type_bits & (@as(u32, 1) << @truncate(self.memory_type_index)) != 0;
+    std.debug.assert(is_type);
+
+    const offset = std.mem.alignForward(usize, self.allocated, memory_requirements.alignment);
+    const next_allocated = offset + memory_requirements.size;
+
+    if (next_allocated > self.capacity) {
+        return error.OutOfMemory;
+    }
+
+    try engine.bindBufferMemory(buffer, self.device_memory, offset);
+    self.allocated = next_allocated;
+}
+
+pub fn bindImage(self: *DeviceAllocation, image: vk.Image) !void {
+    const engine = ctx.engine;
+
+    const memory_requirements = engine.getImageMemoryRequirements(image);
+    const is_type = memory_requirements.memory_type_bits & (@as(u32, 1) << @truncate(self.memory_type_index)) != 0;
+    std.debug.assert(is_type);
+
+    const offset = std.mem.alignForward(usize, self.allocated, memory_requirements.alignment);
+    const next_allocated = offset + memory_requirements.size;
+
+    if (next_allocated > self.capacity) {
+        return error.OutOfMemory;
+    }
+
+    try engine.bindImageMemory(image, self.device_memory, offset);
+    self.allocated = next_allocated;
+}

src/engine/Engine.zig

@@ -6,6 +6,7 @@ const ctx = @import("../AppContext.zig");
 const glfw = @import("zglfw");
 const vk = @import("vulkan");
 
+const DeviceAllocation = @import("DeviceAllocation.zig");
 const Queue = @import("Queue.zig");
 const QueueType = @import("QueueType.zig").QueueType;
 const VkAllocator = @import("VkAllocator.zig");
@@ -418,18 +419,46 @@ pub fn deinit(self: *Engine) void {
 }
 
 pub fn allocate(self: *const Engine, memory_requirements: vk.MemoryRequirements, memory_property_flags: vk.MemoryPropertyFlags) !vk.DeviceMemory {
-    for (self.memory_types.items, 0..) |memory_type, i| {
-        const is_type = memory_requirements.memory_type_bits & (@as(u32, 1) << @truncate(i)) != 0;
-        const has_flags = memory_type.property_flags.contains(memory_property_flags);
-        if (is_type and has_flags) {
-            return try self.device.allocateMemory(&.{
-                .allocation_size = memory_requirements.size,
-                .memory_type_index = @truncate(i),
-            }, ctx.vk_allocator.capture());
-        }
-    }
+    const memory_type_index = try self.findMemoryTypeIndex(memory_requirements.memory_type_bits, memory_property_flags);
 
-    return error.NoSuitableMemoryType;
+    return self.device.allocateMemory(&.{
+        .allocation_size = memory_requirements.size,
+        .memory_type_index = memory_type_index,
+    }, ctx.vk_allocator.capture());
+}
+
+/// Allocate `vk.DeviceMemory` suitable for image created by given
+/// `create_info`, except the allocation is `size` bytes large.
+pub fn allocateForImage(
+    self: *const Engine,
+    create_info: ImageCreateInfo,
+    plane_aspect: vk.ImageAspectFlags,
+    size: usize,
+    memory_property_flags: vk.MemoryPropertyFlags,
+) !DeviceAllocation {
+    const create_info_vk = try create_info.toVk();
+
+    var memory_requirements2: vk.MemoryRequirements2 = .{
+        .memory_requirements = undefined,
+    };
+    self.device.getDeviceImageMemoryRequirements(&.{
+        .p_create_info = &create_info_vk,
+        .plane_aspect = plane_aspect,
+    }, &memory_requirements2);
+
+    const memory_requirements = memory_requirements2.memory_requirements;
+    const memory_type_index = try self.findMemoryTypeIndex(memory_requirements.memory_type_bits, memory_property_flags);
+    const device_memory = try self.device.allocateMemory(&.{
+        .allocation_size = size,
+        .memory_type_index = memory_type_index,
+    }, ctx.vk_allocator.capture());
+
+    return .{
+        .device_memory = device_memory,
+        .allocated = 0,
+        .capacity = size,
+        .memory_type_index = memory_type_index,
+    };
 }
 
 pub fn setObjectName(self: *const Engine, handle: anytype, comptime fmt: []const u8, args: anytype) void {
@@ -663,8 +692,16 @@ fn findPresentationQueueFamily(queue_families_properties: []const vk.QueueFamily
     return null;
 }
 
-fn makeArena(self: *const Engine) std.heap.ArenaAllocator {
-    return .init(self.vk_allocator.allocator);
+fn findMemoryTypeIndex(self: *const Engine, memory_type_bits: u32, memory_property_flags: vk.MemoryPropertyFlags) !u32 {
+    for (self.memory_types.items, 0..) |memory_type, i| {
+        const is_type = memory_type_bits & (@as(u32, 1) << @truncate(i)) != 0;
+        const has_flags = memory_type.property_flags.contains(memory_property_flags);
+        if (is_type and has_flags) {
+            return @truncate(i);
+        }
+    }
+
+    return error.NoSuitableMemoryType;
 }
 
 fn resolveCommandPool(self: *const Engine, queue_type: QueueType) vk.CommandPool {
@@ -769,6 +806,33 @@ pub const ImageCreateInfo = struct {
     usage: vk.ImageUsageFlags,
     queue_family_indices: []const u32 = &.{},
     initial_layout: vk.ImageLayout,
+
+    pub fn toVk(self: ImageCreateInfo) !vk.ImageCreateInfo {
+        const allocator_frame = ctx.allocator_frame;
+
+        var queue_family_indices_set: std.AutoArrayHashMapUnmanaged(u32, void) = .{};
+        for (self.queue_family_indices) |queue_family_index| {
+            try queue_family_indices_set.put(allocator_frame, queue_family_index, {});
+        }
+
+        const queue_family_indices = queue_family_indices_set.keys();
+
+        return .{
+            .flags = self.flags,
+            .image_type = self.image_type,
+            .format = self.format,
+            .extent = self.extent,
+            .mip_levels = self.mip_levels,
+            .array_layers = self.array_layers,
+            .samples = self.samples,
+            .tiling = self.tiling,
+            .usage = self.usage,
+            .sharing_mode = if (queue_family_indices.len > 1) .concurrent else .exclusive,
+            .queue_family_index_count = if (queue_family_indices.len > 1) @intCast(queue_family_indices.len) else 0,
+            .p_queue_family_indices = if (queue_family_indices.len > 1) queue_family_indices.ptr else null,
+            .initial_layout = self.initial_layout,
+        };
+    }
 };
 
 pub const ImageViewCreateInfo = struct {
@@ -1110,31 +1174,8 @@ pub fn createGraphicsPipeline(self: *Engine, create_info: GraphicsPipelineCreate
 }
 
 pub fn createImage(self: *Engine, create_info: ImageCreateInfo) !vk.Image {
-    const allocator_frame = ctx.allocator_frame;
-
-    var queue_family_indices_set: std.AutoArrayHashMapUnmanaged(u32, void) = .{};
-    for (create_info.queue_family_indices) |queue_family_index| {
-        try queue_family_indices_set.put(allocator_frame, queue_family_index, {});
-    }
-
-    const queue_family_indices = queue_family_indices_set.keys();
-
-    const image = self.device.createImage(&.{
-        .flags = create_info.flags,
-        .image_type = create_info.image_type,
-        .format = create_info.format,
-        .extent = create_info.extent,
-        .mip_levels = create_info.mip_levels,
-        .array_layers = create_info.array_layers,
-        .samples = create_info.samples,
-        .tiling = create_info.tiling,
-        .usage = create_info.usage,
-        .sharing_mode = if (queue_family_indices.len > 1) .concurrent else .exclusive,
-        .queue_family_index_count = if (queue_family_indices.len > 1) @intCast(queue_family_indices.len) else 0,
-        .p_queue_family_indices = if (queue_family_indices.len > 1) queue_family_indices.ptr else null,
-        .initial_layout = create_info.initial_layout,
-    }, ctx.vk_allocator.capture());
-    return image;
+    const create_info_vk = try create_info.toVk();
+    return self.device.createImage(&create_info_vk, ctx.vk_allocator.capture());
 }
 
 pub fn createImageView(self: *Engine, create_info: ImageViewCreateInfo) !vk.ImageView {

src/engine/Materials.zig

@@ -0,0 +1,340 @@
+//! Module for loading persistent materials, which are all stored in a single
+//! storage buffer in VRAM.
+//!
+//! This module is intended to be initialized once and to persist until the end
+//! of the whole program's runtime. Trying to use it in any other way will
+//! result in weird behavior.
+
+const Materials = @This();
+const std = @import("std");
+
+const ctx = @import("../AppContext.zig");
+const media = @import("media");
+const shaders = @import("../shaders.zig");
+const vk = @import("vulkan");
+
+const Atom = @import("../engine/Atom.zig").Atom;
+const Engine = @import("../engine/Engine.zig");
+const Textures = @import("Textures.zig");
+
+pub const Id = enum(u16) {
+    // VOLATILE When modifying the list of explicitly defined material IDs (i.e.
+    // any explicit enum value), we need to update `Materials.init`
+    // implementation.
+
+    /// A material ID that can be used as a "null" material. An object with this
+    /// material ID must not be rendered. If this material is rendered anyway,
+    /// an appropriate "error"-looking material will be used.
+    empty,
+    _,
+
+    /// Cast an integer into an ID. This can produce an invalid ID.
+    pub fn fromInt(value: u16) Id {
+        return @enumFromInt(value);
+    }
+
+    /// Cast an index into an ID. This can produce an invalid ID. The caller
+    /// asserts that the index is not greater than the max ID value.
+    pub fn fromIndex(index: usize) Id {
+        std.debug.assert(index < max_materials);
+        return @enumFromInt(@as(u16, @intCast(index)));
+    }
+
+    /// Cast an index into an ID. This can produce an invalid ID. Returns an
+    /// error if the index is greater than the max ID value.
+    pub fn fromIndexSafe(index: usize) error{Overflow}!Id {
+        if (index >= max_materials) return error.Overflow;
+        return @enumFromInt(@as(u16, @intCast(index)));
+    }
+
+    /// Cast an ID into an integer.
+    pub fn toInt(self: Id) u16 {
+        return @intFromEnum(self);
+    }
+};
+
+pub const Key = struct {
+    /// Atom representing the filename of the material.
+    filename: Atom,
+};
+
+/// Maps a key value to a material ID. Preallocated with `allocator_general`.
+map: std.AutoHashMapUnmanaged(Key, Id),
+/// Stores all material data in a single contiguous storage buffer. Use the
+/// material ID as an index into this buffer.
+material_buffer: shaders.MaterialBuffer,
+/// The amount of materials currently loaded.
+material_count: usize,
+
+/// With `@sizeOf(Material) == 52` and `max_materials == 4096`, the material
+/// storage buffer should take 208 kiB in VRAM.
+pub const max_materials = 4096;
+
+pub fn init() !Materials {
+    const allocator_general = ctx.allocator_general;
+
+    var map: std.AutoHashMapUnmanaged(Key, Id) = .empty;
+    errdefer map.deinit(allocator_general);
+    try map.ensureTotalCapacity(allocator_general, max_materials);
+
+    var material_buffer = try shaders.MaterialBuffer.init(.{
+        .usage = .storage,
+        .target_queue = .graphics,
+        .array_capacity = max_materials,
+        .name = "Materials",
+    });
+    errdefer material_buffer.deinit();
+
+    // VOLATILE Synchronize with explicit values on top of `Id` type.
+
+    try material_buffer.write(.{
+        .element_offset = Id.empty.toInt(),
+        .elements = &.{
+            .{
+                .base_color = .zero,
+                .emissive = .init(1, 0, 1),
+                .ior = 1.45,
+                .metallic = 0,
+                .normal_scale = 1,
+                .occlusion_texture_strength = 1,
+                .roughness = 1,
+                .base_color_texture = .empty_base_color,
+                .emissive_texture = .empty_emissive,
+                .normal_texture = .empty_normal,
+                .occlusion_roughness_metallic_texture = .empty_occlusion_roughness_metallic,
+            },
+        },
+    });
+
+    return .{
+        .map = map,
+        .material_buffer = material_buffer,
+        .material_count = @typeInfo(Id).@"enum".fields.len,
+    };
+}
+
+pub fn deinit(self: *Materials) void {
+    const allocator_general = ctx.allocator_general;
+
+    std.log.scoped(.deinit).debug("Deinitializing {*}", .{self});
+
+    self.material_buffer.deinit();
+    self.map.deinit(allocator_general);
+    self.* = undefined;
+}
+
+/// Get the ID of a material given its filename (as a string). Returns `null` if
+/// such material hasn't been loaded. Returns `.empty` when the filename is
+/// `null`.
+pub fn get(self: *const Materials, maybe_filename: ?[]const u8) ?Id {
+    if (maybe_filename) |filename| {
+        return self.map.get(.{
+            // If the atom doesn't exist, then the material cannot possibly exist.
+            .filename = .fromStringIfExists(filename) orelse return null,
+        });
+    } else {
+        return .empty;
+    }
+}
+
+/// Get the ID of a material given its filename (as an atom). Returns `null` if
+/// such material hasn't been loaded. Returns `.empty` when the filename is
+/// `.empty`.
+pub fn getAtom(self: *const Materials, filename: Atom) ?Id {
+    if (filename != .empty) {
+        return self.map.get(.{
+            .filename = filename,
+        });
+    } else {
+        return .empty;
+    }
+}
+
+/// Get the ID of a material given its filename (as a string). Returns either an
+/// existing material ID or loads a new material along with its textures and
+/// assigns a new ID, if necessary. Will not return any error if the material
+/// already exists. Returns `.empty` when the filename is `null`.
+///
+/// When a material or its textures are being loaded, `temp_allocator` is used
+/// for temporary allocations necessary to perform all operations. No memory
+/// allocated with `temp_allocator` is retained, so the allocator can be
+/// deinitialized or reset after this function returns. Note that during loading
+/// the engine will make its own persistent allocations, so an out of memory
+/// error is not necessarily related to `temp_allocator`.
+pub fn getOrLoad(
+    self: *Materials,
+    textures: *Textures,
+    stbi: *media.stbi,
+    maybe_filename: ?[]const u8,
+) !Id {
+    if (maybe_filename) |filename| {
+        const key: Key = .{
+            // If the material already exists, then the atom must exist and the
+            // following line will not return any error.
+            .filename = try .fromString(filename),
+        };
+
+        // We don't use `getOrPutAssumeCapacity` method, because we might already be
+        // at full capacity, in which case we should return `error.OutOfMaterials`.
+
+        if (self.map.get(key)) |id| {
+            return id;
+        } else {
+            const id = Id.fromIndexSafe(self.material_count) catch |err| switch (err) {
+                error.Overflow => return error.OutOfMaterials,
+            };
+            try self.loadMaterial(textures, stbi, filename, id.toInt());
+
+            self.map.putAssumeCapacityNoClobber(key, id);
+            self.material_count += 1;
+
+            return id;
+        }
+    } else {
+        return .empty;
+    }
+}
+
+/// Get the ID of a material given its filename (as an atom). Returns either an
+/// existing material ID or loads a new material along with its textures and
+/// assigns a new ID, if necessary. Will not return any error if the material
+/// already exists. Returns `.empty` when the filename is `.empty`.
+///
+/// When a material or its textures are being loaded, `temp_allocator` is used
+/// for temporary allocations necessary to perform all operations. No memory
+/// allocated with `temp_allocator` is retained, so the allocator can be
+/// deinitialized or reset after this function returns. Note that during loading
+/// the engine will make its own persistent allocations, so an out of memory
+/// error is not necessarily related to `temp_allocator`.
+pub fn getOrLoadAtom(
+    self: *Materials,
+    textures: *Textures,
+    stbi: *media.stbi,
+    filename: Atom,
+) !Id {
+    if (filename != .empty) {
+        const key: Key = .{
+            .filename = filename,
+        };
+
+        // We don't use `getOrPutAssumeCapacity` method, because we might already be
+        // at full capacity, in which case we should return `error.OutOfMaterials`.
+
+        if (self.map.get(key)) |id| {
+            return id;
+        } else {
+            const id = Id.fromIndexSafe(self.material_count) catch |err| switch (err) {
+                error.Overflow => return error.OutOfMaterials,
+            };
+            try self.loadMaterial(textures, stbi, filename.toString(), id.toInt());
+
+            self.map.putAssumeCapacityNoClobber(key, id);
+            self.material_count += 1;
+
+            return id;
+        }
+    } else {
+        return .empty;
+    }
+}
+
+/// Scan the materials directory and load all materials that haven't been loaded
+/// already. Will not traverse subdirectories. Any errors will be skipped and
+/// logged.
+///
+/// When a material or its textures are being loaded, `temp_allocator` is used
+/// for temporary allocations necessary to perform all operations. No memory
+/// allocated with `temp_allocator` is retained, so the allocator can be
+/// deinitialized or reset after this function returns. Note that during loading
+/// the engine will make its own persistent allocations, so an out of memory
+/// error is not necessarily related to `temp_allocator`.
+pub fn loadAll(
+    self: *Materials,
+    textures: *Textures,
+    stbi: *media.stbi,
+) void {
+    const io = ctx.io;
+
+    const cwd = std.Io.Dir.cwd();
+
+    var dir = cwd.openDir(io, "assets/materials", .{ .iterate = true }) catch |err| {
+        std.log.err("Error while opening metarials directory: {s}", .{@errorName(err)});
+        return;
+    };
+    defer dir.close(io);
+
+    var it = dir.iterate();
+    while (it.next() catch |err| {
+        std.log.err("Error while iterating over materials directory: {s}", .{@errorName(err)});
+        return;
+    }) |entry| {
+        if (entry.kind != .file) {
+            std.log.warn("Skipping material entry {s}, which is not a file", .{entry.name});
+            continue;
+        }
+
+        _ = self.getOrLoad(textures, stbi, entry.name) catch |err| {
+            std.log.err("Error while loading material entry {s}: {s}", .{ entry.name, @errorName(err) });
+        };
+    }
+}
+
+fn loadMaterial(self: *Materials, textures: *Textures, stbi: *media.stbi, filename: []const u8, index: u32) !void {
+    const allocator_frame = ctx.allocator_frame;
+    const io = ctx.io;
+
+    const MaterialJson = struct {
+        baseColor: [3]f32 = .{ 1, 1, 1 },
+        baseColorTexture: ?[]const u8 = null,
+        emissive: [3]f32 = .{ 0, 0, 0 },
+        emissiveTexture: ?[]const u8 = null,
+        ior: f32 = 1.45,
+        metallic: f32 = 1,
+        normalScale: f32 = 1,
+        normalTexture: ?[]const u8 = null,
+        occlusionRoughnessMetallicTexture: ?[]const u8 = null,
+        occlusionTextureStrength: f32 = 1,
+        roughness: f32 = 1,
+    };
+
+    std.log.debug("Loading material \"{s}\"...", .{filename});
+
+    const cwd = std.Io.Dir.cwd();
+
+    var dir = try cwd.openDir(io, "assets/materials", .{});
+    defer dir.close(io);
+
+    // NOTE Buffer size approximated based on expected JSON structure.
+    var buffer: [512]u8 = undefined;
+
+    const file = try dir.openFile(io, filename, .{});
+    defer file.close(io);
+
+    var file_reader = file.reader(io, &buffer);
+    var json_reader = std.json.Reader.init(allocator_frame, &file_reader.interface);
+
+    const material_json = try std.json.parseFromTokenSourceLeaky(MaterialJson, allocator_frame, &json_reader, .{
+        .duplicate_field_behavior = .@"error",
+        .ignore_unknown_fields = false,
+        .allocate = .alloc_if_needed,
+    });
+
+    try self.material_buffer.write(.{
+        .element_offset = index,
+        .elements = &.{
+            .{
+                .base_color = .initArray(material_json.baseColor),
+                .emissive = .initArray(material_json.emissive),
+                .ior = material_json.ior,
+                .metallic = material_json.metallic,
+                .normal_scale = material_json.normalScale,
+                .occlusion_texture_strength = material_json.occlusionTextureStrength,
+                .roughness = material_json.roughness,
+                .base_color_texture = try textures.getOrLoad(stbi, material_json.baseColorTexture, .base_color),
+                .emissive_texture = try textures.getOrLoad(stbi, material_json.emissiveTexture, .emissive),
+                .normal_texture = try textures.getOrLoad(stbi, material_json.normalTexture, .normal),
+                .occlusion_roughness_metallic_texture = try textures.getOrLoad(stbi, material_json.occlusionRoughnessMetallicTexture, .occlusion_roughness_metallic),
+            },
+        },
+    });
+}

src/engine/Texture.zig

@@ -5,6 +5,7 @@ const ctx = @import("../AppContext.zig");
 const vk = @import("vulkan");
 
 const CommandBuffer = @import("CommandBuffer.zig");
+const DeviceAllocation = @import("DeviceAllocation.zig");
 const Engine = @import("Engine.zig");
 const StagingBuffer = @import("StagingBuffer.zig");
 const TargetQueue = @import("TargetQueue.zig").TargetQueue;
@@ -68,11 +69,14 @@ pub const InitInfo = struct {
     height: u32,
     usage: Usage,
     target_queue: TargetQueue,
+    device_allocation: ?*DeviceAllocation = null,
     name: ?[]const u8 = null,
 };
 
 image: vk.Image,
 image_view: vk.ImageView,
+/// Is `.null_handle` when external device memory is provided via
+/// `device_allocation` in init info.
 device_memory: vk.DeviceMemory,
 target_queue: TargetQueue,
 
@@ -114,14 +118,20 @@ pub fn init(init_info: InitInfo) !Texture {
         engine.setObjectName(image, "I {s} [{s}]", .{ name, @tagName(init_info.usage) });
     }
 
-    const memory_requirements = engine.getImageMemoryRequirements(image);
-    const device_memory = try engine.allocate(memory_requirements, .{ .device_local_bit = true });
+    var device_memory: vk.DeviceMemory = .null_handle;
     errdefer engine.freeMemory(device_memory);
-    if (init_info.name) |name| {
-        engine.setObjectName(device_memory, "DM {s} [{s}]", .{ name, @tagName(init_info.usage) });
-    }
 
-    try engine.bindImageMemory(image, device_memory, 0);
+    if (init_info.device_allocation) |device_allocation| {
+        try device_allocation.bindImage(image);
+    } else {
+        const memory_requirements = engine.getImageMemoryRequirements(image);
+        device_memory = try engine.allocate(memory_requirements, .{ .device_local_bit = true });
+        if (init_info.name) |name| {
+            engine.setObjectName(device_memory, "DM {s} [{s}]", .{ name, @tagName(init_info.usage) });
+        }
+
+        try engine.bindImageMemory(image, device_memory, 0);
+    }
 
     const image_view = try engine.createImageView(.{
         .image = image,

src/engine/Textures.zig

@@ -0,0 +1,352 @@
+//! Module for loading persistent textures.
+
+const Textures = @This();
+const std = @import("std");
+
+const ctx = @import("../AppContext.zig");
+const media = @import("media");
+const vk = @import("vulkan");
+
+const Atom = @import("Atom.zig").Atom;
+const DeviceAllocation = @import("DeviceAllocation.zig");
+const Engine = @import("Engine.zig");
+const Texture = @import("Texture.zig");
+
+pub const Id = enum(u16) {
+    // VOLATILE Synchronize explicit values with `init` implementation.
+
+    /// 1×1 texture with usage `.base_color`, whose texel is read as `vec4(1)`.
+    empty_base_color = 0,
+    /// 1×1 texture with usage `.emissive`, whose texel is read as `vec4(1)`.
+    empty_emissive = 1,
+    /// 1×1 texture with usage `.normal`, whose texel is read as
+    /// `vec4(0, 0, 1, 1)`.
+    empty_normal = 2,
+    /// 1×1 texture with usage `,occlusion_roughness_metallic`, whose texel is
+    /// read as `vec4(1)`.
+    empty_occlusion_roughness_metallic = 3,
+    _,
+
+    /// Cast an integer into an ID. This can produce an invalid ID.
+    pub fn fromInt(value: u16) Id {
+        return @enumFromInt(value);
+    }
+
+    /// Cast an index into an ID. This can produce an invalid ID. The caller
+    /// asserts that the index is not greater than the max ID value.
+    pub fn fromIndex(index: usize) Id {
+        std.debug.assert(index < max_textures);
+        return @enumFromInt(@as(u16, @intCast(index)));
+    }
+
+    /// Cast an index into an ID. This can produce an invalid ID. Returns an
+    /// error if the index is greater than the max ID value.
+    pub fn fromIndexSafe(index: usize) error{Overflow}!Id {
+        if (index >= max_textures) return error.Overflow;
+        return @enumFromInt(@as(u16, @intCast(index)));
+    }
+
+    /// Cast an ID into an integer.
+    pub fn toInt(self: Id) u16 {
+        return @intFromEnum(self);
+    }
+};
+
+pub const Key = struct {
+    /// Atom representing the filename of the texture.
+    filename: Atom,
+    /// Desired usage of the texture.
+    usage: Texture.Usage,
+};
+
+/// Maps a key value to a texture ID. Preallocated with `allocator_general`.
+map: std.AutoHashMapUnmanaged(Key, Id),
+/// Stores all `Texture` structs and maps a texture ID to a `Texture` struct.
+/// Preallocated with `allocator_general`.
+array: std.ArrayList(Texture),
+device_allocation: DeviceAllocation,
+
+pub const max_textures = 4096;
+/// Enough for 4096 textures of usage `.base_color` and 64×64 dimensions.
+pub const max_memory = 64 * 1024 * 1024;
+
+pub fn init() !Textures {
+    const allocator_general = ctx.allocator_general;
+    const engine = ctx.engine;
+
+    var map: std.AutoHashMapUnmanaged(Key, Id) = .empty;
+    errdefer map.deinit(allocator_general);
+    try map.ensureTotalCapacity(allocator_general, max_textures);
+
+    var array: std.ArrayList(Texture) = try .initCapacity(allocator_general, max_textures);
+    errdefer {
+        for (array.items) |*texture| {
+            texture.deinit();
+        }
+        array.deinit(allocator_general);
+    }
+
+    var device_allocation = try engine.allocateForImage(
+        .{
+            .image_type = .@"2d",
+            .format = .r8g8b8a8_unorm,
+            .extent = .{
+                .width = 1,
+                .height = 1,
+                .depth = 1,
+            },
+            .mip_levels = 1,
+            .array_layers = 1,
+            .samples = .{ .@"1_bit" = true },
+            .tiling = .optimal,
+            .usage = .{
+                .transfer_dst_bit = true,
+                .sampled_bit = true,
+            },
+            .queue_family_indices = &.{
+                engine.graphics_queue.allocation.family,
+                engine.transfer_queue.allocation.family,
+            },
+            .initial_layout = .undefined,
+        },
+        .{ .color_bit = true },
+        max_memory,
+        .{ .device_local_bit = true },
+    );
+    errdefer engine.freeMemory(device_allocation.device_memory);
+
+    // VOLATILE Synchronize with explicit values on top of `Id` type.
+
+    const empty_base_color_texture = try Texture.init(.{
+        .width = 1,
+        .height = 1,
+        .usage = .base_color,
+        .target_queue = .graphics,
+        .device_allocation = &device_allocation,
+        .name = "@Empty",
+    });
+    array.appendAssumeCapacity(empty_base_color_texture);
+
+    const empty_emissive_texture = try Texture.init(.{
+        .width = 1,
+        .height = 1,
+        .usage = .emissive,
+        .target_queue = .graphics,
+        .device_allocation = &device_allocation,
+        .name = "@Empty",
+    });
+    array.appendAssumeCapacity(empty_emissive_texture);
+
+    const empty_normal_texture = try Texture.init(.{
+        .width = 1,
+        .height = 1,
+        .usage = .normal,
+        .target_queue = .graphics,
+        .device_allocation = &device_allocation,
+        .name = "@Empty",
+    });
+    array.appendAssumeCapacity(empty_normal_texture);
+
+    const empty_occlusuion_roughness_metallic_texture = try Texture.init(.{
+        .width = 1,
+        .height = 1,
+        .usage = .occlusion_roughness_metallic,
+        .target_queue = .graphics,
+        .device_allocation = &device_allocation,
+        .name = "@Empty",
+    });
+    array.appendAssumeCapacity(empty_occlusuion_roughness_metallic_texture);
+
+    try empty_base_color_texture.writeSamples(u8, &.{ 255, 255, 255, 255 });
+    try empty_emissive_texture.writeSamples(f16, &.{ 1.0, 1.0, 1.0, 1.0 });
+    try empty_normal_texture.writeSamples(i8, &.{ 0, 0, 127, 127 });
+    try empty_occlusuion_roughness_metallic_texture.writeSamples(u8, &.{ 255, 255, 255, 255 });
+
+    return .{
+        .map = map,
+        .array = array,
+        .device_allocation = device_allocation,
+    };
+}
+
+pub fn deinit(self: *Textures) void {
+    const allocator_general = ctx.allocator_general;
+
+    std.log.scoped(.deinit).debug("Deinitializing {*}", .{self});
+
+    for (self.array.items) |*texture| {
+        texture.deinit();
+    }
+    self.device_allocation.deinit();
+    self.array.deinit(allocator_general);
+    self.map.deinit(allocator_general);
+    self.* = undefined;
+}
+
+/// Get the ID of a texture given its filename (as a string) and usage. Returns
+/// `null` if such texture hasn't been loaded. When the filename is `null`,
+/// returns an empty texture ID appropriate for given usage.
+pub fn get(self: *const Textures, maybe_filename: ?[]const u8, usage: Texture.Usage) ?Id {
+    if (maybe_filename) |filename| {
+        return self.map.get(.{
+            // If the atom doesn't exist, then the texture cannot possibly exist.
+            .filename = .fromStringIfExists(filename) orelse return null,
+            .usage = usage,
+        });
+    } else {
+        return emptyTextureForUsage(usage);
+    }
+}
+
+/// Get the ID of a texture given its filename (as an atom) and usage. Returns
+/// `null` if such texture hasn't been loaded. When the filename is `.empty`,
+/// returns an empty texture ID appropriate for given usage.
+pub fn getAtom(self: *const Textures, filename: Atom, usage: Texture.Usage) ?Id {
+    if (filename != .empty) {
+        return self.map.get(.{
+            .filename = filename,
+            .usage = usage,
+        });
+    } else {
+        return emptyTextureForUsage(usage);
+    }
+}
+
+/// Get the ID of a texture given its filename (as a string) and usage. Returns
+/// either an existing texture ID or loads a new texture and assigns a new ID,
+/// if necessary. Will not return any error if the texture already exists. When
+/// the filename is `null`, returns an empty texture ID appropriate for given
+/// usage.
+pub fn getOrLoad(
+    self: *Textures,
+    stbi: *media.stbi,
+    maybe_filename: ?[]const u8,
+    usage: Texture.Usage,
+) !Id {
+    if (maybe_filename) |filename| {
+        const key: Key = .{
+            // If the texture already exists, then the atom must exist and the
+            // following line will not return any error.
+            .filename = try .fromString(filename),
+            .usage = usage,
+        };
+
+        // We don't use `getOrPutAssumeCapacity` method, because we might already be
+        // at full capacity, in which case we should return `error.OutOfTextures`.
+
+        if (self.map.get(key)) |id| {
+            return id;
+        } else {
+            const id = Id.fromIndexSafe(self.array.items.len) catch |err| switch (err) {
+                error.Overflow => return error.OutOfTextures,
+            };
+            const texture = try loadTexture(stbi, filename, usage, &self.device_allocation);
+
+            self.map.putAssumeCapacityNoClobber(key, id);
+            self.array.appendAssumeCapacity(texture);
+
+            return id;
+        }
+    } else {
+        return emptyTextureForUsage(usage);
+    }
+}
+
+/// Get the ID of a texture given its filename (as an atom) and usage. Returns
+/// either an existing texture ID or loads a new texture and assigns a new ID,
+/// if necessary. Will not return any error if the texture already exists. When
+/// the filename is `.empty`, returns an empty texture ID appropriate for given
+/// usage.
+pub fn getOrLoadAtom(
+    self: *Textures,
+    stbi: *media.stbi,
+    filename: Atom,
+    usage: Texture.Usage,
+) !Id {
+    if (filename != .empty) {
+        const key: Key = .{
+            .filename = filename,
+            .usage = usage,
+        };
+
+        // We don't use `getOrPutAssumeCapacity` method, because we might already be
+        // at full capacity, in which case we should return `error.OutOfTextures`.
+
+        if (self.map.get(key)) |id| {
+            return id;
+        } else {
+            const id = Id.fromIndexSafe(self.array.items.len) catch |err| switch (err) {
+                error.Overflow => return error.OutOfTextures,
+            };
+            const texture = try loadTexture(stbi, filename.toString(), usage, &self.device_allocation);
+
+            self.map.putAssumeCapacityNoClobber(key, id);
+            self.array.appendAssumeCapacity(texture);
+
+            return id;
+        }
+    } else {
+        return emptyTextureForUsage(usage);
+    }
+}
+
+fn loadTexture(
+    stbi: *media.stbi,
+    filename: []const u8,
+    usage: Texture.Usage,
+    device_allocation: *DeviceAllocation,
+) !Texture {
+    const io = ctx.io;
+
+    std.log.debug("Loading texture \"{s}\" as {s}...", .{ filename, @tagName(usage) });
+
+    const cwd = std.Io.Dir.cwd();
+
+    var dir = try cwd.openDir(io, "assets/textures", .{});
+    defer dir.close(io);
+
+    var file = try dir.openFile(io, filename, .{});
+    defer file.close(io);
+
+    // The textures are expected to be small; a standard block base color as a
+    // PNG takes well below 1 kiB.
+    var buf: [4096]u8 = undefined;
+    var reader = file.reader(io, &buf);
+
+    const img = try stbi.loadDynamicIo(&reader.interface);
+    defer stbi.freeDynamic(img);
+
+    const data = img.data[0 .. img.width * img.height];
+
+    if (usage == .normal) {
+        for (data) |*pixel| {
+            pixel.r = pixel.r +% 128;
+            pixel.g = pixel.g +% 128;
+            pixel.b = pixel.b +% 128;
+            pixel.a = pixel.a +% 128;
+        }
+    }
+
+    var texture = try Texture.init(.{
+        .width = img.width,
+        .height = img.height,
+        .usage = usage,
+        .target_queue = .graphics,
+        .device_allocation = device_allocation,
+        .name = filename,
+    });
+    errdefer texture.deinit();
+
+    try texture.writeRaw(@ptrCast(data));
+    return texture;
+}
+
+fn emptyTextureForUsage(usage: Texture.Usage) !Id {
+    return switch (usage) {
+        .base_color => .empty_base_color,
+        .normal => .empty_normal,
+        .occlusion_roughness_metallic => .empty_occlusion_roughness_metallic,
+        .emissive => .empty_emissive,
+        .depth => error.InvalidUsage,
+    };
+}