# Changelog for keid-core ## 0.2.0.0 Vulkan 1.3 baseline with dynamic rendering and a render graph. - Instance, VMA and shader target environment use Vulkan 1.3. * Shaders are SPIR-V 1.6 and `discard` compiles to `OpDemoteToHelperInvocation`. Use `terminateInvocation` or `demote` to pick the semantics explicitly. * Device features are requested via `PhysicalDeviceVulkan11Features`, `PhysicalDeviceVulkan12Features` and `PhysicalDeviceVulkan13Features`. * All features guaranteed on Vulkan 1.3 devices are required, except `robustBufferAccess` and `robustImageAccess`. * `descriptorIndexing` and the features guaranteed with it are required. * The VMA allocator is created with `ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT`, and `ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT` when `VK_EXT_memory_budget` is granted. * Optional requirements cover features and extensions present on at least 16 of 20 desktop devices from the LunarG desktop baseline 2026 reports. Their results are available as `pdiCapabilities`. * Optional requirements are grouped by extension. Features and properties of a group are requested only when all of the group's extensions are available. * Features of extensions promoted to Vulkan 1.4 are requested through their core structs, e.g. `PhysicalDeviceMaintenance5Features`, and `robustness2` through `PhysicalDeviceRobustness2FeaturesKHR`. The extensions are required by name. * Physical devices without Vulkan 1.3 or a required feature or extension are skipped during selection, with the unmet requirements logged. * On macOS `VK_KHR_portability_subset` is enabled when present. - Requires `vulkan >= 3.27`, `vulkan-utils >= 0.5.11`, `fragr >= 0.1`, `vulkan-utils-framegraph >= 0.1`, `vulkan-utils-spirv >= 0.1` and `spirv-reflect-types == 0.4.*`. - Rendering uses Vulkan dynamic rendering. * `Render.Target.HasRendering` describes a render target: `RenderingFormats` (color, depth and stencil formats, sample count, view mask) for pipelines, and a `RenderingInfo` per swapchain image for recording. * `Render.Target.render` is the render graph step of a target. It renders into the target for the current swapchain image and sets the viewport and scissor to the render area. * Graphics pipelines take their sample count, attachment formats and view mask from the target, with one blend attachment per color attachment. `Engine.Vulkan.Pipeline.External` observers do the same. * `Render.Target.RenderTarget` keeps target resources current across swapchain updates (`updateTarget`) and alive across frames in flight (`refcountTarget`). Stages allocate them with `sAllocateTargets` and frames carry them in `fTargets`. * `Render.Target.Offscreen.Offscreen tag` renders into its color and depth images. The color image is tracked under the owner's tag (`color`), and `render` and `renderReading` draw into it. * Depth images use depth-only formats: `D32_SFLOAT`, then `X8_D24_UNORM_PACK32` and `D16_UNORM`, each supporting depth attachments and sampling. Depth attachments render in `DEPTH_ATTACHMENT_OPTIMAL` and are sampled in `SHADER_READ_ONLY_OPTIMAL`. - Frames are recorded through a render graph, built with `fragr` and `vulkan-utils-framegraph` every frame. * Stages describe their frame with `sRenderGraph :: rt -> p -> st -> rr -> RenderGraph rt p rr st`. It receives the acquired swapchain image and returns the version to present. * `Render.Graph.Graph env i o` is an arrow from image handles to image handles. `Engine.Types.StageGraph` and `RenderGraph` specialise it to stages. * Passes declare how they use each image (`sampled`, `colorAttachment`, `depthAttachment`, `transferSrc`, `transferDst`, storage access). The graph places the barriers and layout transitions, and tracked images keep their state across frames. * `Render.Graph.importImage` brings a tracked image (`Tracked tag`) into the frame. Targets register their images with the slice registry (`Vulkan.Utils.FrameGraph.Image.SliceRegistry`, through `HasSliceRegistry` and `ghSliceRegistry`), and the swapchain images are tracked in `srTrackedImages`. * `Render.Graph.changed` turns a worker update into a `Bool`, for passes that run only on some frames. * `Render.Graph.record` runs a graph in a one-shot command buffer, where `readback` hands the result of a pass to the host. * `Stage.assemble` takes the render graph after the rendering and resources components. `Resources` holds `rBeforeLoop` and `rUpdateBuffers`. * `Resource.Image.Downsample.Pyramid` builds a mip chain in the graph: `generate` copies a source image into mip 0 and blits every following mip from the previous one. - Shaders are checked against each other and against pipeline layouts using `vulkan-utils-spirv` reflection. * `Render.Code.compileStages` compiles the GLSL stages of a pipeline at build time. The build fails when a stage input has no matching output in the previous stage, or when stages disagree on a descriptor or push constant block. * Graphics and compute pipeline creation reflects the SPIR-V and checks that the descriptor set layouts, push constant ranges and vertex attributes cover what the shaders use. Mismatches are thrown as one error listing each of them. * `External.spawnReflect` and `spawnReflect_` check the stage interfaces when loading and pass on only the stage code. A failed pipeline rebuild logs the error and keeps the previous pipeline. * `Engine.SpirV.Reflect` has `reflect`, `check`, `stageProblems`, `layoutProblems` and `vertexInputProblems`. Its previous API, `Graphics.cReflect` and the `StageReflect` synonyms are removed. * `Engine.Vulkan.Format.numericFormat` tells float, signed and unsigned 32-bit formats apart. - Shared pieces come from `vulkan-utils`. * `RefCounted`, `newRefCounted`, `releaseRefCounted`, `takeRefCounted` and `resourceTRefCount` moved to `Vulkan.Utils.RefCounted`, where `RefCounted` is abstract. `Engine.Types.RefCounted` keeps `wrapped`. * `Specialization`, `SpecializationConst` and `withSpecialization` moved from `Engine.Vulkan.Shader` to `Vulkan.Utils.Pipeline.Specialization`, which also has `allocateSpecialization`. * `Engine.Vulkan.Swapchain.threwSwapchainError` wraps the `vulkan-utils` one and rethrows `ERROR_SURFACE_LOST_KHR`. * Frames use `Vulkan.Utils.Frame.waitTwice` and `allocateTimelineSemaphore`. * Instances are created with `Vulkan.Utils.Initialization.allocateVulkanInstance` and `Vulkan.Utils.Init.Headless.allocateInstance`, which add the macOS portability requirement and flag and report unmet instance requirements to stderr. `Engine.Setup.applicationInfo` holds the application info. * `Queues` moved from `Engine.Vulkan.Types` to `Vulkan.Utils.Queues`. It is ordered graphics, compute, transfer, so queue assignment visits compute before transfer, and has an `Applicative` instance. * `RecycledResources` moved from `Engine.Types` and `Engine.Frame` to `Vulkan.Utils.VulkanContext`, with `rrImageAvailable`, `rrCommandPools` and `rrData`. * `Engine.Vulkan.Swapchain.SwapchainResources` wraps `Vulkan.Utils.Swapchain.Swapchain` (`srSwapchain`) with the depth format, sample count, anisotropy and requested image count. Surface formats with sRGB encoding are preferred (`srgbEncoding`), and recreation keeps the swapchain's present mode. * `Engine.Vulkan.Swapchain` no longer re-exports `HasSwapchain`; import it from `Engine.Vulkan.Types`. - Added `Engine.Vulkan.Capabilities` with a per-device capability probe. * `Capabilities` holds the granted core and extension feature structs, granted extension names, core and extension properties, memory and queue family properties, and the denied optional requirements. * `PhysicalDeviceInfo` has `pdiCapabilities` and `pdiDeviceCreateInfo`. The logical device is created with exactly the probed set. Device properties are in `capsProperties`. * Device requirement reports go to the log. * Swapchain anisotropy is 1 when `samplerAnisotropy` is not granted. * Graphics pipelines enable sample shading only when `sampleRateShading` is granted. * Added `Engine.Setup.vmaFlags` and `Engine.Setup.allocateVma`. - The swapchain holds a render-finished semaphore per image (`sRenderFinished`). Swapchain recreation waits for the graphics queue to idle before the old semaphores are released. - A stage waits for its in-flight frames to retire (`Engine.Frame.drain`) before it is released. App exit waits for the device before releasing the swapchain. - Fixed `SpirV.Compile.glsl` reusing stale output. It recompiles when the compiler arguments change or the `.spv` is missing, and retries a failed compile on the next run. - Fixed a crash at exit when a stage release was still running while the device and VMA were destroyed. App teardown waits for pending stage releases. - Fixed an interrupted stage (e.g. Ctrl-C) destroying frame semaphores that submitted work still used. The stage loop waits for the device to idle before unwinding on an exception. - Fixed `Engine.Vulkan.Pipeline.Raytrace` shader stage flags for `rgen`, `rahit`, `rmiss` and `rcall`. - Fixed a retiring frame freeing its command buffer after its command pools went to the next frame. - Fixed `SUBOPTIMAL_KHR` from image acquisition leaving the image-available semaphore signalled. Such a frame is rendered and presented before the swapchain is recreated. - Fixed stage switches and app exit calling `vkDeviceWaitIdle` from two threads at once. - Fixed loader threads and the render loop using the same `VkQueue` at once (`UNASSIGNED-Threading-MultipleThreads-Write`). * Added `Engine.Vulkan.Types.Queue`, carrying a lock for its `VkQueue`. Queue slots that alias one `VkQueue` share its lock, distinct queues don't block each other. * `getQueues` returns `Queues Queue` instead of `Queues (QueueFamilyIndex, Vk.Queue)`. Setup locks the queues once, `pdiGetQueues` still returns the raw handles. * Added `withQueue`, `withQueues`, `waitDeviceIdle` and `lockQueues`. * `Resource.CommandBuffer.oneshot_`, frame submission, presentation and swapchain recreation hold the queue lock for their queue calls. `oneshot_` releases it before waiting for its fence. * `Engine.Frame.queueSubmit` takes a `Queue`. * App exit waits for the device idle while holding all queue locks. - Removed `Engine.Setup.deviceProps`, `Engine.Setup.portabilityEnum`, `Engine.Setup.Device.deviceHasTimelineSemaphores`, `pdiProperties`, `rrRenderFinishedSemaphore`, `SwapchainInfo`, `createSwapchain`, `srInfo`, `srImages`, `srImageViews`, `srRelease`, the present mode argument of `recreateSwapchainResources`, `HasRenderPass`, `RenderPass`, `NoRenderPass`, `sAllocateRP`, `fRenderpass`, `rAllocateRP`, `Render.Pass`, `Render.Pass.Offscreen`, `Offscreen.Settings.sColorLayout`/`sDepthLayout`/`sMipMap`, `Offscreen.depthTexture`/`depthCube`, `Engine.Stage.Component.Scene`, `scBeforeLoop`, `scUpdateBuffers`, `scRecordCommands`, `sRecordCommands`, `Resource.Image.Downsample.mipPyramid`, and the sample count argument of `Graphics.allocate`, `Graphics.create` and the `External` observers. ## 0.1.11.1 - Added `Texture.fromAllocatedImage` - Added `Resource.Image.Downsample.mipPyramid` * Exported `Image.DstImage` constructor. * Added `Image.allocateDstMipFor`. - Added `Worker.merge1M` for the times you absolutely must do some `MonadUnliftIO m` in reaction to the change. - Added `Resource.Static.collection` to splice the record type and fill it with source paths. - Added `MonadTrans Bound` instance. - Added `Worker.merge*` args-flipped variants of `spawnMerge*` with function in the last position. - Added `External.Params` wrapper for HKD pipeline collection that keeps the value in a Var. - Added `External.bindGraphics` helper to bind the most recent pipeline version. - Fixed 'Specialization.packConstData` for Float->Word32 bitcast. - Added `Offscreen.settingsTexture` and `settingsCubemap` as baselines. - Added `AllocatedImage.aiName`. ## 0.1.11.0 - Fixes and updates to match geomancy-0.3 rewrite. * Reverse-depth perspective camera. * Conter-clockwise winding. * PVM matrix composition order. - Changed the compatibility extensions for device and instance to be required, but put them under a `darwin_HOST_OS` define. * Even being optional they break launching under RenderDoc. ## 0.1.10.0 - Added `ghWindowSize` to replace `ghScreenVar` - a unified var to track window and framebuffer sizes, and their relative scale. (So you can use "pixel" sizes when running under scaled rendering a la MacOS.) - Added `Engine.Setup.Window.Size` and `getSize` to collect that information. - A related helper: `askWindowSize` to tie both. ## 0.1.9.1 - Addded new wrappers to `Engine.App`` * `withDataDir` to change directory so the `data` directory will match `./data`. * `withDefaultArgs` to set default options like msaa. - Added screen-grabbing functions to `Resource.Image`. - Added compatibility extension for instance CI to run on MoltenVK. - Added `Engine.Types.HasMonoTime` class and `secondsSinceStart` to get stable monotonic time in a sane range. ## 0.1.9.0 - Extracted `Engine.UI.Layout` and `...Layout.Linear` to `geomancy-layout`. - Added `Engine.Camera.trackOrthoPixelsCentered` to replace `trackScreen`. - Language features updated to GHC-9.4. ## 0.1.8.0 Massive ~~breakage~~ fixing around allocate/create/destroy patterns and naming things. - Deleted `Resource.DescriptorSets`. - Added `Resource.Vulkan.DescriptorPool`. - Renamed `Engine.Vulkan.Types.DsBindings` to `DsLayoutBindings`. - Added `allocate_` for `Engine.Vulkan.Pipeline.Graphics` and `Compute`. - Added `size`, `withSize` and experimental `HasField` instance for `Resource.Texture`. - Fixed SPIR-V signatures compatibility by hiding builtin interface vars. - `Engine.Worker.spawn*` and `Engine.Events.*` handlers and now self-registereing. - Due to `RunState`/`Sink RunState` loop callbacks now use a `MonadSink rs m` instead of `StageRIO rs`. - Added `Resource.Texture.Ktx2`. * It lacks the BC7 hack to force sRGB for compressed textures as it is possible to set the correct format directly. - Moved Base textures to KTX2 containers. KTX1 is soft-deprecated. - Graphics pipelines now able to fill the config automatically with `Graphics.vertexInput` helper. Using: * `HasVertexInputBindings` class that provides attribute bindings. * `HasVkFormat` class to generate bindings parameters automatically (with generics) or explicitly. * `vertexFormat`, `instanceFormat` helpers for using `HasVkFormat` to provide `HasVertexInputBindings` instances. - Added `Resource.Model.Observer` that wraps coherent buffers and is able to observe multi-buffered resources. - Changed `Swapchain.setDynamicFullscreen` to accept a frame directly. - Added `MonadReader` and `MonadState` instances for `Bound` to allow fetching models at draw call site. ## 0.1.7.2 - Added `--size` option to set the initial window size. - Added `--max-fps` option to limit frame rate. ## 0.1.7.1 - SPIR-V reflection loader changed to `spirv-reflect-ffi`. ## 0.1.7.0 - Graphics pipelines extracted to `Engine.Vulkan.Pipeline.Graphics`. - Added pipeline stage collections and `StageInfo` class. * Shader creation can now pluck stage flags from the collection. - Added `Engine.Vulkan.Pipeline.Raytrace` stages (no pipelines yet). - Added `Engine.Vulkan.Pipeline.External` worker for reloading pipelines. - Added `Engine.SpirV.Reflect` to facilitate safe reloads using `spirv-reflect` toolchain. - Added `Engine.Engine.Stage.Component` with rendering/resources/scenes decoupled. ## 0.1.6.1 - Minimal `vulkan` version is now 3.17. - Fixed VMA setup for headless rendering. - Add `Generically1` from `base-4.17` to replace `distributive`/`repesentable`. - `Engine.Worker.Cell` instances generalized to arbitrary pairs. * I.e. `(Var i, Var o)` is a `Cell`-like structure that can be driven externally while retaining the `Var` and `Observer` machinery. - `withFrozenCallStack` fixes for GHC-9.0. - `Engine.Worker` boilerplate for coherent `Resource.Buffer`. - Added `Resource.Image.Atlas` experimental container for tile atlases. - Added `Resource.Region` for detachable allocation scopes. - Added `Engine.Window.MouseButton.Collection` to facilitate button-related dispatch. - Added a shortcut around loop when a window is quitting. * Skips allocation of loop resources that wouldn't be used. * Sidesteps a race before release/allocate chain when unwinding stages leading to crashes. - Added `Engine.UI.Layout.Linear`. * Experimental for now, but require no workers and FRP-compatible. ## 0.1.6.0 - Added `Engine.Camera` with projection and view controls. - Worker `Cell` changed into an input-annotated `Merge`. ## 0.1.5.1 - Fixed `VMA.AllocatorCreateInfo` for `vulkan-3.15` and newer. ## 0.1.5.0 - Removed `allocateRenderpass_` from `RenderPass` class. - Added `allocateRP` stage field. - Added `Engine.Vulkan.Pipeline.Compute`. * Common shader code extracted to `Engine.Vulkan.Shader`. - Added shader specialization constants. * Graphic and compute pipeline configs extended with `spec` parameter. * `Shader.Specialization` class is used to derive vulkan schema at runtime and store values. - Added `Pipline.Configure` and `Compute.Configure` families to produce a matching `Config` type. - Added `cDepthCompare` to `Pipeline.Config`. - Removed `Zero` instance for pipline configs. * Use `baseConfig` value for better type inference and less imports. ## 0.1.4.1 - Added size information to `Resource.Image`: `aiExtent`. ## 0.1.4.0 - Changed `Render.Samplers.allocate` to use `maxAnisotropy` directly. - Relaxed `DescriptorSet.allocatePool` to any `MonadResource`. - Added KHR_Surface to headless requirements. - Added `Render.Pass.setViewportScissor`. - Added TRANSFER_SRC to Offscreen image usage. - Published `Render.Samplers.params`. ## 0.1.3.1 - Added `Engine.Setup.setupHeadless` to use without a surface. - Added queue assignment fallback when there are no distinct queues for compute and transfer. Fixes startup crash on Intel iGPUs. ## 0.1.3.0 - Changed mesh codec to use `Serialise` class instead of `Storable`. - Replaced RIO in resource loaders with constraints. - Added `Render.Pass` base module and `Render.Pass.Offscreen`. - `Resource.Image.AllocatedImage` got format and subresource information. - Removed `Resource.Image.createColorResource`, `Resource.Image.createDepthResource`. * Added unified `Resource.Image.create` instead. * Function names shortened to match qulified import style. ## 0.1.2.0 - Added `Resource.Source` type to mix external and embedded byte sources. - Added `Zstd.Compressed` wrapper and functions to compress/decompress `ByteString`. - Removed `Ktx1.createTexture`. - Added `load`, `loadBytes`, `loadKtx1` instead. ## 0.1.1.1 - Added `spawnMergeT` to merge traversable collections. - Added `HasStateRef` to make stage state accessible from `StageFrameRIO`. - Added module labels to pipelines and their layouts. ## 0.1.1.0 - Added `--display NUM` to application arguments. - Allow `Timed` workers to skip output update. - `spawnTimed` and `spawnTimed_` changed args: active/dt moved to front. - `spawnTimed` now uses initialization function instead of deriving initial output from initial state. ## 0.1.0.1 - Inter-stage resource release waits for render job to finish.