Explainer: initialization (#1636)

kainino0x · web-flow · commit 1e9bec7740ef · 2021-04-15T17:31:16.000-04:00
* Explainer: initialization

* clarify similarity to WebGLRenderingContext
diff --git a/explainer/index.bs b/explainer/index.bs
@@ -56,6 +56,52 @@ See also the description of [the content and device timelines in the specificati
 
 ## Adapter Selection and Device Init ## {#initialization}
 
+Issue: Some changes are expected here.
+
+A WebGPU "adapter" (`GPUAdapter`) is an object which provides a connection to a particular WebGPU
+implementation on the system (e.g. a hardware accelerated implementation on an integrated or
+discrete GPU, or software implementation).
+To get a `GPUAdapter` is to select which implementation to use (if multiple are available).
+
+Each adapter may have different optional capabilities called "features" and "limits".
+These are the maximum possible capabilities that can be requested when a device is created.
+
+To get an adapter, an application calls `navigator.gpu.requestAdapter()`, optionally passing
+options which may influence what adapter is chosen.
+
+`requestAdapter()` always resolves, but may resolve to null if an adapter can't be returned with
+the specified options.
+
+<pre highlight=js>
+const adapter = await navigator.gpu.requestAdapter(options);
+if (!adapter) return goToFallback();
+</pre>
+
+A WebGPU "device" (`GPUDevice`) represents a connection to a WebGPU implementation, as well as
+an arena for all WebGPU objects created from it (textures, command buffers, etc.)
+All WebGPU usage is done through a WebGPU "device" (`GPUDevice`) or objects created from it.
+In this sense, it serves a subset of the purpose of `WebGLRenderingContext`; however, unlike
+`WebGLRenderingContext`, it is not associated with a canvas object, and most commands are
+issued through "child" objects.
+
+To get a device, an application calls `adapter.requestDevice()`, optionally passing a descriptor
+which enables additional optional capabilities (features and limits).
+When any work is issued to the device, it is strictly validated against the capabilities passed
+to `requestDevice()` - not the capabilities of the adapter.
+
+`requestDevice()` will reject (only) if the request exceeds the capabilities of the adapter.
+It may *not* resolve to `null`; instead, to simplify the number of different cases an app must
+handle, it may resolve to a `GPUDevice` which has already been lost - see [[#device-loss]].
+
+<pre highlight=js>
+const device = await adapter.requestDevice(descriptor);
+device.lost.then(recoverFromDeviceLoss);
+</pre>
+
+An adapter may become unavailable, e.g. if it is unplugged from the system, disabled to save
+power, or marked "stale" (`[[current]]` becomes false).
+Such an adapter can no longer vend valid devices, and always returns already-lost `GPUDevice`s.
+
 
 ## Object Validity and Destroyed-ness ## {#invalid-and-destroyed}
 
@@ -395,7 +441,7 @@ For example:
 ```
 
 
-## Adapter and Device Loss ## {#device-loss}
+## Device Loss ## {#device-loss}
 
 Any situation that prevents further use of a `GPUDevice`, regardless of whether it is caused by a
 WebGPU call (e.g. `device.destroy()`, unrecoverable out-of-memory, GPU process crash, or GPU
@@ -983,6 +1029,7 @@ which mentions that strongly-typed bitflags in JavaScript would be useful.
 
 # WebGPU Shading Language # {#wgsl}
 
+
 # Security and Privacy self-review # {#questionnaire}
 
 ## What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary? ## {#questionnaire-1}
@@ -1063,7 +1110,7 @@ However WebGPU can be used to render to fullscreen or WebXR which does change th
 WebGPU can also run GPU computations that take too long and cause of device timeout and a restart of GPU (TDR), which can produce a couple system-wide black frames.
 Note that this is possible with "just" HTML / CSS but WebGPU makes it easier to cause a TDR.
 
-## What temporary identifiers do the features in this specification create or expose to the web?## {#questionnaire-13} 
+## What temporary identifiers do the features in this specification create or expose to the web? ## {#questionnaire-13}
 
 None.
 
