From 28b6c44ac4f8329f5e1dbdd9aad47a5672282ef0 Mon Sep 17 00:00:00 2001
From: "Myles C. Maxfield" <mmaxfield@apple.com>
Date: Tue, 30 Nov 2021 14:43:29 -0800
Subject: [PATCH] Allow GPUShaderModules to contain MTLLibraries

> The resolution is to add a dictionary of entry point name to pipeline layout to createShaderModule(), which is optional, and implementations can totally ignore it 100% (no validation).

Fixes https://github.com/gpuweb/gpuweb/issues/1064.
---
 spec/index.bs | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/spec/index.bs b/spec/index.bs
index 7574abc069..98b4361c59 100644
--- a/spec/index.bs
+++ b/spec/index.bs
@@ -4040,9 +4040,14 @@ Issue(gpuweb/gpuweb#354): Finish defining multithreading API and add `[Serializa
 ### Shader Module Creation ### {#shader-module-creation}
 
 <script type=idl>
+dictionary GPUShaderModuleCompilationHint {
+    required GPUPipelineLayout layout;
+};
+
 dictionary GPUShaderModuleDescriptor : GPUObjectDescriptorBase {
     required USVString code;
     object sourceMap;
+    record<USVString, GPUShaderModuleCompilationHint> hints;
 };
 </script>
 
@@ -4051,6 +4056,39 @@ 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]]
 
+{{GPUShaderModuleDescriptor/hints}}, if defined, maps an entry point name from
+the shader to a {{GPUShaderModuleCompilationHint}}. No validation is performed with
+any of these {{GPUShaderModuleCompilationHint}}. Implementations should use any
+information present in the {{GPUShaderModuleCompilationHint}} to perform as much
+compilation as is possible within {{GPUDevice/createShaderModule()}}.
+
+Note: Supplying information in {{GPUShaderModuleDescriptor/hints}} does not have any
+observable effect, other than performance. 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 {{GPUDevice/createShaderModule()}} rather than multiple times in
+the multiple calls to {{GPUDevice/createComputePipeline()}} /
+{{GPUDevice/createRenderPipeline()}}.
+
+Note: If possible, authors should be supplying the same information to
+{{GPUDevice/createShaderModule()}} and {{GPUDevice/createComputePipeline()}} /
+{{GPUDevice/createRenderPipeline()}}.
+
+Note: If an author is unable to provide this {{GPUShaderModuleDescriptor/hints}}
+information at the time of calling {{GPUDevice/createShaderModule()}}, they should
+usually not delay calling {{GPUDevice/createShaderModule()}}; but should instead just
+omit the unknown information from {{GPUShaderModuleDescriptor/hints}} or
+{{GPUShaderModuleCompilationHint}}. Omitting this information may cause compilation
+to be deferred to {{GPUDevice/createComputePipeline()}} /
+{{GPUDevice/createRenderPipeline()}}.
+
+Note: If an author is not confident that the information passed to
+{{GPUDevice/createShaderModule()}} will match the information later passed to
+{{GPUDevice/createComputePipeline()}} / {{GPUDevice/createRenderPipeline()}} with that
+same module, they should avoid passing that information to
+{{GPUDevice/createShaderModule()}}, as passing mismatched information to
+{{GPUDevice/createShaderModule()}} may cause unnecessary compilations to occur.
+
 <dl dfn-type=method dfn-for=GPUDevice>
     : <dfn>createShaderModule(descriptor)</dfn>
     ::