From d4da46fe6f8efa0285d30f8ae83940cc94a4bd7a Mon Sep 17 00:00:00 2001 From: luigi-rosso Date: Sun, 17 May 2026 02:02:53 +0000 Subject: [PATCH] Update scripting API documentation --- .../api-reference/gpu/color-attachment.mdx | 7 +++-- .../gpu/depth-stencil-attachment.mdx | 2 +- scripting/api-reference/gpu/gpu-canvas.mdx | 28 +++++++---------- .../api-reference/gpu/render-pass-desc.mdx | 5 ++- .../api-reference/interfaces/context.mdx | 31 ++++++++++++++----- scripting/api-reference/interfaces/node.mdx | 2 +- 6 files changed, 44 insertions(+), 31 deletions(-) diff --git a/scripting/api-reference/gpu/color-attachment.mdx b/scripting/api-reference/gpu/color-attachment.mdx index a0009ee5..9fb781b4 100644 --- a/scripting/api-reference/gpu/color-attachment.mdx +++ b/scripting/api-reference/gpu/color-attachment.mdx @@ -2,19 +2,20 @@ title: ColorAttachment --- -Color attachment descriptor for beginRenderPass. +Color attachment descriptor for context:beginRenderPass. ## Fields ### `view` -Explicit render target view; defaults to canvas backing texture. +Required render target view. Use GPUCanvas:colorView() for the +canvas's 1× presentation target, or any GPUTexture:view(). ### `resolveTarget` -1x resolve target for MSAA (formats must match). +1× resolve target for MSAA (formats must match `view`). ### `loadOp` diff --git a/scripting/api-reference/gpu/depth-stencil-attachment.mdx b/scripting/api-reference/gpu/depth-stencil-attachment.mdx index 085fefc3..08f580d6 100644 --- a/scripting/api-reference/gpu/depth-stencil-attachment.mdx +++ b/scripting/api-reference/gpu/depth-stencil-attachment.mdx @@ -2,7 +2,7 @@ title: DepthStencilAttachment --- -Depth/stencil attachment descriptor for beginRenderPass. +Depth/stencil attachment descriptor for context:beginRenderPass. ## Fields diff --git a/scripting/api-reference/gpu/gpu-canvas.mdx b/scripting/api-reference/gpu/gpu-canvas.mdx index e51884d4..bcc9c052 100644 --- a/scripting/api-reference/gpu/gpu-canvas.mdx +++ b/scripting/api-reference/gpu/gpu-canvas.mdx @@ -2,8 +2,12 @@ title: GPUCanvas --- -A GPU canvas. Use `.image` with `renderer:drawImage()` to composite -the result. Issue GPU draw calls via `beginRenderPass()`. +A GPU canvas — a 1× presentation target, same role as a WebGPU surface +texture. Use `.image` with `renderer:drawImage()` to composite the +result. Render to it via `context:beginRenderPass({ color = {{ view = +canvas:colorView(), ... }} })`. MSAA requires a user-allocated +`GPUTexture.new({ sampleCount = N, renderTarget = true })` as the +color view, with the canvas's `colorView()` set as `resolveTarget`. ## Fields @@ -45,20 +49,9 @@ resize(width: number, height: number) -> () ``` -Resize the canvas. Recreates the backing texture and any depth buffer. - - -### `beginRenderPass` - -{/* function beginRenderPass(self, desc: RenderPassDesc?): GPURenderPass */} -
-```lua -beginRenderPass(desc: RenderPassDesc?) -> GPURenderPass -``` -
- -Begin a GPU render pass targeting this canvas. -Omitting desc.color renders to the canvas's own backing texture. +Resize the canvas. Recreates the 1× backing texture. Any +user-allocated MSAA / depth textures must be recreated by the +script to match the new dimensions. ### `colorView` @@ -70,6 +63,7 @@ colorView() -> GPUTextureView ``` -View of the canvas backing texture. Use as a sampler input in a subsequent pass. +View of the canvas backing texture. Use as a color attachment, an +MSAA resolve target, or a sampler input in a subsequent pass. diff --git a/scripting/api-reference/gpu/render-pass-desc.mdx b/scripting/api-reference/gpu/render-pass-desc.mdx index dd57b97b..d30fc21e 100644 --- a/scripting/api-reference/gpu/render-pass-desc.mdx +++ b/scripting/api-reference/gpu/render-pass-desc.mdx @@ -2,7 +2,10 @@ title: RenderPassDesc --- -Full render pass descriptor for GPUCanvas:beginRenderPass. +Render pass descriptor for context:beginRenderPass. Must include at +least one color attachment or a depthStencil attachment. All attachments +(color views + depth) must share one sampleCount, derived per WebGPU +rules — pass sampleCount is inferred from the views, not declared. ## Fields diff --git a/scripting/api-reference/interfaces/context.mdx b/scripting/api-reference/interfaces/context.mdx index 1ca48793..7297a848 100644 --- a/scripting/api-reference/interfaces/context.mdx +++ b/scripting/api-reference/interfaces/context.mdx @@ -256,20 +256,35 @@ Use beginFrame/endFrame inside drawCanvas to render. {/* function gpuCanvas(self, desc: { width: number, height: number, - sampleCount: number?, }): GPUCanvas */}
```lua -gpuCanvas(desc: {width: number, height: number, sampleCount: number?,}) -> GPUCanvas +gpuCanvas(desc: {width: number, height: number,}) -> GPUCanvas ```
-Create a GPU canvas for custom GPU rendering. -Use beginRenderPass inside drawCanvas to render. -Pass `sampleCount` (2, 4, or 8) to enable MSAA on the canvas backing -texture. When set, beginRenderPass automatically routes rendering -through the MSAA color texture and resolves to the 1× backing — -no extra setup needed in the script. +Create a GPU canvas — a 1× presentation target. Render to it via +`context:beginRenderPass(...)` using `canvas:colorView()` as a +color attachment. For MSAA, allocate the multisampled color and +depth textures yourself with `GPUTexture.new({ sampleCount = N, +renderTarget = true })` and pass them in the descriptor. + + +### `beginRenderPass` + +{/* function beginRenderPass(self, desc: RenderPassDesc): GPURenderPass */} +
+```lua +beginRenderPass(desc: RenderPassDesc) -> GPURenderPass +``` +
+ +Open a GPU render pass. The descriptor must include at least one +color attachment or a depthStencil attachment; every attachment +carries its own GPUTextureView. The pass's sampleCount is derived +from the attachments (WebGPU rules: all must share one +sampleCount). Must be called inside a drawCanvas phase. Issue +draw calls on the returned pass, then call `:finish()`. ### `features` diff --git a/scripting/api-reference/interfaces/node.mdx b/scripting/api-reference/interfaces/node.mdx index 55dda234..ebbcc012 100644 --- a/scripting/api-reference/interfaces/node.mdx +++ b/scripting/api-reference/interfaces/node.mdx @@ -140,7 +140,7 @@ drawCanvas(self: T) -> () Called during the drawCanvases pass (before draw). -All canvas beginFrame/beginRenderPass calls must happen here. +All canvas:beginFrame / context:beginRenderPass calls must happen here. ### `pointerDown`