From 054ca5ea2152e5a31defbd111814020e3fd31273 Mon Sep 17 00:00:00 2001 From: abux Date: Sat, 1 Aug 2026 16:58:58 +0100 Subject: [PATCH] Slight Cleanup | Added some documentation --- src/gtl.zig | 159 ++++++++++++++++++++--------------------- src/keyed_slot_map.zig | 17 +++++ src/log.zig | 60 +++++++++++++--- src/ring_buffer.zig | 35 +++++++++ src/slot_map.zig | 17 ++++- 5 files changed, 195 insertions(+), 93 deletions(-) diff --git a/src/gtl.zig b/src/gtl.zig index 9a06967..2929486 100644 --- a/src/gtl.zig +++ b/src/gtl.zig @@ -21,7 +21,7 @@ pub const TypeID = @import("type_id.zig").of; // // --- SHADER --- -const ShaderID = union(enum) { pbr, unlit, custom: Handle([]const u8) }; +const ShaderID = union(enum) { pbr, unlit, custom: Handle(ShaderID) }; const GPUShader = struct { raw: *anyopaque }; // --- PIPELINE --- @@ -29,97 +29,86 @@ const PipelineKey = struct { shader: ShaderID }; const GPUPipeline = struct { raw: *anyopaque }; // --- MATERIAL --- -const Material = struct { +const MaterialDep = struct { shader: ShaderID = .pbr, albedo: @Vector(4, f32) = .{ 0, 0, 0, 1 }, }; +/// ---------------------------------------------------- +/// ---------------------------------------------------- +const Material = struct { + /// ---------------------------------------------------- + /// ---------------------------------------------------- + pub const Style = struct { + albedo: @Vector(4, f32) = .{ 1, 1, 1, 1 }, + metallic: f32 = 0.0, + roughness: f32 = 0.5, + }; + + /// ---------------------------------------------------- + /// ---------------------------------------------------- + pub const Unique = struct { + shader: ShaderID = .pbr, + + front_face: enum { cw, ccw } = .ccw, + cull_mode: enum { back, front, none } = .back, + topology: enum { triangle_list, point_list, line_list } = .triangle_list, + blend_mode: enum { none, alpha, additive, multiply } = .none, + }; + + // + // FIELDS + // + + style: Style = .{}, + unique: Unique = .{}, +}; + test "SlotMap" { // --- ALLOCATOR --- const alloc = std.testing.allocator; - - // - // LISTS - // + std.debug.print("{s}━━━ SLOTMAP ━━━{s}\n", .{ ansi.blue, ansi.reset }); // --- MATERIALS --- - var materials: std.ArrayList(Material) = .empty; - defer materials.deinit(alloc); - - // - // SLOT MAPS - // - - // --- SHADER MAP --- - var shaders: KeyedSlotMap(ShaderID, GPUShader) = .init(alloc); - defer shaders.deinit(); - - // --- PIPELINE MAP --- - var pipelines: KeyedSlotMap(PipelineKey, GPUPipeline) = .init(alloc); - defer pipelines.deinit(); + var materials: SlotMap(Material) = .init(alloc); + defer materials.deinit(); // --- ADD MATERIALS --- - try materials.append(alloc, .{ .shader = .pbr }); // BLACK - try materials.append(alloc, .{ .shader = .pbr, .albedo = .{ 1, 0, 0, 1 } }); // RED - try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 1, 0, 1 } }); // GREEN - try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 0, 1, 1 } }); // GREEN + _ = try materials.put(.{ .style = .{ .albedo = .{ 0.8, 0.2, 0.2, 1.0 } } }); + _ = try materials.put(.{ .unique = .{ .topology = .line_list } }); - { - // --- DEBUG --- - std.debug.print("┏━ MATERIALS\n", .{}); - defer std.debug.print("┗━\n", .{}); + // --- # --- + if (log.print(.debug, "MATERIALS", ansi.blue)) |a| { + defer a.end(); - for (materials.items) |material| { - // --- REGISTER SHADER --- - const shader = try shaders.getOrPut( - material.shader, - .{ .raw = undefined }, - ); - _ = shader; + // --- # --- + for (materials.items()) |material| { + if (a.section(.debug, "", ansi.cyan)) |b| { + defer b.end(); - // --- DEBUG --- - std.debug.print("┃ ┏━\n", .{}); - std.debug.print("┃ ┃ Shader: {s}\n", .{@tagName(material.shader)}); - std.debug.print("┃ ┃ Albedo: rgba({}, {}, {}, {})\n", .{ material.albedo[0], material.albedo[1], material.albedo[2], material.albedo[3] }); - std.debug.print("┃ ┗━\n", .{}); + // --- STYLE --- + if (b.section(.debug, "STYLE", ansi.yellow)) |style| { + defer style.end(); + + style.write("Albedo: rgba({}, {}, {}, {})", .{ material.style.albedo[0], material.style.albedo[1], material.style.albedo[2], material.style.albedo[3] }); + style.write("Metallic: {}", .{material.style.metallic}); + style.write("Roughness: {}", .{material.style.roughness}); + } + + // --- STYLE --- + if (b.section(.debug, "UNIQUE", ansi.red)) |unique| { + defer unique.end(); + + unique.write("Shader: {s}", .{@tagName(material.unique.shader)}); + unique.write("Topology: {s}", .{@tagName(material.unique.topology)}); + unique.write("Cull Mode: {s}", .{@tagName(material.unique.cull_mode)}); + } + } } } +} - { - // --- DEBUG --- - std.debug.print("┏━ SHADERS\n", .{}); - defer std.debug.print("┗━\n", .{}); - - for (shaders.items()) |entry| { - const source = switch (entry.key) { - .pbr => "assets/shaders/pbr.wgsl", - .unlit => "assets/shaders/unlit.wgsl", - .custom => "idk", - }; - - std.debug.print("┃ ┏━\n", .{}); - std.debug.print("┃ ┃ ID: {s}\n", .{@tagName(entry.key)}); - std.debug.print("┃ ┃ Source: {s}\n", .{source}); - std.debug.print("┃ ┗━\n", .{}); - } - } - - { - std.debug.print("┏━ ANSI\n", .{}); - defer std.debug.print("┗━\n", .{}); - std.debug.print( - \\{s}┃ RED - \\{s}┃ GREEN - \\{s}┃ BLUE - \\{s} - , .{ - ansi.red, - ansi.green, - ansi.blue, - ansi.reset, - }); - } - +test "SlotMap-DEP" { { // --- LOG --- log.warn("...", .{}, @src()); @@ -176,20 +165,26 @@ test "SlotMap" { if (a.section(.err, "MEMORY", ansi.green)) |b| { defer b.end(); + // --- VALUES --- b.write("VRAM -> {}GB", .{24}); } } } - var ring: RingBuffer([]const u8, 3) = .{}; + // + // RING BUFFER EXAMPLE + // - try ring.push("Hello"); - try ring.push("World"); - try ring.push("!"); + var prev_inputs: RingBuffer([]const u8, 256) = .{}; + + try prev_inputs.push("w"); + try prev_inputs.push("s"); + try prev_inputs.push("a"); + try prev_inputs.push("d"); var i: usize = 0; - while (ring.pop()) |data| { - i += 1; - std.debug.print("ring[{}] = \"{s}\"\n", .{ i, data }); + while (prev_inputs.pop()) |data| { + defer i += 1; + log.debug("[{}][PreviousInputs] -> \"{s}\"", .{ i, data }, null); } } diff --git a/src/keyed_slot_map.zig b/src/keyed_slot_map.zig index d262275..cc6b168 100644 --- a/src/keyed_slot_map.zig +++ b/src/keyed_slot_map.zig @@ -3,6 +3,23 @@ const SlotMap = @import("slot_map.zig").SlotMap; const Handle = @import("handle.zig").Handle; /// ---------------------------------------------------- +/// # Example +/// +/// ```zig +/// // --- SHADER MAP --- +/// var shaders: KeyedSlotMap(ShaderID, GPUShader) = .init(alloc); +/// defer shaders.deinit(); +/// +/// // --- PIPELINE MAP --- +/// var pipelines: KeyedSlotMap(PipelineKey, GPUPipeline) = .init(alloc); +/// defer pipelines.deinit(); +/// +/// // --- ADD MATERIALS --- +/// try materials.append(alloc, .{ .shader = .pbr }); // BLACK +/// try materials.append(alloc, .{ .shader = .pbr, .albedo = .{ 1, 0, 0, 1 } }); // RED +/// try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 1, 0, 1 } }); // GREEN +/// try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 0, 1, 1 } }); // GREEN +/// ``` /// ---------------------------------------------------- pub fn KeyedSlotMap( comptime K: type, diff --git a/src/log.zig b/src/log.zig index a200cd2..d3ea8b3 100644 --- a/src/log.zig +++ b/src/log.zig @@ -68,38 +68,38 @@ pub fn set(c: Config) void { /// ---------------------------------------------------- /// ---------------------------------------------------- -pub fn debug(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn debug(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.debug, src, fmt, args); } /// ---------------------------------------------------- /// ---------------------------------------------------- -pub fn trace(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn trace(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.trace, src, fmt, args); } /// ---------------------------------------------------- /// ---------------------------------------------------- -pub fn info(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn info(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.info, src, fmt, args); } /// ---------------------------------------------------- /// ---------------------------------------------------- -pub fn warn(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn warn(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.warn, src, fmt, args); } /// ---------------------------------------------------- /// ---------------------------------------------------- -pub fn err(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn err(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.err, src, fmt, args); } /// ---------------------------------------------------- /// Uses **@breakpoint()** /// ---------------------------------------------------- -pub fn fatal(comptime fmt: []const u8, args: anytype, src: std.builtin.SourceLocation) void { +pub fn fatal(comptime fmt: []const u8, args: anytype, src: ?std.builtin.SourceLocation) void { log(.fatal, src, fmt, args); if (@import("builtin").mode == .Debug) @breakpoint(); } @@ -160,7 +160,7 @@ pub const Print = struct { const box = boxChars(); - // Print parent's prefix. + // --- PRINT PARENT'S PREFIX --- printPrefix(self.depth, self.colors[0..self.depth]); std.debug.print("{s}{s}{s} ", .{ self.color, @@ -168,6 +168,7 @@ pub const Print = struct { ansi.reset, }); + // --- # --- std.debug.print( "{s}{s}{s}{s} {s}\n", .{ @@ -201,6 +202,45 @@ pub const Print = struct { }; /// ---------------------------------------------------- +/// # Output +/// +/// ```text +/// ┏━ DEVICE INFO +/// ┃ device -> GTX +/// ┃ vendor -> Nvidia +/// ┃ ┏━ MEMORY +/// ┃ ┃ VRAM -> 24GB +/// ┃ ┗━ +/// ┗━ +/// ``` +/// +/// # Styles +/// +/// - default +/// - rounded +/// - pipe +/// - custom +/// +/// # Example +/// +/// ```zig +/// // --- PRINT --- +/// if (log.print(.debug, "DEVICE INFO", ansi.bold ++ ansi.red)) |a| { +/// defer a.end(); +/// +/// // --- VALUES --- +/// a.write("device -> {s}", .{"GTX"}); +/// a.write("vendor -> {s}", .{"Nvidia"}); +/// +/// // --- SECTION --- +/// if (a.section(.err, "MEMORY", ansi.green)) |b| { +/// defer b.end(); +/// +/// // --- VALUES --- +/// b.write("VRAM -> {}GB", .{24}); +/// } +/// } +/// ``` /// ---------------------------------------------------- pub fn print( level: Level, @@ -251,7 +291,7 @@ fn boxChars() BoxChars { /// ---------------------------------------------------- fn log( level: Level, - src: std.builtin.SourceLocation, + src: ?std.builtin.SourceLocation, comptime fmt: []const u8, args: anytype, ) void { @@ -271,7 +311,9 @@ fn log( // --- CHECK LOCATION --- if (config.source_loc) { w.writeAll(ansi.bright_black) catch return; - w.print("({s}:{d}) ", .{ std.fs.path.basename(src.file), src.line }) catch return; + if (src) |v| { + w.print("({s}:{d}) ", .{ std.fs.path.basename(v.file), v.line }) catch return; + } w.writeAll(ansi.reset) catch return; } diff --git a/src/ring_buffer.zig b/src/ring_buffer.zig index 9926d0e..570cc4b 100644 --- a/src/ring_buffer.zig +++ b/src/ring_buffer.zig @@ -1,6 +1,41 @@ const std = @import("std"); /// ---------------------------------------------------- +/// # Common uses +/// +/// - Undo/Redo History +/// - Animation Frame History +/// - Previous Input History +/// - Event Queues +/// +/// # Styles +/// +/// - `push()` returns `error.Full` when the buffer is full +/// - `pushOverwrite()` replaces the oldest element when full +/// - `pop()` removes and returns the oldest element +/// +/// # Example +/// +/// ```zig +/// // --- LIFETIME --- +/// var prev_inputs: RingBuffer( +/// []const u8, // Type +/// 256, // Capacity +/// ) = .{}; +/// +/// // --- PUSH --- +/// try prev_inputs.push("w"); +/// try prev_inputs.push("s"); +/// try prev_inputs.push("a"); +/// try prev_inputs.push("d"); +/// +/// // --- READ --- +/// var i: usize = 0; +/// while (prev_inputs.pop()) |data| { +/// defer i += 1; +/// log.debug("[{}][PreviousInputs] -> \"{s}\"", .{ i, data }, @src()); +/// } +/// ``` /// ---------------------------------------------------- pub fn RingBuffer( comptime T: type, diff --git a/src/slot_map.zig b/src/slot_map.zig index bb90970..04254c5 100644 --- a/src/slot_map.zig +++ b/src/slot_map.zig @@ -2,6 +2,17 @@ const std = @import("std"); const Handle = @import("handle.zig").Handle; /// ---------------------------------------------------- +/// # Example +/// +/// ```zig +/// // --- MATERIALS --- +/// var materials: SlotMap(Material) = .init(alloc); +/// defer materials.deinit(); +/// +/// // --- ADD MATERIALS --- +/// _ = try materials.put(.{ .style = .{ .albedo = .{ 0.8, 0.2, 0.2, 1.0 } } }); +/// _ = try materials.put(.{ .unique = .{ .topology = .line_list } }); +/// ``` /// ---------------------------------------------------- pub fn SlotMap(comptime T: type) type { return struct { @@ -47,7 +58,7 @@ pub fn SlotMap(comptime T: type) type { pub fn put( self: *Self, value: T, - ) error{ Duplicate, OutOfMemory }!Handle(T) { + ) error{OutOfMemory}!Handle(T) { // --- NEW GENERATION --- if (self.free_list.pop()) |idx| { self.values.items[@intCast(idx)] = value; @@ -91,7 +102,9 @@ pub fn SlotMap(comptime T: type) type { // --- GENERATION --- self.generations.items[idx] +|= 1; - self.free_list.append(self.alloc, idx) catch unreachable; + self.free_list.append(self.alloc, idx) catch |err| { + std.debug.print("[SLOTMAP_ERROR] {s}\n", .{@errorName(err)}); + }; } /// ----------------------------------------------------