{"id":38141746,"url":"https://github.com/nyorain/vil","last_synced_at":"2026-01-16T22:51:24.235Z","repository":{"id":41481840,"uuid":"310136465","full_name":"nyorain/vil","owner":"nyorain","description":"Vulkan Layer for Live Introspection \u0026 Debugging. Allows to view all vulkan state live inside your application.","archived":false,"fork":false,"pushed_at":"2025-12-29T00:25:59.000Z","size":41676,"stargazers_count":121,"open_issues_count":4,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-12-30T20:38:42.411Z","etag":null,"topics":["debugger","debugging","graphics","introspection","layer","live","tool","vil","vulkan"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nyorain.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-11-04T22:56:32.000Z","updated_at":"2025-12-30T11:19:19.000Z","dependencies_parsed_at":"2024-12-18T18:32:40.918Z","dependency_job_id":"61750629-8da0-4ed0-afb5-eb7c3d4f6da8","html_url":"https://github.com/nyorain/vil","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/nyorain/vil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyorain%2Fvil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyorain%2Fvil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyorain%2Fvil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyorain%2Fvil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nyorain","download_url":"https://codeload.github.com/nyorain/vil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nyorain%2Fvil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28486598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T22:47:06.728Z","status":"ssl_error","status_checked_at":"2026-01-16T22:46:52.401Z","response_time":107,"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":["debugger","debugging","graphics","introspection","layer","live","tool","vil","vulkan"],"created_at":"2026-01-16T22:51:24.135Z","updated_at":"2026-01-16T22:51:24.223Z","avatar_url":"https://github.com/nyorain.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VIL: Vulkan Introspection Layer\n\nVulkan layer that allows to inspect GPU state and submitted commands live\ninside your applications.\n\n\u003cimg align='center' src='https://github.com/nyorain/vil/blob/main/docs/pics/hiz.gif' width='300\"'\u003e\n\nFeatures:\n\n- show all created resources, their information and state\n\t- can be identified via debug names\n\t- visualize content of images and see buffer content\n- inspect recorded and executing command buffers with live GPU timings\n\t- quickly inspect pipeline state\n\t- inspect all submissions, queues and synchronization primitives\n\t- view the effective properties of draw \u0026 dispatch calls, also for indirect commands\n\t- show all state bound for a draw/dispatch command and all outputs, live\n\t\t- display images\n\t\t- show and interpret buffer content\n\t\t- show vertex input (vertex output, model visualization and\n\t\t  other pre-rasterization stages are WIP)\n\t\t- show the contents of framebuffer attachments after a draw call\n\t- debug shaders, seeing the variables update live (WIP)\n- show general debug information about the application such as\n\t- enabled device and instance extensions\n\t- enabled features\n\t- overall statistics on used memory and available memory budget\n\nThis is still in an early stage of development, bug reports and feedback welcome.\nSee the [rough overview](docs/features.md) over the currently implemented vulkan\ncommands/extensions. Keep in mind that using extensions/features not supported\nby the layer at the moment might cause crashes.\n\nIntended much more as a live debugging tool than a profiling tool.\nDoes not have all the features of existing debugging tools (such as [renderdoc](https://github.com/baldurk/renderdoc))\nat the moment, but can already be useful to debug problems that are\nhard to find in traditional debugging tools.\nUnlike capture-based tools, this allows a **live** introspection.\nThis can be useful to debug temporal or synchronization issues (doing this\nwith per-frame captures can be bothersome) or as first-try\ndebugging approach to figure out roughly where a problem is, without\nhaving to wait for a capture to load. It also is useful as a general-purpose\nintrospection tool, capture-based tools are usually optimized to only show\nresources important for their capture, leaving out the rest.\n\nDownsides:\n\n- Writing captures/gpu state to disk and viewing it later on is not possible\n  and is likely just out of the scope of this project. There are great\n  tools for that.\n- This isn't as stable/feature-complete as known tools\n- Shader debugging is in a very experimental stage, more of a prototype\n- The live nature of the introspection makes inspected state more volatile.\n  While it is possible to freeze some state and also view e.g.\n  invalidated/destroyed command records, you might run into issues\n  where state you would want to inspect (from a specific frame) is just\n  not available anymore.\n\n\u003c!--- ![Example of command viewer 2](docs/pics/sponza-buf.png) --\u003e\n\u003c!---- ![Example of resource viewer](docs/pics/sponza-scatter-res.png) --\u003e\n\n# Building \u0026 Installing\n\nSupported/Tested platforms:\n\n- Unix, gcc \u0026 clang (with solid C++17 support)\n\t- xcb, xlib and wayland platforms\n  - hooked overlay not supported on wayland, it is too well designed to allow hacks like that.\n    Just integrate vil with your application using the API or set the `VIL_CREATE_WINDOW=1` environment var\n\tfor a separate window (that works on native wayland). Or make your application use xcb/xlib.\n\t- only actively tested on linux, bug reports and improvements for\n\t  other platforms appreciated\n- Windows with MSVC 2019/2022 (x64)\n  You can find prebuilt libraries in the release section. To install the layer,\n  just run the `register_layer.bat` after unpacking the zip.\n\nWindows+MinGW will hopefully eventually be supported/tested. Please report\nissues, if you try this.\n\n**NOTE**: 32-bit platforms are currently not supported. Pull requests are welcome but you'd likely have to maintain it yourself/set up CI.\n\nTo build the layer from scratch, you'll need an up-to-date version of [meson](https://github.com/mesonbuild/meson/releases).\n\n## Building on Unix\n\nJust clone the repository and run:\n\n```shell\nmeson build\nninja -C build\n```\n\nTo install the layer you can just run `meson install --tags runtime` (you might need superuser rights for that).\nBy default, meson will install to `/usr/local` so - depending on your system - the layer configuration file or\nlayer library itself might not be found by the vulkan loader. Either make sure that `/usr/local` is properly\nincluded in your system's library and vulkan loader search paths or change the install prefix to `/usr`\nvia meson (e.g. run `meson --prefix=/usr build` in the beginning).\nBe warned that using the `/usr` prefix for manually built libs/applications is generally not recommended since it might mess\nwith your package manager.\n\n## Building on Windows\n\nOn windows, this is actively tested with MSVC 2019, older version will likely not work due to incomplete/incorrect C++17 support.\nSince we require c11, MSVC \u003e= 19.28 is required (visual studio 16.8).\nThe recommended/tested way to build it:\n\n1. Run `meson build --backend vs2019` (or `vs2022`) from command line in the vil folder.\n2. If everything goes correctly, you will have a Visual Studio solution (in a `build` folder) that you can build.\n\nAlternatively, you can also use ninja to build it on windows.\n\nYou will still need to install the layer after building it, so that other applications\ncan find it. Just run the `register_layer.bat` in the build folder (running it once\nis enough, it just adds the path to the registry).\nFor more information, manual installation (or if you are vary of running random\nbat files from the internet), see [here](docs/install.md)\n\n# Using vil\n\nOnce installed, you have to make sure vulkan applications load `VK_LAYER_live_introspection`.\nEither pass it to your `VkInstanceCreateInfo` or enable it via environment variable `VK_INSTANCE_LAYERS=VK_LAYER_live_introspection`.\nDuring the early stages of this project, you likely want to load it *before* any validation layer. If\nyour application then triggers validation errors with *vil* that are not there without it,\nmake sure to report them here!\n\nThere are multiple ways of using the introspection gui:\n\n- Make the layer create a new window containing the debug gui when the application starts.\n  This is enabled by default.\n  You can control it via the environment variable `VIL_CREATE_WINDOW={0, 1}`.\n- Make the layer draw an overlay over your application\n\t- Since the layer gui still needs input you have to supply it via\n\t  a separate api. See [include/vil_api.h](include/vil_api.h).\n\t  As soon as you call the API to create an overlay on a swapchain,\n\t  the extra debug window will be closed (if there was one).\n\t- Experimental: Make the layer hook the application's input\n\t  so the overlay can work as a simple drop-in, without having to change\n\t  the application for it. This is highly platform-specific and might\n\t  not work with certain platforms/applications.\n\t  This is not enabled by default (and might be disabled from the default\n\t  build config or even completely removed from the layer in future).\n\t  You can force it via the environment variable `VIL_HOOK_OVERLAY=1`.\n\n## About retail games\n\nUsing this layer in retail application/games (i.e. applications you don't develop yourself,\nwithout available source code or debugging symbols) **IS NOT OFFICIALLY SUPPORTED**.\nThere are multiple reasons for this:\n\n- It can be expected that the layer will cause issues in quite some games,\n  especially in this early stage of development. Bug reports of the\n  form \"Game XY crashes when enabling this layer\" are not too useful since\n  it would require installing Game XY and then trying to reverse-engineer\n  what it does to cause a crash in the layer. Sometimes, the result would\n  be that the game/application simply does not follow the vulkan spec\n  and while the driver can handle it, the layer cannot.\n- Using this layer in games might trigger anti-cheat mechanisms.\n  Using this layer in multiplayer games might get you banned.\n  Even just playing games that include a multiplayer mode locally with the\n  layer might get you in trouble. Just don't do it.\n- Usage of this layer in retail products might be motivated by abuse.\n  Keep in mind that while game developers usually have no problem with\n  players sharing videos or screenshots of the gameplay; extracting\n  textures, models, raw framebuffer data or rendering techniques from the game\n  (and then distributing them) might not be in the interest of the developer\n  or fair use of the material. This is not the usecase this layer\n  is intended for and not a usecase that will be supported in any way.\n\nWith that out of the way, there is nothing per se wrong with using the\nlayer in retail products and games you have not written yourself. As long as you\ndon't expect us to make it to work or distribute the results.\nWhen you can point out what *exactly* is causing the layer to crash with a\nspecific game or fix a problem inside the layer to allow using it with\na retail product, we definitely want to hear of it. But additional code paths\ninside the layer that work around specific *game issues* will not\nbe accepted.\n\n# License\n\nSPDX-License-Identifier: GPL-3.0-only\n\nUnless stated otherwise, code and assets in this repository are licensed under\nGPLv3. Contributors [don't have to sign a CLA](https://drewdevault.com/2018/10/05/Dont-sign-a-CLA.html).\n\nNote that since this is a dynamically loaded vulkan layer and not a library\nyou link your application against, using this in production of proprietary\nproducts should not be a problem and is inside the intended usecase.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyorain%2Fvil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnyorain%2Fvil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnyorain%2Fvil/lists"}