scena/diagnostics/
help.rs

1use super::{AssetError, LookupError, PrepareError, RenderError};
2
3impl AssetError {
4    pub fn help(&self) -> &'static str {
5        match self {
6            Self::NotFound { .. } => "check the asset path and the configured AssetFetcher",
7            Self::Io { .. } => "check filesystem or network access in the host application",
8            Self::Parse { .. } => "validate the asset with the source tool or glTF validator",
9            Self::UnsupportedRequiredExtension { .. } => {
10                "remove the required extension, export with a supported profile, or enable a decoder feature when one exists"
11            }
12            Self::UnsupportedOptionalExtensionUsed { .. } => {
13                "use extension_diagnostics to inspect the degradation policy before import"
14            }
15            Self::MissingTexture { .. } => {
16                "fix the glTF material slot texture index or export the referenced image"
17            }
18            Self::UnsupportedTextureFormat { .. } => {
19                "use a supported texture format such as PNG, JPEG, or WebP, or enable a decoder feature when one exists"
20            }
21            Self::Cancelled { .. } => {
22                "retry the load with a fresh AssetLoadControl when the host still needs the asset"
23            }
24            Self::UnsupportedEnvironmentFormat { .. } => {
25                "use an equirectangular .hdr environment or the bundled default environment"
26            }
27            Self::ReloadRequiresRetain { .. } => {
28                "set RetainPolicy::Always before loading assets that need hot reload"
29            }
30            Self::GeometryHandleNotFound { .. }
31            | Self::MaterialHandleNotFound { .. }
32            | Self::TextureHandleNotFound { .. }
33            | Self::EnvironmentHandleNotFound { .. } => {
34                "verify the handle came from the same Assets collection: \
35                 call assets.contains_<kind>(handle) on the store you queried; \
36                 compare assets.store_id() against the store that minted the \
37                 handle to distinguish 'wrong store' from 'stale handle freed \
38                 by Assets::release_unreferenced'"
39            }
40        }
41    }
42}
43
44impl PrepareError {
45    pub fn help(&self) -> &'static str {
46        match self {
47            Self::InvalidTargetSize { .. } => "construct Renderer with non-zero target dimensions",
48            Self::AssetsRequired { .. } => {
49                "call Renderer::prepare_with_assets when the scene contains asset handles"
50            }
51            Self::GeometryNotFound { .. }
52            | Self::MaterialNotFound { .. }
53            | Self::TextureNotFound { .. }
54            | Self::EnvironmentNotFound { .. } => {
55                "keep the Assets collection that created the handle alive and pass it to prepare"
56            }
57            Self::EnvironmentAssetsRequired { .. } => {
58                "call Renderer::prepare_with_assets when an environment handle is active"
59            }
60            Self::UnsupportedGeometryTopology { .. } => {
61                "convert the geometry to triangles or lines before prepare"
62            }
63            Self::UnsupportedMaterialKind { .. }
64            | Self::UnsupportedAlphaMode { .. }
65            | Self::UnsupportedModelNode { .. } => {
66                "choose a supported renderer path or import through Scene::instantiate"
67            }
68            Self::MultipleShadowedDirectionalLights { .. } => {
69                "keep one shadowed directional light enabled for v1.0"
70            }
71            Self::InvalidSkinGeometry { .. } => "verify joint and weight arrays match vertex count",
72            Self::BackendCapabilityMismatch { .. } => {
73                "query renderer.capabilities and choose a compatible quality/profile path"
74            }
75            Self::GpuResourceUpload { .. } => {
76                "call Renderer::prepare again after fixing the browser/GPU resource state; render must not hide upload failures"
77            }
78        }
79    }
80}
81
82impl RenderError {
83    pub fn help(&self) -> &'static str {
84        match self {
85            Self::NotPrepared { .. } => {
86                "call Renderer::prepare after scene, target, or renderer changes"
87            }
88            Self::NoActiveCamera => "call Scene::add_default_camera or Scene::set_active_camera",
89            Self::CameraNotFound(_) => "use a CameraKey created by this Scene",
90            Self::InvalidSurfaceSize { .. } => {
91                "ignore zero-sized host surface events until the surface is visible"
92            }
93            Self::SurfaceLost { .. } => "call recover_surface, then prepare again",
94            Self::ContextLost { .. } | Self::GpuDeviceLost { .. } => {
95                "call recover_context with retained assets, then prepare again"
96            }
97            Self::GpuResourcesNotPrepared { .. } => "call Renderer::prepare before rendering",
98            Self::GpuReadback { .. } => {
99                "retry after device polling or choose a supported readback path"
100            }
101        }
102    }
103}
104
105impl LookupError {
106    pub fn help(&self) -> &'static str {
107        match self {
108            Self::NodeNotFound(_) => "use a NodeKey created by this Scene",
109            Self::NodeNameNotFound { .. } => "call nodes_named to inspect available import names",
110            Self::AmbiguousNodeName { .. } => {
111                "call nodes_named or path_segments for explicit lookup"
112            }
113            Self::AnchorNotFound { .. } => {
114                "call anchors_named or anchor_debug_metadata to inspect anchors"
115            }
116            Self::AmbiguousAnchorName { .. } => {
117                "call anchors_named or anchors_for to choose a host node"
118            }
119            Self::ConnectorNotFound { .. } => {
120                "call connectors_named or diagnostic overlays to inspect connectors"
121            }
122            Self::AmbiguousConnectorName { .. } => {
123                "call connectors_named or resolve by host node before connecting"
124            }
125            Self::ClipNotFound { .. } => "call clips_named to inspect available animation clips",
126            Self::AmbiguousClipName { .. } => "call clips_named to choose a specific clip",
127            Self::VariantNotFound { .. } => {
128                "call SceneImport::material_variants to inspect declared KHR_materials_variants names"
129            }
130            Self::PathNotFound { .. } => {
131                "use SceneImport::path_segments when names contain slashes"
132            }
133            Self::InvalidViewport { .. } => "use non-zero physical viewport dimensions",
134            Self::ImportHasNoBounds => {
135                "frame a node, add renderable geometry, or choose a manual camera pose"
136            }
137            Self::StaleImport => {
138                "re-resolve nodes, anchors, and clips from the replacement SceneImport"
139            }
140            Self::NodeIsNotMesh { .. } => "check NodeKind before using mesh-only helpers",
141            Self::NonInvertibleParentTransform { .. } => {
142                "use a finite non-zero parent scale before applying world-space placement helpers"
143            }
144            Self::GeometryNotFound { .. } => {
145                "call asset-aware helpers with the same Assets store that created or loaded the geometry"
146            }
147            Self::CameraNotFound(_) => "use a CameraKey created by this Scene",
148            Self::ClippingPlaneNotFound(_) => "use a ClippingPlaneKey created by this Scene",
149            Self::InstanceSetNotFound(_) => "use an InstanceSetKey created by this Scene",
150            Self::LabelNotFound(_) => "use a LabelKey created by this Scene",
151        }
152    }
153}
scena/diagnostics/help.rs

scena/diagnostics/
help.rs
