{"id":20161591,"url":"https://github.com/stablecoder/vulkan-mini-libs-2","last_synced_at":"2025-10-18T21:54:44.414Z","repository":{"id":39919534,"uuid":"395846721","full_name":"StableCoder/vulkan-mini-libs-2","owner":"StableCoder","description":"Useful self-contained header files for Vulkan development, such as error codes and enum/bitflag serialization.","archived":false,"fork":false,"pushed_at":"2025-04-04T23:52:40.000Z","size":1828,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T00:14:42.055Z","etag":null,"topics":["bitflag","bitset","c","cpp","cpp17","cpp20","flag","flagbits","flags","python","vulkan","vulkan-library","xml","xml-parser"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StableCoder.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-08-14T01:06:21.000Z","updated_at":"2025-04-04T23:52:44.000Z","dependencies_parsed_at":"2024-02-18T01:27:16.053Z","dependency_job_id":"d5e01db8-87e8-4911-8c52-4360516144ab","html_url":"https://github.com/StableCoder/vulkan-mini-libs-2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StableCoder%2Fvulkan-mini-libs-2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StableCoder%2Fvulkan-mini-libs-2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StableCoder%2Fvulkan-mini-libs-2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StableCoder%2Fvulkan-mini-libs-2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StableCoder","download_url":"https://codeload.github.com/StableCoder/vulkan-mini-libs-2/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248131315,"owners_count":21052819,"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":["bitflag","bitset","c","cpp","cpp17","cpp20","flag","flagbits","flags","python","vulkan","vulkan-library","xml","xml-parser"],"created_at":"2024-11-14T00:19:46.611Z","updated_at":"2025-10-18T21:54:39.336Z","avatar_url":"https://github.com/StableCoder.png","language":"C","readme":"# Vulkan (and OpenXR) Mini Libs 2  \u003c!-- omit in toc --\u003e\n[![pipeline status](https://git.stabletec.com/utilities/vulkan-mini-libs-2/badges/main/pipeline.svg)](https://git.stabletec.com/utilities/vulkan-mini-libs-2/commits/main)\n[![coverage report](https://git.stabletec.com/utilities/vulkan-mini-libs-2/badges/main/coverage.svg)](https://git.stabletec.com/utilities/vulkan-mini-libs-2/commits/main)\n[![license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://git.stabletec.com/utilities/vulkan-mini-libs-2/blob/main/LICENSE)\n\n- [Vulkan Value Serialization (C/C++)](#vulkan-value-serialization-cc)\n  - [Serialization](#serialization)\n  - [Parsing](#parsing)\n- [Vulkan Result to String (C)](#vulkan-result-to-string-c)\n- [OpenXR Result to String (C)](#openxr-result-to-string-c)\n- [Vulkan Error Code (C++)](#vulkan-error-code-c)\n- [Vulkan Struct Cleanup (C)](#vulkan-struct-cleanup-c)\n- [Generating fresh Mini-Libs](#generating-fresh-mini-libs)\n\nA set of small header-only libraries that are of limited scope each to perform a very specific task.\n\nCompared to the previous version of these libraries which generated header versions for each Vulkan header version, this one remains backwards and forwards compatible, serving a given whole range of header versions (typically v1.0.72 - current for Vulkan, all of OpenXR) through the use of the provided XML registry specficiations.\n\n# Vulkan Value Serialization (C/C++)\n\nThis program builds header files for use in C11/C++17 or newer. It\ncontains all Vulkan enum types/flags/values of the indicated Vulkan header spec\nversion range, and can convert to/from strings representing those values.\n\nSupports both plain enums and the bitmasks.\n\nWhen converting values to strings, where possible a shorter version of the\nenum string is used, where the verbose type prefix is removed:\n- VK_IMAGE_LAYOUT_GENERAL =\u003e GENERAL\n- VK_CULL_MODE_FRONT_BIT | VK_CULL_MODE_BACK_BIT =\u003e FRONT | BACK\n\nWhen converting from strings into values, either the short OR full string can\nbe used where strings are case insensitive, and underscores can be replaced\nwith spaces, and addition whitespace can be added to either side of the first/\nlast alphanumeric character, as these are trimmed off.\n\nFor example, all of the following convert to VK_IMAGE_LAYOUT_GENERAL:\n`vk imAGE_LayOut GenerAL`, `VK_IMAGE_LAYOUT_GENERAL`,`GENERAL`, `   General `\n\nAlso, to assist with forward and backwards compatibility, all the vendor tags can \nstripped from the typenames and values, since they can be removed in later versions \nleading to incompatibility issues. For example, the flag for VkToolPurposeFlagBitsEXT, \n`VK_TOOL_PURPOSE_VALIDATION_BIT_EXT`, can will output as `VALIDATION`, and can \nbe read similarly, with the above rules applicable for parsing. Also removed often is\nthe `_BIT` suffix.\n\n## Usage \u003c!-- omit in toc --\u003e\n\nOn *ONE* compilation unit, include the definition of `#define VK_VALUE_SERIALIZATION_CONFIG_MAIN` before the header is included so that the definitions are compiled somewhere following the one definition rule (ODR).\n\n### C \u003c!-- omit in toc --\u003e\n\nFor C, there are the simple functions for parsing and serializing:\n- vk_parse32\n- vk_parse64\n- vk_serialize32\n- vk_serialize64\n```c\n#define VK_VALUE_SERIALIZATION_CONFIG_MAIN\n#include \u003cvk_value_serialization.h\u003e\n```\n\n### C++ \u003c!-- omit in toc --\u003e\n\nUsing the HPP header in C++ also grants the use of a few templated functions and macros to make usage just a tad easier, no longer having to deal with the casting to uint types, and can be included similarly, and does include the original C functions as well:\n```c\n#define VK_VALUE_SERIALIZATION_CONFIG_MAIN\n#include \u003cvk_value_serialization.hpp\u003e\n```\n## Serialization\n\n```c\n/**\n * @brief Serializes a Vulkan enumerator/flag type (32-bit)\n * @param pVkType is a pointer to the string name of the Vulkan enumerator/flag type\n * @param vkValue is the numeric value being serialized\n * @param pSerializedLength is a pointer to an integer related to the size of pSerialized, as\n * described below.\n * @param pSerialized is either NULL or a pointer to an character array.\n * @note pSerialized is only written to if STEC_VK_SERIALIZATION_RESULT_SUCCESS or\n * STEC_VK_SERIALIZATION_RESULT_ERROR_INCOMPLETE is returned.\n *\n * If pSerialized is NULL, then the size required to return all layer names is returned in\n * pSerializedLength. Otherwise, pSerializedLength must point to a variable set by the user to the\n * size of the pSerialized array, and on return the variable is overwritten with the characters\n * actually written to pSerialized. If pSerializedLength is less than the total size required to\n * return all, at most pSerializedLength is written, and\n * STEC_VK_SERIALIZATION_RESULT_ERROR_INCOMPLETE will be returned instead of\n * STEC_VK_SERIALIZATION_RESULT_SUCCESS, to indicate that not all names were returned.\n *\n * If the Vulkan type could not be determined or found, then\n * STEC_VK_SERIALIZATION_RESULT_ERROR_TYPE_NOT_FOUND is returned.\n *\n * If the value given in vkValue is 0 and the corresponding Vulkan type doesn't have an equivalent\n * 0-value that can be serialized, then STEC_VK_SERIALIZATION_RESULT_ERROR_TYPE_HAS_NO_EMPTY_VALUE\n * is returned. If Any other given vkValue or bitmask cannot be translated fully, then\n * STEC_VK_SERIALIZATION_RESULT_ERROR_VALUE_NOT_FOUND is returned.\n */\nSTecVkSerializationResult vk_serialize32(char const *pVkType,\n                                         uint32_t vkValue,\n                                         uint32_t *pSerializedLength,\n                                         char *pSerialized);\n```\n\n### Usage \u003c!-- omit in toc --\u003e\n\n```c\nchar testStr[20];\nuint32_t serializedLength = 20;\nSTecVkSerializationResult result;\nresult = vk_serialize32(\"VkDebugReportFlagsEXT\",\n                        VK_DEBUG_REPORT_DEBUG_BIT_EXT | VK_DEBUG_REPORT_ERROR_BIT_EXT,\n                        \u0026serializedLength, testStr);\n  // result is STEC_VK_SERIALIZATION_RESULT_SUCCESS\n  // testStr's first 13 characters is now \"DEBUG | ERROR\"\n  // serializedLength is now 13\n```\n\n```c\nchar testStr[20];\nuint32_t serializedLength = 8;\nSTecVkSerializationResult result;\nresult = vk_serialize32(\"VkDebugReportFlagsEXT\",\n                        VK_DEBUG_REPORT_DEBUG_BIT_EXT | VK_DEBUG_REPORT_ERROR_BIT_EXT,\n                        \u0026serializedLength, testStr);\n  // result is STEC_VK_SERIALIZATION_RESULT_ERROR_INCOMPLETE\n  // testStr's first 8 characters is now \"DEBUG | \"\n  // serializedLength is now 8\n```\n\n## Parsing\n\n```c\n/**\n * @brief Parses a Vulkan enumerator/flag serialized string (32-bit)\n * @param pVkType is a pointer to the string name of the Vulkan enumerator/flag type\n * @param pVkString is a pointer to the string being parsed\n * @param pParsedValue is a pointer to a value that will be modified with the parsed value. Only\n * modified if STEC_VK_SERIALIZATION_RESULT_SUCCESS is returned.\n *\n * This attempts to parse the given Vulkan string, according to the values available for the Vulkan\n * type, and updates the return parsed value upon STEC_VK_SERIALIZATION_RESULT_SUCCESS.\n *\n * If the type cannot be determined or found, STEC_VK_SERIALIZATION_RESULT_ERROR_TYPE_NOT_FOUND is\n * returned.\n *\n * If a particular token in the parsing string cannot be determined or found, then\n * STEC_VK_SERIALIZATION_RESULT_ERROR_VALUE_NOT_FOUND is returned.\n */\nSTecVkSerializationResult vk_parse32(char const *pVkType,\n                                     char const *pVkString,\n                                     uint32_t *pParsedValue);\n```\n\n### Usage \u003c!-- omit in toc --\u003e\n\n```c\nVkImageLayout parsedLayout;\nSTecVkSerializationResult result;\nresult = vk_parse32(\"VkImageLayout\", \"TRANSFER_DST_OPTIMAL\", (uint32_t *)\u0026parsedLayout);\n  // parsedLayout is now VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL\n\nVkPipelineStageFlags2 parsedStagsFlags;\nresult = vk_parse64(\"VkPipelineStageFlagBits2\",\n           \"INVOCATION_MASK_BIT_HUAWEI | VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT\",\n           (uint64_t *)\u0026parsedStagsFlags);\n  // parsedStagsFlags is now VK_PIPELINE_STAGE_2_TOP_OF_PIPE_BIT | VK_PIPELINE_STAGE_2_INVOCATION_MASK_BIT_HUAWEI\n```\n\n# Vulkan Result to String (C)\n\nC-compatible header file with functions which will convert a VkResult to the corresponding string representation, or as close as possible in the case with shared values.\n\n## Usage \u003c!-- omit in toc --\u003e\n\nOn *ONE* compilation unit, include the definition of `#define VK_RESULT_TO_STRING_CONFIG_MAIN` before the header is included so that the definitions are compiled somewhere following the one definition rule (ODR).\n\nThere are two functions that can be called:\n- `char const *VkResult_to_string(VkResult)` which returns NULL if there is no compiled string representation for the given VkResult.\n- `char const *vkResultToString(VkResult)` which returns a string of '(unrecognized positive VkResult value)' or '(unrecognized negative VkResult value)' if there is no compiled string representation for the given VkResult.\n\n```cpp\n#define VK_RESULT_TO_STRING_CONFIG_MAIN\n#include \"vk_result_to_string.h\"\n#include \u003ciostream\u003e\n\nint main(int, char **) {\n  char const* resStr = vkResultToString(VK_ERROR_DEVICE_LOST);\n  std::cout \u003c\u003c resStr \u003c\u003c std::endl;\n}\n```\n\n# OpenXR Result to String (C)\n\nC-compatible header file with a single function, `XrResult_to_string`, which will convert a given XrResult to a string representation, or as close as possible in the case with shared values. If the given value doesn't have a corresponding string, it returns `NULL`.\n\n## Usage \u003c!-- omit in toc --\u003e\n\nOn *ONE* compilation unit, include the definition of `#define XR_RESULT_TO_STRING_CONFIG_MAIN` before the header is included so that the definitions are compiled somewhere following the one definition rule (ODR).\n\n```cpp\n#define XR_RESULT_TO_STRING_CONFIG_MAIN\n#include \"xr_result_to_string.h\"\n#include \u003ciostream\u003e\n\nint main(int, char **) {\n  char const* resStr = XrResult_to_string(XR_ERROR_TIME_INVALID);\n  if(resStr != nullptr)\n    std::cout \u003c\u003c resStr \u003c\u003c std::endl;\n}\n```\n\n# Vulkan Error Code (C++)\n\nHeader file for C++. Contains the implementation details that allow the use of VkResult values with std::error_code and std::error_category.\n\n## Usage \u003c!-- omit in toc --\u003e\n\nOn *ONE* compilation unit, include the definition of `#define VK_ERROR_CODE_CONFIG_MAIN` **AND** ensure that `#define VK_RESULT_TO_STRING_CONFIG_MAIN` is defined somewhere before the header is included, not necessarily in the same compilation unit, so that the definitions are compiled somewhere following the one definition rule (ODR).\n\nThen, one can implicitly convert VkResult to std::error_code:\n```cpp\n#define VK_RESULT_TO_STRING_CONFIG_MAIN\n#define VK_ERROR_CODE_CONFIG_MAIN\n#include \"vk_error_code.hpp\"\n#include \u003ciostream\u003e\n\nint main(int, char **) {\n  std::error_code ec = (VkResult)VK_ERROR_DEVICE_LOST;\n\n  std::cout \u003c\u003c ec.value() \u003c\u003c ':' \u003c\u003c ec.message() \u003c\u003c std::endl;\n}\n```\n\n# Vulkan Struct Cleanup (C)\n\nC11-compatible C header that has all available structs in the generated range, and can safely free memory held by the given struct. This operates on the principle that *all* data that the struct points to externally is *owned* by the struct and it's children, and can be safely freed.\n\nIt does follow through the `pNext` pointers to any other structs that are assumed to have `sType` members and cleans those up as well (through the `cleanup_vk_struct` function). It is also assumed that the held data are managed as separate allocations.\n\nStructs that have no externally held data are inlined as empty functions for better compilation efficacy.\n\n## Usage \u003c!-- omit in toc --\u003e\n\nOn *ONE* compilation unit, include the definition of `#define VK_STRUCT_CLEANUP_CONFIG_MAIN` so that the definitions are compiled somewhere following the one definition rule (ODR).\n\nOtherwise, call the appropriate function based on the Vulkan struct name, which is prefixed by `cleanup_\u003cVK_STRUCT_NAME\u003e(ptr)`. ie. for the `VkPipelineShaderStageCreateInfo` call `cleanup_VkPipelineShaderStageCreateInfo(pCI);`.\n\nIf a Vulkan struct is an undetermined type, but is at least of a type that contains VkStructureType/sType member, then `vk_cleanup_struct(ptr)` can be used.\n\n# Generating fresh Mini-Libs\n\nIn the root of the repository is a shell script, `tools/generate.sh` that will iterate through the range of Vulkan versions, parsing the XML files and collecting the relevant data. After that, it generates the header files using that procesed data.\n\n\n## Possible Arguments \u003c!-- omit in toc --\u003e\n\n### -s, --start \\\u003cINT\u003e \u003c!-- omit in toc --\u003e\nThe starting version of Vulkan to generate for (default: 72 for Vulkan, 0 for OpenXR)\n\nNOTE: Minimal version is 72, as that is when the XML was first published.\n\n### -e, --end \\\u003cINT\u003e \u003c!-- omit in toc --\u003e\nThe ending version of Vulkan to generate for (default: none)\n\n### -o, --output \\\u003cDIR\u003e \u003c!-- omit in toc --\u003e\n\nThe directory in which to generate header files (default: \u003crepo\u003e/include)\n\n### --openxr \u003c!-- omit in toc --\u003e\n\nParses then generates files for OpenXR instead of the Vulkan default.\n\n### --skip-parse \u003c!-- omit in toc --\u003e\nSkips parsing the XML doc and re-generating the cache file. Use this if the cache has been previously generated and you're just re-generating the headers from that cache.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstablecoder%2Fvulkan-mini-libs-2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstablecoder%2Fvulkan-mini-libs-2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstablecoder%2Fvulkan-mini-libs-2/lists"}