Revamp documentation and simplify ImGui texture bindings

.gitignore

@@ -433,5 +433,5 @@ FodyWeavers.xsd
 ## macOS generated files
 .DS_Store
 
-## DocFx generated files
-_site/
+## DocFX generated files
+_site/

README.md

@@ -1,86 +1,91 @@
 <p align="center">
-  <img src="documents/images/Zenith.NET.svg" alt="Zenith.NET Logo" width="128" height="128">
+  <img src="documents/images/Zenith.NET.svg" alt="Zenith.NET icon" width="128" height="128">
 </p>
 
 <h1 align="center">Zenith.NET</h1>
 
 <p align="center">
-  A modern rendering hardware interface for .NET.<br/>
-  One consistent C# API for graphics and compute across DirectX 12, Metal 4, and Vulkan 1.4.
+  A modern rendering hardware interface for .NET.
 </p>
 
 <p align="center">
-  <a href="https://www.nuget.org/packages/Zenith.NET"><img src="https://img.shields.io/nuget/v/Zenith.NET.svg?style=flat-square" alt="NuGet"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/qian-o/Zenith.NET?style=flat-square" alt="License"></a>
+  <a href="https://qian-o.github.io/Zenith.NET/learn/">Learn</a> ·
+  <a href="https://qian-o.github.io/Zenith.NET/learn/samples.html">Samples</a> ·
+  <a href="https://qian-o.github.io/Zenith.NET/api/">API Reference</a> ·
+  <a href="https://www.nuget.org/packages?q=Zenith.NET">NuGet</a>
 </p>
 
----
-
 ## Overview
 
-Zenith.NET provides a consistent C# API for resources, pipelines, command recording, synchronization, and presentation across DirectX 12, Metal 4, and Vulkan 1.4.
+Zenith.NET is a rendering hardware interface (RHI) that provides one C# API for graphics and compute across DirectX 12, Metal 4, and Vulkan 1.4. It gives applications explicit control over GPU resources, pipelines, command recording, synchronization, and presentation.
 
-The RHI exposes rasterization, compute, and indirect commands. Inline Ray Tracing and mesh shading are optional; check `Capabilities.RayTracingSupported` and `Capabilities.MeshShadingSupported` before use. Bindless resource handles expose shader resources, while queues, barriers, and texture layouts express ordering and access dependencies.
+Build rasterization and compute workloads, access shader resources through bindless handles, and coordinate GPU work through queues, barriers, and timelines. Inline ray tracing and mesh shading are available through the same API when the device exposes the corresponding capabilities.
 
-## Get Started
+## Getting Started
 
-Install the core package and one graphics API package:
+In a .NET 10 project, install the core package and a backend supported by your platform and graphics driver. For Vulkan:
 
-```powershell
+```console
 dotnet add package Zenith.NET
 dotnet add package Zenith.NET.Vulkan
 ```
 
-Create a graphics context in C#:
+Create a graphics context:
 
 ```csharp
 using Zenith.NET;
 using Zenith.NET.Vulkan;
 
 using GraphicsContext context = GraphicsContext.CreateVulkan(useValidationLayer: true);
