Module plugin_api 

Plugin substrate: target descriptors, shared bind layouts, WGSL helpers, pipeline builders. See plugin_api for the published extension surface. Plugin substrate: target descriptors, shared bind layouts, WGSL helpers, and pipeline builders.

This module publishes the pieces a plugin needs to build pipelines that drop into the lib’s existing render passes. A plugin reuses:

• Target descriptors ([OpaqueTargetDesc], [OitTargetDesc], [MaskTargetDesc], [PickTargetDesc], [ShadowTargetDesc]) describe the render-target formats, blend states, and depth-stencil state each lib pass expects. Pipelines built against these are compatible with the corresponding pass.
• [SharedBindings] is the group-0 bind layout (camera, lights, shadows, clip, IBL) shared by every scene pipeline. Plugin pipeline layouts list it as group 0.
• [shared_wgsl] holds string constants with the standard bind declarations and shading helpers (viewport_pbr_shade, viewport_oit_pack, viewport_sample_csm, etc.) so plugin shaders stay in lockstep with the lib’s lighting and transparency contracts.
• Pipeline builders on crate::resources::DeviceResources (build_opaque_pipeline, build_oit_pipeline, …) construct the common variants in one call. Plugins ship one shader and call a builder per variant.

All accessors live on crate::resources::DeviceResources.

Compatibility policy

Pre-1.0, this surface evolves more freely than a stable crate would, but the policy below describes what plugins can rely on within a given minor version and how breakage is signalled.

Plugins are expected to track viewport-lib minor versions. The convention is that a minor bump may rename or remove items the audit flags as non-additive; a patch bump never does.

• Group-0 binding indices ([SharedBindings]) are additive-only. The constants in SharedBindings (CAMERA_BINDING, …) keep their numeric values forever. New bindings are appended at the next free index. This is the strongest guarantee in the API: a plugin pipeline built once stays valid as new bindings are added.

• WGSL helper strings in [shared_wgsl] are stable within a minor version. Helper function signatures (viewport_pbr_shade, viewport_oit_pack, viewport_sample_csm, …) and the struct layouts they declare may change with a minor bump. When a helper’s signature changes in an incompatible way, the helper is renamed (the old name is removed) so a plugin shader that referenced the old name fails to compile loudly rather than silently producing wrong output. Additive changes (new helpers, new optional fields appended to structs) ride patch bumps.

• Target descriptors and pipeline builder signatures are stable within a minor version. Format constants (HDR_COLOR_FORMAT, blend states, depth-stencil state) follow the same rule: any change rides a minor bump and is noted in the CHANGELOG.

• The deformer registry hook contract is additive-only. The DeformVertex and DeformContext struct shapes (see crate::resources::mesh_sidecar::registry::DeformerDesc) keep existing fields stable across releases; new fields may be appended. The composition-order policy (ObjectSpace before WorldSpace, priority ascending within stage) is part of the contract and will not change.

• Builder methods on crate::resources::DeviceResources that construct pipelines for plugins (build_opaque_pipeline, build_oit_pipeline, …) keep their behaviour stable within a minor version. Signature changes ride minor bumps and are listed in the CHANGELOG.

Anything not listed above is internal: a plugin that reaches past the published surface (private modules, undocumented constants) may break at any release.

Re-exports

pub use cull::BatchMeta;

pub use cull::CullSubmission;

pub use cull::InstanceAabb;

pub use cull::SingleMeshDraw;

pub use item_type::ItemFrameContext;

pub use item_type::ItemTypePlugin;

pub use item_type::OutlineMaskContext;

pub use item_type::PaintContext;

pub use item_type::PickRay;

pub use item_type::PluginItemCollection;

pub use item_type::ShadowCastContext;

pub use target_desc::MaskTargetDesc;

pub use target_desc::OIT_ACCUM_BLEND;

pub use target_desc::OIT_REVEAL_BLEND;

pub use target_desc::OitTargetDesc;

pub use target_desc::OpaqueTargetDesc;

pub use target_desc::PickTargetDesc;

pub use target_desc::ShadowTargetDesc;

Modules

cull

GPU-driven culling service published to plugins.

item_type

ItemTypePlugin trait and supporting types.

shared_wgsl

WGSL helper catalog.

target_desc

Render-target descriptors published for plugin pipeline construction.

Structs

SharedBindings

Group-0 bind layout shared by every scene pipeline.