docs: expand the README and add a Chinese/English switch - #4
Conversation
Describe backends, resources, pipelines, recording, submit and the 14 capability domains from the current types. Co-authored-by: CGBull <1824339952@qq.com>
GitHub shows README.md in Chinese. README.en.md carries the same contract, and the header links language, design, and issues. Co-authored-by: CGBull <1824339952@qq.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4cf275fa35
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| SharpGPU is a .NET 10 hardware abstraction over DirectX 12, Vulkan and Metal. The public surface is a set of explicit mechanisms: devices, resources, immutable pipelines, binding tables, command encoders, queues and presentation. Pass topology, barrier inference, memory aliasing and transient-resource lifetime stay with the caller, typically a render graph. | ||
|
|
||
| Shaders enter as compiled payloads. SharpGPU does not ship a shader compiler. Swap-chain acquire and present report `ERHISwapChainStatus` and leave recreate to the caller. Unsupported factories throw `NotSupportedException` rather than substituting another execution path. |
There was a problem hiding this comment.
For Metal callers using ERHIShaderPayloadKind.MslSource, MetalFunction decodes the UTF-8 source and calls MTLDevice.NewLibrary to compile it, so shaders do not always enter as compiled payloads. This wording, repeated in the package README, can incorrectly lead Metal users to believe that offline compilation to a metallib is mandatory; distinguish the accepted MSL-source path and its native runtime compilation from SharpGPU shipping a standalone shader compiler.
Useful? React with 👍 / 👎.
|
|
||
| `RHIInstanceDescriptor` also carries the debug and validation switches, the native surface kind, and the requested graphics, compute and transfer queue counts. One `RHIInstance` owns every enumerated device. `GetDevice` returns a device by index. A queue is `RHIDevice.GetCommandQueue(ERHIPipelineType, index)`. | ||
|
|
||
| `ERHIDeviceState` is `Unknown`, `Operational`, `Lost`, `Removed` or `Reset`. `Lost` is a timeout or device-loss recovery. `Removed` is a physical adapter going away. `Reset` means previous resources are dead and must be created again. Native failures surface as `RHIException`, which carries `ERHIErrorCode`, the backend, the native code and message, and the device state. |
There was a problem hiding this comment.
When handling a timeout or device-loss diagnostic, this description reverses the implemented lifecycle: Metal queue timeouts remain SubmissionFailed with an Operational device, while RHIDevice.MarkDeviceLost transitions to Lost permanently and all subsequent device-backed operations rethrow the stored diagnostic. There is no recovery transition on that device, so describing Lost as a timeout or recovery can cause callers to reuse invalid resources instead of creating a new device.
Useful? React with 👍 / 👎.
|
|
||
| Raster recording covers draws, indirect draws, viewports and binding. Compute recording covers dispatch and indirect dispatch. Transfer recording covers copies and blits. Every encoder records `RHIBarrier` values: global, buffer or texture. Stage and access masks use Before/After pairs. Texture barriers also carry `ERHITextureLayout` (13 values, including copy, resolve, present and `Common`). A non-null source or destination queue is a cross-queue ownership transfer. | ||
|
|
||
| Indirect command buffers are a separate capability used to record draw streams in parallel and `Execute` them inside an encoder. Vulkan does not implement that contract. |
There was a problem hiding this comment.
For callers implementing indirect execution, there is no public indirect command-buffer object or Execute method to record in parallel. The contract is explicitly RHIIndirectCommandLayout plus an indirect argument buffer, consumed through ExecuteIndirect; its source documentation also states that it is not a device-generated command buffer. Presenting a different programming model and method name sends users toward APIs that do not exist.
Useful? React with 👍 / 👎.
|
|
||
| `RHIFence` is the CPU/GPU signal. `Wait` returns `ERHIFenceStatus` (`Success`, `NotReady` or `Undefined`), not a boolean. `Reset` is legal once the signal has completed. `RHISemaphore` is the GPU/GPU signal carried in the submit descriptor. | ||
|
|
||
| Timestamp, occlusion and pipeline-statistics results are read from `RHIQuery` after the GPU has written them. `TryGetTimestamp`, `TryGetOcclusion` and `TryGetPipelineStatistics` return false while the result is still pending. Calibrated timestamps are `QueryClockCalibration` on devices whose synchronization capability reports them. There is no CPU-clock substitute. |
There was a problem hiding this comment.
For users reading timestamp, occlusion, or statistics results, none of TryGetTimestamp, TryGetOcclusion, or TryGetPipelineStatistics exists on RHIQuery. Callers must first inspect ResolveData() for NotReady, then read timestamp/occlusion values from Results or use the domain-specific TryGetRasterStatistics, TryGetComputeStatistics, and TryGetRayTracingStatistics methods; following the documented sequence currently results in uncompilable code.
Useful? React with 👍 / 👎.
2 participants
变更
#3 合并时只包含删掉
DESIGN.md、把工程边界收进AGENTS.md的那一笔。其后的 README 改动留在已合并分支上，没有进入main。本 PR 把这两笔补上。README.md。英文全文在README.en.md。页首互相链接：English · 设计与架构 · 问题反馈/简体中文 · Design · Issues。设计与架构锚到文内对象模型，不另建设计文档。功能矩阵、QuickStart、验证命令和运行时代码未改。