diff --git a/dist/index.d.ts b/dist/index.d.ts index 1c6db03..ec0de9f 100644 --- a/dist/index.d.ts +++ b/dist/index.d.ts @@ -458,6 +458,9 @@ interface GPUBindGroupEntry { interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase { + /** + * A list of entries describing the shader resource bindings for a bind group. + */ entries: Iterable; } @@ -809,9 +812,16 @@ interface GPUExternalTextureBindingLayout {} interface GPUExternalTextureDescriptor extends GPUObjectDescriptorBase { + /** + * The video source to import the external texture from. + */ source: | HTMLVideoElement | VideoFrame; + /** + * The color space the image contents of {@link GPUExternalTextureDescriptor#source} will be + * converted into when reading. + */ colorSpace?: PredefinedColorSpace; } @@ -838,35 +848,46 @@ interface GPUImageCopyExternalImage { * The source of the image copy. The copy source data is captured at the moment that * {@link GPUQueue#copyExternalImageToTexture} is issued. Source size is defined by source * type, given by this table: - * * * * * * * * + * * * + * + * - * - * *
Source type - * Width - * Height + * Dimensions *
{@link ImageBitmap} - * {@link ImageBitmap#width|ImageBitmap.width} - * {@link ImageBitmap#height|ImageBitmap.height} + * {@link ImageBitmap#width|ImageBitmap.width}, + * {@link ImageBitmap#height|ImageBitmap.height} + *
{@link HTMLImageElement} + * {@link HTMLImageElement#naturalWidth|HTMLImageElement.naturalWidth}, + * {@link HTMLImageElement#naturalHeight|HTMLImageElement.naturalHeight} *
{@link HTMLVideoElement} - * video/intrinsic width|intrinsic width of the frame - * video/intrinsic height|intrinsic height of the frame + * video/intrinsic width|intrinsic width of the frame, + * video/intrinsic height|intrinsic height of the frame *
{@link VideoFrame} - * {@link VideoFrame#codedWidth|VideoFrame.codedWidth} - * {@link VideoFrame#codedHeight|VideoFrame.codedHeight} + * {@link VideoFrame#codedWidth|VideoFrame.codedWidth}, + * {@link VideoFrame#codedHeight|VideoFrame.codedHeight} + *
{@link ImageData} + * {@link ImageData#width|ImageData.width}, + * {@link ImageData#height|ImageData.height} + *
{@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link CanvasRenderingContext2D} or {@link GPUCanvasContext} + * {@link HTMLCanvasElement#width|HTMLCanvasElement.width}, + * {@link HTMLCanvasElement#height|HTMLCanvasElement.height} *
{@link HTMLCanvasElement} - * {@link HTMLCanvasElement#width|HTMLCanvasElement.width} - * {@link HTMLCanvasElement#height|HTMLCanvasElement.height} + * {@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link WebGLRenderingContextBase} + * {@link WebGLRenderingContextBase#drawingBufferWidth|WebGLRenderingContextBase.drawingBufferWidth}, + * {@link WebGLRenderingContextBase#drawingBufferHeight|WebGLRenderingContextBase.drawingBufferHeight} *
{@link OffscreenCanvas} - * {@link OffscreenCanvas#width|OffscreenCanvas.width} - * {@link OffscreenCanvas#height|OffscreenCanvas.height} + * {@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link ImageBitmapRenderingContext} + * {@link ImageBitmapRenderingContext}'s internal output bitmap + * {@link ImageBitmap#width|ImageBitmap.width}, + * {@link ImageBitmap#height|ImageBitmap.height} *
*/ @@ -1059,16 +1080,23 @@ interface GPUProgrammableStage { /** * The name of the function in {@link GPUProgrammableStage#module} that this stage will use to * perform its work. + * NOTE: Since the {@link GPUProgrammableStage#entryPoint} dictionary member is + * not required, methods which consume a {@link GPUProgrammableStage} must use the + * "[$get the entry point$]" algorithm to determine which entry point + * it refers to. */ entryPoint?: string; /** * Specifies the values of pipeline-overridable constants in the shader module * {@link GPUProgrammableStage#module}. * Each such pipeline-overridable constant is uniquely identified by a single - * pipeline-overridable constant identifier string (representing the numeric ID of the - * constant, if one is specified, and otherwise the constant's identifier name). - * WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison. - * The key of each key-value pair must equal the identifier string of one such constant. + * pipeline-overridable constant identifier string, representing the pipeline + * constant ID of the constant if its declaration specifies one, and otherwise the + * constant's identifier name. + * The key of each key-value pair must equal the + * pipeline-overridable constant identifier string|identifier string + * of one such constant, with the comparison performed + * according to the rules for WGSL identifier comparison. * When the pipeline is executed, that constant will have the specified value. * Values are specified as GPUPipelineConstantValue, which is a {@link double}. * They are converted [$to WGSL type$] of the pipeline-overridable constant (`bool`/`i32`/`u32`/`f32`/`f16`). @@ -1186,7 +1214,7 @@ interface GPURenderPassDepthStencilAttachment { * to prior to executing the render pass. Ignored if {@link GPURenderPassDepthStencilAttachment#stencilLoadOp} * is not {@link GPULoadOp#"clear"}. * The value will be converted to the type of the stencil aspect of `view` by taking the same - * number of LSBs as the number of bits in the stencil aspect of one texel block of `view`. + * number of LSBs as the number of bits in the stencil aspect of one texel block|texel of `view`. */ stencilClearValue?: GPUStencilValue; /** @@ -1381,10 +1409,17 @@ interface GPUSamplerDescriptor */ compare?: GPUCompareFunction; /** - * Specifies the maximum anisotropy value clamp used by the sampler. - * Note: Most implementations support {@link GPUSamplerDescriptor#maxAnisotropy} values in range - * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor#maxAnisotropy} will - * be clamped to the maximum value that the platform supports. + * Specifies the maximum anisotropy value clamp used by the sampler. Anisotropic filtering is + * enabled when {@link GPUSamplerDescriptor#maxAnisotropy} is > 1 and the implementation supports it. + * Anisotropic filtering improves the image quality of textures sampled at oblique viewing + * angles. Higher {@link GPUSamplerDescriptor#maxAnisotropy} values indicate the maximum ratio of + * anisotropy supported when filtering. + *
+ * Most implementations support {@link GPUSamplerDescriptor#maxAnisotropy} values in range + * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor#maxAnisotropy} + * will be clamped to the maximum value that the platform supports. + * The precise filtering behavior is implementation-dependent. + *
*/ maxAnisotropy?: number; } @@ -1410,9 +1445,13 @@ interface GPUShaderModuleDescriptor */ code: string; /** - * If defined MAY be interpreted as a source-map-v3 format. - * Source maps are optional, but serve as a standardized way to support dev-tool - * integration such as source-language debugging [[SourceMap]]. + * If defined, **may** be interpreted in the [[!SourceMap]] v3 format. + * If an implementation supports this option but is unable to process the provided value, + * it should show a developer-visible warning but must not produce any application-observable + * error. + * Note: + * Source map support is optional, but serves as a semi-standardized way to support dev-tool + * integration such as source-language debugging. * WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier * comparison. */ @@ -1428,12 +1467,14 @@ interface GPUShaderModuleDescriptor * Supplying information in {@link GPUShaderModuleDescriptor#compilationHints} does not have any * observable effect, other than performance. It may be detrimental to performance to * provide hints for pipelines that never end up being created. - * Because a single shader module can hold - * multiple entry points, and multiple pipelines can be created from a single shader - * module, it can be more performant for an implementation to do as much compilation as - * possible once in {@link GPUDevice#createShaderModule} rather than multiple times in - * the multiple calls to {@link GPUDevice#createComputePipeline} or - * {@link GPUDevice#createRenderPipeline}. + * Because a single shader module can hold multiple entry points, and multiple pipelines + * can be created from a single shader module, it can be more performant for an + * implementation to do as much compilation as possible once in + * {@link GPUDevice#createShaderModule} rather than multiple times in the multiple calls to + * {@link GPUDevice#createComputePipeline()} or {@link GPUDevice#createRenderPipeline}. + * Hints are only applied to the entry points they explicitly name. + * Unlike {@link GPUProgrammableStage#entryPoint|GPUProgrammableStage.entryPoint}, + * there is no default, even if only one entry point is present in the module. * * Note: * Hints are not validated in an observable way, but user agents **may** surface identifiable @@ -1541,7 +1582,7 @@ interface GPUTextureDescriptor * Similar caveats exist for other formats and pairs of formats on other systems. * * Formats in this list must be texture view format compatible with the texture format. - *
+ *
* Two {@link GPUTextureFormat}s `format` and `viewFormat` are texture view format compatible if: * - `format` equals `viewFormat`, or * - `format` and `viewFormat` differ only in whether they are `srgb` formats (have the `-srgb` suffix). @@ -1857,6 +1898,20 @@ interface GPUAdapter { * The limits in `this`.{@link GPUAdapter#[[adapter]]}.{@link adapter#[[limits]]}. */ readonly limits: GPUSupportedLimits; + /** + * Information about the physical adapter underlying this {@link GPUAdapter}. + * For a given {@link GPUAdapter}, the {@link GPUAdapterInfo} values exposed are constant over time. + * The same object is returned each time. To create that object for the first time: + *
+ *
+ * **Called on:** {@link GPUAdapter} `this`. + * **Returns:** {@link GPUAdapterInfo} + * Content timeline steps: + * 1. Return a [$new adapter info$] for `this.adapter`. + *
+ *
+ */ + readonly info: GPUAdapterInfo; /** * Returns the value of {@link GPUAdapter#[[adapter]]}.{@link adapter#[[fallback]]}. */ @@ -1864,17 +1919,13 @@ interface GPUAdapter { /** * Requests a device from the adapter. * This is a one-time action: if a device is returned successfully, - * the adapter becomes invalid. + * the adapter [$expires$]. * @param descriptor - Description of the {@link GPUDevice} to request. */ requestDevice( descriptor?: GPUDeviceDescriptor ): Promise; - /** - * Requests the {@link GPUAdapterInfo} for this {@link GPUAdapter}. - * Note: Adapter info values are returned with a Promise to give user agents an - * opportunity to perform potentially long-running checks in the future. - */ + /** @deprecated Use `adapter.info` instead (once available in browsers). */ requestAdapterInfo(): Promise; } diff --git a/generated/index.d.ts b/generated/index.d.ts index c0a5485..ce08984 100644 --- a/generated/index.d.ts +++ b/generated/index.d.ts @@ -404,6 +404,9 @@ interface GPUBindGroupEntry { interface GPUBindGroupLayoutDescriptor extends GPUObjectDescriptorBase { + /** + * A list of entries describing the shader resource bindings for a bind group. + */ entries: Array; } @@ -755,9 +758,16 @@ interface GPUExternalTextureBindingLayout {} interface GPUExternalTextureDescriptor extends GPUObjectDescriptorBase { + /** + * The video source to import the external texture from. + */ source: | HTMLVideoElement | VideoFrame; + /** + * The color space the image contents of {@link GPUExternalTextureDescriptor#source} will be + * converted into when reading. + */ colorSpace?: PredefinedColorSpace; } @@ -784,35 +794,46 @@ interface GPUImageCopyExternalImage { * The source of the image copy. The copy source data is captured at the moment that * {@link GPUQueue#copyExternalImageToTexture} is issued. Source size is defined by source * type, given by this table: - * * * * * * * * + * * * + * + * - * - * *
Source type - * Width - * Height + * Dimensions *
{@link ImageBitmap} - * {@link ImageBitmap#width|ImageBitmap.width} - * {@link ImageBitmap#height|ImageBitmap.height} + * {@link ImageBitmap#width|ImageBitmap.width}, + * {@link ImageBitmap#height|ImageBitmap.height} + *
{@link HTMLImageElement} + * {@link HTMLImageElement#naturalWidth|HTMLImageElement.naturalWidth}, + * {@link HTMLImageElement#naturalHeight|HTMLImageElement.naturalHeight} *
{@link HTMLVideoElement} - * video/intrinsic width|intrinsic width of the frame - * video/intrinsic height|intrinsic height of the frame + * video/intrinsic width|intrinsic width of the frame, + * video/intrinsic height|intrinsic height of the frame *
{@link VideoFrame} - * {@link VideoFrame#codedWidth|VideoFrame.codedWidth} - * {@link VideoFrame#codedHeight|VideoFrame.codedHeight} + * {@link VideoFrame#codedWidth|VideoFrame.codedWidth}, + * {@link VideoFrame#codedHeight|VideoFrame.codedHeight} + *
{@link ImageData} + * {@link ImageData#width|ImageData.width}, + * {@link ImageData#height|ImageData.height} + *
{@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link CanvasRenderingContext2D} or {@link GPUCanvasContext} + * {@link HTMLCanvasElement#width|HTMLCanvasElement.width}, + * {@link HTMLCanvasElement#height|HTMLCanvasElement.height} *
{@link HTMLCanvasElement} - * {@link HTMLCanvasElement#width|HTMLCanvasElement.width} - * {@link HTMLCanvasElement#height|HTMLCanvasElement.height} + * {@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link WebGLRenderingContextBase} + * {@link WebGLRenderingContextBase#drawingBufferWidth|WebGLRenderingContextBase.drawingBufferWidth}, + * {@link WebGLRenderingContextBase#drawingBufferHeight|WebGLRenderingContextBase.drawingBufferHeight} *
{@link OffscreenCanvas} - * {@link OffscreenCanvas#width|OffscreenCanvas.width} - * {@link OffscreenCanvas#height|OffscreenCanvas.height} + * {@link HTMLCanvasElement} or {@link OffscreenCanvas} with {@link ImageBitmapRenderingContext} + * {@link ImageBitmapRenderingContext}'s internal output bitmap + * {@link ImageBitmap#width|ImageBitmap.width}, + * {@link ImageBitmap#height|ImageBitmap.height} *
*/ @@ -1005,16 +1026,23 @@ interface GPUProgrammableStage { /** * The name of the function in {@link GPUProgrammableStage#module} that this stage will use to * perform its work. + * NOTE: Since the {@link GPUProgrammableStage#entryPoint} dictionary member is + * not required, methods which consume a {@link GPUProgrammableStage} must use the + * "[$get the entry point$]" algorithm to determine which entry point + * it refers to. */ entryPoint?: string; /** * Specifies the values of pipeline-overridable constants in the shader module * {@link GPUProgrammableStage#module}. * Each such pipeline-overridable constant is uniquely identified by a single - * pipeline-overridable constant identifier string (representing the numeric ID of the - * constant, if one is specified, and otherwise the constant's identifier name). - * WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier comparison. - * The key of each key-value pair must equal the identifier string of one such constant. + * pipeline-overridable constant identifier string, representing the pipeline + * constant ID of the constant if its declaration specifies one, and otherwise the + * constant's identifier name. + * The key of each key-value pair must equal the + * pipeline-overridable constant identifier string|identifier string + * of one such constant, with the comparison performed + * according to the rules for WGSL identifier comparison. * When the pipeline is executed, that constant will have the specified value. * Values are specified as GPUPipelineConstantValue, which is a {@link double}. * They are converted [$to WGSL type$] of the pipeline-overridable constant (`bool`/`i32`/`u32`/`f32`/`f16`). @@ -1174,7 +1202,7 @@ interface GPURenderPassDepthStencilAttachment { * to prior to executing the render pass. Ignored if {@link GPURenderPassDepthStencilAttachment#stencilLoadOp} * is not {@link GPULoadOp#"clear"}. * The value will be converted to the type of the stencil aspect of `view` by taking the same - * number of LSBs as the number of bits in the stencil aspect of one texel block of `view`. + * number of LSBs as the number of bits in the stencil aspect of one texel block|texel of `view`. */ stencilClearValue?: GPUStencilValue; /** @@ -1340,10 +1368,17 @@ interface GPUSamplerDescriptor */ compare?: GPUCompareFunction; /** - * Specifies the maximum anisotropy value clamp used by the sampler. - * Note: Most implementations support {@link GPUSamplerDescriptor#maxAnisotropy} values in range - * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor#maxAnisotropy} will - * be clamped to the maximum value that the platform supports. + * Specifies the maximum anisotropy value clamp used by the sampler. Anisotropic filtering is + * enabled when {@link GPUSamplerDescriptor#maxAnisotropy} is > 1 and the implementation supports it. + * Anisotropic filtering improves the image quality of textures sampled at oblique viewing + * angles. Higher {@link GPUSamplerDescriptor#maxAnisotropy} values indicate the maximum ratio of + * anisotropy supported when filtering. + *
+ * Most implementations support {@link GPUSamplerDescriptor#maxAnisotropy} values in range + * between 1 and 16, inclusive. The used value of {@link GPUSamplerDescriptor#maxAnisotropy} + * will be clamped to the maximum value that the platform supports. + * The precise filtering behavior is implementation-dependent. + *
*/ maxAnisotropy?: number; } @@ -1369,9 +1404,13 @@ interface GPUShaderModuleDescriptor */ code: string; /** - * If defined MAY be interpreted as a source-map-v3 format. - * Source maps are optional, but serve as a standardized way to support dev-tool - * integration such as source-language debugging [[SourceMap]]. + * If defined, **may** be interpreted in the [[!SourceMap]] v3 format. + * If an implementation supports this option but is unable to process the provided value, + * it should show a developer-visible warning but must not produce any application-observable + * error. + * Note: + * Source map support is optional, but serves as a semi-standardized way to support dev-tool + * integration such as source-language debugging. * WGSL names (identifiers) in source maps follow the rules defined in WGSL identifier * comparison. */ @@ -1387,12 +1426,14 @@ interface GPUShaderModuleDescriptor * Supplying information in {@link GPUShaderModuleDescriptor#compilationHints} does not have any * observable effect, other than performance. It may be detrimental to performance to * provide hints for pipelines that never end up being created. - * Because a single shader module can hold - * multiple entry points, and multiple pipelines can be created from a single shader - * module, it can be more performant for an implementation to do as much compilation as - * possible once in {@link GPUDevice#createShaderModule} rather than multiple times in - * the multiple calls to {@link GPUDevice#createComputePipeline} or - * {@link GPUDevice#createRenderPipeline}. + * Because a single shader module can hold multiple entry points, and multiple pipelines + * can be created from a single shader module, it can be more performant for an + * implementation to do as much compilation as possible once in + * {@link GPUDevice#createShaderModule} rather than multiple times in the multiple calls to + * {@link GPUDevice#createComputePipeline()} or {@link GPUDevice#createRenderPipeline}. + * Hints are only applied to the entry points they explicitly name. + * Unlike {@link GPUProgrammableStage#entryPoint|GPUProgrammableStage.entryPoint}, + * there is no default, even if only one entry point is present in the module. *
* Note: * Hints are not validated in an observable way, but user agents **may** surface identifiable @@ -1500,7 +1541,7 @@ interface GPUTextureDescriptor * Similar caveats exist for other formats and pairs of formats on other systems. *
* Formats in this list must be texture view format compatible with the texture format. - *
+ *
* Two {@link GPUTextureFormat}s `format` and `viewFormat` are texture view format compatible if: * - `format` equals `viewFormat`, or * - `format` and `viewFormat` differ only in whether they are `srgb` formats (have the `-srgb` suffix). @@ -1770,6 +1811,20 @@ interface GPUAdapter { * The limits in `this`.{@link GPUAdapter#[[adapter]]}.{@link adapter#[[limits]]}. */ readonly limits: GPUSupportedLimits; + /** + * Information about the physical adapter underlying this {@link GPUAdapter}. + * For a given {@link GPUAdapter}, the {@link GPUAdapterInfo} values exposed are constant over time. + * The same object is returned each time. To create that object for the first time: + *
+ *
+ * **Called on:** {@link GPUAdapter} `this`. + * **Returns:** {@link GPUAdapterInfo} + * Content timeline steps: + * 1. Return a [$new adapter info$] for `this.adapter`. + *
+ *
+ */ + readonly info: GPUAdapterInfo; /** * Returns the value of {@link GPUAdapter#[[adapter]]}.{@link adapter#[[fallback]]}. */ @@ -1777,18 +1832,12 @@ interface GPUAdapter { /** * Requests a device from the adapter. * This is a one-time action: if a device is returned successfully, - * the adapter becomes invalid. + * the adapter [$expires$]. * @param descriptor - Description of the {@link GPUDevice} to request. */ requestDevice( descriptor?: GPUDeviceDescriptor ): Promise; - /** - * Requests the {@link GPUAdapterInfo} for this {@link GPUAdapter}. - * Note: Adapter info values are returned with a Promise to give user agents an - * opportunity to perform potentially long-running checks in the future. - */ - requestAdapterInfo(): Promise; } declare var GPUAdapter: { diff --git a/gpuweb b/gpuweb index d2dea7f..93faa4b 160000 --- a/gpuweb +++ b/gpuweb @@ -1 +1 @@ -Subproject commit d2dea7f485531b9b225bee0772dcae8c9e44248f +Subproject commit 93faa4bf752f2152d0295c443d9697e4a5b0e337