viewport-lib-types 0.4.0

Pure-data types for viewport-lib: submission payloads, handles, and frame config, free of any GPU dependency.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
//! Error types for the viewport library.

/// Errors that can occur during mesh upload and manipulation.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ViewportError {
    /// Mesh data has empty positions or indices.
    #[error("empty mesh: {positions} positions, {indices} indices")]
    EmptyMesh {
        /// Number of positions provided.
        positions: usize,
        /// Number of indices provided.
        indices: usize,
    },

    /// Positions and normals arrays have different lengths.
    #[error("mesh length mismatch: {positions} positions vs {normals} normals")]
    MeshLengthMismatch {
        /// Number of positions provided.
        positions: usize,
        /// Number of normals provided.
        normals: usize,
    },

    /// A mesh's vertex or index buffer would exceed the device's maximum
    /// buffer size. Creating it anyway raises a validation error that takes
    /// the whole device down, so the upload is refused instead.
    #[error("mesh needs a {bytes} byte buffer but the device maximum is {max}")]
    MeshTooLarge {
        /// Size of the largest buffer the mesh needs.
        bytes: u64,
        /// The device's `max_buffer_size` limit.
        max: u64,
    },

    /// A position/normal override buffer was bound to a mesh whose vertex
    /// count differs from the buffer's. The shader indexes the override per
    /// mesh vertex, so a smaller buffer reads out of bounds and a different
    /// count silently scrambles the geometry.
    #[error(
        "override buffer has {override_vertices} vertices but mesh {mesh_id} has {mesh_vertices}"
    )]
    OverrideBufferVertexCountMismatch {
        /// Index of the mesh the override was bound to.
        mesh_id: usize,
        /// Vertex count of the mesh.
        mesh_vertices: usize,
        /// Vertex count the override buffer holds.
        override_vertices: usize,
    },

    /// A buffer handed to the renderer was created without a usage flag the
    /// binding requires (for example `STORAGE` for an external instance
    /// positions buffer, or `COPY_SRC` for an external marching-cubes scalar
    /// source).
    #[error("external buffer is missing the {missing} usage flag")]
    ExternalBufferUsageMissing {
        /// Name of the missing `wgpu::BufferUsages` flag.
        missing: &'static str,
    },

    /// An external marching-cubes scalar source does not cover the volume:
    /// the offset is not 4-byte aligned, or the buffer holds fewer bytes past
    /// the offset than the volume's `nx * ny * nz` `f32` nodes need.
    #[error(
        "external scalar source needs {needed_bytes} bytes but the buffer has {available_bytes} past offset {offset_bytes}"
    )]
    McScalarSourceMismatch {
        /// Bytes the volume's scalar field occupies (`nx * ny * nz * 4`).
        needed_bytes: u64,
        /// Bytes available in the buffer from `offset_bytes` to its end.
        available_bytes: u64,
        /// The requested byte offset into the buffer.
        offset_bytes: u64,
    },

    /// An external deform-slot source does not cover the slot: the offset is
    /// not 4-byte aligned, or the buffer holds fewer bytes past the offset than
    /// the requested window needs.
    #[error(
        "external deform source needs {needed_bytes} bytes but the buffer has {available_bytes} past offset {offset_bytes}"
    )]
    DeformSourceMismatch {
        /// Bytes the requested slot window occupies.
        needed_bytes: u64,
        /// Bytes available in the buffer from `offset_bytes` to its end.
        available_bytes: u64,
        /// The requested byte offset into the buffer.
        offset_bytes: u64,
    },

    /// A ranged write does not fit a [`ContentBuffer`]: either the window runs
    /// past the allocation, or the byte length is not a whole number of
    /// elements at the buffer's stride.
    ///
    /// The buffer does not grow to accommodate a write. Growing behind a call
    /// the caller believes is cheap is the cost this whole family of APIs
    /// exists to remove, so `reserve` is an explicit step.
    ///
    /// [`ContentBuffer`]: https://docs.rs/viewport-lib
    #[error(
        "content buffer write [{first_element}..{first_element}+{element_count}) at stride {stride_bytes} does not fit {capacity} elements"
    )]
    ContentBufferWriteOutOfRange {
        /// First element of the requested window.
        first_element: u32,
        /// Elements the supplied bytes cover, or `0` when the byte length is
        /// not a whole multiple of the stride.
        element_count: u32,
        /// Elements the current allocation holds.
        capacity: u32,
        /// Bytes per element.
        stride_bytes: u32,
    },

    /// A ranged deform-slot write does not fit the data attached to that slot:
    /// `first_element + element_count` exceeds what the slot holds.
    #[error(
        "deform slot {slot} write [{first_element}..{first_element}+{element_count}) exceeds the slot's {slot_elements} elements"
    )]
    DeformSlotWriteOutOfRange {
        /// The slot the write targeted.
        slot: usize,
        /// First element of the requested window.
        first_element: u32,
        /// Number of elements in the requested window.
        element_count: u32,
        /// How many elements the slot's attached data holds.
        slot_elements: u32,
    },

    /// A ranged deform-slot write named a slot with no CPU data attached.
    /// Attach the slot first with `attach_deform_slot`, which establishes its
    /// length and stride; a ranged write only updates what is already there.
    #[error("deform slot {slot} on mesh {mesh_id} has no attached data to write into")]
    DeformSlotNotAttached {
        /// The mesh the write targeted.
        mesh_id: usize,
        /// The slot the write targeted.
        slot: usize,
    },

    /// A volume sub-region write does not fit inside the volume it addresses:
    /// `origin + dims` exceeds the texture's own dimensions on at least one
    /// axis, or `dims` has a zero extent.
    ///
    /// The texture does not grow to accommodate a region write. Resizing a 3D
    /// texture means reallocating it, which is what
    /// `replace_volume` is for.
    #[error("volume region at {origin:?} sized {dims:?} does not fit a {volume_dims:?} volume")]
    VolumeRegionOutOfRange {
        /// First texel of the requested box.
        origin: [u32; 3],
        /// Size of the requested box.
        dims: [u32; 3],
        /// Dimensions of the volume being written.
        volume_dims: [u32; 3],
    },

    /// A ranged channel write named a channel the stored object does not hold.
    ///
    /// Which channels an object has is fixed when it is uploaded: a point cloud
    /// uploaded with one flat colour has no per-point colour buffer, and a
    /// binding cannot appear later without reallocating and rebuilding the bind
    /// group, which is exactly the cost a ranged write exists to avoid. Upload
    /// the channel populated, even with placeholder values, and then write it.
    #[error("the object has no {channel} channel to write into")]
    ChannelNotPresent {
        /// Item type name the write was addressed to.
        type_name: &'static str,
        /// Channel named by the write.
        channel: &'static str,
    },

    /// A ranged write to a channel whose colourmap or size domain is derived
    /// from the values rather than supplied.
    ///
    /// The domain spans the whole array, so a write that touches part of it
    /// cannot know the new extremes without rescanning everything, which is the
    /// cost being avoided. Supply the domain (`ColourSource::Scalar { range:
    /// Some(..) }`, `SizeSource::Scalar { domain: Some(..) }`) and the write is
    /// well defined; leave it derived and replace the object whole.
    #[error("channel {channel} has a derived domain, so a ranged write cannot maintain it")]
    ChannelDomainNotFixed {
        /// Item type name the write was addressed to.
        type_name: &'static str,
        /// Channel named by the write.
        channel: &'static str,
    },

    /// A sliced override binding does not fit inside the supplied buffer:
    /// `base_element + element_count` vec3 elements (12 bytes each) exceed
    /// the buffer's size.
    #[error(
        "override slice [{base_element}..{base_element}+{element_count}) exceeds the buffer's {buffer_elements} vec3 elements"
    )]
    OverrideSliceOutOfRange {
        /// First vec3 element of the requested window.
        base_element: u32,
        /// Number of vec3 elements in the requested window.
        element_count: u32,
        /// How many whole vec3 elements the buffer holds.
        buffer_elements: u64,
    },

    /// A handle does not resolve to a live resource: its slot was freed, reused
    /// at a newer generation, or its index is out of range for the store.
    #[error("handle {index} does not resolve to a live resource (store holds {count})")]
    StaleHandle {
        /// The slot index the handle points at.
        index: usize,
        /// The number of live entries currently in the store.
        count: usize,
    },

    /// An index buffer entry references a vertex that does not exist.
    #[error("invalid vertex index {vertex_index} (vertex count: {vertex_count})")]
    InvalidVertexIndex {
        /// The offending index value.
        vertex_index: u32,
        /// Total number of vertices.
        vertex_count: usize,
    },

    /// The per-triangle material list handed to
    /// `MeshData::sort_triangles_into_submeshes` does not have one entry per
    /// triangle of the index buffer.
    #[error("triangle material list has {material_ids} entries for {triangles} triangles")]
    SubmeshTriangleCountMismatch {
        /// Number of triangles in the mesh (`indices.len() / 3`).
        triangles: usize,
        /// Number of material ids provided.
        material_ids: usize,
    },

    /// A submesh range extends past the end of the mesh's index buffer.
    #[error(
        "submesh range {first_index}..{} exceeds index count {index_count}",
        *first_index as u64 + *range_count as u64
    )]
    SubmeshRangeOutOfBounds {
        /// First index of the offending range.
        first_index: u32,
        /// Number of indices in the offending range.
        range_count: u32,
        /// Total number of indices in the mesh.
        index_count: usize,
    },

    /// Volume scalar data length does not match the declared grid dimensions.
    #[error("volume data length {actual} does not match dims {dims:?} (expected {expected})")]
    VolumeDataLengthMismatch {
        /// Number of scalar values provided.
        actual: usize,
        /// Expected length, equal to `dims[0] * dims[1] * dims[2]`.
        expected: usize,
        /// Grid dimensions `[nx, ny, nz]`.
        dims: [u32; 3],
    },

    /// Texture RGBA data has an unexpected size.
    #[error("invalid texture data: expected {expected} bytes, got {actual}")]
    InvalidTextureData {
        /// Expected byte count (width * height * 4).
        expected: usize,
        /// Actual byte count provided.
        actual: usize,
    },

    /// A texture was bound into a slot that needs the other colour space.
    ///
    /// The space travels on the [`TextureData`](crate::data::texture::TextureData)
    /// the texture was uploaded with, and each slot documents the space it needs.
    /// Uploading a data map through the colour path renders a plausible but wrong
    /// image (a neutral 128 in a normal map decodes to 0.216 instead of 0), so it
    /// is reported here rather than drawn. Rebuild the payload with the named
    /// constructor; if the bytes really are meant to be read as given, say so with
    /// the matching constructor rather than working around this.
    #[error(
        "{slot} was given a texture uploaded as {found}; build it with {constructor} (texture {texture})"
    )]
    TextureColourSpaceMismatch {
        /// The slot field, as a consumer writes it.
        slot: &'static str,
        /// The space the texture was uploaded in.
        found: &'static str,
        /// The `TextureData` constructor that produces what the slot needs.
        constructor: &'static str,
        /// Raw id of the offending texture.
        texture: u64,
    },

    /// A [`TextureData`](crate::data::texture::TextureData) carries a colour
    /// space that cannot be right for its contents: an sRGB normal map, sRGB
    /// float pixels, or a data-only compressed format labelled sRGB. Usually a
    /// [`with_colour_space`](crate::data::texture::TextureData::with_colour_space)
    /// relabel that went the wrong way.
    #[error("invalid texture colour space: {reason}")]
    InvalidTextureColourSpace {
        /// What is wrong with the label.
        reason: &'static str,
    },

    /// An upload was given a well-formed
    /// [`TextureData`](crate::data::texture::TextureData) that its slot cannot
    /// take: the wrong colour space or size, a payload kind the slot does not
    /// sample, or a normal map where none is used. Match on `reason` to fix it,
    /// for example by relabelling the colour space and retrying.
    #[error("{slot} cannot take this texture: {reason}")]
    UnsupportedTextureData {
        /// The kind of upload that rejected it.
        slot: crate::data::texture::UploadSlot,
        /// Why.
        reason: crate::data::texture::TextureRejection,
    },

    /// `upload_environment` was called while every environment slot was in
    /// use. Free one with `free_environment` before uploading another.
    #[error("too many environments: the set holds at most {max}")]
    TooManyEnvironments {
        /// How many environments the set holds.
        max: u32,
    },

    /// `upload_material` was called with every material block in use. The
    /// limit is what one storage-buffer binding of the device holds; free
    /// materials with `free_material` before uploading more.
    #[error("too many materials: the table holds at most {max}")]
    TooManyMaterials {
        /// How many material blocks the table holds.
        max: usize,
    },

    /// A material's plugin parameters or textures do not match what its plugin
    /// declares: an unknown parameter name, a value of the wrong kind, more
    /// values than fit, a texture past the plugin's `texture_count`, or
    /// parameters on a material whose plugin is not registered.
    #[error("invalid material plugin values: {reason}")]
    InvalidMaterialParams {
        /// What did not match.
        reason: String,
    },

    /// A material plugin declares more textures than the device can bind in
    /// the fragment stage alongside the renderer's own.
    #[error(
        "material plugin '{name}' declares {requested} textures; the device has room for {available}"
    )]
    MaterialPluginTextureBudget {
        /// The plugin's name.
        name: String,
        /// The plugin's `texture_count`.
        requested: u32,
        /// Textures left in the device's fragment-stage budget.
        available: u32,
    },

    /// A compressed-texture upload requested a format the device cannot sample,
    /// or a format that is not block-compressed.
    ///
    /// The device check reads the format's required wgpu feature (for example
    /// `TEXTURE_COMPRESSION_BC`, `_ASTC`, or `_ETC2`). When this is returned for
    /// a hardware reason, the caller should fall back to `upload_texture` /
    /// `upload_normal_map` or ship a variant the device supports.
    #[error(
        "unsupported texture format {format}: device lacks its required feature, or the format is not block-compressed"
    )]
    UnsupportedTextureFormat {
        /// The rejected format, as its wgpu debug name. Carried as a plain string
        /// so this error type stays free of any `wgpu` type.
        format: String,
    },

    /// A compressed-texture upload had base dimensions that are not a multiple
    /// of the format's block size. Block-compressed textures must be created
    /// with block-aligned dimensions; pad the image (and adjust UVs) or upload
    /// it uncompressed.
    #[error(
        "compressed texture {width}x{height} is not block-aligned (block {block_width}x{block_height})"
    )]
    CompressedTextureNotBlockAligned {
        /// Base (mip 0) width in texels.
        width: u32,
        /// Base (mip 0) height in texels.
        height: u32,
        /// Format block width.
        block_width: u32,
        /// Format block height.
        block_height: u32,
    },

    /// A mip level of a compressed-texture upload had the wrong byte length for
    /// its block-packed dimensions.
    #[error(
        "invalid compressed texture data at mip {level}: expected {expected} bytes, got {actual}"
    )]
    InvalidCompressedTextureData {
        /// The mip level whose data was the wrong size (0 is the base level).
        level: u32,
        /// Expected block-packed byte count for this level.
        expected: usize,
        /// Actual byte count provided for this level.
        actual: usize,
    },

    /// Attempted to access or replace a slot that is empty (its resource was
    /// previously freed).
    #[error("slot {index} is empty")]
    SlotEmpty {
        /// The slot index that was accessed.
        index: usize,
    },

    /// Named scalar attribute not found on the given mesh.
    #[error("attribute '{name}' not found on mesh {mesh_id}")]
    AttributeNotFound {
        /// The mesh index that was accessed.
        mesh_id: usize,
        /// The attribute name that was requested.
        name: String,
    },

    /// Attribute data length does not match the existing buffer.
    ///
    /// `replace_attribute` requires the same vertex count as the original upload.
    #[error("attribute length mismatch: expected {expected} f32 elements, got {got}")]
    AttributeLengthMismatch {
        /// Expected number of f32 elements (original attribute length).
        expected: usize,
        /// Actual number of f32 elements provided.
        got: usize,
    },

    /// A buffer required for GPU marching cubes upload exceeds the device's
    /// `max_buffer_size` limit. The caller should fall back to CPU marching cubes.
    #[error("GPU MC buffer '{buffer}' needs {needed} bytes but device limit is {limit}")]
    McBufferTooLarge {
        /// Short name identifying which buffer exceeded the limit (e.g. `"vertex_buf"`).
        buffer: &'static str,
        /// Bytes required for the allocation.
        needed: u64,
        /// The device's `max_buffer_size` limit.
        limit: u64,
    },

    /// Gaussian splat data is malformed or empty.
    #[error("invalid gaussian splat data: {reason}")]
    InvalidGaussianSplatData {
        /// Short description of what is wrong.
        reason: &'static str,
    },

    /// A background upload worker panicked or dropped its channel before
    /// sending a result.
    #[error("upload worker did not complete: {reason}")]
    JobWorkerLost {
        /// Short description of how the worker was lost.
        reason: &'static str,
    },

    /// `upload_result_*` was called before the corresponding job reached the
    /// `Ready` state. Poll `upload_status` and retry on the next frame.
    #[error("upload job is not yet ready to take its result")]
    JobNotReady,

    /// `upload_result_*` was called with a `JobId` that does not belong to
    /// the matching upload type, has already been taken, or was never
    /// issued.
    #[error("upload job has no result available: {reason}")]
    JobResultMissing {
        /// Short description of why the result is unavailable.
        reason: &'static str,
    },

    /// No deformer slots remain. The registry has a fixed number of slots;
    /// once all are taken, release one with `remove_deformer` before
    /// registering another.
    #[error("deformer registry exhausted: {max} slots in use")]
    DeformSlotsExhausted {
        /// Total number of slots the registry exposes.
        max: usize,
    },

    /// The deformer is one the renderer registers for itself (skinning) and
    /// cannot be removed.
    #[error("deformer '{name}' is built in and cannot be removed")]
    DeformerReserved {
        /// The built-in deformer's name.
        name: String,
    },

    /// A deformer with this name is already registered.
    #[error("deformer name '{name}' already registered")]
    DeformNameTaken {
        /// The duplicate name that was rejected.
        name: String,
    },

    /// The composed mesh-family shader failed validation, either because the
    /// supplied `wgsl_body` is malformed or because composition produced an
    /// invalid module. The reason carries the underlying validator message
    /// and identifies which shader failed.
    #[error("deformer shader invalid: {reason}")]
    DeformShaderInvalid {
        /// Validator message prefixed by the shader name that failed.
        reason: String,
    },

    /// A shading hook with this name is already registered (or the name
    /// collides with a registered deformer; both splice `<name>__`-prefixed
    /// declarations into the same modules).
    #[error("shading hook name '{name}' already registered")]
    ShadeNameTaken {
        /// The duplicate name that was rejected.
        name: String,
    },

    /// The composed lit shader failed validation, either because the supplied
    /// `wgsl_body` is malformed, defines none of the three hook functions, or
    /// because composition produced an invalid module. The reason carries the
    /// underlying validator message and identifies which shader failed.
    #[error("shading hook shader invalid: {reason}")]
    ShadeShaderInvalid {
        /// Validator message prefixed by the shader name that failed.
        reason: String,
    },

    /// An overlay fill function could not be registered: its name is not a
    /// fresh WGSL identifier, its body defines no `fill` function, or the
    /// overlay shaders it composes into fail validation. The reason names
    /// which.
    #[error("overlay fill invalid: {reason}")]
    OverlayFillInvalid {
        /// What was wrong, with the validator message where there is one.
        reason: String,
    },

    /// A plugin's `install` needed a piece the install context did not carry,
    /// most often a `ViewportRuntime` on a host that does not use one. The
    /// message names what was missing.
    #[error("plugin install requires {needed}, but the install context did not provide it")]
    PluginInstallMissing {
        /// Name of the missing piece, e.g. "a ViewportRuntime".
        needed: &'static str,
    },

    /// A feature's `uninstall` cannot take out what it installed. Returned in
    /// place of `Ok(())` so a removal that did nothing does not read as one
    /// that worked.
    #[error("{feature} cannot be uninstalled")]
    PluginUninstallUnsupported {
        /// Name of the feature.
        feature: &'static str,
    },

    /// Content was uploaded for, or freed from, an item type whose plugin is
    /// not registered with the renderer. The item type that owns a store is
    /// the only thing that can hold its content, so the call had nowhere to
    /// go. The message names the type.
    #[error("no item type plugin registered under {type_name}")]
    ItemTypePluginMissing {
        /// Registered name of the item type that owns the content.
        type_name: &'static str,
    },

    /// A LOD group was registered with no levels.
    #[error("LOD group has no levels")]
    LodGroupEmpty,

    /// The mesh list and threshold list passed to `register_lod_group` differ
    /// in length. Each level needs exactly one threshold.
    #[error("LOD level count mismatch: {meshes} meshes vs {thresholds} thresholds")]
    LodLevelCountMismatch {
        /// Number of meshes provided.
        meshes: usize,
        /// Number of thresholds provided.
        thresholds: usize,
    },

    /// LOD thresholds must strictly decrease from the full level to the crudest,
    /// since each level applies to a smaller on-screen size than the one before.
    #[error(
        "LOD thresholds must strictly decrease (level {level} is not smaller than the previous)"
    )]
    LodThresholdsNotDescending {
        /// The level whose threshold is not smaller than its predecessor's.
        level: usize,
    },

    /// A level's mesh is not compatible with the other levels in the group: a
    /// switch to it would change rendering. Today this means its named
    /// attribute set or its deformer attachment differs from level 0.
    #[error("LOD level {level} is incompatible with level 0: {reason}")]
    LodLevelIncompatible {
        /// The level that does not match level 0.
        level: usize,
        /// What differs (a missing attribute name, or a deform mismatch).
        reason: String,
    },

    /// The device is below the floor the renderer can be built on.
    ///
    /// Returned by `ViewportRenderer::try_with_config`; `with_config` panics
    /// with the same message.
    #[error("the renderer cannot run on this device: {reason}")]
    DeviceUnsupported {
        /// What the device lacks.
        reason: String,
    },

    /// `RendererConfig::scene_depth_format` named a format the scene passes
    /// cannot use. They need a depth aspect and a stencil aspect:
    /// `Depth24PlusStencil8` or `Depth32FloatStencil8`.
    #[error(
        "scene depth format {format} is not supported: use Depth24PlusStencil8 or Depth32FloatStencil8"
    )]
    InvalidSceneDepthFormat {
        /// The rejected format, as its wgpu debug name.
        format: String,
    },

    /// The GPU device was lost (a driver reset, a watchdog kill, out of memory,
    /// or `device.destroy()`). The renderer stays lost: drop it and build a new
    /// one on a new device. Every handle it returned is invalid.
    #[error("the GPU device was lost ({reason}): {message}")]
    DeviceLost {
        /// Why the device was lost, as the backend's `DeviceLostReason`.
        reason: String,
        /// The backend's message, possibly empty.
        message: String,
    },

    /// A plugin needs more than the device offers, so it was not registered.
    #[error("plugin '{type_name}' was not registered: the device lacks {}", .missing.join(", "))]
    PluginUnsupported {
        /// The plugin's name.
        type_name: String,
        /// One entry per capability the device lacks.
        missing: Vec<String>,
    },

    /// An item type is already registered under this name. Remove it first to
    /// register a different plugin under the same name.
    #[error("item type name '{name}' is already registered")]
    ItemTypeNameTaken {
        /// The name that is taken.
        name: String,
    },

    /// The call needs a higher tier than the renderer runs at: scene content on
    /// an overlay-only device.
    #[error("this needs the {needed} tier and the renderer runs at the {have} tier")]
    TierUnsupported {
        /// The tier the call needs.
        needed: crate::tier::Tier,
        /// The tier the renderer runs at.
        have: crate::tier::Tier,
    },

    /// A LOD group id does not refer to a registered group.
    #[error("LOD group {index} is not registered")]
    LodGroupNotFound {
        /// The group index that was looked up.
        index: usize,
    },
}

/// Convenience alias for `Result<T, ViewportError>`.
pub type ViewportResult<T> = Result<T, ViewportError>;