Adapting to the API changes from wgpu v28 to trunk, I find that DepthStencilState now has optional fields:
/// If disabled, depth will not be written to. Must be `Some` if `format` is
/// a depth format.
pub depth_write_enabled: Option<bool>,
/// Comparison function used to compare depth values in the depth test.
/// Must be `Some` if `depth_write_enabled` is `true` or either stencil face
/// `depth_fail_op` is not `Keep`.
pub depth_compare: Option<CompareFunction>,
This documentation doesn’t tell me what it means when these fields are None, or when I should make them None. I suspect based on #8840 and conversation with @cwfitzgerald that this is “they may be None if their values would be irrelevant anyway”. If so, then this should be documented clearly, so that users can be confident their code is correct and efficiently migrate from v28.
We should also consider whether this optionality is good Rust API at all. In JavaScript, optionality of irrelevant values is a benefit: it lets the user write shorter code with fewer superfluous elements. In Rust, for a struct that does not implement Default, it adds clutter in many cases. If the Options need to be present for reasons of using wgpu as a WebGPU implementation, then we should consider whether wgpu should provide a different struct type for good Rust API.
Adapting to the API changes from wgpu v28 to trunk, I find that
DepthStencilStatenow has optional fields:This documentation doesn’t tell me what it means when these fields are
None, or when I should make themNone. I suspect based on #8840 and conversation with @cwfitzgerald that this is “they may beNoneif their values would be irrelevant anyway”. If so, then this should be documented clearly, so that users can be confident their code is correct and efficiently migrate from v28.We should also consider whether this optionality is good Rust API at all. In JavaScript, optionality of irrelevant values is a benefit: it lets the user write shorter code with fewer superfluous elements. In Rust, for a struct that does not implement
Default, it adds clutter in many cases. If theOptions need to be present for reasons of usingwgpuas a WebGPU implementation, then we should consider whetherwgpushould provide a different struct type for good Rust API.