From 9e28a3cc74b7a1fa3209c5035ccd4906750dd08b Mon Sep 17 00:00:00 2001 From: Brandon Jones Date: Tue, 27 Oct 2020 09:25:37 -0700 Subject: [PATCH 1/6] Documented guaranteed swap chain formats and validation --- spec/index.bs | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/spec/index.bs b/spec/index.bs index 3dd76940e4..6eab152a44 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -1424,6 +1424,18 @@ GPUDevice includes GPUObjectBase; : \[[device]], of type [=device=], readonly :: The [=device=] that this {{GPUDevice}} refers to. + + : \[[swap_chain_formats]], of type [=list=]<{{GPUTextureFormat}}>, readonly + :: + The {{GPUTextureFormat}}s that are valid to configure a {{GPUSwapChain}} with for this device. + The list must [=list/contain=] {{GPUTextureFormat/"bgra8unorm"}}, {{GPUTextureFormat/"bgra8unorm-srgb"}} + and {{GPUTextureFormat/"rgba16float"}}. Other renderable formats may be added according to + the capabilities of the user agent and [=device=]. + + : \[[preferred_swap_chain_format]], of type {{GPUTextureFormat}}, readonly + :: + The optimal {{GPUTextureFormat}} to use for {{GPUSwapChain}}s with for this device. + If no optimal format is known this value should be {{GPUTextureFormat/"bgra8unorm"}}. {{GPUDevice}} has the methods listed in its WebIDL definition above, which are defined elsewhere in @@ -6833,12 +6845,19 @@ interface GPUCanvasContext { **Arguments:** 
-                descriptor: Description of the {{GPUSwapChain}} to configure.
+                |descriptor|: Description of the {{GPUSwapChain}} to configure.
**Returns:** {{GPUSwapChain}} - Issue: Describe {{GPUCanvasContext/configureSwapChain()}} algorithm steps. + 1. If any of the following conditions are unsatisfied, generate a validation error and stop. +
+ - |descriptor|.{{GPUSwapChainDescriptor/device}} is a [=valid=] {{GPUDevice}}. + - |descriptor|.{{GPUSwapChainDescriptor/device}}.{{GPUDevice/[[swap_chain_formats]]}} + [=list/contains=] |descriptor|.{{GPUSwapChainDescriptor/format}}. +
+ + Issue: Describe remaining {{GPUCanvasContext/configureSwapChain()}} algorithm steps. : getSwapChainPreferredFormat(device) @@ -6851,12 +6870,17 @@ interface GPUCanvasContext { **Arguments:** 
-                device: Device the swap chain format should be queried for.
+                |device|: Device the swap chain format should be queried for.
**Returns:** {{Promise}}<{{GPUTextureFormat}}> - Issue: Describe {{GPUCanvasContext/getSwapChainPreferredFormat()}} algorithm steps. + 1. If any of the following conditions are unsatisfied, generate a validation error and stop. +
+ - |device| is a [=valid=] {{GPUDevice}}. +
+ + 1. Return |device|.{{GPUDevice/[[preferred_swap_chain_format]]}}. From 86c8154e32c07e6f4f0bab96979839364531e045 Mon Sep 17 00:00:00 2001 From: Brandon Jones Date: Tue, 27 Oct 2020 14:18:29 -0700 Subject: [PATCH 2/6] Modifying to fit Kai's suggestions --- spec/index.bs | 83 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 62 insertions(+), 21 deletions(-) diff --git a/spec/index.bs b/spec/index.bs index 6eab152a44..e84f24f44a 100644 --- a/spec/index.bs +++ b/spec/index.bs @@ -1424,18 +1424,6 @@ GPUDevice includes GPUObjectBase; : \[[device]], of type [=device=], readonly :: The [=device=] that this {{GPUDevice}} refers to. - - : \[[swap_chain_formats]], of type [=list=]<{{GPUTextureFormat}}>, readonly - :: - The {{GPUTextureFormat}}s that are valid to configure a {{GPUSwapChain}} with for this device. - The list must [=list/contain=] {{GPUTextureFormat/"bgra8unorm"}}, {{GPUTextureFormat/"bgra8unorm-srgb"}} - and {{GPUTextureFormat/"rgba16float"}}. Other renderable formats may be added according to - the capabilities of the user agent and [=device=]. - - : \[[preferred_swap_chain_format]], of type {{GPUTextureFormat}}, readonly - :: - The optimal {{GPUTextureFormat}} to use for {{GPUSwapChain}}s with for this device. - If no optimal format is known this value should be {{GPUTextureFormat/"bgra8unorm"}}. {{GPUDevice}} has the methods listed in its WebIDL definition above, which are defined elsewhere in @@ -6832,6 +6820,20 @@ interface GPUCanvasContext { }; +{{GPUCanvasContext}} has the following internal slots: + +
+ : \[[supported_formats]], of type [=ordered map=]<{{GPUDevice}}, [=set=]<{{GPUTextureFormat}}>> + :: + The {{GPUTextureFormat}}s that are valid to configure a {{GPUSwapChain}} with for a given {{GPUDevice}}. + + : \[[preferred_format]], of type [=ordered map=]<{{GPUDevice}}, {{GPUTextureFormat}}> + :: + An optimal {{GPUTextureFormat}} to use when creating a {{GPUSwapChain}} for a given {{GPUDevice}}. +
+ +{{GPUCanvasContext}} has the following methods: +
: configureSwapChain(descriptor) :: @@ -6841,7 +6843,7 @@ interface GPUCanvasContext { textures it has produced.
- **Called on:** {{GPUCanvasContext}} this. + **Called on:** {{GPUCanvasContext}} |this|. **Arguments:** 
@@ -6853,8 +6855,9 @@ interface GPUCanvasContext {
             1. If any of the following conditions are unsatisfied, generate a validation error and stop.
                 

                     - |descriptor|.{{GPUSwapChainDescriptor/device}} is a [=valid=] {{GPUDevice}}.
-                    - |descriptor|.{{GPUSwapChainDescriptor/device}}.{{GPUDevice/[[swap_chain_formats]]}}
-                        [=list/contains=] |descriptor|.{{GPUSwapChainDescriptor/format}}.
+                    - Let |supportedFormats| be the [$supported swap chain formats$] for |this| and
+                        |descriptor|.{{GPUSwapChainDescriptor/device}}.
+                    - |supportedFormats| [=set/contains=] |descriptor|.{{GPUSwapChainDescriptor/format}}.
                 

 
             Issue: Describe remaining {{GPUCanvasContext/configureSwapChain()}} algorithm steps.
@@ -6866,7 +6869,7 @@ interface GPUCanvasContext {
         given device.
 
         

-            **Called on:** {{GPUCanvasContext}} this.
+            **Called on:** {{GPUCanvasContext}} |this|.
 
             **Arguments:**
             
@@ -6875,15 +6878,53 @@ interface GPUCanvasContext {
 
             **Returns:** {{Promise}}<{{GPUTextureFormat}}>
 
-            1. If any of the following conditions are unsatisfied, generate a validation error and stop.
-                

-                    - |device| is a [=valid=] {{GPUDevice}}.
-                

+            1. Let |promise| be [=a new promise=].
+            1. Issue the following steps on the [=Device timeline=] of |this|:
+                

+                    1. If any of the following conditions are unsatisfied, [=reject=] |promise| with
+                        an {{OperationError}} and stop.
+
+                        

+                            - |device| is a [=valid=] {{GPUDevice}}.
+                        

 
-            1. Return |device|.{{GPUDevice/[[preferred_swap_chain_format]]}}.
+                    1. Let |preferredFormat| be the [$preferred swap chain format$] for |this| and |device|.
+                    1. Let |supportedFormats| be the [$supported swap chain formats$] for |this| and |device|.
+                    1. [=set/Append=] |preferredFormat| to |supportedFormats|.
+                    1. [=Resolve=] |promise| with |preferredFormat|.
+                

+            1. Return |promise|.
+The guaranteed swap chain formats are a [=set=] of {{GPUTextureFormat}}s that must be +supported when specified as a {{GPUSwapChainDescriptor}}.{{GPUSwapChainDescriptor/format}} regardless +of the given {{GPUSwapChainDescriptor}}.{{GPUSwapChainDescriptor/device}}, initially set to: +«{{GPUTextureFormat/"bgra8unorm"}}, {{GPUTextureFormat/"bgra8unorm-srgb"}}, {{GPUTextureFormat/"rgba16float"}}». + +
+ To get the supported swap chain formats for a given {{GPUCanvasContext}} + |context| and a given {{GPUDevice}} |device| run the following steps: + + 1. Let |supportedFormats| be |context|.{{GPUCanvasContext/[[supported_formats]]}} + 1. If |supportedFormats|[|device|] does not exis: + 1. Set |supportedFormats|[|device|] to be a [=set/clone=] of [=guaranteed swap chain formats=]. + 1. Return |supportedFormats|[|device|]. +
+ +
+ To get the preferred swap chain format for a given {{GPUCanvasContext}} + |context| and a given {{GPUDevice}} |device| run the following steps:: + + 1. Let |preferredFormat| be |context|.{{GPUCanvasContext/[[preferred_format]]}} + 1. If |preferredFormat|[|device|] does not exist: + 1. Set |preferredFormat|[|device|] to be an renderable {{GPUTextureFormat}} known to be + optimal for use with |context| and |device|. The user agent may use any criteria to + select the format. If no optimal format is known, the user agent should select one of + the [=guaranteed swap chain formats=]. + 1. Return |preferredFormat|[|device|]. +
+ {{GPUCanvasContext}} has the following internal slots:
- : \[[supported_formats]], of type [=ordered map=]<{{GPUDevice}}, [=set=]<{{GPUTextureFormat}}>> + : \[[supported_formats]], of type [=ordered map=]<{{GPUAdapter}}, [=set=]<{{GPUTextureFormat}}>> :: - The {{GPUTextureFormat}}s that are valid to configure a {{GPUSwapChain}} with for a given {{GPUDevice}}. + The {{GPUTextureFormat}}s that are valid to configure a {{GPUSwapChain}} with for a given {{GPUAdapter}}. - : \[[preferred_format]], of type [=ordered map=]<{{GPUDevice}}, {{GPUTextureFormat}}> + : \[[preferred_format]], of type [=ordered map=]<{{GPUAdapter}}, {{GPUTextureFormat}}> :: - An optimal {{GPUTextureFormat}} to use when creating a {{GPUSwapChain}} for a given {{GPUDevice}}. + An optimal {{GPUTextureFormat}} to use when creating a {{GPUSwapChain}} for a given {{GPUAdapter}}.
{{GPUCanvasContext}} has the following methods: @@ -6852,15 +6852,18 @@ interface GPUCanvasContext { **Returns:** {{GPUSwapChain}} - 1. If any of the following conditions are unsatisfied, generate a validation error and stop. -
- - |descriptor|.{{GPUSwapChainDescriptor/device}} is a [=valid=] {{GPUDevice}}. - - Let |supportedFormats| be the [$supported swap chain formats$] for |this| and - |descriptor|.{{GPUSwapChainDescriptor/device}}. - - |supportedFormats| [=set/contains=] |descriptor|.{{GPUSwapChainDescriptor/format}}. -
+ 1. Issue the following steps on the [=Device timeline=] of |this|: +
+ 1. If any of the following conditions are unsatisfied, generate a validation error and stop. +
+ - |descriptor|.{{GPUSwapChainDescriptor/device}} is a [=valid=] {{GPUDevice}}. + - Let |supportedFormats| be the [$supported swap chain formats$] for |this| and + |descriptor|.{{GPUSwapChainDescriptor/device}}.{{GPUDevice/adapter}}. + - |supportedFormats| [=set/contains=] |descriptor|.{{GPUSwapChainDescriptor/format}}. +
- Issue: Describe remaining {{GPUCanvasContext/configureSwapChain()}} algorithm steps. + Issue: Describe remaining {{GPUCanvasContext/configureSwapChain()}} algorithm steps. +
: getSwapChainPreferredFormat(device) @@ -6872,28 +6875,16 @@ interface GPUCanvasContext { **Called on:** {{GPUCanvasContext}} |this|. **Arguments:** - 
-                |device|: Device the swap chain format should be queried for.
+            
+                |adapter|: Adapter the swap chain format should be queried for.
             

 
-            **Returns:** {{Promise}}<{{GPUTextureFormat}}>
-
-            1. Let |promise| be [=a new promise=].
-            1. Issue the following steps on the [=Device timeline=] of |this|:
-                

-                    1. If any of the following conditions are unsatisfied, [=reject=] |promise| with
-                        an {{OperationError}} and stop.
+            **Returns:** {{GPUTextureFormat}}
 
-                        

-                            - |device| is a [=valid=] {{GPUDevice}}.
-                        

-
-                    1. Let |preferredFormat| be the [$preferred swap chain format$] for |this| and |device|.
-                    1. Let |supportedFormats| be the [$supported swap chain formats$] for |this| and |device|.
-                    1. [=set/Append=] |preferredFormat| to |supportedFormats|.
-                    1. [=Resolve=] |promise| with |preferredFormat|.
-                

-            1. Return |promise|.
+            

+                1. Let |preferredFormat| be the [$preferred swap chain format$] for |this| and |adapter|.
+                1. Return |preferredFormat|.
+            

         
 
 
@@ -6904,25 +6895,27 @@ of the given {{GPUSwapChainDescriptor}}.{{GPUSwapChainDescriptor/device}}, initi
 
 

     To get the supported swap chain formats for a given {{GPUCanvasContext}}
-    |context| and a given {{GPUDevice}} |device| run the following steps:
+    |context| and a given {{GPUAdapter}} |adapter| run the following steps:
 
     1. Let |supportedFormats| be |context|.{{GPUCanvasContext/[[supported_formats]]}}
-    1. If |supportedFormats|[|device|] does not exis:
-        1. Set |supportedFormats|[|device|] to be a [=set/clone=] of [=guaranteed swap chain formats=].
-    1. Return |supportedFormats|[|device|].
+    1. If |supportedFormats|[|adapter|] does not exis:
+        1. Set |supportedFormats|[|adapter|] to be a [=set/clone=] of [=guaranteed swap chain formats=].
+        1. Let |preferredFormat| be the [$preferred swap chain format$] for |context| and |adapter|.
+        1. [=set/Append=] |preferredFormat| to |supportedFormats|[|adapter|].
+    1. Return |supportedFormats|[|adapter|].
 

 
 

     To get the preferred swap chain format for a given {{GPUCanvasContext}}
-    |context| and a given {{GPUDevice}} |device| run the following steps::
+    |context| and a given {{GPUAdapter}} |adapter| run the following steps::
 
     1. Let |preferredFormat| be |context|.{{GPUCanvasContext/[[preferred_format]]}}
-    1. If |preferredFormat|[|device|] does not exist:
-        1. Set |preferredFormat|[|device|] to be an renderable {{GPUTextureFormat}} known to be
-            optimal for use with |context| and |device|. The user agent may use any criteria to
+    1. If |preferredFormat|[|adapter|] does not exist:
+        1. Set |preferredFormat|[|adapter|] to be an renderable {{GPUTextureFormat}} known to be
+            optimal for use with |context| and |adapter|. The user agent may use any criteria to
             select the format. If no optimal format is known, the user agent should select one of
             the [=guaranteed swap chain formats=].
-    1. Return |preferredFormat|[|device|].
+    1. Return |preferredFormat|[|adapter|].
 

 
 
 
-{{GPUCanvasContext}} has the following internal slots:
-
-

-    : \[[preferred_format]], of type [=ordered map=]<{{GPUAdapter}}, {{GPUTextureFormat}}>
-    ::
-        An optimal {{GPUTextureFormat}} to use when creating a {{GPUSwapChain}} for a given {{GPUAdapter}}.
-

-
 {{GPUCanvasContext}} has the following methods:
 
 

@@ -6881,7 +6868,8 @@ interface GPUCanvasContext {
             **Returns:** {{GPUTextureFormat}}
 
             

-                1. Return |adapter|.{{GPUAdapter/[[preferred_format]]}}
+                1. Return an optimal {{GPUTextureFormat}} to use when creating a {{GPUSwapChain}}
+                    with the given |adapter|. Must be one of the [=supported swap chain formats=].