{"id":21703546,"url":"https://github.com/jolifantobambla/shadercl","last_synced_at":"2026-02-06T16:03:06.107Z","repository":{"id":107321656,"uuid":"349072138","full_name":"JolifantoBambla/shadercl","owner":"JolifantoBambla","description":"Common Lisp/CFFI bindings for shaderc.","archived":false,"fork":false,"pushed_at":"2021-07-21T08:29:11.000Z","size":142,"stargazers_count":7,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-11T15:33:00.771Z","etag":null,"topics":["cffi","glsl","hlsl","shaderc","spir-v","spirv","vulkan"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","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/JolifantoBambla.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":"2021-03-18T12:50:34.000Z","updated_at":"2023-08-18T07:07:09.000Z","dependencies_parsed_at":"2023-04-24T11:47:43.439Z","dependency_job_id":null,"html_url":"https://github.com/JolifantoBambla/shadercl","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/JolifantoBambla/shadercl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JolifantoBambla%2Fshadercl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JolifantoBambla%2Fshadercl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JolifantoBambla%2Fshadercl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JolifantoBambla%2Fshadercl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JolifantoBambla","download_url":"https://codeload.github.com/JolifantoBambla/shadercl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JolifantoBambla%2Fshadercl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29167870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T15:38:29.831Z","status":"ssl_error","status_checked_at":"2026-02-06T15:37:48.592Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cffi","glsl","hlsl","shaderc","spir-v","spirv","vulkan"],"created_at":"2024-11-25T21:33:20.265Z","updated_at":"2026-02-06T16:03:06.064Z","avatar_url":"https://github.com/JolifantoBambla.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shadercl\nCommon Lisp/CFFI bindings for [shaderc](https://github.com/google/shaderc).\n\n`shaderc` allows you to compile GLSL and HLSL shaders to SPIR-V at runtime from your REPL.\n\n## Requirements\n\n### External Requirements\n* [shaderc](https://github.com/google/shaderc): the target version is `v2021.1` but the API is not likely to change much, so other versions will probably work as well. `shaderc` is included in the [Vulkan SDK](https://vulkan.lunarg.com/sdk/home) (beginning with version `1.2.135`, so you might want to follow the installation instructions there.\n\n### Common Lisp Dependencies\nAll CL dependencies are installable via `quicklisp`:\n\n* alexandria\n* cffi\n\n### Supported CL implementations \u0026 Operating Systems\n`shaderc` has been tested on Linux (Ubuntu 20.04) and Windows 10 (currently only tested with SBCL).\n\nThe following implementations are known to work and tested via GitHub Actions:\n\n* SBCL\n* CCL\n* ABCL\n* ECL\n\n## Installation\nThis project is not on `quicklisp` yet, but you can clone the repository to one of your `ql:*local-project-directories*` and load it via:\n\n```cl\n(ql:quickload :shaderc)\n```\n\n## Usage\n\nThe system consists of two packages:\n\n* `%shaderc` contains the lower level `cffi` bindings\n* `shaderc` contains some higher level functions using `%shaderc`\n\nTo compile a GLSL vertex shader to a SPIR-V binary, you can use the function `shaderc:compile-to-spv`.\nThe result of this function can be used directly to bind the `code` slot of a `vk:shader-module-create-info` (see [vk](https://github.com/JolifantoBambla/vk#vkshadermodulecreateinfo)).\n\nE.g.:\n\n```cl\n(defparameter vertex-shader \"\n#version 400\n\n#extension GL_ARB_separate_shader_objects : enable\n#extension GL_ARB_shading_language_420pack : enable\n\nlayout (std140, binding = 0) uniform buffer {\n       mat4 mvpc;\n} uniformBuffer;\n\nlayout (location = 0) in vec4 pos;\nlayout (location = 1) in vec4 inColor;\n\nlayout (location = 0) out vec4 outColor;\n\nvoid main() {\n   outColor = inColor;\n   gl_Position = uniformBuffer.mvpc * pos;\n}\")\n\n(compile-to-spv vertex-shader :vertex-shader)\n```\n\n### Compilation Options\n\nThe various compilation options the `shaderc` compiler offers, can be set via an instance of `shaderc:compile-options-set`.\nEach option is represented as a slot of this class. The following is a list of the supported options:\n\n```cl\n\"MACROS - A hash map of predefined macros and their values which should be added to the compilation options.\n  The name of each macro must be a string. The value of a macro can be a string or NIL.\n  Passing these macros to the compilation options has the same  effect as passing -Dname=value to the command-line compiler.\n  If value is NIL, it has the same effect as passing -Dname to the command-line compiler.\n\nLANG - The source language (i.e. a %SHADERC:SOURCE-LANGUAGE).\n  Defaults to :GLSL.\n\nGENERATE-DEBUG-INFO - If this is truthy, debug information is generated.\n\nOPTIMIZATION-LEVEL - The optimization level to use during compilation (i.e. a %SHADERC:OPTIMIZATION-LEVEL.\n  Defaults to :ZERO.\n\nFORCED-VERSION-PROFILE - Forces the GLSL language version and profile to a given pair in the format: (version profile)\n  The version is the same as it would appear in the #version annotation in the source.\n  The profile is a %SHADERC:PROFILE.\n  Version and profile specified here overrides the #version annotation in the source.\n\nINCLUDE-RESOLVE-CALLBACK - An includer callback type for mapping an #include request to an include result.\n  Must have the signature:\n    (cffi:defcallback \u003cname\u003e (:pointer (:struct %shaderc:include-result)) ((user-data :pointer)\n                                                                           (requested-source :string)\n                                                                           (include-type %shaderc:include-type)\n                                                                           (requesting-source :string)\n                                                                           (include-depth %shaderc:size-t)))\n  The user_data parameter specifies the client context.\n  The requested_source parameter specifies the name of the source being requested.\n  The type parameter specifies the kind of inclusion request being made.\n  The requesting_source parameter specifies the name of the source containing the #include request.\n  The includer owns the result object and its contents, and both must remain valid until the release callback is called on the result object.\n  Defaults to: DEFAULT-INCLUDE-RESOLVE-CALLBACK\n\nINCLUDE-RESULT-RELEASE-CALLBACK - An includer callback type for destroying an include result.\n  Must have the signature:\n    (cffi:defcallback \u003cname\u003e :void ((user-data :pointer)\n                                    (include-result (:pointer (:struct %shaderc:include-result)))))\n  Defaults to: DEFAULT-INCLUDE-RESULT-RELEASE-CALLBACK\n\nUSER-DATA - A pointer specifying the client context for INCLUDE-RESOLVE-CALLBACK and INCLUDE-RESULT-RELEASE-CALLBACK.\n  Defaults to: CFFI:NULL-POINTER\n\nSUPPRESS-WARNINGS - If this is truthy, warnings are suppressed.\n  This overrides WARNINGS-AS-ERRORS.\n\nTARGET-ENV - The target shader environment, affecting which warnings or errors will be issued.\n  The target environment must be given in a list in the following format: (target-env env-version),\n  where target-env is a %SHADERC:TARGET-ENV and env-version is a %SHADERC:ENV-VERSION.\n\nTARGET-SPIRV - The target SPIR-V version (i.e. a %SHADERC:SPIRV-VERSION).\n  Generated modules will use this version of SPIR-V.\n\nWARNINGS-AS-ERRORS - If this is truthy, warnings are treated as errors.\n  This is overridden by SUPPRESS-WARNINGS if both are set.\n\nLIMITS - A hash map of limits for resources.\n  Its keys are keywords from %SHADERC:LIMIT and its values are integers.\n\nAUTO-BIND-UNIFORMS - Sets whether the compiler should automatically assign bindings to uniforms that aren't already explictly bound.\n  Defaults to: NIL\n\nAUTO-COMBINED-IMAGE-SAMPLER - Sets whether the compiler should automatically remove sampler variables and convert image variables to combined\n  image-sampler variables.\n  Defaults to: NIL\n\nHLSL-IO-MAPPING - Sets whether the compiler should use HLSL IO mapping rules for bindings.\n  Defaults to: NIL\n\nHLSL-OFFSETS - Sets whether the compiler should determine block member offsets using HLSL packing rules instead of standard GLSL rules.\n  Only affects GLSL compilation. HLSL rules are always used when compiling HLSL.\n  Defaults to NIL.\n\nBINDING-BASES - A list of base binding number configuration for uniform resource types.\n  Each element in the list has the format: (uniform-kind base \u0026optional stage)\n  The uniform-kind is a %SHADERC:UNIFORM-KIND, base is an unsigned integer and stage is %SHADERC:SHADER-KIND.\n  If stage is not set, it affects all shader stages except for those where it is explicitly overridden by another entry in the list.\n\nAUTO-MAP-LOCATIONS - Sets whether the compiler should automatically assign locations to uniform variables that don't have explicit\n  locations in the shader source.\n  Defaults to: NIL\n\nHLSL-REGISTER-SET-AND-BINDINGS - A list of descriptor set and binding configurations for HLSL registers.\n  Each element in the list has the format: (register set binding \u0026optional stage).\n  register, set and binding are all strings.\n  stage is a %SHADERC:SHADER-KIND.\n  If stage is not set, the descriptor set and binding for the HLSL register affect all stages except for those where it is explicitly\n  overridden by another entry in the list.\n\nENABLE-HLSL-FUNCTIONALITY-1 - Sets whether the compiler should enable extension SPV_GOOGLE_hlsl_functionality1.\n  Defaults to: NIL\n\nINVERT-Y - Sets whether the compiler should invert position.Y output in vertex shader.\n  Defaults to: NIL\n\nCLAMP-NAN - Sets whether the compiler generates code for max and min builtins which, if given a NaN operand, will return the other operand.\n  Similarly, the clamp builtin will favour the non-NaN operands, as if clamp were implemented as a composition of max and min.\n  Defaults to: NIL\"\n```\n\nInternally the `shaderc` library uses an opaque `shaderc_compile_options` handle and exposes a function for each of the options.\nThe function `shaderc:set-compile-options-from-set` provides an easy way of setting all options at once.\nE.g.:\n\n```cl\n(defparameter compile-opts\n  (make-instance 'compile-options-set\n                 :optimization-level :size))\n\n(let ((opts-handle (%shaderc:compile-options-initialize)))\n  (set-compile-options-from-set opts-handle compile-opts)\n  ;; compile some shaders ...\n  (%shaderc:compile-options-release ,compile-options))\n```\n\nNote that `shaderc:compile-to-spv` takes a `shaderc:compile-options-set` as a key argument (`:options`, which defaults to `nil`) and uses `shaderc:set-compile-options-from-set` to apply all options.\n\nIf you'd rather use the `shaderc_compile_options` handle directly, you can use the low level bindings exposed by `%shaderc`.\n`%shaderc:compile-options-initialize` creates an options handle and `shaderc:compile-options-release` must be used to release it again.\n`shaderc:with-compile-options` provides a shorthand for this.\nIndividual options can then be set by calling the respective functions (e.g. `%shaderc:compile-options-set-source-language compile-options`).\n\n\n### Using includes\n\nThe coolest thing about `shaderc` is that it lets you include other files using `#include` preprocessor directives.\nThese can either be standard includes (e.g. `#include \u003csomefile.glsl\u003e`) or relative includes (e.g. `#include \"../some/file.glsl`).\n\nWhen the `shaderc` compiler encounters an `#include` directive, it triggers a callback which must resolve the include request.\nThe `shaderc:compile-options-set` uses predefined default callbacks for this purpose.\n**If you want to use them, make sure to explicitly pass an instance of `shaderc:compile-options-set` to `shaderc:compile-to-spv` since `:options` defaults to `nil`!**\n\nTo resolve standard includes (`#include \u003csomefile.glsl\u003e`) the default callbacks use the parameter `shaderc:*default-include-dirs*` which will be searched for the requested source file.\n\nTo resolve relative includes (`#include \"some/file.glsl\"`) the default callbacks try to resolve the file path based on the file path of the requesting source.\nThis can either be the `:tag` given to `shaderc:compile-to-spv` or the file name of a previously included files when resolving a nested include.\nSo, if you want to use relative includes in the shader source you pass to `shaderc:compile-to-spv`, make sure to also pass the file path as its `:tag` which corresponds to the \"root\" directory for your include.\nThe default callbacks also allow absolute paths when resolving relative includes (e.g. `#include \"/home/shadercl-user1337/somefile.glsl\"`) in which case the `:tag` (or file path of the requesting source) is ignored.\n\nNote that enabling the `GL_GOOGLE_include_directive` in the shader is not required for includes to work.\n\n#### Custom callbacks\nSince resolving includes is left to the client (i.e. you), you can also provide custom callbacks and develop your own strategy for mapping included file paths to source files.\n\nFor this you need to provide two callbacks: one for resolving the include directive and one for releasing allocated memory when the `shaderc` compiler is done with the included sources.\n\nThe callback for resolving an include directive must return a pointer to a `%shaderc:include-result` struct, which must hold the identifier of the included source (this should be unique in the client context), the actual included source code as well as a pointer which can be used to pass some context information to the client.\nIf the inclusion failed the identifier (`source-name`) must be empty!\nAlso, in that case `content` should hold an error message instead of the included source code.\nSince the C struct also has members for the size of both strings, `%shaderc` also provides a wrapper class of the same name (i.e. `include-result`) as well as translators, which allow you to create such a pointer more easily.\nYou can simply call:\n\n```cl\n(cffi:foreign-alloc '(:struct %shaderc:include-result)\n                    (make-instance 'include-result\n                                   :source-name \"unique-identifier\" ;; defaults to \"\"\n                                   :content \"void someFunc() {}\"    ;; defaults to \"\"\n                                   :user-data some-pointer))        ;; defaults to (cffi:null-pointer)\n```\n\nSince the client (i.e. you) owns the `include-result` and you most certainly allocated some memory when you resolved the include request, you should free this in a second callback.\n\nCheck out the documentation of the `include-resolve-callback`, `include-result-release-callback` and `user-data` options in `shaderc:compile-options-set` for information on how the signatures are supposed to look like.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolifantobambla%2Fshadercl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjolifantobambla%2Fshadercl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolifantobambla%2Fshadercl/lists"}