Revamp documentation and simplify ImGui texture bindings - #37
Merged
Merged
Conversation
Introduce Extensions.cs with ImGuiBinding properties for Texture and TextureView. Refactor ImGuiController to use GCHandle for BackendRendererUserData, enabling instance retrieval. Make binding methods internal and update usage in App.cs to use new extensions. Improve encapsulation and idiomatic access to ImGui texture bindings.
Replaced GCHandle-based instance tracking with a [ThreadStatic] ImGuiController.Current field. Updated ImGuiBinding extension methods to use the new static field. Removed GCHandle allocation and freeing logic, simplifying controller lookup and avoiding direct use of BackendRendererUserData.
Added code to set Current = null at the end of the frame, ensuring the ImGuiController instance is cleared or reset after rendering is complete.
Reformatted Zenith.NET-Logo.svg and Zenith.NET.svg to use consistent indentation and spacing for improved readability and maintainability. No changes to SVG content or appearance.
Updated NuGet.Packaging.props to reference version 1.1.0-alpha instead of 1.0.0.
…r, motion effects, and custom search functionality - Implemented an interactive API browser with dynamic namespace and type filtering. - Added a rotating canvas geometry scene for the home page. - Created a member finder dialog for quick access to API members. - Introduced motion effects for content reveal on scroll. - Developed a custom search interface utilizing DocFX's generated index and search worker.
Updated index.md front matter for new titles and descriptions. Added placeholder comments to several topic Markdown files. Updated toc.yml to include "Learn" section and "First Triangle" page.
- Introduced layout.css for navigation and site structure styling. - Added motion.css for shared illustration animations and transitions. - Created search.css for site search component styling. - Implemented signature-links.js for linking code references in signatures. - Developed site.js for site navigation and interaction functionalities. - Established theme.css for overall theme styling, including color schemes and typography.
- Updated the introductory text in the learning hub to better reflect the purpose of the tutorials. - Revised descriptions for the "First Triangle" and "Samples" entries to clarify their content. - Enhanced the core concepts section with more detailed explanations of execution models, resource management, shader data, synchronization, and platform integration. - Expanded the samples documentation to include detailed descriptions of each sample, their functionality, and requirements for running them. - Improved the layout and styling of the article outline for better navigation. - Added JavaScript functionality to dynamically generate the article outline based on headings. - Updated syntax highlighting configurations for better readability and support for additional languages.
- Created translation guidelines for French, Japanese, Korean, Brazilian Portuguese, Russian, Simplified Chinese, and Traditional Chinese. - Added new JavaScript templates for handling resources and language selection. - Implemented resource validation and binding logic in common JavaScript files. - Introduced schema for resources and updated navigation and resource management scripts. - Ensured that language resources are loaded dynamically based on user preferences.
- Enhanced the samples documentation by adding xref links for pixel formats and capabilities in the `samples.md` file. - Improved clarity and conciseness in the localization strings within `strings.yml`, including descriptions for execution context, ownership, queues, platforms, synchronization, and tutorials. - Adjusted descriptions to better guide users through the rendering and compute processes, ensuring a more intuitive understanding of the Zenith.NET framework.
…se, and Traditional Chinese - Revised resource and structure guidelines to clarify the use of the English resource dictionary as the sole source for translations. - Enhanced instructions on maintaining consistency in key names and values across translations. - Added detailed sections on text and placeholders, emphasizing the importance of preserving context and technical accuracy in translations. - Updated API link and technical meaning sections to ensure clarity in distinguishing between different concepts and terms. - Improved build and review instructions to streamline the translation process and ensure quality control before submission. - Adjusted terminology tables to reflect more precise translations and definitions for technical terms.
- Updated translation guidelines in `translation.md` for clarity on style, context, and usage of terms. - Modified `conceptual.extension.js` to include a new template handling mechanism for resource slots. - Adjusted `_master.tmpl` to ensure translation slot templates are rendered correctly outside the indexed articles. - Enhanced `resources.js` to support additional attributes for resource binding and improved slot template handling. - Updated `resources.common.js` to accommodate the new template structure in resource binding, ensuring proper handling of dynamic content.
Added a UTF-8 BOM to the start of various source files (JavaScript, CSS, HTML, YAML, Markdown, JSON, etc.) to ensure proper encoding and compatibility for multilingual content. No functional changes were made. Also expanded the first entry in toc.yml to include href and items, making the table of contents structure explicit.
Updated Microsoft.WindowsAppSDK to 2.5.1, SkiaSharp to 4.152.1, and Uno.WinUI to 6.7.135.
…oard navigation, and refining CSS transitions across templates
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The new ImGui binding API has a correctness issue in how ImGuiController.Current is cleared (and how missing Current is handled), which can break or mis-route texture bindings at runtime.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 2
Open (2)
What changed in this PR
This PR modernizes Zenith.NET’s documentation site by consolidating “Docs” and “Tutorials” into a unified “Learn” section with a rebuilt DocFX theme, localization workflow, and richer navigation/search, while also simplifying Dear ImGui texture binding usage via Texture.ImGuiBinding / TextureView.ImGuiBinding and updating package/dependency versions.
Changes:
- Unify documentation into a new Learn hub with shared resource-backed pages, new DocFX templates, and multi-language switching/validation.
- Introduce
Texture.ImGuiBinding/TextureView.ImGuiBindingand track the activeImGuiControllerper thread during a frame; update samples accordingly. - Bump package/dependency versions and refresh repository-facing docs/branding (README + icon).
| File | Description |
|---|---|
| sources/NuGet.Packaging.props | Bumps package version to 1.1.0-alpha. |
| sources/Extensions/Zenith.NET.Extensions.ImGui/ImGuiController.cs | Adds per-thread Current controller tracking and adjusts binding API visibility. |
| sources/Extensions/Zenith.NET.Extensions.ImGui/Extensions.cs | Adds ImGuiBinding extension properties for Texture / TextureView. |
| sources/Experiments/FluidTank/App.cs | Updates sample to use renderer.Color.ImGuiBinding. |
| sources/Experiments/CornellBox/App.cs | Updates sample to use renderer.Color.ImGuiBinding. |
| sources/Directory.Packages.props | Updates dependency versions (WindowsAppSDK, SkiaSharp, Uno.WinUI). |
| README.md | Updates links and onboarding pointers to new Learn/API structure. |
| documents/tutorials/toc.yml | Removes legacy Tutorials TOC (Learn replaces it). |
| documents/tutorials/index.md | Removes legacy Tutorials landing page. |
| documents/tutorials/guides/hello-triangle.md | Removes legacy tutorial page (replaced by Learn content). |
| documents/tutorials/guides/compute-shader.md | Removes legacy tutorial page (replaced by Learn content). |
| documents/tutorials/getting-started/project-setup.md | Removes legacy getting-started page (replaced by Learn content). |
| documents/toc.yml | Replaces Docs/Tutorials navigation with resource-keyed Learn + API navigation. |
| documents/templates/toc.extension.js | Adds TOC post-transform to resolve @resource.keys into localized labels. |
| documents/templates/schemas/Resources.schema.json | Adds schema for resource dictionaries used by the template pipeline. |
| documents/templates/Resources.json.primary.tmpl | Adds shared resource JSON output template. |
| documents/templates/Resources.json.primary.js | Adds resource dictionary validation/serialization at build time. |
| documents/templates/resources.common.js | Adds shared resource loading, validation, and HTML binding helpers. |
| documents/templates/public/theme.css | Adds new dark “graphite” theme tokens and base styling. |
| documents/templates/public/syntax.js | Extends syntax highlighting (incl. Slang) without creating navigation links. |
| documents/templates/public/site.js | Adds header/menu behavior and keyboard-friendly enhancements. |
| documents/templates/public/signature-links.js | Adds logic to link API signature type ranges to local reference pages. |
| documents/templates/public/resources.js | Adds runtime resource dictionary validation, formatting, and DOM application. |
| documents/templates/public/resource-format.js | Adds shared placeholder parsing/formatting used both at build and runtime. |
| documents/templates/public/outline.js | Adds article outline generation with scroll/active-section tracking. |
| documents/templates/public/navigation.js | Adds dynamic top nav + section TOC loading from toc.json. |
| documents/templates/public/motion.js | Adds viewport-based reveal animations with reduced-motion support. |
| documents/templates/public/member-finder.js | Adds page-local API member finder dialog with keyboard shortcuts. |
| documents/templates/public/languages.js | Adds language selection, persistence, and safe link rewriting. |
| documents/templates/public/home.js | Adds animated homepage canvas scene with accessibility controls. |
| documents/templates/public/dialog.js | Adds shared dialog keyboard/backdrop behavior. |
| documents/templates/public/content.css | Adds styling for code blocks, tables, alerts, and API/code-link interactions. |
| documents/templates/public/code-links.js | Preserves/restores code reference anchors through highlighting. |
| documents/templates/public/api.js | Adds custom API browser fed from DocFX-generated TOC HTML. |
| documents/templates/partials/site.sidebar.tmpl.partial | Adds responsive sidebar with API browser / TOC offcanvas. |
| documents/templates/partials/site.search.tmpl.partial | Adds search dialog markup + shortcuts. |
| documents/templates/partials/site.member-finder.tmpl.partial | Adds API member finder dialog markup. |
| documents/templates/partials/site.language.tmpl.partial | Adds language menu markup with availability states. |
| documents/templates/partials/site.header.tmpl.partial | Adds header/nav shell with skip link, language, search, and menu toggle. |
| documents/templates/partials/site.footer.tmpl.partial | Adds new footer nav aligned with Learn/API/GitHub. |
| documents/templates/partials/api.type.tmpl.partial | Adds reworked type/member rendering for API pages. |
| documents/templates/partials/api.source.tmpl.partial | Adds source link UI for API members/types. |
| documents/templates/partials/api.signature.tmpl.partial | Adds parameter/type parameter/value sections for API signatures. |
| documents/templates/partials/api.seealso.tmpl.partial | Adds related-links rendering for API pages. |
| documents/templates/partials/api.relationships.tmpl.partial | Adds expandable metadata/relationships section for types. |
| documents/templates/partials/api.namespace.tmpl.partial | Adds namespace-type grid rendering. |
| documents/templates/partials/api.member-launcher.tmpl.partial | Adds launcher button markup for member finder. |
| documents/templates/partials/api.header.tmpl.partial | Adds API header/declaration/signature rendering wrapper. |
| documents/templates/partials/api.enum.tmpl.partial | Adds enum value list rendering. |
| documents/templates/partials/api.code.tmpl.partial | Adds signature code block + hidden reference metadata for linking. |
| documents/templates/ManagedReference.html.primary.tmpl | Adds custom managed reference page layout using new partials. |
| documents/templates/ManagedReference.extension.js | Adds model transforms for resources, anchors, overloads, and signature metadata. |
| documents/templates/layout/_master.tmpl | Adds full site shell (header/sidebar/outline/dialogs/resources state). |
| documents/templates/conceptual.html.primary.tmpl | Adds conceptual page layout using new master template. |
| documents/templates/conceptual.extension.js | Adds conceptual post-transform to bind resources + collect slot templates. |
| documents/locales/zh-CN/translation.md | Adds translation guidelines (zh-CN). |
| documents/locales/ru-RU/translation.md | Adds translation guidelines (ru-RU). |
| documents/locales/pt-BR/translation.md | Adds translation guidelines (pt-BR). |
| documents/locales/ko-KR/translation.md | Adds translation guidelines (ko-KR). |
| documents/locales/ja-JP/translation.md | Adds translation guidelines (ja-JP). |
| documents/locales/fr-FR/translation.md | Adds translation guidelines (fr-FR). |
| documents/locales/es-ES/translation.md | Adds translation guidelines (es-ES). |
| documents/locales/de-DE/translation.md | Adds translation guidelines (de-DE). |
| documents/learn/index.md | Adds Learn hub landing page using resource-bound markup. |
| documents/learn/concepts/synchronization.md | Adds Learn “Synchronization” concept page using resource bindings and xrefs. |
| documents/learn/concepts/execution-model.md | Adds Learn “Execution model” concept page using resource bindings and xrefs. |
| documents/images/Zenith.NET.svg | Updates icon SVG with new size/metadata/branding description. |
| documents/docs/workloads/ray-tracing.md | Removes legacy docs page (migrated into Learn structure). |
| documents/docs/workloads/rasterization.md | Removes legacy docs page (migrated into Learn structure). |
| documents/docs/workloads/mesh-shading.md | Removes legacy docs page (migrated into Learn structure). |
| documents/docs/workloads/compute.md | Removes legacy docs page (migrated into Learn structure). |
| documents/docs/toc.yml | Removes legacy Docs TOC (Learn replaces it). |
| documents/docs/resources/textures.md | Removes legacy resource guide page (migrated into Learn structure). |
| documents/docs/resources/heaps.md | Removes legacy resource guide page (migrated into Learn structure). |
| documents/docs/resources/buffers.md | Removes legacy resource guide page (migrated into Learn structure). |
| documents/docs/presentation/views.md | Removes legacy presentation page (migrated into Learn structure). |
| documents/docs/presentation/swap-chains.md | Removes legacy presentation page (migrated into Learn structure). |
| documents/docs/index.md | Removes legacy Docs landing page (Learn replaces it). |
| documents/docs/fundamentals/synchronization.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docs/fundamentals/shaders.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docs/fundamentals/runtime.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docs/fundamentals/queries.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docs/fundamentals/commands.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docs/fundamentals/bindless-resources.md | Removes legacy fundamentals page (migrated into Learn structure). |
| documents/docfx.json | Reconfigures DocFX build inputs/metadata for Learn + locales + custom templates. |
| documents/api/index.md | Replaces API index page with localized, template-driven landing content. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…inability; add documentation maintenance guide - Updated `signature-links.js` for consistent formatting and improved readability. - Enhanced `site.js` with better loop structures and consistent code style. - Refactored `syntax.js` for clarity and improved structure. - Made minor adjustments to `theme.css` for consistency in CSS variable definitions and spacing. - Updated `resources.common.js` for better readability and consistency in function definitions. - Added a new `maintenance.md` file outlining guidelines for documentation maintenance and content rules.
- Updated CSS files to use shorthand for numeric values and consolidated selectors for hover states. - Refactored JavaScript files to enhance readability by reducing line breaks and simplifying conditional statements. - Improved the handling of resource strings and placeholders in resource-format.js and resources.js. - Streamlined the search functionality in search.js, ensuring consistent formatting and error handling. - Enhanced the navigation loading process in navigation.js for better performance and clarity. - Made minor adjustments to syntax highlighting in syntax.js for better keyword management.
…ss documentation - Updated the layout of the learning hub and samples pages to enhance readability by adjusting indentation and line breaks. - Ensured consistent formatting for resource keys and HTML elements throughout the documents. - Improved the structure of API templates to maintain uniformity in presentation. - Enhanced the sidebar and search components for better user experience by refining button and input element structures.
…maintainability; adjust padding and animation properties
…ch.js for improved search functionality and state management
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.
Replace the separate Docs and Tutorials sections with a unified Learn section covering the first triangle, samples, and core concepts. Rebuild the documentation theme and API browsing experience, with shared pages backed by English resources and nine translations.
ImGuiController.Binding(...)calls withTexture.ImGuiBindingandTextureView.ImGuiBindingextension properties. Track the active controller per thread during a frame and clear it after rendering; update CornellBox and FluidTank to use the new API.1.1.0-alphaand update WindowsAppSDK, SkiaSharp, and Uno.WinUI dependencies.