diff --git a/AGENTS.md b/AGENTS.md index 46ee730..0e97f7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,25 @@ ## Authority -- [DESIGN.md](DESIGN.md) owns product architecture. [docs/VERIFICATION.md](docs/VERIFICATION.md) owns build/test/pack and platform qualification commands. +- This file owns contribution rules and product boundaries. [docs/VERIFICATION.md](docs/VERIFICATION.md) owns build, test, pack and platform qualification commands. - Work on the checked-out branch, normally `main`. Do not create branches, PRs, remotes or publish without explicit user authorization. - Preserve unrelated and uncommitted work. Do not rewrite Git history or discard source provenance during cleanup. ## Product boundary -Keep RHI and backend boundaries explicit. Do not expose backend Heap/Pool/View containers on the public RHI surface. Preserve the maintained Vortice source and patches; do not replace them with an upstream package that lacks the custom behavior. +SharpGPU builds independently of Infinity Engine. Product sources live under `src/`, owned tests under `tests/`, tools under `tools/` and examples under `samples/`. Original source and preserved history stay in [docs/provenance/extraction.json](docs/provenance/extraction.json) and [docs/provenance/commit-map.txt](docs/provenance/commit-map.txt). Missing dependencies fail; they do not fall back to another version. Products do not infer an Infinity Engine location or a developer drive from the current directory, do not duplicate a consuming workspace's revision manifest, and do not record their own commit inside themselves. The Infinity Engine integration records its checkout SHAs in its own root `stack.lock.json`. Current extraction acceptance is tracked by InfinityBrowser TASK-20260907-INFINITYSTACK-EXTRACTION; these instructions are not a claim that migration gates have passed. + +Source and Package modes are explicit and graph-wide. Local checkout paths belong only in ignored `stack.local.props`. Package versions are owned by project configuration and mode-specific NuGet lock files named `packages...lock.json` beside each project. The two modes do not share resolution state. NuGet owns target-framework sections within each lock. Configuration and Platform variants do not change package references. Reviewed locks are committed; verification uses `RestoreLockedMode`. Unsuffixed locks are retired. Output and intermediate paths are isolated by project, platform, RID, configuration and SDK target framework. Native packages use `runtimes//native`; host integrations select their explicit deployment layout. + +The public binding surface is `RHIBindingTable` with `Count` and `SetBindElement(..., arrayIndex)` for finite bindless. RHI does not grow Heap, Pool or View containers. DX12 gives every table group its own CPU mirror plus GPU segment and publishes on `SetBindingTable`; views and interned sampler slots occupy CPU staging only. Vulkan keeps a set per table and pages pools on the device. Metal fills argument tables or reference buffers and locks a private ViewPool at device create. Backends do not resize shader-visible GPU heaps or native pools at runtime. Preserve the maintained Vortice source and patches; do not replace them with an upstream package that lacks the custom behavior. + +DX12 requires successful Agility device-factory initialization using the application D3D12 directory and UTF-8 paths. Source references and packages both deploy these assets; missing assets fail explicitly. The maintained binding and evidence are described in [docs/SharpGPU/VorticeAgilityPathPatch.md](docs/SharpGPU/VorticeAgilityPathPatch.md). Public native-backed operations enforce platform and ownership boundaries. No capability downgrade or compatibility implementation may conceal unsupported execution. + +Backend implementation tests belong to the independent conformance harness. `Infinity.Rendering.Tests` has no product friend access. Test migration provenance is recorded in [docs/provenance/backend-test-migration.json](docs/provenance/backend-test-migration.json). Native configuration tests exercise actual Configure/Resolve behavior in isolated load contexts; product code does not contain a separate engine-path enumerator solely for tests. Windows native DLL loading uses extended-length local/UNC paths at the native boundary, while reported and configured locations remain canonical ordinary paths. + +Product CI owns its project and test inventory and dependency-only pins in `eng/ci.json`. A hosted build and a real-device qualification are distinct results. Source CI cannot stand in for package consumption or another target platform. CI checks out only this product's build and test dependency closure: SharpMath, SharpMetal, and the GPU/Shader peer needed by integration tests. Neural and LLM are not checkout prerequisites. Runtime product dependency direction remains unchanged. The consuming workspace continues to own its stack revision manifest. + +Application notice deployment uses `ThirdPartyNotices//` for both source and package consumers. Source Content metadata and package `buildTransitive` Content items copy the same license inputs during build and publish. Native DLL and Agility locations remain separate. Host staging must preserve these notice files; a license inside the nupkg cache alone does not satisfy this contract. Transitive application-deployment Content is excluded from downstream packing. A consumer must not repack another product's notice assets into framework-specific `contentFiles` that can hide its own portable resources. ## Implementation and verification @@ -16,7 +28,7 @@ Keep RHI and backend boundaries explicit. Do not expose backend Heap/Pool/View c - Keep a single implementation path. Do not introduce legacy aliases, forwarding assemblies, compatibility shims or silent dependency fallbacks. - Source/Package selection is graph-wide. Keep local checkout paths in ignored `stack.local.props`; update the portable template when its contract changes. Do not commit developer drive paths. - Use current build/test/runtime evidence for behavior changes. Test the relevant error, cancellation and lifetime paths. Mark unavailable matching-platform execution `TODO(UNVERIFIED)` or `BLOCKED_PLATFORM`. -- First-party code and package metadata use Mozilla Public License 2.0 (MPL-2.0); preserve [LICENSE](LICENSE), source attribution and third-party licenses and notices. Update README/design/verification when their contracts change. +- First-party code and package metadata use Mozilla Public License 2.0 (MPL-2.0); preserve [LICENSE](LICENSE), source attribution and third-party licenses and notices. Update this file, [README.md](README.md) and [docs/VERIFICATION.md](docs/VERIFICATION.md) when their contracts change. ## 工程洁净度：第一性原则 diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index 2dd6b85..0000000 --- a/DESIGN.md +++ /dev/null @@ -1,34 +0,0 @@ -# SharpGPU product design - -SharpGPU builds independently of Infinity Engine. Product sources live under src, owned tests under tests, tools under tools and examples under samples. See docs/provenance/extraction.json and commit-map.txt for original source and preserved history. - -The runtime baseline is .NET 10; compiler generators retain their appropriate netstandard target. Source and Package dependency modes are explicit and graph-wide. Local source paths belong only in ignored stack.local.props. Package dependency versions are owned by project configuration and mode-specific NuGet lock files. A consuming workspace owns its source revision manifest; the Infinity Engine integration records all six checkout SHAs in its root stack.lock.json. Products do not duplicate that workspace manifest or record their own commit inside themselves. Missing dependencies must fail rather than fall back to another version. - -Output and intermediate paths are isolated by project, platform, RID, configuration and SDK target framework. Native packages use runtimes//native; host integrations select their explicit deployment layout. Products must not infer Infinity Engine location or a developer drive from the current directory. - -Public native-backed operations enforce platform and ownership boundaries. No capability downgrade or compatibility implementation is permitted to conceal unsupported execution. Current extraction acceptance is tracked by InfinityBrowser TASK-20260907-INFINITYSTACK-EXTRACTION; this document is not a claim that migration gates have passed. - -Binding and descriptor strategy stays behind the backend. The public surface is `RHIBindingTable` with `Count` and `SetBindElement(..., arrayIndex)` for finite bindless; RHI does not grow Heap/Pool/View containers. DX12 gives every table group its own CPU mirror plus GPU segment and publishes on `SetBindingTable`; views and interned sampler slots occupy CPU staging only. Vulkan keeps a set per table and pages pools on the device. Metal fills argument tables or reference buffers and locks a private ViewPool at device create. Backends do not resize shader-visible GPU heaps or native pools at runtime. - -DX12 requires successful Agility device-factory initialization using the application D3D12 directory and UTF-8 paths. Source references and packages both deploy these assets; missing assets fail explicitly. The maintained binding and evidence are described in docs/SharpGPU/VorticeAgilityPathPatch.md. - -Backend implementation tests belong to the independent conformance harness. Infinity.Rendering.Tests has no product friend access. Test migration provenance is recorded in docs/provenance/backend-test-migration.json. Native configuration tests exercise actual Configure/Resolve behavior in isolated load contexts; product code does not contain a separate engine-path enumerator solely for tests. - -Windows native DLL loading uses extended-length local/UNC paths at the native boundary, while reported/configured locations remain canonical ordinary paths. This prevents loader path limits from silently selecting shorter runtime directories in deep application layouts. - -Product CI owns its explicit project/test inventory and dependency-only pins -in eng/ci.json. Hosted build and real-device qualification are distinct -results. Source CI cannot stand in for package consumption or another target -platform. The consuming workspace continues to own its stack revision manifest. - -Application notice deployment uses ThirdPartyNotices//... for both -source and package consumers. Source Content metadata and package buildTransitive -Content items copy the same license inputs during build and publish. Native DLL -and Agility locations remain separate. Host staging must preserve these notice -files; a license inside the nupkg cache alone does not satisfy this contract. - -NuGet locks are named packages...lock.json beside each project. Source and Package modes do not share resolution state. NuGet owns TFM sections within each lock. Existing Configuration/Platform variants do not change package references. Reviewed locks are committed; verification uses RestoreLockedMode. Unsuffixed locks are retired. - -CI checks out only this product's build/test dependency closure: SharpMath, SharpMetal and the GPU/Shader peer needed by integration tests. Neural and LLM are not checkout prerequisites for this product. Runtime product dependency direction remains unchanged. - -Transitive application deployment Content is excluded from downstream packing. A consumer must not repack another product's notice assets into framework-specific contentFiles that can hide its own portable resources. diff --git a/README.md b/README.md index ea25576..c8b6ba1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,14 @@ # SharpGPU -A low-level .NET 10 GPU hardware abstraction layer for DirectX 12, Vulkan and Metal. The product owns the RHI, backend implementations, maintained Vortice bindings and MLCook tooling. Runtime capability probing defines which features a device supports. +SharpGPU is a .NET 10 GPU hardware abstraction for DirectX 12, Vulkan and Metal. It supplies explicit mechanisms that map onto those APIs. Pass topology, barrier inference, memory aliasing and transient-resource lifetime stay with the caller. SharpGPU does not compile shaders, and it does not recreate a swap chain when present fails. + +The public backend is an explicit `ERHIBackend`. There is no Auto value. `RHIInstance.GetBackendByPlatform` returns a suggestion; the caller writes that value into `RHIInstanceDescriptor`. `ERHIBackend.Pending` cannot create an instance. `RHIInstance.IsBackendSupported` checks the operating system only. DirectX 12 is omitted from a build that does not define `SHARPGPU_ENABLE_DX12`. + +A frame goes from Instance to Device to Queue, then to resources and immutable pipelines, then to a command buffer. Six encoders exist: Transfer, Compute, RayTracing, Raster, Machine Learning and Work Graph. The public binding surface is `RHIBindingTable`. `SharpGPU.Scopes` and `SharpGPU.Builders` are optional convenience layers. Start from the [ComputeAndDraw sample](samples/ComputeAndDraw) and the [quick start](docs/SharpGPU/QuickStart.md). + +`RHIDeviceCapabilities` publishes 14 domains for the current device only. `Passed` and `BLOCKED_PLATFORM` belong to the [feature matrix](docs/SharpGPU/FeatureMatrix.md) and [verification](docs/VERIFICATION.md). A successful capability probe is not a passed qualification scenario. The matrix records which hosts are still `BLOCKED_PLATFORM`. + +Unsupported factories throw `NotSupportedException`. The implementation does not silently downgrade or substitute another execution path. Device state is Operational, Lost, Removed or Reset. Swap-chain acquire and present return `ERHISwapChainStatus` and leave recreate to the caller. ## Getting started @@ -11,12 +19,12 @@ A low-level .NET 10 GPU hardware abstraction layer for DirectX 12, Vulkan and Me ## Repository layout -`src/` owns runtime code, `samples/` runnable workloads, `docs/` design and verification, and `eng/` verification automation. Tests and tools live in their own directories where applicable. [DESIGN.md](DESIGN.md) defines product boundaries; [AGENTS.md](AGENTS.md) defines contribution rules. +`src/` owns runtime code, `samples/` runnable workloads, `docs/` the feature matrix, quick start and verification, and `eng/` verification automation. Tests and tools live in their own directories where applicable. [AGENTS.md](AGENTS.md) defines contribution rules and product boundaries. Build outputs, isolated package caches and raw run evidence belong under ignored `artifacts/`. Commit source, reviewed lock files and portable configuration templates; keep machine paths in `stack.local.props`. Historical run summaries do not imply that their disposable output directories still exist. +Native inputs and hashes are recorded in [native/assets.json](native/assets.json); NuGet native inputs are restored by the build. Device support must be checked at runtime. + ## License [MPL-2.0](LICENSE). Existing copyright notices and third-party notices remain with their respective files. Extraction records and inherited notices are retained under [docs/provenance](docs/provenance). - -See the [quick start](docs/SharpGPU/QuickStart.md) and [feature matrix](docs/SharpGPU/FeatureMatrix.md) for the RHI contracts. Native inputs and hashes are recorded in [native/assets.json](native/assets.json); NuGet native inputs are restored by the build. Device support must be checked at runtime. diff --git a/docs/SharpGPU/PackageReadme.md b/docs/SharpGPU/PackageReadme.md index 5bb75ab..1101998 100644 --- a/docs/SharpGPU/PackageReadme.md +++ b/docs/SharpGPU/PackageReadme.md @@ -1,12 +1,13 @@ # SharpGPU -SharpGPU is Infinity's low-level GPU HAL for DirectX 12, Vulkan, and Metal-oriented runtime work. +SharpGPU is a .NET 10 GPU hardware abstraction for DirectX 12, Vulkan and Metal. It supplies explicit mechanisms that map onto those APIs. Pass topology, barrier inference, memory aliasing and transient-resource lifetime stay with the caller. SharpGPU does not compile shaders, and it does not recreate a swap chain when present fails. -The public package is intended for source/API/runtime readiness validation. Backend feature claims are governed by runtime capability probing and `SharpGPU.Conformance.Tests`; unsupported features must fail explicitly instead of silently no-oping. +The public binding surface is `RHIBindingTable`. Unsupported factories throw `NotSupportedException` instead of silently substituting another execution path. `RHIDeviceCapabilities` publishes 14 domains for the current device only. `Passed` and `BLOCKED_PLATFORM` are qualification results, not capability tiers. Start with: + - `docs/SharpGPU/QuickStart.md` - `docs/SharpGPU/FeatureMatrix.md` - `docs/VERIFICATION.md` -Current public contract rows are in `docs/SharpGPU/FeatureMatrix.md` (21 RHI domains; pipeline ABI 9; feature-report schema 6). Qualification numbers live only in `docs/VERIFICATION.md`. +Public contract rows live in `docs/SharpGPU/FeatureMatrix.md`. Qualification numbers live only in `docs/VERIFICATION.md`.