Refactor renderer and documentation for clarity and support#27
Merged
Conversation
Added a check in the App class constructor to throw a PlatformNotSupportedException if the application is run on an OS other than Windows, macOS, or Linux. This prevents execution on unsupported platforms.
Refactored window initialization to specify the title ("Cornell Box - Zenith.NET") and size (1280x720) directly in the creation options, making the code more concise and improving clarity.
Restores Vulkan-specific resource binding indexing logic in BindingHelper to ensure correct binding indices. Removes Extensions.cs, eliminating the ImGui overlay extension method and related helpers.
Renamed Mouse_MouseDown, Mouse_MouseUp, and Mouse_MouseMove to OnMouseDown, OnMouseUp, and OnMouseMove for clarity. Updated event subscriptions to use the new method names. No changes to event handler logic.
Refactored the renderer code to remove embedded shader source strings from C# files. Shaders for both path tracing and rasterization are now stored as external `.slang` files in `Assets/Shaders`, and are loaded at runtime using a new `ShaderPath` helper. This improves maintainability, enables syntax highlighting, and separates shader code from application logic. No changes were made to shader logic or rendering behavior.
Replaced all usages of the ConstantBuffer<RasterConstants> variable 'constants' with 'raster' in both VSMain and PSMain. Updated all references to transformation matrices, light, and camera properties accordingly for improved naming consistency.
- Optimize Fresnel-Schlick with multiplications instead of pow - Add buildONB for orthonormal basis; use in sampling functions - Improve GGX and hemisphere sampling with ONB and sincos - Increase shadow ray offsets to reduce self-intersection - Use geometric normal for direct lighting/shadow ray offset - Refactor ACES tonemapping and sRGB conversion into helpers - Apply consistent color processing in both pipelines - Clean up redundant code and clarify light calculations
…ton sequence for improved rendering accuracy
Replaced hardcoded 3.14159265 with PI constant in cosineSampleHemisphere for clarity. Renamed random variables u/v to r1/r2 in sampleLightDirect to match naming conventions and improve code consistency.
Lower light source to y=547.0 for consistency across all files. Replace Blinn-Phong shading in Rasterization.slang with a physically-based rendering (PBR) model using GGX, Schlick geometry, and Fresnel-Schlick functions. Update light attenuation to use inverse-square law, apply ACES filmic tone mapping before sRGB conversion, and refine ambient term for more realistic results.
Previously, the argument table for mesh shading pipelines was set only for the Object and Mesh stages. This change adds the Fragment stage, ensuring that resources are correctly bound and accessible in the fragment shader stage as well.
Introduce helper methods to convert Matrix4x4 to platform-specific 3x4 matrix formats for DirectX 12, Metal, and Vulkan acceleration structures. Replace previous unsafe casts with these explicit conversions to improve clarity and ensure correct memory layout. Update relevant files to use System.Numerics for Matrix4x4 support.
Expanded matrix element assignments in DXFormats.DirectX12, MTLFormats.Metal, and VKFormats.Vulkan to use one line per element instead of compact row assignments. This change improves code readability and maintainability without altering functionality.
Changed DXFormats, MTLFormats, and VKFormats to unsafe static classes, moving the unsafe context from individual methods to the class level. Updated matrix conversion methods to remove the unsafe modifier from their signatures. No logic changes were made.
Deleted the entire CONVENTIONS.md file, including all project conventions, GPU alignment rules, resource patterns, render loop details, geometry data, and code samples for both C# and Slang. This removes all internal documentation and development guidelines from the repository.
Revamp mesh shading to use amplification shader culling and render 1,000 procedural spheres with per-instance frustum culling. Upgrade ray tracing to support soft shadows, rough reflections, Fresnel, and ACES tonemapping with an animated camera. Refactor framework to use App.FrameBuffer and improve resource management. Update all tutorials and documentation for consistency, clarity, and modern GPU best practices.
Added the _gitUrlPattern property to docfx.json, enabling generated documentation to include direct links to specific lines in the GitHub repository. This improves traceability and makes it easier for users to navigate from documentation to the relevant source code.
Replaced PNG files for compute-shader, indirect-drawing, mesh-shading, ray-tracing, and spinning-cube with updated versions. No source code changes included.
Major overhaul of all Zenith.NET tutorial docs for clarity and pedagogy: - Each tutorial now begins with a concise summary and bullet-pointed overview of key concepts and learning objectives. - "Running the Tutorial" sections updated to use an interactive menu, not manual Program.cs edits. - Screenshots and code snippets standardized for consistency and clarity. - Code breakdowns expanded: detailed explanations of shaders, buffers, pipelines, resource binding, and rendering steps for each tutorial. - Prerequisites page rewritten: clear project structure, package requirements, .csproj config, and all shared framework files included with explanations. - Outdated or redundant setup instructions removed or consolidated. - Explanations now include tables, diagrams, and step-by-step breakdowns for better understanding. - Documentation is now more beginner-friendly and visually organized. - No changes to actual renderer code; all changes are to documentation only.
Clean up unused variables in mesh-shading and ray-tracing code snippets. Refine tutorial instructions for dynamic texture resizing. Update NuGet package lists and .csproj sample for correct dependency order. Add instructions and link for required image asset (shoko.png) in the Assets folder. These changes improve clarity and streamline the tutorial setup process.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves cross-backend ray tracing transform handling and refactors tutorial/experiment shader and documentation content to better match the current Zenith.NET APIs and recommended patterns.
Changes:
- Replaced unsafe matrix reinterprets for TLAS/BLAS transforms with explicit
Matrix4x4 -> 3x4conversion helpers (Vulkan/Metal/DirectX 12). - Refactored CornellBox experiment shaders to external
.slangfiles and added a shared shader-path helper. - Updated and expanded tutorial documentation (getting-started → advanced) and enhanced DocFX source linking.
Reviewed changes
Copilot reviewed 31 out of 36 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| sources/Zenith.NET.Vulkan/VKTopLevelAccelerationStructure.cs | Uses explicit transform conversion for TLAS instances. |
| sources/Zenith.NET.Vulkan/VKFormats.cs | Adds Matrix4x4 -> TransformMatrixKHR conversion helper. |
| sources/Zenith.NET.Vulkan/VKBottomLevelAccelerationStructure.cs | Uses explicit transform conversion for BLAS geometry transforms. |
| sources/Zenith.NET.Metal/MTLTopLevelAccelerationStructure.cs | Uses explicit transform conversion for TLAS instances. |
| sources/Zenith.NET.Metal/MTLFormats.cs | Adds Matrix4x4 -> MTLPackedFloat4x3 conversion helper. |
| sources/Zenith.NET.Metal/MTLCommandEncoder.cs | Binds mesh shading argument tables to fragment stage as well. |
| sources/Zenith.NET.Metal/MTLBottomLevelAccelerationStructure.cs | Uses explicit transform conversion for BLAS geometry transforms. |
| sources/Zenith.NET.DirectX12/DXTopLevelAccelerationStructure.cs | Uses explicit transform conversion for TLAS instances. |
| sources/Zenith.NET.DirectX12/DXFormats.cs | Adds Matrix4x4 -> Matrix3X4<float> conversion helper. |
| sources/Zenith.NET.DirectX12/DXBottomLevelAccelerationStructure.cs | Uses explicit transform conversion for BLAS geometry transforms. |
| sources/Experiments/CornellBox/Renderers/Renderer.cs | Adds shared ShaderPath(...) helper for shader file loading. |
| sources/Experiments/CornellBox/Renderers/RasterizationRenderer.cs | Switches raster shaders from inline source to file-based .slang. |
| sources/Experiments/CornellBox/Renderers/PathTracingRenderer.cs | Switches path tracing shader from inline source to file-based .slang. |
| sources/Experiments/CornellBox/Helpers/Extensions.cs | Removes unused ImGui overlay extension. |
| sources/Experiments/CornellBox/Helpers/CornellBoxGeometry.cs | Adjusts ceiling light quad position (y=547). |
| sources/Experiments/CornellBox/Helpers/BindingHelper.cs | Reorders Vulkan binding-index assignment case. |
| sources/Experiments/CornellBox/Handlers/CameraHandler.cs | Renames mouse event handlers for clarity. |
| sources/Experiments/CornellBox/CONVENTIONS.md | Removes large internal conventions document from the experiment. |
| sources/Experiments/CornellBox/Assets/Shaders/Rasterization.slang | Adds external rasterization shader implementation. |
| sources/Experiments/CornellBox/Assets/Shaders/PathTracing.slang | Adds external path tracing shader implementation (MIS/jitter updates). |
| sources/Experiments/CornellBox/App.cs | Adds platform guard and improves window initialization options. |
| documents/tutorials/intermediate/indirect-drawing.md | Updates tutorial narrative and code to current API (App.FrameBuffer, constants naming, etc.). |
| documents/tutorials/intermediate/compute-shader.md | Updates tutorial narrative, shader math, and App.FrameBuffer usage. |
| documents/tutorials/index.md | Updates tutorial descriptions and run-flow (menu-based selection). |
| documents/tutorials/getting-started/textured-quad.md | Updates shader/resource binding explanations and App.FrameBuffer usage. |
| documents/tutorials/getting-started/spinning-cube.md | Updates constants naming, shader semantics, and per-frame update flow. |
| documents/tutorials/getting-started/prerequisites.md | Updates project setup guidance and shared framework code (menu-based Program.cs). |
| documents/tutorials/getting-started/hello-triangle.md | Expands explanation and updates snippets to current API usage. |
| documents/tutorials/advanced/ray-tracing.md | Expands tutorial and updates implementation details (soft shadows/reflections/ACES). |
| documents/tutorials/advanced/mesh-shading.md | Expands tutorial and updates implementation details (GPU culling + instancing). |
| documents/images/indirect-drawing.png | Updates screenshot asset. |
| documents/docfx.json | Adds _gitUrlPattern for improved source navigation links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Updated the Version field in NuGet.Packaging.props from 0.0.7 to 0.0.8 to reflect the latest changes.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Refactored the shadow ray tracing logic to assign TMax directly and validate it without using a temporary variable. This improves code clarity and removes unnecessary steps.
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.
This pull request updates and improves the "Hello Triangle" and "Spinning Cube" tutorial documentation for Zenith.NET, focusing on clarity, code accuracy, and modern best practices. The main changes include rewriting and expanding the explanations, updating code snippets to match the latest API, and improving the structure and readability of both tutorials.
Documentation improvements and tutorial clarity:
hello-triangle.mdandspinning-cube.mdto better explain the concepts covered, emphasizing graphics pipeline setup, buffer usage, and animation. [1] [2]Code and API consistency updates:
App.FrameBufferinstead ofApp.SwapChain.FrameBufferfor rendering output, reflecting recent API changes. [1] [2] [3]constantBufferandMVPConstantstoconstantsBufferandConstantsin the spinning cube tutorial. [1] [2] [3] [4]Shader and buffer improvements:
COLORinstead ofCOLOR0) and simplified the transformation logic in the spinning cube shader for clarity. [1] [2]Resource management and cleanup:
Miscellaneous:
_gitUrlPatterntodocfx.jsonto improve source code navigation in documentation builds.These changes make the tutorials more accurate, maintainable, and accessible for new users of Zenith.NET.