Slight Cleanup | Added some documentation

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;
-
+    std.debug.print("{s}━━━ SLOTMAP ━━━{s}\n", .{ ansi.blue, ansi.reset });
-    //
-    // LISTS
-    //
 
     // --- MATERIALS ---
-    var materials: std.ArrayList(Material) = .empty;
+    var materials: SlotMap(Material) = .init(alloc);
-    defer materials.deinit(alloc);
+    defer materials.deinit();
-
-    //
-    // 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();
 
     // --- ADD MATERIALS ---
-    try materials.append(alloc, .{ .shader = .pbr }); // BLACK
+    _ = try materials.put(.{ .style = .{ .albedo = .{ 0.8, 0.2, 0.2, 1.0 } } });
-    try materials.append(alloc, .{ .shader = .pbr, .albedo = .{ 1, 0, 0, 1 } }); // RED
+    _ = try materials.put(.{ .unique = .{ .topology = .line_list } });
-    try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 1, 0, 1 } }); // GREEN
-    try materials.append(alloc, .{ .shader = .unlit, .albedo = .{ 0, 0, 1, 1 } }); // GREEN
 
-    {
+    // --- # ---
-        // --- DEBUG ---
+    if (log.print(.debug, "MATERIALS", ansi.blue)) |a| {
-        std.debug.print("┏━ MATERIALS\n", .{});
+        defer a.end();
-        defer std.debug.print("┗━\n", .{});
 
-        for (materials.items) |material| {
+        // --- # ---
-            // --- REGISTER SHADER ---
+        for (materials.items()) |material| {
-            const shader = try shaders.getOrPut(
+            if (a.section(.debug, "", ansi.cyan)) |b| {
-                material.shader,
+                defer b.end();
-                .{ .raw = undefined },
-            );
-            _ = shader;
 
-            // --- DEBUG ---
+                // --- STYLE ---
-            std.debug.print("┃ ┏━\n", .{});
+                if (b.section(.debug, "STYLE", ansi.yellow)) |style| {
-            std.debug.print("┃ ┃ Shader: {s}\n", .{@tagName(material.shader)});
+                    defer style.end();
-            std.debug.print("┃ ┃ Albedo: rgba({}, {}, {}, {})\n", .{ material.albedo[0], material.albedo[1], material.albedo[2], material.albedo[3] });
+
-            std.debug.print("┃ ┗━\n", .{});
+                    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 ---
-        // --- DEBUG ---
+                if (b.section(.debug, "UNIQUE", ansi.red)) |unique| {
-        std.debug.print("┏━ SHADERS\n", .{});
+                    defer unique.end();
-        defer std.debug.print("┗━\n", .{});
 
-        for (shaders.items()) |entry| {
+                    unique.write("Shader:    {s}", .{@tagName(material.unique.shader)});
-            const source = switch (entry.key) {
+                    unique.write("Topology:  {s}", .{@tagName(material.unique.topology)});
-                .pbr => "assets/shaders/pbr.wgsl",
+                    unique.write("Cull Mode: {s}", .{@tagName(material.unique.cull_mode)});
-                .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");
+    var prev_inputs: RingBuffer([]const u8, 256) = .{};
-    try ring.push("World");
+
-    try ring.push("!");
+    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| {
+    while (prev_inputs.pop()) |data| {
-        i += 1;
+        defer i += 1;
-        std.debug.print("ring[{}] = \"{s}\"\n", .{ i, data });
+        log.debug("[{}][PreviousInputs] -> \"{s}\"", .{ i, data }, null);
     }
 }

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,

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;
     }
 

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,

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)});
+            };
         }
 
         /// ----------------------------------------------------