Add SDL Shadercross & GPU Examples

.github/workflows/test.yaml

@@ -36,6 +36,18 @@ jobs:
         run: zig build examples
       - name: Build Examples Windows
         run: zig build examples -Dtarget=x86_64-windows
+  gpu_examples:
+    name: Build GPU Examples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: ${{ env.ZIG_VERSION }}
+      - name: Build GPU Examples Linux
+        run: cd gpu_examples && zig build examples
+      - name: Build GPU Examples Windows
+        run: cd gpu_examples && zig build examples -Dtarget=x86_64-windows
   template:
     name: Build Template
     runs-on: ubuntu-latest

build.zig

@@ -119,6 +119,8 @@ pub fn build(b: *std.Build) !void {
     extension_options.addOption(bool, "image", ext_image);
     const ext_net = b.option(bool, "ext_net", "Enable SDL_net extension") orelse false;
     extension_options.addOption(bool, "net", ext_net);
+    const ext_shadercross = b.option(bool, "ext_shadercross", "Enable SDL_shadercross extension") orelse false;
+    extension_options.addOption(bool, "shadercross", ext_shadercross);
     const ext_ttf = b.option(bool, "ext_ttf", "Enable SDL_ttf extension") orelse false;
     extension_options.addOption(bool, "ttf", ext_ttf);
 
@@ -131,10 +133,12 @@ pub fn build(b: *std.Build) !void {
         \\{s}
         \\{s}
         \\{s}
+        \\{s}
     , .{
         if (!sdl3_main) "#define SDL_MAIN_NOIMPL\n" else "",
         if (ext_image) "#include <SDL3_image/SDL_image.h>\n" else "",
         if (ext_net) "#include <SDL3_net/SDL_net.h>\n" else "",
+        if (ext_shadercross) "#include <SDL3_shadercross/SDL_shadercross.h>\n" else "",
         if (ext_ttf) "#include <SDL3_ttf/SDL_ttf.h>\n#include <SDL3_ttf/SDL_textengine.h>\n" else "",
     });
 
@@ -192,6 +196,9 @@ pub fn build(b: *std.Build) !void {
             .target = target,
         }, sdl_system_include_path);
     }
+    if (ext_shadercross) {
+        setupSdlShadercross(b, sdl3, translate_c, sdl_dep_lib, c_sdl_preferred_linkage, cfg);
+    }
 
     _ = setupDocs(b, sdl3);
     _ = setupTest(b, cfg, extension_options, options, c_module);
@@ -200,6 +207,56 @@ pub fn build(b: *std.Build) !void {
     _ = try runExample(b, sdl3, cfg, example_options);
 }
 
