Skip to content

v1.0.0-rc

Latest
Latest

Choose a tag to compare

View all tags
@qian-o qian-o released this 29 Jul 12:10
v1.0.0-rc
c635d9e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Zenith.NET v1.0.0-rc - Bindless resources, barriers, and texture transitions

This release candidate introduces a complete redesign of the Zenith.NET rendering hardware interface. The new model provides one consistent C# API for graphics and compute across DirectX 12, Metal 4, and Vulkan 1.4, with bindless resource access and explicit synchronization at its core.

The three central responsibilities are intentionally separate:

Concern API Responsibility
Shader resource access ResourceHandle Identifies the resource a shader accesses
Same-layout dependency CommandBuffer.Barrier Makes earlier GPU writes available to later GPU work
Texture access role CommandBuffer.Transition Changes the layout of one texture subresource

Bindless Resource Access

Resources and views now expose compact ResourceHandle values directly. Store these handles in constant data, declare the corresponding typed DescriptorHandle<T> fields in Slang, and bind the constant buffer before dispatching or drawing.

  • Buffers expose constant, read-only storage, and read-write storage handles.
  • Textures expose sampled and storage handles.
  • Views provide handles for selected buffer ranges, mip levels, and array layers.
  • Samplers and top-level acceleration structures expose their own handles.
  • ResourceLayout, ResourceTable, ResourceBinding, and SetResourceTable are no longer part of the API.

A handle provides shader access only. It does not own the resource, insert a barrier, or change a texture layout. Applications must keep the referenced resource or view alive and record the required synchronization explicitly.

Explicit Synchronization

Memory Barriers

Use CommandBuffer.Barrier(before, after) when GPU work consumes data produced earlier in the same command buffer without changing a texture layout. BarrierStages identifies the producing and consuming stages, including vertex, fragment, compute, copy, and resolve work.

This covers storage-buffer producer/consumer chains, compute-generated indirect arguments, and other same-layout dependencies. BarrierStages.All remains available when a narrower dependency cannot describe the workload.

Texture Layout Transitions

Every texture subresource has an application-supplied layout while commands are recorded. Use CommandBuffer.Transition(texture, subresource, before, after) whenever its access role changes.

The public layout model includes sampled and storage access, color and depth/stencil attachments, copy and resolve operations, presentation, and a common layout for shared-resource paths. TextureLayout.Undefined may be used as the source only when previous contents can be discarded.

Copy, resolve, and command-buffer upload or download operations do not insert transitions automatically. The synchronous Texture.Upload and Texture.Download helpers perform the current-to-final transitions declared by the caller.

Redesigned RHI

  • Command buffers are borrowed from a queue, submitted back to that queue, and recycled after completion.
  • TimelineValue provides GPU-side dependencies across submissions and queues without blocking the CPU.
  • Render passes receive ColorAttachment and DepthStencilAttachment values directly instead of using framebuffer objects.
  • Buffers and textures support explicit usage declarations, memory residency, views, standalone allocation, and placed allocation through Heap.
  • Slang compilation is available through ZenithCompiler, including reflected compute thread-group sizes.
  • Occlusion and timestamp queries use one common workflow, with queue-owned timestamp conversion to nanoseconds.
  • Rasterization, compute, indirect drawing, inline ray tracing, and mesh shading follow the same resource and synchronization model.

Deprecated Package: Zenith.NET.Extensions.Slang

The Zenith.NET.Extensions.Slang package is deprecated and has been removed from the repository. Shader compilation is now provided by ZenithCompiler in the core Zenith.NET package. Remove the extension package reference when migrating to v1.0.0-rc; no replacement package is required.

Known Issue: Vulkan Acceleration Structures

Warning

Vulkan acceleration-structure and ray-query support is currently experimental. A minimal Vulkan 1.4 reproduction using VK_EXT_descriptor_heap and a Slang DescriptorHandle to access a top-level acceleration structure causes VK_ERROR_DEVICE_LOST on a known NVIDIA 610.74 configuration. Other drivers and hardware may behave differently. See VulkanRayQueryTriangle for the reproduction and current details.

Breaking Changes

This release is not source-compatible with v0.0.8. Existing applications should be migrated to the redesigned API rather than updated package-by-package.

v0.0.8 model v1.0.0-rc model
ResourceLayout, ResourceTable, and SetResourceTable Resource handles stored in constant data and bound through SetConstantBuffer
No public barrier or texture-layout model Explicit BarrierStages, TextureLayout, Barrier, and Transition
FrameBuffer and ClearValue ColorAttachment and DepthStencilAttachment passed directly to BeginRenderPass
Command-buffer submission with optional CPU waiting Submit returns a TimelineValue; call Wait only when the CPU needs completion
Zenith.NET.Extensions.Slang package Deprecated; remove the package reference and use ZenithCompiler from Zenith.NET
Previous resource descriptions and state enums Redesigned descriptions with explicit usages, residency, attachment operations, and subresources

Several public types and enum names have also changed as part of the redesign. Use the new RHI Guide and tutorials as the migration reference.

FluidTank Experiment

This release adds FluidTank, a GPU APIC fluid simulation and renderer built on the redesigned API. It exercises bindless resources, multi-pass compute, explicit barriers and layout transitions, indirect work, and real-time rendering through the same public RHI used by applications.

Requirements

  • .NET 10.0 or later
  • DirectX 12 on Windows, Metal 4 on Apple platforms, or Vulkan 1.4
  • The core package and one backend package at the same version
dotnet add package Zenith.NET --version 1.0.0-rc
dotnet add package Zenith.NET.Vulkan --version 1.0.0-rc

Replace the Vulkan package with Zenith.NET.DirectX12 or Zenith.NET.Metal when using another backend.

Documentation

Release Status

This is the first release candidate for Zenith.NET 1.0. The redesigned API is ready for broader testing, but signatures and platform behavior may still be refined before the stable release.

Primary redesign: #28

Full changelog: v0.0.8...v1.0.0-rc

Assets 2
Loading