Repository navigation
feature(vulkan): support per-dispatch push constants - #124
Merged
chuzcjoe merged 1 commit intoOct 23, 2026
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
VulkanBase::Init()fixespushConstantRangeCountat zero. Derived compute and graphics pipelines cannot declare push constants while reusing the existing descriptor/pipeline initialization path. The existing barycentric rasterizer uploads one fixed triangle into a uniform buffer during initialization and exposes no per-dispatch triangle parameters. Recording several triangles against one repeatedly overwritten uniform buffer would not preserve a parameter snapshot for each dispatch.This PR delivers per-dispatch push constants through the existing pipeline abstraction and uses them in the existing rasterizer. It is independently based on freshly fetched/reconfirmed
origin/masteratf7070c0d9648b2dc7e583fe07e4868b80a57f609. Recent commits, open issues/PRs and relevant closed PRs were checked; closed unmerged transfer-session #117, Mat-view #116 and result-API #118 are not dependencies or repeated here.Solution
GetPushConstantRanges()hook, with an empty default for existing derived pipelines. Validate nonzero stages, stage uniqueness across ranges, four-byte alignment, nonempty sizes and the physical-device size limit before creating resources. Use subtraction for the bounds check to avoid overflow. Initialize descriptor handles to null so rejected initialization remains safe to destroy.ComputeBarycentricto a 32-byte push-constant block containing dimensions and integer vertices. RetainRun(command)for the original triangle; addRun(command, Triangle)for independently recorded triangles. Remove its fixed uniform buffer and descriptor. The output buffer accumulates triangle coverage until the caller clears it; reusing the pipeline across completed submissions remains supported.rasterized.png.Usage
After the normal macOS build, run from the repository root:
The generated PNG contains the original triangle plus a second independently parameterized triangle. Callers can record additional triangles through the existing initialized rasterizer:
rasterizer.Run(command); rasterizer.Run(command, core::example::ComputeBarycentric::Triangle{ .a = glm::ivec2(50, 450), .b = glm::ivec2(150, 50), .c = glm::ivec2(250, 450)});The complete example shows command recording, the final host-read barrier, submission and fence waiting. Triangle argument storage can be changed or released after
Runreturns; the rasterizer, output buffer and context must remain alive until execution completes. Clear or inspect the host-visible output only after completion.Other
VulkanBasesubclasses can overrideGetPushConstantRanges(), match those ranges in their shaders and call nativevkCmdPushConstantswith the existing publicpipeline_layout. Shader stage masks, byte layout and command/layout compatibility remain caller responsibilities. This follows the Khronos push-constant guide and range requirements.Alternatives and candidate comparison
CopyToImageonly exposes whole-image geometry. A consolidated upload has real callers, while region/pitch support needs a concrete update workload. Requires a clear layout/ownership and batching contract.A uniform-buffer ring would require buffer slices, alignment and descriptor-offset lifetimes for a 32-byte payload. Replacing all pipeline initialization in the example would duplicate the library path. The range hook keeps one initialization path, while the example uses native Vulkan command recording. No asynchronous ownership framework or external dependency is added. All changes are within Vulkan, its existing example and its tests/build support; no shared-module or other-backend implementation changes are included.
Validation
Both full platform builds/tests completed on the final committed source tree, with the
corewarnings-as-errors configuration. The scripts request Debug, but current top-level CMake selects the actual Release-O3 -DNDEBUGflags. Final runs were repeated after the last code/formatting changes../scripts/run.sh -t macos -r tests./scripts/run.sh -t arm64-v8a -r testsEnvironment:
adb devices -lconfirmed exactly one authorized physical USB device, 2210132C / nuwa, Android 13 / API 33. The emulator property was empty and hardware was qcom.ANDROID_SERIAL=1dda2807fixed every subsequent adb operation to that device.ANDROID_NDK_ROOTand SDK variables were explicit; sourced/Users/joechu/VulkanSDK/1.4.350.0/setup-env.shand ensured CMake, adb, glslc, slangc and xxd resolved in PATH. No dependency installation, license acceptance, profile edit, APK installation or device-setting change.Four new tests cover device-limit and overlapping-byte/distinct-stage layouts; invalid alignment/size/stage duplication/overflowing bounds; independent parameter snapshots, overlapping/clipped triangles and command-buffer/pipeline reuse across three submissions; all original-triangle pixels, single-pixel and extreme-coordinate output, invalid dimensions/coordinates and recording recovery after rejection. Existing pipelines exercise the unchanged empty-range default.
./build/macos/examples/vk_rasterize_demoalso exited 0. An independent standard-library PNG decoder and integer edge oracle verified all 1,000,000 output pixels against the union of both triangles. The same rasterizer/shader code executed in Android integration tests; the standalone PNG-writing main is a macOS example target. Other graphical examples were built but not visually exercised.git diff --checkpassed; reviewed the complete diff, staged files and source tree. No new code comments, generated binaries/assets or project documentation were committed. Separate final macOS/Android logs, exit codes, device listings, source-tree hash, example/pixel checks and result verifier are retained in this worktree's ignoredbuild/daily-push-constants-20261022/; macOS tmp results were preserved before the Android script recreated tmp.This is a feature acceptance result. No performance benchmark, latency/FPS improvement or process-memory measurement is claimed.
Changes
vulkan/include/VulkanBase.hvulkan/src/VulkanBase.cppexamples/vulkan/ComputeBarycentricRasterizer/Barycentric.compexamples/vulkan/ComputeBarycentricRasterizer/ComputeBarycentric.cppexamples/vulkan/ComputeBarycentricRasterizer/ComputeBarycentric.hexamples/vulkan/ComputeBarycentricRasterizer/main.cpptests/vulkan/CMakeLists.txttests/vulkan/VulkanPushConstantsTest.cpp397 changed lines, below the 1000-line cap: implementation/API/example +123/-45; tests/build +228/-1; benchmark 0; documentation 0. Design, usage, compatibility and acceptance evidence are contained in this PR body; no docs Markdown or README link is added.
Risk
The library hook is additive with an empty default, and existing public method signatures remain available. Adding a virtual hook changes the C++ vtable ABI, so consumers must rebuild derived pipelines together with CORE; binary compatibility with previously compiled subclasses is not promised. The example's private shader interface changes with its rebuilt shader, retains the original triangle overload, and now rejects out-of-range geometry explicitly. It remains a coverage-mask rasterizer with the existing winding rule, not a general mesh renderer.
The conservative write barrier serializes overlapping dispatches; no throughput improvement is claimed. Callers still own command/queue synchronization and resource lifetimes, and native push-constant writes must obey the declared ranges and shader layout. No automatic merge, deployment or publication is part of this PR.