+// Most of this is copied from https://github.com/Beyley/SDL_shadercross_zig/blob/master/build.zig.
+pub fn setupSdlShadercross(
+    b: *std.Build,
+    sdl3: *std.Build.Module,
+    translate_c: *std.Build.Step.TranslateC,
+    sdl_dep_lib: *std.Build.Step.Compile,
+    linkage: std.builtin.LinkMode,
+    cfg: Config,
+) void {
+    const upstream = b.lazyDependency("sdl_shadercross", .{}) orelse return;
+
+    const target = cfg.target;
+    const lib = b.addLibrary(.{
+        .name = "SDL3_shadercross",
+        .version = .{ .major = 3, .minor = 0, .patch = 0 },
+        .linkage = linkage,
+        .root_module = b.createModule(.{
+            .target = target,
+            .optimize = cfg.optimize,
+            .link_libc = true,
+        }),
+    });
+    lib.root_module.linkLibrary(sdl_dep_lib);
+
+    translate_c.addIncludePath(upstream.path("include"));
+    lib.root_module.addIncludePath(upstream.path("include"));
+    lib.root_module.addIncludePath(upstream.path("src"));
+
+    lib.root_module.addCSourceFiles(.{
+        .root = upstream.path("src"),
+        .files = &.{
+            "SDL_shadercross.c",
+        },
+    });
+
+    lib.installHeadersDirectory(upstream.path("include"), "", .{});
+
+    const spirv_headers = b.dependency("spirv_headers", .{});
+    const spirv_cross = b.dependency("spirv_cross", .{
+        .target = target,
+        .optimize = .ReleaseFast, // There is a C bug in spirv-cross upstream! Ignore undefined behavior for now.
+        .spv_cross_reflect = true,
+        .spv_cross_cpp = false,
+    });
+    lib.linkLibrary(spirv_cross.artifact("spirv-cross-c"));
+    lib.addIncludePath(spirv_headers.path("include/spirv/1.2/"));
+
+    sdl3.linkLibrary(lib);
+}
+
 pub fn setupDocs(b: *std.Build, sdl3: *std.Build.Module) *std.Build.Step {
     const sdl3_lib = b.addLibrary(.{
         .root_module = sdl3,

build.zig.zon

@@ -3,6 +3,14 @@
     .version = "0.1.5",
     .minimum_zig_version = "0.15.1",
     .dependencies = .{
+        .freetype = .{
+            .url = "git+https://github.com/allyourcodebase/freetype.git#9d847affbd224cf6a7303ad6d98715e3675ef78c",
+            .hash = "freetype-2.13.3-C3-WdeyJAAD9z8BeYYQ8N3gNlPI9NvHRxg5039S5vhz7",
+        },
+        .harfbuzz = .{
+            .url = "git+https://github.com/allyourcodebase/harfbuzz#6bb522d22cee0ce1d1446bd59fa5b0417f25303e",
+            .hash = "harfbuzz-8.5.0-Ip1VAqCZAADRh-K2AVujG0N3VAal-AKwkZrvlYOaloyB",
+        },
         .sdl = .{
             .url = "git+https://github.com/castholm/SDL.git?ref=v0.3.1%2B3.2.24#1d4b8dcc03bd216712b55318b4ad2402b5511490",
             .hash = "sdl-0.3.1+3.2.24-7uIn9L9AfwFQf90JcTh3Slw__ZA8SEomk6fQI9F8ItY0",
@@ -17,18 +25,22 @@
             .hash = "N-V-__8AAK74BwCyuisw6wdXWDDg8sXuHJd_tPk1VKxLTUBK",
             .lazy = true,
         },
+        .sdl_shadercross = .{
+            .url = "git+https://github.com/libsdl-org/SDL_shadercross#392d12afc1ef084c5cd656307180027399b7a54e",
+            .hash = "N-V-__8AAH9GBgCySY9rt5VJj3A-OGl0Z05BPZ9PgS5Pt1zm",
+        },
         .sdl_ttf = .{
             .url = "git+https://github.com/libsdl-org/SDL_ttf#release-3.2.2",
             .hash = "N-V-__8AAF2JgAA_Y5Qzm3b226N8y7ivM-qFVpCo9NkbfO8Y",
             .lazy = true,
         },
-        .harfbuzz = .{
-            .url = "git+https://github.com/allyourcodebase/harfbuzz#6bb522d22cee0ce1d1446bd59fa5b0417f25303e",
-            .hash = "harfbuzz-8.5.0-Ip1VAqCZAADRh-K2AVujG0N3VAal-AKwkZrvlYOaloyB",
+        .spirv_cross = .{
+            .url = "git+https://github.com/Gota7/spirv_cross-zig#75cfd40f81f63a678d70d7e3de021edd944eb553",
+            .hash = "spirv_cross-0.0.0-bzNVZC4YAADQdsxyfpxC9Iw8xxietH7xoEQxbHY43bmo",
         },
-        .freetype = .{
-            .url = "git+https://github.com/allyourcodebase/freetype.git#9d847affbd224cf6a7303ad6d98715e3675ef78c",
-            .hash = "freetype-2.13.3-C3-WdeyJAAD9z8BeYYQ8N3gNlPI9NvHRxg5039S5vhz7",
+        .spirv_headers = .{
+            .url = "git+https://github.com/KhronosGroup/SPIRV-Headers#1bfd27101e4578d0284061bdf8f09fb4755c7c2d",
+            .hash = "N-V-__8AADq1MQCCoUh-qOkYXGvqKFClPzdiedYrsGFYzTV9",
         },
     },
     .paths = .{

gpu_examples/README.md

@@ -0,0 +1,40 @@
+# SDL3 GPU Examples
+Zig examples of using SDL3's GPU subsystem along with shadercross to run all provided shader formats on the target. SDL shadercross bridges the platform shader format gap such that the shaders "just work" everywhere.
+
+## Build System
+You can use `zig build examples` to build all of the example executables, and `zig build run -Dexample=example-zig-file-here` (Ex: `-Dexample=basic-triangle`) to run a particular example. You may also specify the shader format to use with `-Dshader_format`. Note that the default format is `zig`. You are free to use the build system as a reference for building your own project's, taking the shader format you like most.
+
+Zig shaders use `spirv-opt` on the system to optimize the result of SPIR-V as zig does not optimize SPIR-V iirc? Also, you may not compile zig shaders on a Windows system at the moment [due to this issue](https://github.com/ziglang/zig/issues/23883). There is nothing stopping you from cross-compiling for a Windows system, but doing dev from a Windows environment would be unfun.
+
+GLSL shaders use `glslang` on the system in order to compile GLSL into SPIR-V binaries.
+
+HLSL shaders are compiled at runtime using SDL shadercross. Note that nothing is stopping you from pre-compiling HLSL into SPIR-V using `glslang` if runtime flexibility is not needed.
+
+## Shader Formats
+Each shader format has its own ups and downs.
+
+### Zig
+Pros:
+* It's zig
+* Tooling already installed with the compiler
+
+Cons:
+* Inline assembly required for more complex tasks
+* External tool required at compile time to maximize performance
+* No runtime recompilation support
+
+### Compiled GLSL/HLSL
+Pros:
+* Normal shading language
+
+Cons:
+* Requires `glslang` or other shader compiler at build time
+* No runtime recompilation support
+
+### Runtime HLSL
+Pros:
+* Runtime recompilation support
+* Normal shading language
+
+Cons:
+* Requires additional less-flexible dependencies for SDL shadercross