nordic-dev.net/wgpu
nordic-dev.net/wgpu
2
0
Fork 0
mirror of https://github.com/gfx-rs/wgpu.git synced 2024-11-21 22:33:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Convert some module doc comments

Browse Source 
Some module doc comments were using `/*! ... */` syntax and had
leading ` *` prefixes on each line. This interferes with the
tracking of `clippy::doc_lazy_continuation`, so switch those over
to `//!` style comment blocks.

This leaves `/*! ... */` blocks alone which didn't prefix each
line.
This commit is contained in:
Bruce Mitchener 2024-07-20 10:06:41 +07:00 committed by Erich Gubler
parent ea81a24414
commit 4f02057359
8 changed files with 246 additions and 253 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
player/src/bin/play.rs
View File

@ -1,5 +1,4 @@
/*! This is a player for WebGPU traces. //! This is a player for WebGPU traces.
!*/
#[cfg(not(target_arch = "wasm32"))] #[cfg(not(target_arch = "wasm32"))]
fn main() { fn main() {

5
player/src/lib.rs
View File

@ -1,6 +1,5 @@
/*! This is a player library for WebGPU traces. //! This is a player library for WebGPU traces.
*
!*/
#![cfg(not(target_arch = "wasm32"))] #![cfg(not(target_arch = "wasm32"))]
#![warn(unsafe_op_in_unsafe_fn)] #![warn(unsafe_op_in_unsafe_fn)]

20
player/tests/test.rs
View File

@ -1,13 +1,13 @@
/*! Tester for WebGPU //! Tester for WebGPU
* It enumerates the available backends on the system, //! It enumerates the available backends on the system,
* and run the tests through them. //! and run the tests through them.
* //!
* Test requirements: //! Test requirements:
* - all IDs have the backend `Empty` //! - all IDs have the backend `Empty`
* - all expected buffers have `MAP_READ` usage //! - all expected buffers have `MAP_READ` usage
* - last action is `Submit` //! - last action is `Submit`
* - no swapchain use //! - no swapchain use
!*/
#![cfg(not(target_arch = "wasm32"))] #![cfg(not(target_arch = "wasm32"))]
use player::GlobalPlay; use player::GlobalPlay;

11
wgpu-core/src/track/buffer.rs
View File

@ -1,9 +1,8 @@
/*! Buffer Trackers //! Buffer Trackers
* //!
* Buffers are represented by a single state for the whole resource, //! Buffers are represented by a single state for the whole resource,
* a 16 bit bitflag of buffer usages. Because there is only ever //! a 16 bit bitflag of buffer usages. Because there is only ever
* one subresource, they have no selector. //! one subresource, they have no selector.
!*/
use std::sync::{Arc, Weak}; use std::sync::{Arc, Weak};

9
wgpu-core/src/track/stateless.rs
View File

@ -1,8 +1,7 @@
/*! Stateless Trackers //! Stateless Trackers
* //!
* Stateless trackers don't have any state, so make no //! Stateless trackers don't have any state, so make no
* distinction between a usage scope and a full tracker. //! distinction between a usage scope and a full tracker.
!*/
use std::sync::Arc; use std::sync::Arc;

39
wgpu-core/src/track/texture.rs
View File

@ -1,23 +1,22 @@
/*! Texture Trackers //! Texture Trackers
* //!
* Texture trackers are significantly more complicated than //! Texture trackers are significantly more complicated than
* the buffer trackers because textures can be in a "complex" //! the buffer trackers because textures can be in a "complex"
* state where each individual subresource can potentially be //! state where each individual subresource can potentially be
* in a different state from every other subtresource. These //! in a different state from every other subtresource. These
* complex states are stored separately from the simple states //! complex states are stored separately from the simple states
* because they are signifignatly more difficult to track and //! because they are signifignatly more difficult to track and
* most resources spend the vast majority of their lives in //! most resources spend the vast majority of their lives in
* simple states. //! simple states.
* //!
* There are two special texture usages: `UNKNOWN` and `UNINITIALIZED`. //! There are two special texture usages: `UNKNOWN` and `UNINITIALIZED`.
* - `UNKNOWN` is only used in complex states and is used to signify //! - `UNKNOWN` is only used in complex states and is used to signify
* that the complex state does not know anything about those subresources. //! that the complex state does not know anything about those subresources.
* It cannot leak into transitions, it is invalid to transition into UNKNOWN //! It cannot leak into transitions, it is invalid to transition into UNKNOWN
* state. //! state.
* - `UNINITIALIZED` is used in both simple and complex states to mean the texture //! - `UNINITIALIZED` is used in both simple and complex states to mean the texture
* is known to be in some undefined state. Any transition away from UNINITIALIZED //! is known to be in some undefined state. Any transition away from UNINITIALIZED
* will treat the contents as junk. //! will treat the contents as junk.
!*/
use super::{range::RangedStates, PendingTransition, PendingTransitionList, TrackerIndex}; use super::{range::RangedStates, PendingTransition, PendingTransitionList, TrackerIndex};
use crate::{ use crate::{

407
wgpu-hal/src/lib.rs
View File

@ -1,207 +1,206 @@
/*! A cross-platform unsafe graphics abstraction. //! A cross-platform unsafe graphics abstraction.
* //!
* This crate defines a set of traits abstracting over modern graphics APIs, //! This crate defines a set of traits abstracting over modern graphics APIs,
* with implementations ("backends") for Vulkan, Metal, Direct3D, and GL. //! with implementations ("backends") for Vulkan, Metal, Direct3D, and GL.
* //!
* `wgpu-hal` is a spiritual successor to //! `wgpu-hal` is a spiritual successor to
* [gfx-hal](https://github.com/gfx-rs/gfx), but with reduced scope, and //! [gfx-hal](https://github.com/gfx-rs/gfx), but with reduced scope, and
* oriented towards WebGPU implementation goals. It has no overhead for //! oriented towards WebGPU implementation goals. It has no overhead for
* validation or tracking, and the API translation overhead is kept to the bare //! validation or tracking, and the API translation overhead is kept to the bare
* minimum by the design of WebGPU. This API can be used for resource-demanding //! minimum by the design of WebGPU. This API can be used for resource-demanding
* applications and engines. //! applications and engines.
* //!
* The `wgpu-hal` crate's main design choices: //! The `wgpu-hal` crate's main design choices:
* //!
* - Our traits are meant to be *portable*: proper use //! - Our traits are meant to be *portable*: proper use
* should get equivalent results regardless of the backend. //! should get equivalent results regardless of the backend.
* //!
* - Our traits' contracts are *unsafe*: implementations perform minimal //! - Our traits' contracts are *unsafe*: implementations perform minimal
* validation, if any, and incorrect use will often cause undefined behavior. //! validation, if any, and incorrect use will often cause undefined behavior.
* This allows us to minimize the overhead we impose over the underlying //! This allows us to minimize the overhead we impose over the underlying
* graphics system. If you need safety, the [`wgpu-core`] crate provides a //! graphics system. If you need safety, the [`wgpu-core`] crate provides a
* safe API for driving `wgpu-hal`, implementing all necessary validation, //! safe API for driving `wgpu-hal`, implementing all necessary validation,
* resource state tracking, and so on. (Note that `wgpu-core` is designed for //! resource state tracking, and so on. (Note that `wgpu-core` is designed for
* use via FFI; the [`wgpu`] crate provides more idiomatic Rust bindings for //! use via FFI; the [`wgpu`] crate provides more idiomatic Rust bindings for
* `wgpu-core`.) Or, you can do your own validation. //! `wgpu-core`.) Or, you can do your own validation.
* //!
* - In the same vein, returned errors *only cover cases the user can't //! - In the same vein, returned errors *only cover cases the user can't
* anticipate*, like running out of memory or losing the device. Any errors //! anticipate*, like running out of memory or losing the device. Any errors
* that the user could reasonably anticipate are their responsibility to //! that the user could reasonably anticipate are their responsibility to
* avoid. For example, `wgpu-hal` returns no error for mapping a buffer that's //! avoid. For example, `wgpu-hal` returns no error for mapping a buffer that's
* not mappable: as the buffer creator, the user should already know if they //! not mappable: as the buffer creator, the user should already know if they
* can map it. //! can map it.
* //!
* - We use *static dispatch*. The traits are not //! - We use *static dispatch*. The traits are not
* generally object-safe. You must select a specific backend type //! generally object-safe. You must select a specific backend type
* like [`vulkan::Api`] or [`metal::Api`], and then use that //! like [`vulkan::Api`] or [`metal::Api`], and then use that
* according to the main traits, or call backend-specific methods. //! according to the main traits, or call backend-specific methods.
* //!
* - We use *idiomatic Rust parameter passing*, //! - We use *idiomatic Rust parameter passing*,
* taking objects by reference, returning them by value, and so on, //! taking objects by reference, returning them by value, and so on,
* unlike `wgpu-core`, which refers to objects by ID. //! unlike `wgpu-core`, which refers to objects by ID.
* //!
* - We map buffer contents *persistently*. This means that the buffer can //! - We map buffer contents *persistently*. This means that the buffer can
* remain mapped on the CPU while the GPU reads or writes to it. You must //! remain mapped on the CPU while the GPU reads or writes to it. You must
* explicitly indicate when data might need to be transferred between CPU and //! explicitly indicate when data might need to be transferred between CPU and
* GPU, if [`Device::map_buffer`] indicates that this is necessary. //! GPU, if [`Device::map_buffer`] indicates that this is necessary.
* //!
* - You must record *explicit barriers* between different usages of a //! - You must record *explicit barriers* between different usages of a
* resource. For example, if a buffer is written to by a compute //! resource. For example, if a buffer is written to by a compute
* shader, and then used as and index buffer to a draw call, you //! shader, and then used as and index buffer to a draw call, you
* must use [`CommandEncoder::transition_buffers`] between those two //! must use [`CommandEncoder::transition_buffers`] between those two
* operations. //! operations.
* //!
* - Pipeline layouts are *explicitly specified* when setting bind //! - Pipeline layouts are *explicitly specified* when setting bind
* group. Incompatible layouts disturb groups bound at higher indices. //! group. Incompatible layouts disturb groups bound at higher indices.
* //!
* - The API *accepts collections as iterators*, to avoid forcing the user to //! - The API *accepts collections as iterators*, to avoid forcing the user to
* store data in particular containers. The implementation doesn't guarantee //! store data in particular containers. The implementation doesn't guarantee
* that any of the iterators are drained, unless stated otherwise by the //! that any of the iterators are drained, unless stated otherwise by the
* function documentation. For this reason, we recommend that iterators don't //! function documentation. For this reason, we recommend that iterators don't
* do any mutating work. //! do any mutating work.
* //!
* Unfortunately, `wgpu-hal`'s safety requirements are not fully documented. //! Unfortunately, `wgpu-hal`'s safety requirements are not fully documented.
* Ideally, all trait methods would have doc comments setting out the //! Ideally, all trait methods would have doc comments setting out the
* requirements users must meet to ensure correct and portable behavior. If you //! requirements users must meet to ensure correct and portable behavior. If you
* are aware of a specific requirement that a backend imposes that is not //! are aware of a specific requirement that a backend imposes that is not
* ensured by the traits' documented rules, please file an issue. Or, if you are //! ensured by the traits' documented rules, please file an issue. Or, if you are
* a capable technical writer, please file a pull request! //! a capable technical writer, please file a pull request!
* //!
* [`wgpu-core`]: https://crates.io/crates/wgpu-core //! [`wgpu-core`]: https://crates.io/crates/wgpu-core
* [`wgpu`]: https://crates.io/crates/wgpu //! [`wgpu`]: https://crates.io/crates/wgpu
* [`vulkan::Api`]: vulkan/struct.Api.html //! [`vulkan::Api`]: vulkan/struct.Api.html
* [`metal::Api`]: metal/struct.Api.html //! [`metal::Api`]: metal/struct.Api.html
* //!
* ## Primary backends //! ## Primary backends
* //!
* The `wgpu-hal` crate has full-featured backends implemented on the following //! The `wgpu-hal` crate has full-featured backends implemented on the following
* platform graphics APIs: //! platform graphics APIs:
* //!
* - Vulkan, available on Linux, Android, and Windows, using the [`ash`] crate's //! - Vulkan, available on Linux, Android, and Windows, using the [`ash`] crate's
* Vulkan bindings. It's also available on macOS, if you install [MoltenVK]. //! Vulkan bindings. It's also available on macOS, if you install [MoltenVK].
* //!
* - Metal on macOS, using the [`metal`] crate's bindings. //! - Metal on macOS, using the [`metal`] crate's bindings.
* //!
* - Direct3D 12 on Windows, using the [`d3d12`] crate's bindings. //! - Direct3D 12 on Windows, using the [`d3d12`] crate's bindings.
* //!
* [`ash`]: https://crates.io/crates/ash //! [`ash`]: https://crates.io/crates/ash
* [MoltenVK]: https://github.com/KhronosGroup/MoltenVK //! [MoltenVK]: https://github.com/KhronosGroup/MoltenVK
* [`metal`]: https://crates.io/crates/metal //! [`metal`]: https://crates.io/crates/metal
* [`d3d12`]: ahttps://crates.io/crates/d3d12 //! [`d3d12`]: ahttps://crates.io/crates/d3d12
* //!
* ## Secondary backends //! ## Secondary backends
* //!
* The `wgpu-hal` crate has a partial implementation based on the following //! The `wgpu-hal` crate has a partial implementation based on the following
* platform graphics API: //! platform graphics API:
* //!
* - The GL backend is available anywhere OpenGL, OpenGL ES, or WebGL are //! - The GL backend is available anywhere OpenGL, OpenGL ES, or WebGL are
* available. See the [`gles`] module documentation for details. //! available. See the [`gles`] module documentation for details.
* //!
* [`gles`]: gles/index.html //! [`gles`]: gles/index.html
* //!
* You can see what capabilities an adapter is missing by checking the //! You can see what capabilities an adapter is missing by checking the
* [`DownlevelCapabilities`][tdc] in [`ExposedAdapter::capabilities`], available //! [`DownlevelCapabilities`][tdc] in [`ExposedAdapter::capabilities`], available
* from [`Instance::enumerate_adapters`]. //! from [`Instance::enumerate_adapters`].
* //!
* The API is generally designed to fit the primary backends better than the //! The API is generally designed to fit the primary backends better than the
* secondary backends, so the latter may impose more overhead. //! secondary backends, so the latter may impose more overhead.
* //!
* [tdc]: wgt::DownlevelCapabilities //! [tdc]: wgt::DownlevelCapabilities
* //!
* ## Traits //! ## Traits
* //!
* The `wgpu-hal` crate defines a handful of traits that together //! The `wgpu-hal` crate defines a handful of traits that together
* represent a cross-platform abstraction for modern GPU APIs. //! represent a cross-platform abstraction for modern GPU APIs.
* //!
* - The [`Api`] trait represents a `wgpu-hal` backend. It has no methods of its //! - The [`Api`] trait represents a `wgpu-hal` backend. It has no methods of its
* own, only a collection of associated types. //! own, only a collection of associated types.
* //!
* - [`Api::Instance`] implements the [`Instance`] trait. [`Instance::init`] //! - [`Api::Instance`] implements the [`Instance`] trait. [`Instance::init`]
* creates an instance value, which you can use to enumerate the adapters //! creates an instance value, which you can use to enumerate the adapters
* available on the system. For example, [`vulkan::Api::Instance::init`][Ii] //! available on the system. For example, [`vulkan::Api::Instance::init`][Ii]
* returns an instance that can enumerate the Vulkan physical devices on your //! returns an instance that can enumerate the Vulkan physical devices on your
* system. //! system.
* //!
* - [`Api::Adapter`] implements the [`Adapter`] trait, representing a //! - [`Api::Adapter`] implements the [`Adapter`] trait, representing a
* particular device from a particular backend. For example, a Vulkan instance //! particular device from a particular backend. For example, a Vulkan instance
* might have a Lavapipe software adapter and a GPU-based adapter. //! might have a Lavapipe software adapter and a GPU-based adapter.
* //!
* - [`Api::Device`] implements the [`Device`] trait, representing an active //! - [`Api::Device`] implements the [`Device`] trait, representing an active
* link to a device. You get a device value by calling [`Adapter::open`], and //! link to a device. You get a device value by calling [`Adapter::open`], and
* then use it to create buffers, textures, shader modules, and so on. //! then use it to create buffers, textures, shader modules, and so on.
* //!
* - [`Api::Queue`] implements the [`Queue`] trait, which you use to submit //! - [`Api::Queue`] implements the [`Queue`] trait, which you use to submit
* command buffers to a given device. //! command buffers to a given device.
* //!
* - [`Api::CommandEncoder`] implements the [`CommandEncoder`] trait, which you //! - [`Api::CommandEncoder`] implements the [`CommandEncoder`] trait, which you
* use to build buffers of commands to submit to a queue. This has all the //! use to build buffers of commands to submit to a queue. This has all the
* methods for drawing and running compute shaders, which is presumably what //! methods for drawing and running compute shaders, which is presumably what
* you're here for. //! you're here for.
* //!
* - [`Api::Surface`] implements the [`Surface`] trait, which represents a //! - [`Api::Surface`] implements the [`Surface`] trait, which represents a
* swapchain for presenting images on the screen, via interaction with the //! swapchain for presenting images on the screen, via interaction with the
* system's window manager. //! system's window manager.
* //!
* The [`Api`] trait has various other associated types like [`Api::Buffer`] and //! The [`Api`] trait has various other associated types like [`Api::Buffer`] and
* [`Api::Texture`] that represent resources the rest of the interface can //! [`Api::Texture`] that represent resources the rest of the interface can
* operate on, but these generally do not have their own traits. //! operate on, but these generally do not have their own traits.
* //!
* [Ii]: Instance::init //! [Ii]: Instance::init
* //!
* ## Validation is the calling code's responsibility, not `wgpu-hal`'s //! ## Validation is the calling code's responsibility, not `wgpu-hal`'s
* //!
* As much as possible, `wgpu-hal` traits place the burden of validation, //! As much as possible, `wgpu-hal` traits place the burden of validation,
* resource tracking, and state tracking on the caller, not on the trait //! resource tracking, and state tracking on the caller, not on the trait
* implementations themselves. Anything which can reasonably be handled in //! implementations themselves. Anything which can reasonably be handled in
* backend-independent code should be. A `wgpu_hal` backend's sole obligation is //! backend-independent code should be. A `wgpu_hal` backend's sole obligation is
* to provide portable behavior, and report conditions that the calling code //! to provide portable behavior, and report conditions that the calling code
* can't reasonably anticipate, like device loss or running out of memory. //! can't reasonably anticipate, like device loss or running out of memory.
* //!
* The `wgpu` crate collection is intended for use in security-sensitive //! The `wgpu` crate collection is intended for use in security-sensitive
* applications, like web browsers, where the API is available to untrusted //! applications, like web browsers, where the API is available to untrusted
* code. This means that `wgpu-core`'s validation is not simply a service to //! code. This means that `wgpu-core`'s validation is not simply a service to
* developers, to be provided opportunistically when the performance costs are //! developers, to be provided opportunistically when the performance costs are
* acceptable and the necessary data is ready at hand. Rather, `wgpu-core`'s //! acceptable and the necessary data is ready at hand. Rather, `wgpu-core`'s
* validation must be exhaustive, to ensure that even malicious content cannot //! validation must be exhaustive, to ensure that even malicious content cannot
* provoke and exploit undefined behavior in the platform's graphics API. //! provoke and exploit undefined behavior in the platform's graphics API.
* //!
* Because graphics APIs' requirements are complex, the only practical way for //! Because graphics APIs' requirements are complex, the only practical way for
* `wgpu` to provide exhaustive validation is to comprehensively track the //! `wgpu` to provide exhaustive validation is to comprehensively track the
* lifetime and state of all the resources in the system. Implementing this //! lifetime and state of all the resources in the system. Implementing this
* separately for each backend is infeasible; effort would be better spent //! separately for each backend is infeasible; effort would be better spent
* making the cross-platform validation in `wgpu-core` legible and trustworthy. //! making the cross-platform validation in `wgpu-core` legible and trustworthy.
* Fortunately, the requirements are largely similar across the various //! Fortunately, the requirements are largely similar across the various
* platforms, so cross-platform validation is practical. //! platforms, so cross-platform validation is practical.
* //!
* Some backends have specific requirements that aren't practical to foist off //! Some backends have specific requirements that aren't practical to foist off
* on the `wgpu-hal` user. For example, properly managing macOS Objective-C or //! on the `wgpu-hal` user. For example, properly managing macOS Objective-C or
* Microsoft COM reference counts is best handled by using appropriate pointer //! Microsoft COM reference counts is best handled by using appropriate pointer
* types within the backend. //! types within the backend.
* //!
* A desire for "defense in depth" may suggest performing additional validation //! A desire for "defense in depth" may suggest performing additional validation
* in `wgpu-hal` when the opportunity arises, but this must be done with //! in `wgpu-hal` when the opportunity arises, but this must be done with
* caution. Even experienced contributors infer the expectations their changes //! caution. Even experienced contributors infer the expectations their changes
* must meet by considering not just requirements made explicit in types, tests, //! must meet by considering not just requirements made explicit in types, tests,
* assertions, and comments, but also those implicit in the surrounding code. //! assertions, and comments, but also those implicit in the surrounding code.
* When one sees validation or state-tracking code in `wgpu-hal`, it is tempting //! When one sees validation or state-tracking code in `wgpu-hal`, it is tempting
* to conclude, "Oh, `wgpu-hal` checks for this, so `wgpu-core` needn't worry //! to conclude, "Oh, `wgpu-hal` checks for this, so `wgpu-core` needn't worry
* about it - that would be redundant!" The responsibility for exhaustive //! about it - that would be redundant!" The responsibility for exhaustive
* validation always rests with `wgpu-core`, regardless of what may or may not //! validation always rests with `wgpu-core`, regardless of what may or may not
* be checked in `wgpu-hal`. //! be checked in `wgpu-hal`.
* //!
* To this end, any "defense in depth" validation that does appear in `wgpu-hal` //! To this end, any "defense in depth" validation that does appear in `wgpu-hal`
* for requirements that `wgpu-core` should have enforced should report failure //! for requirements that `wgpu-core` should have enforced should report failure
* via the `unreachable!` macro, because problems detected at this stage always //! via the `unreachable!` macro, because problems detected at this stage always
* indicate a bug in `wgpu-core`. //! indicate a bug in `wgpu-core`.
* //!
* ## Debugging //! ## Debugging
* //!
* Most of the information on the wiki [Debugging wgpu Applications][wiki-debug] //! Most of the information on the wiki [Debugging wgpu Applications][wiki-debug]
* page still applies to this API, with the exception of API tracing/replay //! page still applies to this API, with the exception of API tracing/replay
* functionality, which is only available in `wgpu-core`. //! functionality, which is only available in `wgpu-core`.
* //!
* [wiki-debug]: https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications //! [wiki-debug]: https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications
*/
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
#![allow( #![allow(

5
wgpu-types/src/lib.rs
View File

@ -1,6 +1,5 @@
/*! This library describes the API surface of WebGPU that is agnostic of the backend. //! This library describes the API surface of WebGPU that is agnostic of the backend.
* This API is used for targeting both Web and Native. //! This API is used for targeting both Web and Native.
*/
#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
#![allow( #![allow(