Skip to content

New DepthStencilState optionality is not sufficiently documented #9178

@kpreid

Description

@kpreid

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: apiIssues related to API surface

    Type

    No type

    Projects

    Status

    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions