{"id":27407833,"url":"https://github.com/bronter/wgpu_native_zig","last_synced_at":"2025-04-14T07:18:20.354Z","repository":{"id":248802809,"uuid":"826021826","full_name":"bronter/wgpu_native_zig","owner":"bronter","description":"Zig bindings for wgpu-native","archived":false,"fork":false,"pushed_at":"2025-04-01T22:17:57.000Z","size":161,"stargazers_count":31,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T07:18:13.115Z","etag":null,"topics":["wgpu-native","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bronter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-09T00:58:31.000Z","updated_at":"2025-04-10T11:02:04.000Z","dependencies_parsed_at":"2025-01-04T01:27:21.429Z","dependency_job_id":"59434340-2900-496a-8177-778bc21aa1d5","html_url":"https://github.com/bronter/wgpu_native_zig","commit_stats":null,"previous_names":["bronter/wgpu-native-zig","bronter/wgpu_native_zig"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bronter%2Fwgpu_native_zig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bronter%2Fwgpu_native_zig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bronter%2Fwgpu_native_zig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bronter%2Fwgpu_native_zig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bronter","download_url":"https://codeload.github.com/bronter/wgpu_native_zig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837231,"owners_count":21169374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wgpu-native","zig-package"],"created_at":"2025-04-14T07:18:18.956Z","updated_at":"2025-04-14T07:18:20.338Z","avatar_url":"https://github.com/bronter.png","language":"Zig","funding_links":[],"categories":["Zig"],"sub_categories":[],"readme":"# wgpu_native_zig\nZig bindings for [wgpu-native](https://github.com/gfx-rs/wgpu-native)\n\nThis package exposes two modules: `wgpu-c` and `wgpu`.\n\n`wgpu-c` is just `wgpu.h` (and by extension `webgpu.h`) run through `translate-c`, so as close to wgpu-native's original C API as is possible in Zig.\n\n`wgpu` is a module full of pure Zig bindings for `libwgpu_native`, it does not import any C code and instead relies on `extern fn` declarations to hook up to `wgpu-native`.\n\n## Adding this package to your build\nAdd the package to your dependencies, either with:\n```sh\nzig fetch --save https://github.com/bronter/wgpu_native_zig/archive/refs/tags/v5.0.0.tar.gz\n```\nor by manually adding to your `build.zig.zon`:\n```zig\n.{\n    // ...other stuff\n    .dependencies = .{\n        // ...other dependencies\n        .wgpu_native_zig = .{\n            // You can either use a commit hash:\n            .url=\"https://github.com/bronter/wgpu_native_zig/archive/\u003ccommit_hash\u003e.tar.gz\",\n            // or a tagged release:\n            // .url = \"https://github.com/bronter/wgpu_native_zig/archive/refs/tags/v5.0.0.tar.gz`\n            .hash=\"\u003cdependency hash\u003e\"\n        }\n    }\n}\n```\nThen, in `build.zig` add:\n```zig\n    const wgpu_native_dep = b.dependency(\"wgpu_native_zig\", .{});\n\n    // Add module to your exe (wgpu-c can also be added like this, just pass in \"wgpu-c\" instead)\n    exe.root_module.addImport(\"wgpu\", wgpu_native_dep.module(\"wgpu\"));\n    // Or, add to your lib similarly:\n    lib.root_module.addImport(\"wgpu\", wgpu_native_dep.module(\"wgpu\"));\n```\n\n### Building on Windows\nWindows x86_64 has two options for ABI: GNU and MSVC. For i686 and aarch64, only the MSVC option is available.\nIf you need to specify the build target, you can do that with:\n```zig\nconst target = b.standardTargetOptions(.{\n    .default_target = .{\n        // If not specified, defaults to the GNU abi\n        .abi = .msvc,\n    }\n});\n```\nOr, specify it with your build command. For example, the triangle example in this repository can be run like so:\n```sh\nzig build run-triangle-example -Dtarget=x86_64-windows-msvc\n```\nEither way, pass the resolved target to the dependency like so:\n```zig\nconst wgpu_native_dep = b.dependency(\"wgpu_native_zig\", .{\n  .target = target\n});\n```\nAn example of using `wgpu-native-zig` with static linking on Windows can be found at [wgpu-native-zig-windows-test](https://github.com/bronter/wgpu-native-zig-windows-test).\n\n### Dynamic linking\nDynamic linking can be made to work, though it is a bit messy to use.\nWhen you initialize your `wgpu_native_dep`, add the option for dynamic linking like so:\n```zig\nconst wgpu_native_dep = b.dependency(\"wgpu_native_zig\", .{\n  // Defaults to .static if you don't specify\n  .link_mode = .dynamic\n});\n```\nThen add the following with your install step dependencies:\n```zig\nconst lib_dir = wgpu_native_dep.namedWriteFiles(\"lib\").getDirectory();\n\n// This would also work with .so files on linux\nconst dll_path = lib_dir.join(b.allocator, \"wgpu_native.dll\") catch return;\n\n// addInstallBinFile puts the dll in the same directory as your executable\nconst install_dll = b.addInstallBinFile(dll_path, \"wgpu_native.dll\");\n\n// Make sure that the dll is installed when the install step is run\nb.getInstallStep().dependOn(\u0026install_dll.step);\n```\n\n\n## How the `wgpu` module differs from `wgpu-c`\n* Names are shortened to remove redundancy.\n  * For example `wgpu.WGPUSurfaceDescriptor` becomes `wgpu.SurfaceDescriptor`\n* C pointers (`[*c]`) are replaced with more specific pointer types.\n  * For example `[*c]const u8` is replaced with `?[*:0]const u8`.\n* Pointers to opaque structs are made explicit (and only optional when they need to be).\n  * For example `wgpu.WGPUAdapter` from `webgpu.h` would instead be expressed as `*wgpu.Adapter` or `?*wgpu.Adapter`, depending on the context.\n* Methods are expressed as decls inside of structs\n  * For example \n    ```zig\n    wgpu.wgpuInstanceCreateSurface(instance: WGPUInstance, descriptor: [*c]const WGPUSurfaceDescriptor) WGPUSurface\n    ``` \n    becomes\n    ```zig\n    Instance.createSurface(self: *Instance, descriptor: *const SurfaceDescriptor) ?*Surface\n    ```\n* Certain methods that require a callback such as requestAdapter and requestDevice are provided with wrapper methods.\n  * For example, requesting an adapter with a callback looks something like\n    ```zig\n    fn handleRequestAdapter(status: RequestAdapterStatus, adapter: ?*Adapter, message: ?[*:0]const u8, userdata: ?*anyopaque) callconv(.C) void {\n        switch(status) {\n            .success =\u003e {\n                const ud_adapter: **Adapter = @ptrCast(@alignCast(userdata));\n                ud_adapter.* = adapter.?;\n            },\n            else =\u003e {\n              std.log.err(\"{s}\\n\", .{message});\n            }\n        }\n    }\n    var adapter_ptr: ?*Adapter = null;\n    instance.requestAdapter(null, handleRequestAdapter, @ptrCast(\u0026adapter_ptr));\n    ```\n    whereas the non-callback version looks like\n    ```zig\n    const response = instance.requestAdapterSync(null);\n\n    // Unfortunately propagating anything more than status codes is ugly in Zig;\n    // see https://github.com/ziglang/zig/issues/2647\n    const adapter_ptr: ?*Adapter = switch (response.status) {\n        .success =\u003e response.adapter,\n        else =\u003e blk: {\n            std.log.err(\"{s}\\n\", .{response.message});\n            break :blk null;\n        }\n    };\n    ```\n* Chained structs are provided with inline functions for constructing them, which come in two forms depending on whether or not the chained struct is likely to always be required.\n  * For required chained structs, you can either write them explicitely:\n    ```zig\n    SurfaceDescriptor{\n        .next_in_chain = @ptrCast(\u0026SurfaceDescriptorFromXlibWindow {\n            .chain = ChainedStruct {\n                .s_type = SType.surface_descriptor_from_xlib_window,\n            },\n            .display = display,\n            .window = window,\n        }),\n        .label = \"xlib_surface_descriptor\",\n    };\n    ```\n    or use a function to construct them:\n    ```zig\n    // Here the descriptors from SurfaceDescriptor and SurfaceDescriptorFromXlibWindow have been merged,\n    // so just pass in an anonymous struct with the things that you need; default values will take care of the rest.\n    surfaceDescriptorFromXlibWindow(.{\n        .label = \"xlib_surface_descriptor\",\n        .display = display,\n        .window = window\n    });\n    ```\n  * For optional chained structs, you can either write them explicitely like in the example above, or you can use a method of the parent struct instance to add them, for example:\n    ```zig\n    \u0026(PrimitiveState {\n      .topology = PrimitiveTopology.triangle_list,\n      .strip_index_format = IndexFormat.uint16,\n      .front_face = FrontFace.ccw,\n      .cull_mode = CullMode.back,\n    }).withDepthClipControl(false);\n    ```\n* `WGPUBool` is replaced with `bool` whenever possible.\n  * This pretty much means, it is replaced with `bool` in the parameters and return values of methods, but not in structs or the parameters/return values of procs (which are supposed to be function pointers to things returned by `wgpuGetProcAddress`).\n\n## TODO\n* Test this on other machines with different OS/CPU. Currently only tested on x86_64-linux-gnu and x86_64-windows (msvc and gnu); zig version 0.14.0.\n* Cleanup/organization: \n  * If types are only tied to a specific opaque struct, they should be decls inside that struct.\n    * For example, `ShaderModuleGetCompilationInfoCallback` should be `ShaderModule.GetCompilationInfoCallback`, since that callback type isn't used anywhere outside of the context of `ShaderModule`.\n  * The associated Procs struct should probably be a decl of the opaque struct as well.\n  * There are many things that seem to be in the wrong file.\n    * For example a lot of what is in `pipeline.zig` is actually only used by `Device`, and should probably be in `device.zig` instead.\n  * Since pointers to opaque structs are made explicit, it would be more consistent if pointers to callback functions are explicit as well.\n* Port [wgpu-native-examples](https://github.com/samdauwe/webgpu-native-examples) using wrapper code, as a basic form of documentation.\n* Custom-build `wgpu-native`; provided all the necessary tools/dependencies are present.\n* Bindgen using [the webgpu-headers yaml](https://github.com/webgpu-native/webgpu-headers/blob/main/webgpu.yml)?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbronter%2Fwgpu_native_zig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbronter%2Fwgpu_native_zig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbronter%2Fwgpu_native_zig/lists"}