{"record":{"id":"d24ee45dfe28bb90","repo":"gfx-rs/wgpu","slug":"the-plane-must-be-specified-for-multi-planar-forma","errorCode":null,"errorMessage":"the plane must be specified for multi-planar formats","messagePattern":"the plane must be specified for multi-planar formats","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wgpu-types/src/texture/format.rs","lineNumber":548,"sourceCode":"    /// Returns the number of planes a multi-planar format has.\n    #[must_use]\n    pub fn planes(&self) -> Option<u32> {\n        match *self {\n            Self::NV12 => Some(2),\n            Self::P010 => Some(2),\n            _ => None,\n        }\n    }\n\n    /// Returns the subsampling factor for the indicated plane of a multi-planar format.\n    #[must_use]\n    pub fn subsampling_factors(&self, plane: Option<u32>) -> (u32, u32) {\n        match *self {\n            Self::NV12 | Self::P010 => match plane {\n                Some(0) => (1, 1),\n                Some(1) => (2, 2),\n                Some(plane) => unreachable!(\"plane {plane} is not valid for {self:?}\"),\n                None => unreachable!(\"the plane must be specified for multi-planar formats\"),\n            },\n            _ => (1, 1),\n        }\n    }\n\n    /// Returns a [TextureChannel] with the bits set where the texture format contains\n    /// the respective channels.\n    ///\n    /// # Example\n    /// ```rust\n    /// # use wgpu_types::{TextureFormat, TextureChannel};\n    ///\n    /// // `Rgba` has a `red`, `green`, `blue` and `alpha` channel!\n    /// assert!(TextureFormat::Rgba8Unorm.channels().contains(TextureChannel::RGBA));\n    ///\n    /// // `Rg` hasn't got an alpha channel...\n    /// assert!(!TextureFormat::Rg8Unorm.channels().contains(TextureChannel::ALPHA));\n    /// // ... but it has a red channel ...","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu-types/src/texture/format.rs#L530-L566","documentation":"`TextureFormat::subsampling_factors` requires an explicit plane index (`Some(n)`) for multi-planar formats like NV12 and P010, since subsampling differs per plane. Calling it with `None` on such a format panics because the question is unanswerable without knowing which plane.","triggerScenarios":"Calling `format.subsampling_factors(None)` where format is NV12 or P010 — e.g. generic code that always passes None because it was written for single-planar formats (rgba8unorm etc.).","commonSituations":"Shared texture-size/copy helpers written before multi-planar formats existed; passing through an Option from caller code that doesn't know the format is multi-planar; porting code from APIs where plane defaults to 0.","solutions":["Pass `Some(0)` or `Some(1)` explicitly when the format is NV12/P010","Branch on `format.is_multi_planar()` (or match the format) before choosing None vs Some","Fix the helper to accept a plane parameter and require it for multi-planar formats"],"exampleFix":"// before\nlet (fx, fy) = nv12_format.subsampling_factors(None); // panics\n// after\nlet (fx, fy) = nv12_format.subsampling_factors(Some(0)); // luma plane","handlingStrategy":"validation","validationCode":"fn subsampling(format: wgpu::TextureFormat, plane: u32) -> (u32, u32) {\n    if format.plane_count() > 1 { format.subsampling_factors(Some(plane)) }\n    else { format.subsampling_factors(None) }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass Some(plane) whenever the format is multi-planar; pass None only for single-planar formats","Write generic texture helpers to take the format and resolve plane handling internally","Unit-test helpers against NV12/P010 as well as RGBA formats"],"tags":["wgpu-types","texture-format","plane-index","panic","video"],"backgroundTag":"missing-required-plane","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}