DOCSEARCHbyAlgolia
Submit Docs

Win2D Documentation

repository·winappsdk/main·Indexed 23 days ago

https://github.com/microsoft/win2d

Win2D is an immediate-mode 2D graphics API for Windows. This documentation covers the source code and tools for managing Win2D samples, including the documentation build pipeline using Sandcastle, API configuration synchronization via UpdateApiResourceFiles.cmd, and sample exportation using exportsample.cmd.

Tokens
992
Snippets
5
Records
7
Agent score
84%

What's inside Win2D

  1. Understand the Win2D documentation build pipeline

    winappsdk/main

    The Win2D documentation is generated through a multi-step pipeline that synchronizes the compiled WinRT API surface with XML documentation files:

    1. API Extraction: The ExtractAPISurface tool reflects over compiled WinRT binaries to generate clean C# code (without implementation details) in obj\docs.
    2. Placeholder Generation: The C# compiler creates temporary assemblies and placeholder XML documentation files from the extracted code.
    3. Doc Comparison: The DocDiff tool compares the real documentation comments (stored in winrt\docsrc as XML) against the generated placeholders to detect missing or stale documentation.
    4. Preprocessing: The PreprocessDocs tool processes the docsrc files, injecting boilerplate text for tags like [Win10] and [Experimental].
    5. HTML Generation: The Sandcastle tool (SHFB) combines the temporary assemblies, docsrc XML files, and .aml overview pages to produce HTML documentation in bin\docs.
    6. IntelliSense Generation: The MergeIntellisense tool merges all XML files from the docsrc folders into a single XML file per assembly, which is placed in bin\intellisense for use by Visual Studio.

  3. Add a new conceptual documentation page

    winappsdk/main

    To add a new conceptual documentation page using Microsoft Assistance Markup Language (.aml), follow these steps:

    1. Author the file: Create a new .aml file within the winrt\docsrc folder. You can use existing .aml files as templates. For syntax details, refer to the MAML Guide.
    2. Register the page: Open layout.content and add a new <Topic> node that points to the ID of your new documentation topic.
    3. Build: Run builddocs.cmd to compile the new page into the final documentation output.

  4. Configure NuGet package source for exported samples

    winappsdk/main

    When exporting samples, you can specify a custom directory for NuGet package restoration using the /PackageSource: flag. This is useful if you want the exported samples to attempt to restore packages from a specific network share or local directory instead of the default sources.

    exportsample c:\Path\To\Samples /PackageSource:\\networkshare\path\to\nuget\directory

  6. Run UpdateApiResourceFiles.cmd to sync API config files

    winappsdk/main

    The UpdateApiResourceFiles.cmd script synchronizes the latest API configuration files from the Windows source tree into your local Win2D Git repository. This is a required step to ensure that code generation (codegen) remains up to date with the Windows-centric dependencies.

    Prerequisites:

    • You must run this script from a Windows enlistment.
    • The SDXROOT environment variable must be defined (it relies on Windows source control environment features).

    Usage: UpdateApiResourceFiles.cmd [path]

    • [path] (optional): The absolute path to your local Git repository. If omitted, the script attempts to infer the path based on its own location.
    UpdateApiResourceFiles.cmd C:\Src