ConstructCraft

cc_render API

← API reference · Generated from the source by cargo run -p api_doc; edit the doc comments, not this page.

Offscreen wgpu renderer for the 3D view. The app builds a SceneMesh from the model geometry, uploads it with Renderer3D::upload and calls Renderer3D::render each frame; the resulting texture is shown as an egui image. Renderer3D::set_light lights it by a sun fixed in the world, with cast shadows.

Modules

Module Items Summary
cc_render 0 Offscreen wgpu renderer for the 3D view.
cc_render::camera 2  
cc_render::mesh 9  
cc_render::renderer 8  
cc_render::select 1 Window and crossing selection in a 3D view: which elements a screen rectangle takes, as the plans do with their linework.
cc_render::shadow 4 The sun’s GPU side: its pipelines and uniforms, made the first time a frame is lit by a sun, and its shadow map, made the first time it casts shadows (see sun.rs for the math).
cc_render::sun 10 A sun fixed in the world: the light it casts, the orthographic shadow map fitted to the scene and the ground that catches its shadows.
cc_render::textures 4 Material textures for the 3D view: each material’s image decoded once, resized to one square layer of a texture array (with its mipmaps), so the GPU memory they take is bounded (LAYER_SIZE, MAX_LAYERS).

cc_render

crates/cc_render/src/lib.rs

Re-exports

cc_render::camera

crates/cc_render/src/camera.rs

Items: view_proj · pick_ray

fn view_proj

pub fn view_proj(cam: &CameraState, aspect: f32) -> Mat4

Perspective view-projection matrix (Z up, wgpu depth range 0..1).

fn pick_ray

pub fn pick_ray(cam: &CameraState, aspect: f32, ndc_x: f32, ndc_y: f32) -> Ray

World-space ray through normalized device coordinates (x, y in -1..1, y up).

cc_render::mesh

crates/cc_render/src/mesh.rs

Re-exports

Items: Vertex · SceneMesh · Span · Shown · Highlight · MAX_HIDDEN_RUNS · hidden_runs · Tessellation · SolidStyle

struct Vertex

pub struct Vertex

Traits: Debug, Clone, Copy, Pod, Zeroable

Fields

Methods

struct SceneMesh

pub struct SceneMesh

GPU-ready triangles and edge lines.

Traits: Debug, Clone, Default

Fields

Methods

struct Span

pub struct Span

The ranges of one solid part (see Tessellation) in a SceneMesh’s buffers. A mesh’s spans follow one another: each range starts where the previous span’s ended.

Traits: Debug, Clone, PartialEq, Eq

Fields

Some fields are private.

struct Shown

pub struct Shown

The ranges of a base mesh’s buffers to draw (the others are covered by a Highlight): index ranges of its opaque and transparent triangles and vertex ranges of its edges. Ranges may run past the buffers’ ends.

Traits: Debug, Clone, Default, PartialEq, Eq

Fields

struct Highlight

pub struct Highlight

The selection drawn over a base mesh built without it: the selected solids’ faces (opaque, untextured, in the selection color) and edges, or the selected analytical members or bars, plus the parts of the base mesh to keep (None: all of it).

Traits: Debug, Clone, Default

Fields

const MAX_HIDDEN_RUNS

pub const MAX_HIDDEN_RUNS: usize

The most runs of selected spans SceneMesh::highlight takes: each run splits the base mesh’s draws in two, so a selection scattered wider than this is better built into the base mesh (see hidden_runs).

fn hidden_runs

pub fn hidden_runs(spans: &[Span], selected: &BTreeSet<ElementId>) -> usize

How many runs of consecutive spans of selected elements spans holds: the draws SceneMesh::highlight would add to each of the base mesh’s buffers.

struct Tessellation

pub struct Tessellation

The triangles and outline edges of a model’s solids, without colors: the costly part of a SceneMesh, kept while the geometry stays, so a new selection or view graphics only repaint it.

Traits: Debug, Clone, Default

Some fields are private.

Methods

struct SolidStyle

pub struct SolidStyle

View graphics of an element’s solids in 3D; None keeps the material’s.

Traits: Debug, Clone, Copy, Default, PartialEq

Fields

cc_render::renderer

crates/cc_render/src/renderer.rs

Items: DEPTH_FORMAT · FACE_BIAS · Uniforms · shading · unlit_shadow · PipelineSpec · frame_pipeline · Renderer3D

const DEPTH_FORMAT

pub(crate) const DEPTH_FORMAT: wgpu::TextureFormat

const FACE_BIAS

pub(crate) const FACE_BIAS: wgpu::DepthBiasState

Pushes faces slightly back so coplanar edges win the depth test.

struct Uniforms

pub(crate) struct Uniforms

Traits: Clone, Copy, Pod, Zeroable

Fields

fn shading

pub(crate) fn shading(shading: &cc_core::ShadingSettings) -> [f32; 4]

The greys of shading, as Uniforms::shading holds them.

fn unlit_shadow

pub(crate) fn unlit_shadow(shading: &cc_core::ShadingSettings) -> f32

What the unlit styles keep of a color in a cast shadow under shading (Uniforms::style’s z).

struct PipelineSpec

pub(crate) struct PipelineSpec<'a>

What sets a pipeline drawing into the frame’s targets apart.

Fields

fn frame_pipeline

pub(crate) fn frame_pipeline(device: &wgpu::Device, layout: &wgpu::PipelineLayout, shader: &wgpu::ShaderModule, spec: PipelineSpec) -> wgpu::RenderPipeline

A pipeline drawing into the frame’s multisampled color and depth targets.

struct Renderer3D

pub struct Renderer3D