+
+context.ValidationMessage += static (_, args) => Console.WriteLine($"[{args.Severity}] {args.Message}");
 ```
 
-Continue with the [RHI Guide](https://qian-o.github.io/Zenith.NET/docs/) or build the examples in the [Tutorials](https://qian-o.github.io/Zenith.NET/tutorials/).
+Follow [First Triangle](https://qian-o.github.io/Zenith.NET/learn/first-triangle.html) to build a .NET console application with NuGet packages, from an empty window to the first rendered frame.
 
-## Platform Support
+## Packages
 
-|           | DirectX 12 | Metal 4 | Vulkan 1.4 |
-| :-------: | :--------: | :-----: | :--------: |
-| Windows   | Yes |  | Yes |
-| Apple     |  | Yes | Yes |
-| Android   |  |  | Yes |
-| Linux     |  |  | Yes |
+Choose packages by their role in your application. Add a graphics backend, then the compiler, extensions, or UI integration you need.
 
-## Packages
+### Core and Backends
 
-### Core
+| Package | Purpose |
+| --- | --- |
+| `Zenith.NET` | Shared graphics and compute API, resource types, and command interfaces. |
+| `Zenith.NET.Compiler` | Compile Slang shaders for the selected graphics API. |
+| `Zenith.NET.DirectX12` | DirectX 12 backend. |
+| `Zenith.NET.Metal` | Metal 4 backend. |
+| `Zenith.NET.Vulkan` | Vulkan 1.4 backend. |
 
-[![Zenith.NET](https://img.shields.io/nuget/v/Zenith.NET.svg?label=Zenith.NET&style=flat-square)](https://www.nuget.org/packages/Zenith.NET)
+### Extensions
 
-### Backends
+| Package | Purpose |
+| --- | --- |
+| `Zenith.NET.Extensions.ImageSharp` | Load images into GPU textures with ImageSharp. |
+| `Zenith.NET.Extensions.ImGui` | Dear ImGui rendering and input integration. |
+| `Zenith.NET.Extensions.Skia` | SkiaSharp rendering with Zenith.NET textures. |
+| `Zenith.NET.Extensions.Upscaling` | Spatial and temporal image upscaling. |
 
-[![DirectX12](https://img.shields.io/nuget/v/Zenith.NET.DirectX12.svg?label=DirectX12&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.DirectX12)
-[![Metal](https://img.shields.io/nuget/v/Zenith.NET.Metal.svg?label=Metal&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Metal)
-[![Vulkan](https://img.shields.io/nuget/v/Zenith.NET.Vulkan.svg?label=Vulkan&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Vulkan)
+### UI Integrations
 
-### Extensions
+| Package | Purpose |
+| --- | --- |
+| `Zenith.NET.Views` | Shared rendering-view interfaces and frame events. |
+| `Zenith.NET.Views.Avalonia` | Avalonia rendering control. |
+| `Zenith.NET.Views.Maui` | .NET MAUI rendering control. |
+| `Zenith.NET.Views.WinForms` | Windows Forms rendering control. |
+| `Zenith.NET.Views.WinUI` | WinUI 3 and Uno rendering control. |
+| `Zenith.NET.Views.WPF` | WPF rendering control. |
 
-[![ImageSharp](https://img.shields.io/nuget/v/Zenith.NET.Extensions.ImageSharp.svg?label=ImageSharp&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Extensions.ImageSharp)
-[![ImGui](https://img.shields.io/nuget/v/Zenith.NET.Extensions.ImGui.svg?label=ImGui&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Extensions.ImGui)
-[![Skia](https://img.shields.io/nuget/v/Zenith.NET.Extensions.Skia.svg?label=Skia&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Extensions.Skia)
-[![Upscaling](https://img.shields.io/nuget/v/Zenith.NET.Extensions.Upscaling.svg?label=Upscaling&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Extensions.Upscaling)
+See [Platform Integration](https://qian-o.github.io/Zenith.NET/learn/concepts/platform-integration.html) for native surfaces, frame ownership and UI integration choices.
 
-### Views
+## Documentation and Examples
 
-[![Views](https://img.shields.io/nuget/v/Zenith.NET.Views.svg?label=Views&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views)
-[![Avalonia](https://img.shields.io/nuget/v/Zenith.NET.Views.Avalonia.svg?label=Avalonia&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views.Avalonia)
-[![MAUI](https://img.shields.io/nuget/v/Zenith.NET.Views.Maui.svg?label=MAUI&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views.Maui)
-[![WinForms](https://img.shields.io/nuget/v/Zenith.NET.Views.WinForms.svg?label=WinForms&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views.WinForms)
-[![WinUI](https://img.shields.io/nuget/v/Zenith.NET.Views.WinUI.svg?label=WinUI&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views.WinUI)
-[![WPF](https://img.shields.io/nuget/v/Zenith.NET.Views.WPF.svg?label=WPF&style=flat-square)](https://www.nuget.org/packages/Zenith.NET.Views.WPF)
+- [Learn](https://qian-o.github.io/Zenith.NET/learn/) — a complete triangle tutorial and guides to the programming model.
+- [Samples](https://qian-o.github.io/Zenith.NET/learn/samples.html) — focused examples with C# and Slang source links.
+- [API Reference](https://qian-o.github.io/Zenith.NET/api/) — types and members.
+- [Experiments](sources/Experiments/) — sample applications and utilities in this repository.
 
-## Documentation
+## License
 
-- [RHI Guide](https://qian-o.github.io/Zenith.NET/docs/)
-- [Tutorials](https://qian-o.github.io/Zenith.NET/tutorials/)
-- [API Reference](https://qian-o.github.io/Zenith.NET/api/)
+Zenith.NET is licensed under the [MIT License](LICENSE).

documents/api/.gitignore

@@ -1,5 +1,3 @@
-###############
-#  temp file  #
-###############
+# Generated DocFX API metadata
 *.yml
-.manifest
+.manifest

documents/api/index.md

@@ -1,32 +1,50 @@
-# API Reference
+---
+title: '@reference.title'
+description: '@reference.meta.description'
+---
 
-The API reference documents the public Zenith.NET types, members, parameters, and enum values. Start with the [RHI Guide](../docs/index.md) when learning a workflow.
-
-## Start Here
-
-| Type | Purpose |
-|------|---------|
-| `GraphicsContext` | Creates resources and exposes capabilities and command queues |
-| `CommandQueue` | Owns and lends command buffers for one class of GPU work |
-| `CommandBuffer` | Queue-owned recorder borrowed for one immediate submission |
-| `TimelineValue` | Represents a queue-submission completion point that can be queried or waited on |
-| `QueryHeap` / `QueryHeapDesc` | Collect visibility results and GPU timestamps |
-| `BufferDesc` / `TextureDesc` | Describe resources before creation |
-| `GraphicsPipelineDesc` / `ComputePipelineDesc` | Describe shader pipelines |
-| `Surface` / `SwapChain` | Connect rendering to a window |
-| `ZenithCompiler` | Compiles Slang source for the selected graphics API |
-
-## Public Namespaces
-
-| Namespace | Contents |
-|-----------|----------|
-| `Zenith.NET` | Core RHI types and Slang compilation |
-| `Zenith.NET.DirectX12` | DirectX 12 context factory |
-| `Zenith.NET.Metal` | Metal context factory |
-| `Zenith.NET.Vulkan` | Vulkan context factory |
-| `Zenith.NET.Extensions.ImageSharp` | Image loading and mip generation |
-| `Zenith.NET.Extensions.ImGui` | Dear ImGui integration |
-| `Zenith.NET.Views` | Shared View contracts and frame event data |
-| `Zenith.NET.Views.*` | Framework-specific View controls |
-
-Browse the namespace tree to inspect the complete public API reference. The guide pages link related concepts, while the [Tutorials](../tutorials/index.md) show the types in complete applications.
+<div class="api-reference">
+    <header class="api-heading">
+        <h1>
+            <resource key="reference.title"></resource>
+        </h1>
+        <p class="api-intro">
+            <resource key="reference.description"></resource>
+        </p>
+    </header>
+    <div class="api-start-grid">
+        <a href="~/api/Zenith.NET.GraphicsContext.yml">
+            <span>
+                <resource key="reference.entries.context.label"></resource>
+            </span>
+            <strong>GraphicsContext</strong>
+            <p>
+                <resource key="reference.entries.context.description"></resource>
+            </p>
+        </a>
+        <a href="~/api/Zenith.NET.CommandBuffer.yml">
+            <span>
+                <resource key="reference.entries.commands.label"></resource>
+            </span>
+            <strong>CommandBuffer</strong>
+            <p>
+                <resource key="reference.entries.commands.description"></resource>
+            </p>
+        </a>
+    </div>
+    <section class="api-group">
+        <div class="api-group-heading">
+            <h2>
+                <resource key="ui.api.namespaces"></resource>
+            </h2>
+        </div>
+        <div class="api-namespace-grid" id="api-namespace-grid"></div>
+        <noscript>
+            <p>
+                <a href="~/api/Zenith.NET.yml">
+                    <resource key="reference.navigation.core"></resource>
+                </a>
+            </p>
+        </noscript>
+    </section>
+</div>

documents/docfx.json

@@ -5,12 +5,8 @@
       "src": [
         {
           "src": "../sources",
-          "files": [
-            "**/*.csproj"
-          ],
-          "exclude": [
-            "Experiments/**"
-          ]
+          "files": "**/*.csproj",
+          "exclude": "Experiments/**"
         }
       ],
       "output": "api",
@@ -20,37 +16,83 @@
   "build": {
     "content": [
       {
-        "files": [
-          "api/**/*.{md,yml}",
-          "docs/**/*.{md,yml}",
-          "tutorials/**/*.{md,yml}",
-          "index.md",
-          "toc.yml"
-        ]
+        "files": ["api/**/*.{md,yml}", "learn/**/*.md", "index.md", "toc.yml", "locales/*/strings.yml"]
       }
     ],
-    "resource": [
-      {
-        "files": [
-          "images/**"
-        ]
+    "resource": {
+      "files": "images/**"
+    },
+    "template": ["default", "modern", "templates"],
+    "fileMetadata": {
+      "_section": {
+        "learn/**": "learn",
+        "api/**": "api"
+      },
+      "_apiReference": {
+        "api/**": true
+      },
+      "_disableAffix": {
+        "api/**": true,
+        "learn/index.md": true
+      },
+      "_disableToc": {
+        "learn/**": false,
+        "api/**": false
       }
-    ],
-    "template": [
-      "default",
-      "modern",
-      "templates"
-    ],
+    },
     "globalMetadata": {
       "_appTitle": "Zenith.NET",
       "_appLogoPath": "images/Zenith.NET-Logo.svg",
       "_appFaviconPath": "images/Zenith.NET.svg",
       "_enableSearch": true,
-      "_appFooter": "Zenith.NET is a modern rendering hardware interface for .NET.",
       "_gitContribute": {
         "repo": "https://github.com/qian-o/Zenith.NET",
         "branch": "master"
-      }
+      },
+      "_languages": [
+        {
+          "code": "de-DE",
+          "label": "Deutsch"
+        },
+        {
+          "code": "en-US",
+          "label": "English"
+        },
+        {
+          "code": "es-ES",
+          "label": "Español"
+        },
+        {
+          "code": "fr-FR",
+          "label": "Français"
+        },
+        {
+          "code": "ja-JP",
+          "label": "日本語"
+        },
+        {
+          "code": "ko-KR",
+          "label": "한국어"
+        },
+        {
+          "code": "pt-BR",
+          "label": "Português (Brasil)"
+        },
+        {
+          "code": "ru-RU",
+          "label": "Русский"
+        },
+        {
+          "code": "zh-CN",
+          "label": "简体中文"
+        },
+        {
+          "code": "zh-TW",
+          "label": "繁體中文"
+        }
+      ],
+      "_lang": "en-US",
+      "_sourceLanguage": "en-US"
     },
     "output": "_site",
     "sitemap": {