Merge branch 'main' into vertex-buffer-hole

Author: kainino0x

Doxyfile

@@ -27,6 +27,15 @@ OUTPUT_DIRECTORY       = doc/generated
 
 OPTIMIZE_OUTPUT_FOR_C  = YES
 
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
+WARN_IF_INCOMPLETE_DOC = NO
+# Note EXTRACT_ALL bypasses these, but keep them in case we disable it.
+WARN_IF_UNDOC_ENUM_VAL = YES
+WARN_NO_PARAMDOC       = NO
+WARN_IF_UNDOCUMENTED   = YES
+
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------

Makefile

@@ -24,3 +24,5 @@ gen-check: fix gen
 
 doc: webgpu.h Doxyfile
 	doxygen Doxyfile
+	# Verify that no ` or :: made it through into the final docs
+	! grep -RE '`|>::' doc/generated/**/*.html

doc/articles/Asynchronous Operations.md

@@ -21,7 +21,7 @@ All asynchronous operations start when the application calls an asynchronous web
    `void* userdata1`<br>
    `void* userdata2`
 
-The `callback` function pointer is called when the application _observes completion_ of the asynchronous operation. The `userdata1` and `userdata2` members are passed back to the application as the last two arguments in the callback function. Callbacks **might not** be called unless the application explicitly flushes them in order to _observe completion_. The point in time a callback is called depends on the @ref WGPUCallbackMode of the operation. webgpu.h provides three callback modes: `::WGPUCallbackMode_WaitAnyOnly`, `::WGPUCallbackMode_AllowProcessEvents`, and `::WGPUCallbackMode_AllowSpontaneous`.
+The `callback` function pointer is called when the application _observes completion_ of the asynchronous operation. The `userdata1` and `userdata2` members are passed back to the application as the last two arguments in the callback function. Callbacks **might not** be called unless the application explicitly flushes them in order to _observe completion_. The point in time a callback is called depends on the @ref WGPUCallbackMode of the operation. webgpu.h provides three callback modes: @ref WGPUCallbackMode_WaitAnyOnly, @ref WGPUCallbackMode_AllowProcessEvents, and @ref WGPUCallbackMode_AllowSpontaneous.
 
 > @copydoc ::WGPUCallbackMode_WaitAnyOnly
 > @copydoc ::WGPUCallbackMode_AllowProcessEvents
@@ -32,13 +32,13 @@ The `callback` function pointer is called when the application _observes complet
 
 Waits on any WGPUFuture in the list of `futures` to complete for `timeoutNS` nanoseconds. Returns when at least one `WGPUFuture` is completed or `timeoutNS` elapses, whichever is first. If `timeoutNS` is zero, all `futures` are polled once, without blocking.
 
-Returns `::WGPUWaitStatus_Success` if at least one `WGPUFuture` completes. WGPUFutureWaitInfo::completed is set to true for all completed futures. See @ref WGPUWaitStatus for other status codes.
+Returns @ref WGPUWaitStatus_Success if at least one `WGPUFuture` completes. WGPUFutureWaitInfo::completed is set to true for all completed futures. See @ref WGPUWaitStatus for other status codes.
 
 Within this call, for any `WGPUFuture`s that completed, their respective callbacks will fire.
 
 ### Timed Wait {#Timed-Wait}
 
-Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in `::wgpuCreateInstance` with `WGPUInstanceFeatures::timedWaitAnyEnable`, and the number of futures waited on must be less than or equal to `WGPUInstanceFeatures::timedWaitAnyMaxCount`. Supported instance features may be queried using `::wgpuGetInstanceFeatures`.
+Use of _timed waits_ (`timeoutNS > 0`), must be enabled on the WGPUInstance in @ref wgpuCreateInstance with `WGPUInstanceFeatures::timedWaitAnyEnable`, and the number of futures waited on must be less than or equal to `WGPUInstanceFeatures::timedWaitAnyMaxCount`. Supported instance features may be queried using @ref wgpuGetInstanceCapabilities.
 
 ### Mixed Sources {#Mixed-Sources}
 
