{"id":22909098,"url":"https://github.com/castholm/zigglgen","last_synced_at":"2025-04-06T03:05:24.914Z","repository":{"id":158830175,"uuid":"589364881","full_name":"castholm/zigglgen","owner":"castholm","description":"Zig OpenGL binding generator","archived":false,"fork":false,"pushed_at":"2025-03-06T21:57:39.000Z","size":1560,"stargazers_count":102,"open_issues_count":0,"forks_count":14,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T02:03:49.101Z","etag":null,"topics":["bindings","opengl","zig","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":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/castholm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2023-01-15T23:09:41.000Z","updated_at":"2025-03-28T07:57:19.000Z","dependencies_parsed_at":"2024-03-02T19:22:24.567Z","dependency_job_id":"72ee7334-c07d-41b9-85d2-76ac47bc3888","html_url":"https://github.com/castholm/zigglgen","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castholm%2Fzigglgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castholm%2Fzigglgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castholm%2Fzigglgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/castholm%2Fzigglgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/castholm","download_url":"https://codeload.github.com/castholm/zigglgen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427005,"owners_count":20937200,"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":["bindings","opengl","zig","zig-package"],"created_at":"2024-12-14T03:34:48.892Z","updated_at":"2025-04-06T03:05:24.886Z","avatar_url":"https://github.com/castholm.png","language":"Zig","funding_links":[],"categories":["Zig"],"sub_categories":[],"readme":"\u003c!--\n© 2024 Carl Åstholm\nSPDX-License-Identifier: MIT\n--\u003e\n\n# zigglgen\n\nThe only Zig OpenGL binding generator you need.\n\n## Installation and usage\n\nzigglgen currently supports the following versions of the Zig compiler:\n\n- `0.14.0`\n- `0.15.0-dev` (master)\n\nOlder or more recent versions of the compiler are not guaranteed to be compatible.\n\n1\\. Run `zig fetch` to add the zigglgen package to your `build.zig.zon` manifest:\n\n```sh\nzig fetch --save git+https://github.com/castholm/zigglgen.git\n```\n\n2\\. Generate a set of OpenGL bindings in your `build.zig` build script:\n\n```zig\nconst std = @import(\"std\");\n\npub fn build(b: *std.Build) void {\n    const exe_mod = b.createModule(...);\n\n    // Choose the OpenGL API, version, profile and extensions you want to generate bindings for.\n    const gl_bindings = @import(\"zigglgen\").generateBindingsModule(b, .{\n        .api = .gl,\n        .version = .@\"4.1\",\n        .profile = .core,\n        .extensions = \u0026.{ .ARB_clip_control, .NV_scissor_exclusive },\n    });\n\n    // Import the generated module.\n    exe_mod.addImport(\"gl\", gl_bindings);\n}\n```\n\n3\\. Initialize OpenGL and start issuing commands:\n\n```zig\nconst windowing = @import(...);\nconst gl = @import(\"gl\");\n\n// Procedure table that will hold OpenGL functions loaded at runtime.\nvar procs: gl.ProcTable = undefined;\n\npub fn main() !void {\n    // Create an OpenGL context using a windowing system of your choice.\n    const context = windowing.createContext(...);\n    defer context.destroy();\n\n    // Make the OpenGL context current on the calling thread.\n    windowing.makeContextCurrent(context);\n    defer windowing.makeContextCurrent(null);\n\n    // Initialize the procedure table.\n    if (!procs.init(windowing.getProcAddress)) return error.InitFailed;\n\n    // Make the procedure table current on the calling thread.\n    gl.makeProcTableCurrent(\u0026procs);\n    defer gl.makeProcTableCurrent(null);\n\n    // Issue OpenGL commands to your heart's content!\n    const alpha: gl.float = 1;\n    gl.ClearColor(1, 1, 1, alpha);\n    gl.Clear(gl.COLOR_BUFFER_BIT);\n }\n```\n\nSee [castholm/zig-examples](https://github.com/castholm/zig-examples) for example projects.\n\n## API\n\nSee [this gist](https://gist.github.com/castholm/a99b650cdd523244b456c7597e321e6e) for a preview of what the generated\ncode might look like.\n\n### OpenGL symbols\n\nzigglgen generates declarations for OpenGL functions, constants, types and extensions using the original names as\ndefined in the various OpenGL specifications (as opposed to the prefixed names used in C).\n\n|           | C                     | Zig                |\n|-----------|:----------------------|:-------------------|\n| Command   | `glClearColor`        | `ClearColor`       |\n| Constant  | `GL_TRIANGLES`        | `TRIANGLES`        |\n| Type      | `GLfloat`             | `float`            |\n| Extension | `GL_ARB_clip_control` | `ARB_clip_control` |\n\n### `info`\n\n```zig\npub const info = struct {};\n```\n\nContains information about the generated set of OpenGL bindings, such as the OpenGL API, version and profile the\nbindings were generated for.\n\n### `ProcTable`\n\n```zig\npub const ProcTable = struct {};\n```\n\nHolds pointers to OpenGL functions loaded at runtime.\n\nThis struct is very large, so you should avoid storing instances of it on the stack. Use global variables or allocate\nthem on the heap instead.\n\n### `ProcTable.init`\n\n```zig\npub fn init(procs: *ProcTable, loader: anytype) bool {}\n```\n\nInitializes the specified procedure table and returns `true` if successful, `false` otherwise.\n\nA procedure table must be successfully initialized before passing it to `makeProcTableCurrent` or accessing any of\nits fields.\n\n`loader` is duck-typed. Given the prefixed name of an OpenGL command (e.g. `\"glClear\"`), it should return a pointer to\nthe corresponding function. It should be able to be used in one of the following two ways:\n\n- `@as(?PROC, loader(@as([*:0]const u8, prefixed_name)))`\n- `@as(?PROC, loader.getProcAddress(@as([*:0]const u8, prefixed_name)))`\n\nIf your windowing system has a \"get procedure address\" function, it is usually enough to simply pass that function as\nthe `loader` argument.\n\nNo references to `loader` are retained after this function returns.\n\nThere is no corresponding `deinit` function.\n\n### `makeProcTableCurrent`\n\n```zig\npub fn makeProcTableCurrent(procs: ?*const ProcTable) void {}\n```\n\nMakes the specified procedure table current on the calling thread.\n\nA valid procedure table must be made current on a thread before issuing any OpenGL commands from that same thread.\n\n### `getCurrentProcTable`\n\n```zig\npub fn getCurrentProcTable() ?*const ProcTable {}\n```\n\nReturns the procedure table that is current on the calling thread.\n\n### `extensionSupported`\n\n(Only generated if at least one extension is specified.)\n\n```zig\npub fn extensionSupported(comptime extension: Extension) bool {}\n```\n\nReturns `true` if the specified OpenGL extension is supported by the procedure table that is current on the calling\nthread, `false` otherwise.\n\n## FAQ\n\n### Which OpenGL APIs are supported?\n\nAny APIs, versions, profiles and extensions included in Khronos's [OpenGL XML API\nRegistry](https://github.com/KhronosGroup/OpenGL-Registry/tree/main/xml) are supported. These include:\n\n- OpenGL 1.0 through 3.1\n- OpenGL 3.2 through 4.6 (Compatibility/Core profile)\n- OpenGL ES 1.1 (Common/Common-Lite profile)\n- OpenGL ES 2.0 through 3.2\n- OpenGL SC 2.0\n\nThe [`updateApiRegistry.ps1`](updateApiRegistry.ps1) PowerShell script is used to fetch the API registry and convert it\nto a set of Zig source files that are committed to revision control and used by zigglgen.\n\n### Why is a thread-local procedure table required?\n\nPer the OpenGL spec, OpenGL function pointers loaded when one OpenGL context is current are not guaranteed to remain\nvalid when a different context becomes current. This means that it would be incorrect to load a single set of function\npointers to global memory just once at application startup and then have them be shared by all current and future\nOpenGL contexts.\n\nIn order to support portable multi-threaded multi-context OpenGL applications, it must be possible to load multiple sets\nof function pointers. Because OpenGL contexts are already thread-local, it makes a lot of sense to handle function\npointers in a similar manner.\n\n### Why aren't OpenGL constants represented as Zig enums?\n\nThe short answer is that it's simply not possible to represent groups of OpenGL constants as Zig enums in a\nsatisfying manner:\n\n- The API registry currently specifies some of these groups, but far from all of them, and the groups are not guaranteed\n  to be complete. Groups can be extended by extensions, so Zig enums would need to be defined as non-exhaustive, and\n  using constants not specified as part of a group would require casting.\n- Some commands like *GetIntegerv* that can return constants will return them as plain integers. Comparing the returned\n  values against Zig enum fields would require casting.\n- Some constants in the same group are aliases for the same value, which makes them impossible to represent as\n  Zig enums.\n\n### Why did calling a supported extension function result in a null pointer dereference?\n\nCertain OpenGL extension add features that are only conditionally available under certain OpenGL versions/profiles or\nwhen certain other extensions are also supported; for example, the *VertexWeighthNV* command from the *NV_half_float*\nextension is only available when the *EXT_vertex_weighting* extension is also supported. Unfortunately, the API registry\ndoes not specify these interactions in a consistent manner, so it's not possible for zigglgen to generate code that\nensures that calls to supported extension functions are always safe.\n\nIf you use OpenGL extensions it is your responsibility to read the extension specifications carefully and understand\nunder which conditions their features are available.\n\n### Why can't I pass my windowing system's `getProcAddress` function to `ProcTable.init`?\n\nIt might have the wrong signature, such as taking a `[:0]const u8` (0-terminated slice) instead of a `[*:0]const u8`\n(0-terminated many-pointer), or returning a pointer without an alignment qualifier. To fix this, define your own\nfunction that wraps the windowing system's function and corrects the mismatch:\n\n```zig\nfn fixedGetProcAddress(prefixed_name: [*:0]const u8) ?gl.PROC {\n    return @alignCast(windowing.getProcAddress(std.mem.span(prefixed_name)));\n}\n\n// ...\n\nif (!gl_procs.init(fixedGetProcAddress)) return error.InitFailed;\n```\n\n## Contributing\n\nIf you have any issues or suggestions, please open an issue or a pull request.\n\n### Help us define overrides for function parameters and return types!\n\nDue to the nature of the API Registry being designed for C, zigglgen currently generates most pointers types as `[*c]`\npointers, which is less than ideal. A long-term goal for zigglgen is for every single pointer type to be correctly\nannotated. There are approximately 3300 commands defined in the API registry and if we work together, we can achieve\nthat goal sooner. Even fixing up just a few commands would mean a lot!\n\nOverriding parameters/return types is very easy; all you need to do is add additional entries to the\n`paramOverride`/`returnTypeOverride` functions in [`zigglgen.zig`](zigglgen.zig), then open a pull request with your\nchanges (bonus points if you also reference relevant OpenGL references page or specifications in the description of your\npull request).\n\n## License\n\nThis repository is [REUSE-compliant](https://reuse.software/). The effective SPDX license expression for the repository as a whole is:\n\n```\nApache-2.0 AND MIT\n```\n\nCopyright notices and license texts have been reproduced in [`LICENSE.txt`](LICENSE.txt), for your convenience.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastholm%2Fzigglgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcastholm%2Fzigglgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcastholm%2Fzigglgen/lists"}