viewport_lib/
lib.rs

1#![warn(missing_docs)]
2//! `viewport-lib` : a 3D viewport library for `wgpu` applications.
3//!
4//! Built on `wgpu` and `glam`, with no required UI toolkit. The crate provides
5//! the renderer, camera, picking, and interaction pieces; host applications keep
6//! control of their own windowing and event loop.
7//!
8//! # Quick start (single viewport)
9//!
10//! 1. Create a [`ViewportRenderer`] from a `wgpu::Device` and target format.
11//! 2. Upload meshes or volumes through [`ViewportGpuResources`].
12//! 3. Build a [`FrameData`] each frame (camera via [`CameraFrame`] and
13//!    [`RenderCamera`], scene content via [`SceneFrame`], viewport chrome via
14//!    [`ViewportFrame`], etc.).
15//! 4. Call [`ViewportRenderer::prepare`] and then [`ViewportRenderer::paint_to`].
16//!
17//! # Multi-viewport rendering
18//!
19//! To render the same scene from multiple independent cameras (e.g. a CAD
20//! quad-view layout), use the split prepare/paint API:
21//!
22//! ```rust,ignore
23//! // --- Setup (once at startup) ---
24//! let vp_persp = renderer.create_viewport(&device);   // ViewportId(0)
25//! let vp_top   = renderer.create_viewport(&device);   // ViewportId(1)
26//! let vp_front = renderer.create_viewport(&device);   // ViewportId(2)
27//!
28//! // --- Each frame ---
29//! // 1. Build per-viewport FrameData (shared scene, independent cameras).
30//! let frame_persp = FrameData {
31//!     camera: CameraFrame::from_camera(&cam_persp, vp_size).with_viewport_index(vp_persp.0),
32//!     scene: shared_scene.clone(),
33//!     ..FrameData::default()
34//! };
35//! // ... similarly for vp_top, vp_front ...
36//!
37//! // 2. Prepare scene data once (lighting, shadows, batching).
38//! let (scene_fx, _) = frame_persp.effects.split();
39//! renderer.prepare_scene(&device, &queue, &frame_persp, &scene_fx);
40//!
41//! // 3. Prepare per-viewport state (camera uniforms, clip planes, overlays).
42//! renderer.prepare_viewport(&device, &queue, vp_persp, &frame_persp);
43//! renderer.prepare_viewport(&device, &queue, vp_top,   &frame_top);
44//! renderer.prepare_viewport(&device, &queue, vp_front, &frame_front);
45//!
46//! // 4a. LDR path : single render pass with viewport/scissor rects.
47//! let mut rp = encoder.begin_render_pass(...);
48//! rp.set_viewport(0.0, 0.0, half_w, half_h, 0.0, 1.0);
49//! renderer.paint_viewport(&mut rp, vp_persp, &frame_persp);
50//! rp.set_viewport(half_w, 0.0, half_w, half_h, 0.0, 1.0);
51//! renderer.paint_viewport(&mut rp, vp_top, &frame_top);
52//! // ...
53//!
54//! // 4b. HDR path : one command buffer per viewport, each into its own texture.
55//! let cmd0 = renderer.render_viewport(&device, &queue, &view0, vp_persp, &frame_persp);
56//! let cmd1 = renderer.render_viewport(&device, &queue, &view1, vp_top,   &frame_top);
57//! queue.submit([cmd0, cmd1]);
58//! ```
59//!
60//! Single-viewport applications require zero code changes:
61//! [`prepare`](ViewportRenderer::prepare), [`paint_to`](ViewportRenderer::paint_to), and
62//! [`render`](ViewportRenderer::render) continue to work as before.
63
64/// Error types for the viewport library.
65pub mod error;
66
67/// Arcball camera, frustum, view presets, and animator.
68pub mod camera;
69/// BVH picking, marching cubes, isolines, and cap geometry.
70pub mod geometry;
71/// Gizmo, snap, selection, picking, and input.
72pub mod interaction;
73/// On-surface vector quantities (intrinsic vectors, Whitney one-forms).
74pub mod quantities;
75/// Main viewport renderer wrapping all GPU resources.
76pub mod renderer;
77/// GPU resource container (pipelines, buffers, bind groups).
78pub mod resources;
79/// Scene graph, material, traits, and AABB.
80pub mod scene;
81/// Axes orientation indicator.
82pub mod widgets;
83
84// ---------------------------------------------------------------------------
85// Module re-exports : preserve old `viewport_lib::foo::Bar` paths.
86// ---------------------------------------------------------------------------
87
88pub use geometry::bvh;
89pub use geometry::primitives;
90pub use interaction::clip_plane;
91pub use interaction::gizmo;
92pub use interaction::input;
93pub use interaction::manipulation;
94pub use interaction::picking;
95pub use interaction::selection;
96pub use interaction::snap;
97pub use scene::aabb;
98pub use scene::material;
99pub use scene::traits;
100pub use widgets::axes_indicator;
101
102// ---------------------------------------------------------------------------
103// Flat re-exports : these form the public crate API.
104// ---------------------------------------------------------------------------
105
106pub use error::{ViewportError, ViewportResult};
107
108pub use camera::animator::{CameraAnimator, CameraDamping, Easing};
109pub use camera::camera::{Camera, CameraTarget, Projection};
110pub use camera::frustum::{CullStats, Frustum};
111pub use camera::view_preset::ViewPreset;
112
113pub use scene::aabb::Aabb;
114pub use scene::material::{BackfacePattern, BackfacePolicy, Material, ParamVis, ParamVisMode, PatternConfig};
115pub use scene::scene::{Group, GroupId, Layer, LayerId, Scene, SceneNode};
116pub use scene::traits::{RenderMode, ViewportObject};
117
118pub use geometry::bvh::PickAccelerator;
119pub use geometry::implicit::{ImplicitRenderOptions, march_implicit_surface, march_implicit_surface_color};
120pub use geometry::isoline::{IsolineItem, extract_isolines};
121pub use geometry::marching_cubes::{VolumeData, extract_isosurface};
122
123pub use interaction::gizmo::{
124    Gizmo, GizmoAxis, GizmoMode, GizmoSpace, PivotMode, gizmo_center_for_pivot,
125};
126pub use interaction::input::{
127    Action, ActionState, Binding, FrameInput, InputMode, InputSystem, KeyCode, Modifiers,
128    MouseButton, NavigationMode,
129};
130// New input pipeline : re-exported at crate root for convenience.
131pub use interaction::input::{
132    ActionFrame, BindingPreset, ButtonState, ModifiersMatch, NavigationActions,
133    OrbitCameraController, ResolvedActionState, ScrollUnits, ViewportBinding, ViewportContext,
134    ViewportEvent, ViewportGesture, ViewportInput, viewport_all_bindings,
135};
136pub use interaction::manipulation::solvers::{
137    angular_rotation_from_cursor, constrained_scale, constrained_translation,
138};
139pub use interaction::manipulation::{
140    GizmoInfo, ManipResult, ManipulationContext, ManipulationController, ManipulationKind,
141    ManipulationState, TransformDelta,
142};
143
144pub use interaction::clip_plane::{
145    ClipAxis, ClipPlaneContext, ClipPlaneController, ClipPlaneDelta, ClipPlaneHit, ClipPlaneResult,
146    ClipPlaneSessionKind, hit_test_normal_handle, hit_test_plane_quad, plane_from_axis_preset,
147    project_drag_onto_normal, ray_plane_intersection, snap_plane_distance,
148};
149pub use interaction::picking::{
150    GpuPickHit, PickHit, ProbeBinding, RectPickResult, pick_rect,
151    pick_scene_accelerated_with_probe_cpu, pick_scene_nodes_with_probe_cpu, pick_scene_with_probe_cpu,
152    pick_volume_cpu, voxel_world_aabb,
153};
154pub use interaction::selection::{NodeId, Selection};
155pub use interaction::snap::{ConstraintOverlay, SnapConfig};
156pub use interaction::sub_object;
157pub use interaction::sub_object::{SubObjectRef, SubSelection, SubSelectionRef, VolumeSelectionInfo};
158
159pub use widgets::axes_indicator::AxisView;
160
161pub use renderer::shader_hashes::ShaderValidation;
162pub use renderer::stats::{FrameStats, PerformancePolicy, RuntimeMode};
163pub use renderer::{
164    CameraFrame, CameraFrustumItem, ClipObject, ClipShape, ComputeFilterItem, ComputeFilterKind,
165    EffectsFrame, EnvironmentMap, FilterMode, FrameData, GlyphItem, GlyphType, GroundPlane,
166    GroundPlaneMode, ImageAnchor, InteractionFrame, LabelAnchor, LabelItem, LightKind, LightSource,
167    LightingSettings, LoadingBarAnchor, LoadingBarItem, OverlayFrame, OverlayImageItem, PickId,
168    PointCloudItem, PointRenderMode,
169    PolylineItem, PostProcessSettings, RenderCamera, RulerItem, ScalarBarAnchor, ScalarBarItem,
170    ScalarBarOrientation, SceneEffects,
171    SceneFrame, SceneRenderItem, ScreenImageItem,
172    ShadowFilter, StreamtubeItem, SurfaceSubmission, ToneMapping, ViewportEffects, ViewportFrame,
173    ViewportId, ViewportRenderer, VolumeItem,
174};
175
176pub use quantities::{
177    edge_one_form_to_glyphs, face_intrinsic_to_glyphs,
178    polyline_edge_vectors_to_glyphs, polyline_node_vectors_to_glyphs,
179    vertex_intrinsic_to_glyphs,
180    volume_mesh_cell_vectors_to_glyphs, volume_mesh_vertex_vectors_to_glyphs,
181};
182
183pub use resources::colormap_data::{
184    export_paraview_xml_colormap, lerp_colormap_lut, parse_paraview_xml_colormap,
185};
186pub use resources::mesh_store::MeshId;
187pub use resources::sparse_volume::SparseVolumeGridData;
188#[allow(deprecated)]
189pub use resources::volume_mesh::{CELL_SENTINEL, TET_SENTINEL, VolumeMeshData};
190pub use resources::{
191    AttributeData, AttributeKind, AttributeRef, BuiltinColormap, BuiltinMatcap, CameraUniform,
192    ClipVolumeUniform, ColormapId, ComputeFilterResult, FontError, FontHandle, GpuImplicitItem,
193    GpuImplicitOptions, GpuMarchingCubesJob, ImplicitBlendMode, ImplicitPrimitive, LightUniform,
194    LightsUniform, MatcapId, MeshData, SingleLightUniform, ViewportGpuResources, VolumeGpuId,
195    VolumeId, lerp_attributes,
196};
viewport_lib/lib.rs

viewport_lib/
lib.rs