@@ -59,13 +59,13 @@ Asynchronous operations may originate from different sources. There are CPU-time
 ## wgpuInstanceProcessEvents {#Process-Events}
 `void wgpuInstanceProcessEvents(WGPUInstance)`
 
-Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with `::WGPUCallbackMode_AllowProcessEvents` that have completed. This is a non-blocking operation.
+Processes asynchronous events on this `WGPUInstance`, calling any callbacks for asynchronous operations created with @ref WGPUCallbackMode_AllowProcessEvents that have completed. This is a non-blocking operation.
 
 ## Device Events
 
 Device events are slightly different in that their callback info (`WGPUDeviceLostCallbackInfo` and `WGPUUncapturedErrorCallbackInfo`) are passed on the `WGPUDeviceDescriptor`, instead of in a function argument. There is no `WGPUFuture` returned for either callback.
 @todo Add a getter for the device lost WGPUFuture. See discussion at https://github.com/webgpu-native/webgpu-headers/issues/199#issuecomment-1866850031.
 
-The `WGPUUncapturedErrorCallbackInfo` _does not_ have a callback mode member. It is always as-if it were `::WGPUCallbackMode_AllowSpontaneous`. Note also that the uncaptured error callback is a _repeating_ callback that fires multiple times, unlike other callbacks in webgpu.h.
+The `WGPUUncapturedErrorCallbackInfo` _does not_ have a callback mode member. It is always as-if it were @ref WGPUCallbackMode_AllowSpontaneous. Note also that the uncaptured error callback is a _repeating_ callback that fires multiple times, unlike other callbacks in webgpu.h.
 
 The uncaptured error callback is guaranteed not to fire after the device becomes lost. When the device is lost, it is an appropriate time for the application to free userdata variables for the uncaptured error callback. Note that the device becomes lost _before_ the actual device lost callback fires. First the device state transitions to lost, then the device lost callback fires. The timing of the callback depends on the device lost callback mode.

doc/articles/Errors.md

@@ -25,7 +25,7 @@ These behave similarly to the Promise-returning JavaScript APIs. Instead of ther
 
 These errors include:
 
