Refactor renderer and documentation for clarity and support (#27)

* Add platform check to restrict app to supported OSes

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.

* Set window title and size during creation

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.

* Restore Vulkan binding indexing; remove ImGui overlay helper

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.

* Refactor mouse event handler method names in CameraHandler

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.

* Move shaders to external Slang files and load from disk

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.

* Rename 'constants' buffer to 'raster' in shaders

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.

* Refactor sampling, tonemapping, and shading in shaders

- 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

* Refactor BRDF calculations and shadow ray origins for improved accuracy

* Enhance BRDF sampling and light sampling with power heuristic and Halton sequence for improved rendering accuracy

* Refactor: use PI constant and unify RNG variable names

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.

* Update light position and add PBR shading to rasterizer

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.

* Add Fragment stage to mesh shading argument table setup

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.

* Add explicit Matrix4x4-to-3x4 conversions for RTAS

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.

* Refactor matrix assignments for clarity in format methods

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.

* Mark format helper classes as unsafe, update method signatures

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.

* Remove CONVENTIONS.md documentation

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.

* Modernize advanced tutorials: mesh shading & ray tracing

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.

* Add _gitUrlPattern to docfx.json for source code links

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.

* Update demo images for compute, mesh, ray tracing, and cube

Replaced PNG files for compute-shader, indirect-drawing, mesh-shading, ray-tracing, and spinning-cube with updated versions. No source code changes included.

* Rewrite and clarify all tutorial documentation

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.

* Update docs: clarify code, dependencies, and asset setup

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.

* Bump package version to 0.0.8

Updated the Version field in NuGet.Packaging.props from 0.0.7 to 0.0.8 to reflect the latest changes.

* Update sources/Experiments/CornellBox/Assets/Shaders/PathTracing.slang

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Simplify shadow ray TMax assignment and validation

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.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Bump version to 0.0.7 and enhance documentation and API clarity (#26)

* Bump package version to 0.0.7

Updated the Version field in NuGet.Packaging.props from 0.0.6 to 0.0.7 to prepare for the next release. No other changes were made.

* fix(docs): update README to remove work in progress status for Metal backend

* fix(docs): update docfx.json and main.js for improved documentation structure

* fix(docs): correct order of properties in docfx.json

* fix(docs): correct order of properties in docfx.json

* feat(search): enhance search results navigation with back button support

* Update docs and samples for Metal 4 & Vulkan 1.4 support

Clarify API versions (DirectX 12, Metal 4, Vulkan 1.4) throughout docs, tables, and code comments. Refactor backend selection logic for correct platform mapping. Update resource binding helper and ray tracing samples for accuracy. Improve table formatting and header link visibility in CSS. Expand design philosophy to explain backend version choices.

* fix(docs): update CornellBox conventions for accuracy in DirectX and Vulkan versions

* Update templates and metadata for API version clarity

- Streamlined bug report template by merging sections and clarifying environment details; updated placeholders to specify API versions (DirectX 12, Metal 4, Vulkan 1.4).
- Removed general issue template (custom.yaml) and "Feature Discussions" contact link, directing general queries to Discussions.
- Updated NuGet package description and tags to reflect precise supported API versions.

* Update platform order to Windows, macOS, Linux throughout

Reorder platform checks in App.cs for backend/surface selection.
Standardize documentation and UI to use "Windows, macOS, Linux".
Fix minor typos and clarify backend binding notes in docs.
No functional changes; improves clarity and consistency.

* Update package tag from Metal4 to Metal in NuGet props

Broadened the <PackageTags> entry in NuGet.Packaging.props by replacing "Metal4" with "Metal" to refer to all versions of Metal, not just version 4. This improves discoverability and accuracy of the package metadata.

* fix(docs): standardize graphics API naming conventions in documentation

* Add Silk.NET.MoltenVK.Native for MoltenVK support

Added Silk.NET.MoltenVK.Native (v2.23.0) to enable MoltenVK,
improving Vulkan compatibility on macOS. Updated both
Directory.Packages.props and Zenith.NET.Vulkan.csproj to include
the new package dependency.

* fix: use history.replaceState for search navigation

refactor: simplify API for Metal compatibility (#19)

* Refactor resource binding and pipeline descriptors

- Replace ResourceSet/ResourceSetDesc with ResourceTable/ResourceTableDesc
- Simplify pipeline descriptors to use a single ResourceLayout
- Remove unused shader stages and ray tracing pipeline support
- Streamline PrimitiveTopology and RayTracingGeometryFlags enums
- Refactor Uploader buffer management for better lease handling
- Update validation logic to match new resource and pipeline models
- Remove HitGroup, HitGroupType, and related ray tracing code
- General cleanup for a simpler, more maintainable API

* Refactor: unify resource binding with ResourceTable

Major refactor replacing ResourceSet with ResourceTable for both DirectX 12 and Vulkan backends. Updates all creation and binding logic to use the new abstraction, introduces DXResourceTable and VKResourceTable, and removes the old ResourceSet classes. Simplifies pipeline and shader stage handling by removing tessellation, geometry, and ray tracing pipeline support. Cleans up extension methods, pipeline layouts, and descriptor binding logic. This unifies and modernizes resource management across backends.

* Add Metal backend support and refactor resource binding

This commit introduces support for the Metal graphics backend in ImGuiRenderer by adding Metal shader byte arrays, a Metal-specific resource layout, and logic to select these when Metal is used. It also refactors resource binding throughout the renderer, replacing ResourceSet with ResourceTable and updating all related code paths, including ImTextureID binding, command buffer calls, and disposal logic. Additionally, shader compilation for Metal now targets metallib, and argument lists are cleaned up. These changes modernize the renderer and enable Metal support.

* Rename Metal shader arrays/descs to Metallib/MetallibDesc

Renamed Metal and MetalDesc to Metallib and MetallibDesc throughout the codebase to clarify that these refer to Metal library (.metallib) resources. This improves code clarity and consistency regarding Metal shader handling.

* Refactor: Replace ResourceSet with ResourceTable throughout

Refactored all render passes and resource binding logic to use ResourceTable instead of ResourceSet. Updated all relevant fields, methods, and resource creation/disposal code. Migrated RTGIPass from RayTracingPipeline to a compute-shader-based approach using RayQuery, and updated RTGI.slang accordingly. Adjusted resource layout bindings and shader stage flags to match the new model. This unifies and modernizes the resource binding system in line with recent graphics API changes.

* Ignore JetBrains .idea/ directory in .gitignore

Added .idea/ to .gitignore to prevent JetBrains IDE configuration files from being tracked in version control. This helps keep the repository clean from user-specific IDE settings.

* Update NuGet package versions in Directory.Packages.props

Bumped versions for Avalonia, Microsoft.Maui.Controls, Microsoft.WindowsAppSDK, SkiaSharp, Slangc.NET, and Uno.WinUI to their latest releases. No other changes were made.

* Update resource binding to ResourceTable; refactor ray tracing

Replaced ResourceSet with ResourceTable across docs and tutorials. Refactored pipeline descriptions to use a single ResourceLayout and ResourceTable. Ray tracing now uses RayQuery in compute shaders, removing multi-stage pipeline and hit groups. Updated all code samples, API references, and navigation for consistency. Documentation now reflects unified terminology and modern resource binding patterns.

* Add SceneConstants buffer and procedural ray intersection

Introduced SceneConstants struct and constant buffer for passing render target dimensions to the compute shader. Refactored resource layout and shader logic to use the constant buffer instead of querying texture dimensions. Added custom IntersectSphere function for procedural ray-sphere intersection, used in both main and shadow ray queries. Improved shading logic and updated output texture format. Updated resource cleanup and tutorial documentation to reflect these changes.

* Remove SceneConstants; query output size in shader

Simplifies the ray tracing renderer by removing the SceneConstants struct and its constant buffer from both C# and shader code. The shader now uses GetDimensions to obtain the output texture's width and height, eliminating the need to pass these values explicitly. Resource bindings and related buffer management code are updated accordingly, improving flexibility and reducing boilerplate.

* Update docs: clarify pipeline features and workflow steps

- Bolded pipeline names in the features table for clarity.
- Clarified Ray Tracing supports RayQuery in any shader stage.
- Updated workflow step to mention mesh shading dispatches.

* Clarify RayQuery support in any shader stage in docs

Updated README, ray-tracing.md, and index.md to state that RayQuery-based ray tracing is supported in any shader stage, not just compute shaders. Adjusted descriptions and tables to remove compute-only references and accurately reflect Zenith.NET's ray tracing capabilities.

* Add PackageProjectUrl to NuGet package metadata

Added the <PackageProjectUrl> property in NuGet.Packaging.props to include the project's website (https://qian-o.github.io/Zenith.NET) in the NuGet package metadata. This enhances discoverability and provides users with a direct link to project documentation and resources.

* Bump package version to 0.0.6

Updated the Version field in NuGet.Packaging.props from 0.0.5 to 0.0.6 to prepare for the next release. No other changes were made.

* Update ray tracing docs with placeholder; add link in indirect

Replaced detailed ray-tracing.md content with a construction notice and topic summary. Updated "See Also" section to a bulleted list. Added a Ray Tracing link to indirect-drawing.md under "Next Steps."

* Rename pipeline features to Graphics, Compute, Mesh Shading

Updated documentation and navigation to use "Graphics", "Compute", and "Mesh Shading" instead of "Graphics Pipeline", "Compute Pipeline", and "Mesh Shading Pipeline" for consistency. Replaced old feature docs with new placeholder pages and updated toc.yml and feature tables accordingly.

* Format and whitespace cleanup in documentation files

Minor formatting and whitespace adjustments across Markdown docs.
No content or structural changes; improved consistency in
badges, tips, and blank lines.

* Remove trailing commas from array initializers in renderers

Cleaned up code style by removing trailing commas from the last
elements of array initializers in MeshShadingRenderer,
SpinningCubeRenderer, TexturedQuadRenderer, and
IndirectDrawingRenderer. No changes to code logic or behavior.

* Remove redundant using directive from Extensions.cs

Cleaned up Extensions.cs by removing an unnecessary using directive for Zenith.NET.Views.Maui, as the file is already within the same namespace. This reduces redundancy and improves code clarity.

Feature: Add MauiZenithView for iOS and MacCatalyst (#17)

* Add Sandbox.Maui: cross-platform MAUI sample with Zenith.NET

Added a new .NET MAUI project, Sandbox.Maui, targeting Android, iOS, MacCatalyst, and Windows. The project demonstrates integration of Zenith.NET graphics rendering within a MAUI UI, including a sample page with a counter and a ZenithView. Platform-specific startup/configuration files, app icons, splash screens, images, and fonts were included. Added resource dictionaries for colors and styles, and documentation for asset management. Project references to Zenith.NET graphics backends and Zenith.NET.Views.Maui were established.

* Update render pass to clear color, depth, and stencil buffers

Changed render pass options to clear all buffers by setting
Depth to 1.0, Stencil to 0, and Flags to ClearFlags.All,
ensuring color, depth, and stencil buffers are cleared at
the start of each render pass.

* Add Metal swapchain support to MauiZenithView (iOS/MacCat)

Implement CAMetalLayer and swapchain management for MauiZenithView on both iOS and MacCatalyst. This includes dynamic swapchain creation, resizing, and presentation, as well as updated pixel formats for color and depth-stencil attachments. Rendering is now performed only when the graphics context and view size are valid, improving resource management and enabling efficient Metal-based rendering.

* Add Foundation and ObjCRuntime usings to MauiZenithView

Added using directives for Foundation and ObjCRuntime in MauiZenithView.cs to enable access to Apple platform-specific types and functionality. This prepares the file for features or integrations that rely on these namespaces.

* Use Vulkan only; add animated HSV gradient background

Removed OS-specific graphics context selection in App.xaml.cs to always use Vulkan. Added animated HSV color gradient background in MainPage.xaml.cs by incrementing hue on each render and converting HSV to Vector4. Added System.Numerics import for Vector4 support.

* Remove Sandbox.Maui project and all related files

Deleted the entire Sandbox.Maui experimental MAUI application, including its project file, source code, platform-specific files, resources, and configuration. Also removed its reference from the solution file. This cleans up the repository by eliminating the MAUI sample app and all associated assets.

* Remove XML declaration from Zenith.NET.slnx file

The XML declaration at the top of Zenith.NET.slnx was removed or replaced. No changes were made to the solution structure or project references.

* Refactor pixel format selection with ZenithViewHelper

Centralize color and depth/stencil pixel format selection in a new ZenithViewHelper class, replacing hardcoded formats throughout the codebase. Update all platform backends to use these helper properties, add conversion utilities as needed, and adjust Uno backend stream writing for correct byte order. This improves consistency, maintainability, and cross-platform support.

* Refactor color format resolution to use ColorFormat()

Replace static Convert methods with ColorFormat(), which uses ZenithViewHelper.ColorTargetFormat directly. This centralizes and simplifies color/pixel format handling for surfaces and textures, and updates error messages to reference the global format.

* Refactor ZenithViewHelper property initialization

Moved property initialization for ColorTargetFormat and DepthStencilTargetFormat from the static constructor to inline expression-bodied properties. This removes the need for a static constructor and improves code clarity and conciseness.

* Bump package version to 0.0.5 in NuGet.Packaging.props

Updated the package version from 0.0.4 to 0.0.5 in NuGet.Packaging.props. No other metadata or configuration changes were made.

* Rename pixel format properties for clarity and consistency

Renamed `ColorTargetFormat` to `ColorFormat` and
`DepthStencilTargetFormat` to `DepthStencilFormat` in
`ZenithViewHelper`. Updated all usages across the codebase,
including texture creation, swap chain setup, pixel format
switching, and output configuration. This improves naming
consistency and makes the property names more descriptive.

* Fix resource check logic and close class in MauiZenithView

Updated EnsureResources to validate both width and height are non-zero before proceeding, correcting a previous logic error. Also added a missing closing brace to properly terminate the MauiZenithView class.

* Refactor pixel write loop for R8G8B8A8UNorm format

Simplified the loop structure for handling PixelFormat.R8G8B8A8UNorm by removing a redundant outer loop. Now, pixel data is written per row with a single loop over x inside the y loop, improving clarity without changing the pixel writing logic.

* Simplify Class instantiation using target-typed new

Refactored the LayerClass method to use C# target-typed new
for creating the Class object, improving code conciseness and
readability. No functional changes were made.

Prepare release v0.0.4 (#15)

* Update template path and improve navbar logo styling

Changed template directory in docfx.json from "template" to "templates". Refined main.css by enhancing #logo styling and adding .navbar-brand class for better navbar alignment and appearance.

* Bump package version to 0.0.4

Updated the Version field in NuGet.Packaging.props from 0.0.3 to 0.0.4. No other changes were made.

* Update branding and layout in docs and styles

- Removed _appName and simplified _appTitle in docfx.json
- Added YAML front matter and welcome message to index.md
- Removed .navbar-brand styles and updated #logo height in main.css

* Add default theme and GitHub icon link to main.js

Set default theme to 'auto' and introduce an iconLinks array with a GitHub link in the main.js default export object.

Prepare release v0.0.3 (#12)

* Bump package version to 0.0.3 in NuGet.Packaging.props

Updated the package version from 0.0.2 to 0.0.3 in NuGet.Packaging.props. No other metadata or configuration changes were made.

* Enhance README branding and add Zenith.NET logo SVG

Improved the README.md with a centered logo, heading, description, and a status badge for better visual appeal and clarity. Added a new Zenith.NET.svg file containing a custom vector logo for use in documentation and project branding.

* Add linear gradient to SVG and include BOM

Added a <defs> section with a linear gradient (dotnet-grad) from #512BD4 to #C239B3 in the SVG for enhanced styling options. Also, a Unicode BOM was introduced at the start of the file.

* Add NuGet package icon and update packaging props

Updated NuGet.Packaging.props to specify Zenith.NET.png as the package icon and include it in the release build. Added the actual icon image to the repository to ensure the NuGet package displays a custom icon when published.

Update README NuGet tables & bump package version to 0.0.2 (#9)

README now lists all NuGet packages with descriptions and badges for core, backends, extensions, and UI integrations. NuGet.Packaging.props updated: version set to 0.0.2, improved package description, and removed release notes field.