Draws a SceneMesh into an offscreen, multisampled texture, with an optional Highlight (the selection) over it, lit from the camera or by a sun fixed in the world (see Renderer3D::set_light).

Some fields are private.

Methods

cc_render::select

crates/cc_render/src/select.rs

Window and crossing selection in a 3D view: which elements a screen rectangle takes, as the plans do with their linework. A window takes the elements whose solids lie wholly inside it (and in front of the camera); a crossing also takes those that any face of reaches into it. Hidden faces count too, as in plans.

Items: elements_in_rect

fn elements_in_rect

pub fn elements_in_rect(solids: &[Solid], cam: &CameraState, aspect: f32, lo: DVec2, hi: DVec2, window: bool, shown: &mut dyn FnMut(ElementId) -> bool) -> Vec<ElementId>

Elements of solids (those shown accepts) taken by the rectangle from lo to hi in normalized device coordinates (-1..1, y up): wholly inside it when window, or reaching into it otherwise.

cc_render::shadow

crates/cc_render/src/shadow.rs

The sun’s GPU side: its pipelines and uniforms, made the first time a frame is lit by a sun, and its shadow map, made the first time it casts shadows (see sun.rs for the math).

Items: SUN_SHADER · Casters · SunPass · caught

const SUN_SHADER

pub(crate) const SUN_SHADER: &str

The sun’s shader module: the renderer’s with the sun’s entry points.

struct Casters

pub(crate) struct Casters<'a>

The opaque triangles that cast shadows.

Fields

struct SunPass

pub(crate) struct SunPass

Fields

Some fields are private.

Methods

fn caught

pub(crate) fn caught<T>(device: &wgpu::Device, make: impl FnOnce() -> T) -> Option<T>

Run make catching the device errors it causes (wgpu aborts on those left uncaught): None if there were any. Native devices report them at once; a report still pending counts as none.

cc_render::sun

crates/cc_render/src/sun.rs

A sun fixed in the world: the light it casts, the orthographic shadow map fitted to the scene and the ground that catches its shadows. Pure math; the renderer draws them (see shadow.rs).

Items: Light · replace · SHADOW_MAP_SIZE · Bounds · ShadowFit · fit · ground_quad · SunUniforms · SunSetup · setup

struct Light

pub struct Light

A sun fixed in the world.

Traits: Clone, Copy, Debug, PartialEq

Fields

Methods

fn replace

pub(crate) fn replace(current: &mut Option<Light>, light: Option<Light>) -> bool

Sets current to the usable form of light; returns whether it changed (what has been drawn with the old one is then out of date).

const SHADOW_MAP_SIZE

pub(crate) const SHADOW_MAP_SIZE: u32

Side of the square shadow map, texels.

struct Bounds

pub(crate) struct Bounds

An axis-aligned box.

Traits: Clone, Copy, Debug, PartialEq

Fields

Methods

struct ShadowFit

pub(crate) struct ShadowFit

The light’s view of a scene: world to its clip space, where x and y run -1 to 1 across the shadow map and depth 0 (nearest the sun) to 1.

Traits: Clone, Copy, Debug, PartialEq

Fields

fn fit

pub(crate) fn fit(bounds: &Bounds, d: Vec3, ground: Option<&[Vec3; 4]>, map: u32) -> Option<ShadowFit>

The orthographic view from a sun towards unit d (above the horizon or not) that holds every point of bounds (the casters, which set the depth range) and, across the map, the ground corners (receivers behind or in front of every caster are compared at the range’s ends, where they are lit). It depends on the scene and the sun only, so shadows stay put while the camera moves. None for input that is not a number.

fn ground_quad

pub(crate) fn ground_quad(bounds: &Bounds, d: Vec3, z: f32) -> Option<[Vec3; 4]>

The ground at height z that catches the shadows of bounds from a sun towards unit d (above the horizon): a level rectangle along the shadows from the scene to the tip of the longest one, cut at the length a sun MIN_GROUND_ALTITUDE_DEG up casts. Its corners, counter-clockwise seen from above, are those of the scene slid along the sun’s rays onto the ground, so the light sees them within the scene: they fall inside its shadow map. None when nothing stands above the ground, the sun is (almost) level or the input is not a number.

struct SunUniforms

pub(crate) struct SunUniforms

The sun’s uniforms (Sun in sun.wgsl).

Traits: Clone, Copy, Debug, PartialEq, Pod, Zeroable

Fields

struct SunSetup

pub(crate) struct SunSetup

What a frame lit by a sun draws.

Traits: Clone, Copy, Debug, PartialEq

Fields

fn setup

pub(crate) fn setup(light: Light, bounds: Option<Bounds>, map: u32) -> SunSetup

The sun’s setup for light (usable) over a scene within bounds: no diffuse light, shadows or ground below the horizon; shadows only when asked for and the scene has bounds.

cc_render::textures

crates/cc_render/src/textures.rs

Material textures for the 3D view: each material’s image decoded once, resized to one square layer of a texture array (with its mipmaps), so the GPU memory they take is bounded (LAYER_SIZE, MAX_LAYERS). A material whose image cannot be decoded, or past the last layer, shows its appearance color instead.

Items: LAYER_SIZE · MAX_LAYERS · TextureSet · mip_count

const LAYER_SIZE

pub const LAYER_SIZE: u32

Side of a layer, pixels.

const MAX_LAYERS

pub const MAX_LAYERS: usize

Most textures a view holds at once.

struct TextureSet

pub struct TextureSet

The textures of a project’s materials, ready to upload.

Traits: Debug, Clone, Default

Some fields are private.

Methods

fn mip_count

pub(crate) fn mip_count() -> u32

Mip levels of a layer: LAYER_SIZE down to 1 pixel.