-- @ref SynchronousStructChainingError cases.
+- @ref StructChainingError cases.
 - [Content-timeline](https://www.w3.org/TR/webgpu/#content-timeline) errors other than those which are surfaced as @ref DeviceError in `webgpu.h`. See specific documentation to determine how each error is exposed.
 
 Generally these will return some kind of failure status (like \ref WGPUStatus_Error) or `NULL`, and produce an @ref ImplementationDefinedLogging message.
@@ -36,15 +36,15 @@ Entry points may also specify that they produce "implementation-defined logging"
 These messages are logged in an implementation defined way (e.g. to an implementation-specific callback, or to a logging runtime).
 They are intended to be intended to be read by humans, useful primarily for development and crash reporting.
 
-## Struct-Chaining Errors {#StructChainingErrors}
+## Struct-Chaining Error {#StructChainingError}
 
-A struct-chaining error happens when the @ref SType of a struct in a struct chain is not valid for that chain.
+A struct-chaining error happens when the @ref WGPUSType of a struct in a struct chain is not valid for that chain.
 
-Struct chains which are used in device-timeline validation/operations (e.g. @ref WGPUBufferDescriptor in @ref WGPUDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error.
+Struct chains which are used in device-timeline validation/operations (e.g. @ref WGPUBufferDescriptor in @ref wgpuDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error.
 
 ### Out-Struct-Chain Error {#OutStructChainError}
 
-Operations which take out-struct-chains (e.g. @ref WGPULimits, in @ref WGPUAdapterGetLimits/@ref WGPUDeviceGetLimits, but not in @ref WGPUDeviceDescriptor) handle struct-chaining errors as follows:
+Operations which take out-struct-chains (e.g. @ref WGPULimits, in @ref wgpuAdapterGetLimits and @ref wgpuDeviceGetLimits, but not in @ref WGPUDeviceDescriptor) handle struct-chaining errors as follows:
 
 - The output struct and struct chain is not modified.
 - The operation produces a @ref SynchronousError (return value and log message).

doc/articles/SentinelValues.md

@@ -1,6 +1,6 @@
 # Sentinel Values {#SentinelValues}
 
-## Undefined
+## Undefined and Null
 
 Since WebGPU is defined first as a JavaScript API, it uses the JavaScript value
 `undefined` in many places to indicate the lack of a value.
@@ -14,7 +14,8 @@ It may also be used in functions/methods. For example, `GPUBuffer`'s
 can be called equivalently as `b.getMappedRange()`, `b.getMappedRange(0)`,
 `b.getMappedRange(undefined)`, or `b.getMappedRange(undefined, undefined)`.
 
-To represent `undefined` in C, `webgpu.h` uses `*_UNDEFINED` sentinel numeric values
+To represent `undefined` in C, `webgpu.h` uses `NULL` where possible (anything
+behind a pointer, including objects), `*_UNDEFINED` sentinel numeric values
 (generally `UINT32_MAX`, etc.) and `*_Undefined` enum values (generally `0`).
 
 The place that uses the type will define what to do with an undefined value.
@@ -26,13 +27,19 @@ It may be:
   (usually this is either a special value or it has more complex defaulting,
   for example depending on other values).
 
-## Other sentinel values
-
-Undefined values are also be used in C-specific ways in place of WebIDL's
-more flexible typing:
-
-- \ref WGPUVertexBufferLayout::stepMode = \ref WGPUVertexStepMode_Undefined with \ref WGPUVertexBufferLayout::attributeCount
-- \ref WGPUBufferBindingType_BindingNotUsed
-- \ref WGPUSamplerBindingType_BindingNotUsed
-- \ref WGPUTextureSampleType_BindingNotUsed
-- \ref WGPUStorageTextureAccess_BindingNotUsed
+## C-Specific Sentinel Values
+
+Undefined and null values are also used in C-specific ways in place of
+WebIDL's more flexible typing:
+
+- \ref WGPUStringView has a special null value
+- \ref WGPUFuture has a special null value
+- Special cases to indicate the parent struct is null, avoiding extra layers of
+  pointers just for nullability:
+    - \ref WGPUVertexBufferLayout::stepMode = \ref WGPUVertexStepMode_Undefined with \ref WGPUVertexBufferLayout::attributeCount
+    - \ref WGPUBufferBindingLayout::type = \ref WGPUBufferBindingType_BindingNotUsed
+    - \ref WGPUSamplerBindingLayout::type = \ref WGPUSamplerBindingType_BindingNotUsed
+    - \ref WGPUTextureBindingLayout::sampleType = \ref WGPUTextureSampleType_BindingNotUsed
+    - \ref WGPUStorageTextureBindingLayout::access = \ref WGPUStorageTextureAccess_BindingNotUsed
+    - \ref WGPURenderPassColorAttachment::view = `NULL`
+    - \ref WGPUColorTargetState::format = \ref WGPUTextureFormat_Undefined

doc/articles/Surfaces.md

@@ -11,7 +11,7 @@ Sections below give more details about these operations, including the specifica
 
 ## Surface Creation {#Surface-Creation}
 
-A @ref WGPUSurface is child object of a @ref WGPUInstance and created using `::wgpuInstanceCreateSurface`.
+A @ref WGPUSurface is child object of a @ref WGPUInstance and created using @ref wgpuInstanceCreateSurface.
 The description of a @ref WGPUSurface is a @ref WGPUSurfaceDescriptor with a sub-descriptor chained containing the environment-specific objects used to identify the surface.
 
 Surfaces that can be presented to using `webgpu.h` (but not necessarily by all implementations) are:
@@ -56,9 +56,9 @@ struct WGPUSurface {
 };
 ```
 
-The behavior of `::wgpuInstanceCreateSurface``(instance, descriptor)` is:
+The behavior of <code>@ref wgpuInstanceCreateSurface</code><code>(instance, descriptor)</code> is:
 
- - If any of these validation steps fails, return an error @ref WGPUSurface:
+ - If any of these validation steps fails, return an error @ref WGPUSurface object:
 
     - Validate that all the sub-descriptors in the chain for `descriptor` are known to this implementation.
     - Validate that `descriptor` contains information about exactly one OS surface.
@@ -70,16 +70,16 @@ The behavior of `::wgpuInstanceCreateSurface``(instance, descriptor)` is:
 
 Depending on the OS, GPU used, backing API for WebGPU and other factors, different capabilities are available to render and present the @ref WGPUSurface.
 For this reason, negotiation is done between the WebGPU implementation and the application to choose how to use the @ref WGPUSurface.
-This first step of the negotiation is querying what capabilities are available using `::wgpuSurfaceGetCapabilities` that fills an @ref WGPUSurfaceCapabilities structure with the following information:
+This first step of the negotiation is querying what capabilities are available using @ref wgpuSurfaceGetCapabilities that fills an @ref WGPUSurfaceCapabilities structure with the following information:
 
  - A bit set of supported @ref WGPUTextureUsage that are guaranteed to contain @ref WGPUTextureUsage_RenderAttachment.
  - A list of supported @ref WGPUTextureFormat values, in order of preference.
  - A list of supported @ref WGPUPresentMode values (guaranteed to contain @ref WGPUPresentMode_Fifo).
  - A list of supported @ref WGPUCompositeAlphaMode values (@ref WGPUCompositeAlphaMode_Auto is always supported but never listed in capabilities as it just lets the implementation decide what to use).
 
-The call to `::wgpuSurfaceGetCapabilities` may allocate memory for pointers filled in the @ref WGPUSurfaceCapabilities structure so `::wgpuSurfaceCapabilitiesFreeMembers` must be called to avoid leaking memory once the capabilities are no longer needed.
+The call to @ref wgpuSurfaceGetCapabilities may allocate memory for pointers filled in the @ref WGPUSurfaceCapabilities structure so @ref wgpuSurfaceCapabilitiesFreeMembers must be called to avoid leaking memory once the capabilities are no longer needed.
 
-This is an example of how to query the capabilities or a @ref WGPUSurface:
+This is an example of how to query the capabilities of a <code>@ref WGPUSurface</code>:
 
 ```c
 // Get the capabilities
@@ -103,7 +103,7 @@ for (size_t i = 0; i < caps.presentModeCount; i++) {
 wgpuSurfaceCapabilitiesFreeMembers(caps);
 ```
 
-The behavior of `::wgpuSurfaceGetCapabilities``(surface, adapter, caps)` is:
+The behavior of <code>@ref wgpuSurfaceGetCapabilities</code><code>(surface, adapter, caps)</code> is:
 
  - If any of these validation steps fails, return false. (TODO return an error WGPUStatus):
 
@@ -116,14 +116,14 @@ The behavior of `::wgpuSurfaceGetCapabilities``(surface, adapter, caps)` is:
 ## Surface Configuration {#Surface-Configuration}
 
 Before it can use it for rendering, the application must configure the surface.
-The configuration is the second step of the negotiation, done after analyzing the results of `::wgpuSurfaceGetCapabilities`.
+The configuration is the second step of the negotiation, done after analyzing the results of @ref wgpuSurfaceGetCapabilities.
 It contains the following kinds of parameters:
 
  - The @ref WGPUDevice that will be used to render to the surface.
- - Parameters for the textures returned by `::wgpuSurfaceGetCurrentTexture`.
+ - Parameters for the textures returned by @ref wgpuSurfaceGetCurrentTexture.
  - @ref WGPUPresentMode and @ref WGPUCompositeAlphaMode parameters for how and when the surface will be presented to the user.
 
-This is an example of how to configure a @ref WGPUSurface:
+This is an example of how to configure a <code>@ref WGPUSurface</code>:
 
 ```c
 WGPUSurfaceConfiguration config = {
@@ -163,13 +163,13 @@ WGPUTextureDescriptor GetSurfaceEquivalentTextureDescriptor(const WGPUSurfaceCon
 
 When a surface is successfully configured, the new configuration overrides any previous configuration and destroys the previous current texture (if any) so it can no longer be used.
 
-The behavior of `::wgpuSurfaceConfigure``(surface, config)` is:
+The behavior of <code>@ref wgpuSurfaceConfigure</code><code>(surface, config)</code> is:
 
  - If any of these validation steps fails, TODO: what should happen on failure?
 
    - Validate that `surface` is not an error.
    - Let `adapter` be the adapter used to create `device`.
-   - Let `caps` be the @ref WGPUSurfaceCapabilities filled with `::wgpuSurfaceGetCapabilities``(surface, adapter, &caps)`.
+   - Let `caps` be the @ref WGPUSurfaceCapabilities filled with <code>@ref wgpuSurfaceGetCapabilities</code><code>(surface, adapter, &caps)</code>.
    - Validate that all the sub-descriptors in the chain for `caps` are known to this implementation.
    - Validate that `device` is alive.
    - Validate that `config->presentMode` is in `caps->presentModes`.
@@ -182,23 +182,23 @@ The behavior of `::wgpuSurfaceConfigure``(surface, config)` is:
  - Set `surface.config` to a deep copy of `config`.
  - If `surface.currentFrame` is not `None`:
 
-   - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called.
+   - Do as if <code>@ref wgpuTextureDestroy</code><code>(surface.currentFrame)</code> was called.
    - Set `surface.currentFrame` to `None`.
 
 It can also be useful to remove the configuration of a @ref WGPUSurface without replacing it with a valid one.
 Without removing the configuration, the @ref WGPUSurface will keep referencing the @ref WGPUDevice that cannot be totally reclaimed.
 
-The behavior of `::wgpuSurfaceUnconfigure``()` is:
+The behavior of <code>@ref wgpuSurfaceUnconfigure</code><code>()</code> is:
 
  - Set `surface.config` to `None`.
  - If `surface.currentFrame` is not `None`:
 
-   - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called.
+   - Do as if <code>@ref wgpuTextureDestroy</code><code>(surface.currentFrame)</code> was called.
    - Set `surface.currentFrame` to `None`.
 
 ## Presenting to Surface {#Surface-Presenting}
 
-Each frame, the application retrieves the @ref WGPUTexture for the frame with `::wgpuSurfaceGetCurrentTexture`, renders to it and then presents it on the screen with `::wgpuSurfacePresent`.
+Each frame, the application retrieves the @ref WGPUTexture for the frame with @ref wgpuSurfaceGetCurrentTexture, renders to it and then presents it on the screen with @ref wgpuSurfacePresent.
 
 Issues can happen when trying to retrieve the frame's @ref WGPUTexture, so the application must check @ref WGPUSurfaceTexture `.status` to see if the surface or the device was lost, or some other windowing system issue caused a timeout.
 The environment can also change the surface without breaking it, but making the current configuration suboptimal. 
@@ -234,7 +234,7 @@ wgpuTextureRelease(surfaceTexture.texture);
 
 ```
 
-The behavior of `::wgpuSurfaceGetCurrentTexture``(surface, surfaceTexture)` is:
+The behavior of <code>@ref wgpuSurfaceGetCurrentTexture</code><code>(surface, surfaceTexture)</code> is:
 
 1. Set `surfaceTexture->texture` to `NULL`.
 1. If any of these validation steps fails, set `surfaceTexture->status` to `WGPUSurfaceGetCurrentTextureStatus_Error` and return (TODO send error to device?).
@@ -255,13 +255,13 @@ The behavior of `::wgpuSurfaceGetCurrentTexture``(surface, surfaceTexture)` is:
 1. Add a new reference to `t`.
 1. Set `surfaceTexture->texture` to a new reference to `t`.
 
-The behavior of `::wgpuSurfacePresent``(surface)` is:
+The behavior of <code>@ref wgpuSurfacePresent</code><code>(surface)</code> is:
 
  - If any of these validation steps fails, TODO send error to device?
 
    - Validate that `surface` is not an error.
    - Validate that `surface.currentFrame` is not `None`.
 
- - Do as if `::wgpuTextureDestroy``(surface.currentFrame)` was called.
+ - Do as if <code>@ref wgpuTextureDestroy</code><code>(surface.currentFrame)</code> was called.
  - Present `surface.currentFrame` to the `surface`.
  - Set `surface.currentFrame` to `None`.