{"id":34852446,"url":"https://github.com/s1ddok/mtlswift","last_synced_at":"2025-12-25T19:27:34.909Z","repository":{"id":53790711,"uuid":"169735108","full_name":"s1ddok/mtlswift","owner":"s1ddok","description":"Metal shader Swift encoding code generator","archived":false,"fork":false,"pushed_at":"2023-01-02T21:33:13.000Z","size":495,"stargazers_count":69,"open_issues_count":6,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-04-14T06:38:23.036Z","etag":null,"topics":["codegen","metal","swift"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s1ddok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-08T12:56:17.000Z","updated_at":"2023-04-02T02:51:04.000Z","dependencies_parsed_at":"2023-02-01T04:15:29.782Z","dependency_job_id":null,"html_url":"https://github.com/s1ddok/mtlswift","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"purl":"pkg:github/s1ddok/mtlswift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1ddok%2Fmtlswift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1ddok%2Fmtlswift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1ddok%2Fmtlswift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1ddok%2Fmtlswift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s1ddok","download_url":"https://codeload.github.com/s1ddok/mtlswift/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s1ddok%2Fmtlswift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28035503,"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","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["codegen","metal","swift"],"created_at":"2025-12-25T19:27:23.350Z","updated_at":"2025-12-25T19:27:34.902Z","avatar_url":"https://github.com/s1ddok.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mtlswift\n\nSwift code generator for Metal encoding code. This tool enables bugs-free, rapid shader-driven development, reduces your GPU codebase by at least a factor of two and prevents any encoding bugs (i.e. wrong resources indexes, shader names etc)\n\n## Usage\n\nCurrently, `mtlswift` supports two execution commands:\n* `mtlswift generate ...`\n  This command generates encoders from provided shaders and stops execution.\n* `mtlswift watch ...`\n  This command makes mtlswift subscribe to the files changes of provided shaders and continuously update the result.\n\nThe user is able to provide multiple paths to the shaders files or folders containing them, for example:\n```Shell\nmtlswift watch ../shaders_folder/ ../../another_shaders_folder/Shaders.metal\n```\n\n\u003e WARNING: This tool currently generates encoders for [`Alloy`](https://github.com/s1ddok/Alloy) syntax. We will probably support vanilla Metal code in the future.\n\n#### CLI Options\n\nList of currently supported arguments:\n* `--output ...`, `-o`\n  This argument specifies the output file path. If multiple inputs are provided, the encoders file will contain concatenated result.\n\n* `--ignore ...`, `-i`\n  The user is able to specify folder or a file to be ignored. This argument might be passed multiple times, for example:\n  ```Shell\n  mtlswift watch . -i shaders_to_ignore.metal -i folder_to_ignore/\n  ```\n* `--recursive`, `-r`\n  This flag enables recursive search for `.metal` files in provided folders.\n\n## Syntax\n\nTo support encoders generation first of all you need to add `namespace mtlswift {}` at the beginning of the file.\n\n```C++\n#include \u003cmetal_stdlib\u003e\n\nusing namespace metal;\n\nnamespace mtlswift {}\n```\n\n### Customizing generation\n\nEvery custom annotation starts with `mtlswift:`. The program uses this declaration prefix to identify the start of a declaration. It must be written in a doc string way right before the kernel.\n  \n  ```C++\n  /// mtlswift: ...\n  kernel void exampleKernel(...\n  ```\n\n* `dispatch:`\n\n  A dispatch type to use. All of dispatch types has to be followed by either constant amount of threads via literals (like `X, Y, Z`), specifying a target texture to cover via `over:` argument or stating that amount of threads will be provided by user by using `provided`. You can see all of the examples into each section, but you can choose the combination yourself.\n\n  * `even`\n\n    Dispatch threadgroups of a uniform threadgroup size. `Width`, `height` and `depth` describe the grid size.\n    \n    ```C++\n    /// mtlswift:dispatch:even:1024, 768, 1\n    kernel void exampleKernel(texture2d\u003chalf, access::read_write\u003e inPlaceTexture [[ texture(0) ]],\n                              ...\n    ```\n\n  * `exact`\n\n    Dispatch threads with threadgroups of non-uniform size. \n    \n    ```C++\n    /// mtlswift:dispatch:exact:over:inPlaceTexture\n    kernel void exampleKernel(texture2d\u003chalf, access::read_write\u003e inPlaceTexture [[ texture(0) ]],\n                              ...\n    ```\n\n  * `optimal(function_constant_index)`\n    \n    Uses `exact` type if GPU supports non uniform threadgroup size and `over` if it doesn't. This declaration requires a boolean function constant index to be passed to make the decision what dispatch type to use.\n    \n    ```C++\n    constant bool deviceSupportsNonuniformThreadgroups [[function_constant(0)]];\n\n    /// mtlswift:dispatch:optimal(0):provided\n    kernel void exampleKernel(texture2d\u003chalf, access::read\u003e sourceTexture [[ texture(0) ]],\n                              ...\n    ```\n    \n  * `none`\n  \n    The dispatch type set by default. In this case user has to dispatch kernel manually, after calling `encode` method\n\n* `threadgroupSize:`\n\n  Specify the threadgroup size.\n  \n  * `X, Y, Z`\n  \n    Allows to specify constant X, Y and Z dimensions for threadgroup size.\n    \n  * `max`\n  \n    This parameter sets the pipeline state's [`max2dThreadgroupSize`](https://github.com/s1ddok/Alloy/blob/b82aa3fde347a81eef9551be7ffc28eec2b93bca/Alloy/MTLComputePipelineState%2BThreads.swift#L24).\n    \n  * `executionWidth`\n  \n    This parameter sets the pipeline state's [`executionWidthThreadgroupSize`](https://github.com/s1ddok/Alloy/blob/b82aa3fde347a81eef9551be7ffc28eec2b93bca/Alloy/MTLComputePipelineState%2BThreads.swift#L12).\n    \n  * `provided`\n  \n    In this case user has to pass the threadgroup size and an argument to `encode(...` function.\n\n  ```C++\n  /// mtlswift:threadgroupSize:provided\n  kernel void exampleKernel(texture2d\u003chalf, access::read\u003e sourceTexture [[ texture(0) ]],\n                            ...\n  ```\n\n* `swiftParameterType:`\n\n  The type of the buffers passed to the kernel.\n\n  ```C++\n  /// mtlswift:swiftParameterType:offset:vector_ushort2\n  /// mtlswift:swiftParameterType:intensities:vector_float3\n  kernel void exampleKernel(constant ushort2\u0026 offset [[ buffer(0) ]],\n                            constant float3\u0026 intensities [[buffer(1)]],\n                            ...\n  ```\n* `swiftParameterName:`\n\n  The name of the buffers passed to the kernel.\n\n  ```C++\n  /// mtlswift:swiftParameterName:intensities:parameters\n  kernel void exampleKernel(constant ushort2\u0026 offset [[ buffer(0) ]],\n                            constant float3\u0026 intensities [[buffer(1)]],\n                            ...\n  ```\n* `swiftName:`\n\n   Encoder's name in generated Swift code. Must be followed by a valid Swift identifier.\n   \n* `accessLevel:`\n\n   Specifies the access visibility of the encoder. Must be followed by either `public`, `open`, `internal`, `private` or `fileprivate`. `internal` is the default.\n\n# Contributors \n\n* [@eugenebokhan](https://github.com/eugenebokhan) is responsible for nice CLI that this tool has and also for docs that can guide you around\n\n## License\n\n MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1ddok%2Fmtlswift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs1ddok%2Fmtlswift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs1ddok%2Fmtlswift/lists"}