PoC: feat(gui): add developer diagnostics

[kakra]

Summary

Add developer-oriented Vulkan resource and performance diagnostics to the vkShade overlay.

This remains a draft proof of concept. The image tracker provides a concrete reference for the required metadata and GUI workflows, while the final resource and depth architecture may be replaced by the maintainer's planned implementation.

The branch is kept current so that functionality can be compared against new upstream work and removed as equivalent facilities become available.

Vulkan image tracking

Add device-scoped image tracking for:

• application-created images and image views;
• swapchain images;
• vkShade-owned render images;
• framebuffer attachments;
• imageless framebuffer attachments supplied at render-pass begin;
• classic render passes and RenderPass2 variants;
• dynamic-rendering color, depth, stencil, and resolve attachments.

The tracker records factual metadata including:

• origin and observed role;
• extent, image type, and format;
• sample count, mip levels, and array layers;
• Vulkan usage flags;
• observed aspects;
• last observed frame and observation count.

Tracking is observational. Errors are caught and logged without changing Vulkan calls, return values, or application-visible behavior.

Buffers panel

Add a Buffers tab containing a scrollable image table.

Soft category controls can prioritize:

• color images;
• depth/stencil images;
• storage images;
• swapchain images;
• vkShade-internal images.

Active categories use OR matching and stable partitioning. Non-matching images remain visible in their original order and use the theme's disabled text color.

Snapshots are refreshed only while the panel is visible and the table uses ImGuiListClipper for large image lists.

GPU timing

Measure GPU time using Vulkan timestamp queries around:

• the complete vkShade render path;
• the effect chain;
• the remaining copy and GUI work.

The query pool is created lazily and timestamps are recorded only while the performance HUD is enabled. Results are collected after the existing per-swapchain fence wait, avoiding an additional synchronization point.

Timestamp counters with fewer than 64 valid bits and counter wraparound are handled explicitly.

Performance HUD

Add a View-menu toggle for a non-interactive HUD which remains visible while the main window is closed.

For total vkShade work, effects, and remaining work, the HUD displays:

• current GPU time;
• rolling average;
• rolling minimum;
• rolling maximum.

Statistics cover the latest 120 published samples. A sequence counter ensures that each query result is consumed once, and the rolling windows are reset when timing becomes unavailable.

The retained sample window can later serve as the basis for a timing graph. Per-effect measurements are intentionally left for separate work because they require additional timestamp ranges around individual effect passes.

Scope

This draft does not add:

• depth-buffer access or selection;
• texture previews;
• uniform controls;
• clipboard or CSV export;
• log-panel changes;
• effects enable-state controls.

The previous live-log commits were removed because that functionality is now provided upstream by #92.

Validation

• Release build succeeds.
• git diff --check is clean.
• All eight unit tests pass.
• Timestamp delta and valid-bit wraparound behavior are covered.
• Rolling-window fill, replacement, and reset behavior are covered.
• Buffer diagnostics were smoke-tested with Euro Truck Simulator 2 under Proton.
• The GPU timing path reported approximately 2.1 ms for the active six-effect ETS2 shader stack at 4K output.

The PR deliberately remains in draft while the resource/depth architecture is developed upstream. Tracker commits can be removed as they are superseded, while the independent performance-diagnostics commits can be retained or split out later.

[kakra]

Fixed the linter warning about the shadowed symbol.

[kakra]

@ralgar I've added a few draft PRs ontop of this to give you a glimpse of what follows. Feel free to look into them and comment but do not consider them final until rebased on top of the previous merge.

[ralgar]

Hey, I've had a proper look through #73 and I think I'd like to split this up a bit.

I'm pretty happy with the GUI changes (the tabs and log buffer) and would like to get those separated out so I can merge them, pending a couple of minor changes. They actually fit well with the GUI work I was already planning. :D

For the Vulkan resource tracking, though, I think I'd rather take that part on myself. There are some architectural/performance concerns I have with the current approach, particularly around tracking every image and putting a shared mutex into the rendering/command-recording path. I have a fairly specific direction in mind for how I want to approach the depth-image side of this, so I'd rather implement that part myself than have you rework the current tracker.

More generally, I'm happy for you to keep contributing fixes and smaller features, but I'd like to discuss larger architectural changes before they're implemented. Opening an issue to discuss the approach first would probably be a good way to handle that. There are a few areas of the project where I already have plans for the underlying architecture, and I'd rather coordinate those up front.

So, for #73, I'd suggest splitting out the first two commits and putting the resource-tracking side on hold for now. I also need to slow down a bit on new feature work while I catch up with the existing bugs and tech debt from my initial hack-a-thon. My priority right now is getting to a stable v0.1. The only major feature I consider necessary before that is the preset/uniform integration I'm currently working on, and I'd like to keep the scope tightly controlled until we get there. Pretty much everything until then should be fixes, cleanup, and small QoL features.

I haven't looked at your other PRs in detail yet, but scope-wise they're all fine I think.

[kakra]

Yeah sure, please let me know, how to split.

The resource tracking has actually been a very late addition to my patch queue. I added it to better understand what's going on. I just bundled it up with the other changes as one first diagnostic tool.

While working on that, I discovered that the actually is a "File" menu, but I'm not sure how it works or what it does. It certainly can clear the effects list. :-D

For the resource tracking itself, yes, please go on with your own idea. You know your ideas, plans and current remaining code bugs best. Actually, it feels better, if the bigger integrations are made by you. No rush please. I can easily rebase my pending commits onto your work until then.

The only thing that's current left for me would be depth buffer access. I didn't want to add that before understanding the buffers. But that can wait, I have other projects running that could need some attention. ;-)

For now:

• I tried to keep each commit scope small, so it can be cherry picked. Let me know what you want to have extracted into a separate PR.
• The commits should be in grouped order, so the series should be easy to split.
• The other PRs do not really depend on the resource tracker and could be easily rebased back onto main, they just touch similar areas of the code base. Let me know which of the other PRs should go in first and I rebase my work.

Again, no rush. vkShade is a great project. But my local changes can stay rebased until the next project phase starts. For my effects list, I currently only need the bit depth variable. For some near future ideas, I would need depth buffer access but I can hack that on locally for now.

So, please, do not feel rushed. Rather understand my PRs as an idea what might be needed next but stay with your own decisions about the implementation details. I keep my PRs updated until they become obsolete or you feel like they could go in and comment on them.

Let me know if I can prioritize things for the v0.1 release. We could create issues about pending issues to coordinate work, and create a Github milestone.

Thanks a lot for this project, and keeping it alive. You probably know, why you created it: Other projects became stale, or were missing ideas, and it's just fun to approach new ideas and improve skills.

I that spirit, I will keep sharing my ideas - with no requirement or expectations to get them merged fast or as-is.

[kakra]

I'm pretty happy with the GUI changes (the tabs and log buffer)

From this, I get that I should extract those changes into a new PR. I will do that later today, stay tuned.

[kakra]

Demoted to draft.

BTW: I'm fine with throwing code designs away or redesigning them - no worries on your side, there will be no wasted effort on my side, because every effort is learning. ;-) If you feel a different architectural approach is needed, I very much appreciate that feedback. I now created another PR instead, containing only the tabbed GUI and live log. The colorization commit has been excluded from it for now: Let me know if you want to include it.

[kakra]

As a final note: I think my implementation is still useful as a proof of concept and provider of functional insights which can give valuable feedback for a final design. So I leave it open as a draft and keep the branch available until it is obsoleted by current code.

[kakra]

@ralgar Updated with a few new ideas.