tecs.gfx.meshes

Per-view 3D lighting, shadows, ambient probes and environments.

A View owns one lighting configuration. Directional rays, point lights and spotlights illuminate all mesh materials except unlit ones. Three texel-snapped directional cascades and a local-light shadow atlas retain their maps until the scene, camera or relevant settings change. Ambient cubes and environments are independent: one provides diffuse irradiance, the other roughness-dependent specular reflections and the sky.

const lighting = tecs.gfx.meshes.newLighting()
lighting.shadows = true
lighting.ssao = true
world:spawn(tecs.gfx.View({
    camera3D = tecs.gfx.newCamera3D({y = 2, z = 6}),
    lighting = lighting
}))

Module contents

Constructors

ConstructorDescription
newLightingCreates independently mutable lighting settings with the documented defaults.

Types

TypeKindDescription
LightingrecordLights meshes with a directional source, optional fog and an ambient cube.

Constructors#

newLightingconstructor#

function newLighting(): Lighting

Creates independently mutable lighting settings with the documented defaults.

Returns

TypeDescription
Lighting

caller-owned settings to attach to a View

Types#

Lightingrecord#

record Lighting
    directionX: number = -0.5
    directionY: number = -1
    directionZ: number = -0.5
    r: number = 1
    g: number = 1
    b: number = 1
    intensity: number = 1
    ambient: number = 0.15
    fog: boolean = false
    fogStart: number = 20
    fogFinish: number = 100
    fogR: number = 0
    fogG: number = 0
    fogB: number = 0
    probe: {number} = {}
    probeIntensity: number = 1
    shadows: boolean = false
    shadowScale: number = 1
    shadowDistance: number = 100
    shadowSplitLambda: number = 0.7
    shadowSplitBlend: number = 0.1
    shadowDepthPadding: number = 20
    shadowStrength: number = 1
    shadowBias: number = 0.0015
    shadowSoftness: number = 1
    ssao: boolean = false
    ssaoScale: number = 0.5
    ssaoRadius: number = 0.5
    ssaoBias: number = 0.025
    ssaoIntensity: number = 1
    ssaoPower: number = 1.5
    localShadows: boolean = false
    localShadowSize: integer = 256
    localShadowCapacity: integer = 4
    localShadowBias: number = 0.002
    localShadowSoftness: number = 1
    environment: string? = nil
    environmentIntensity: number = 1
    skyboxIntensity: number = 1
    environmentRotation: number = 0
end
@derive(nupp.derive.Debug, nupp.derive.Serde)

Lights meshes with a directional source, optional fog and an ambient cube. A View owns these settings. Changes take effect on its next rendered frame.

Fields

directionX#
directionX: number

Caller-writable. Sets the X direction in which light rays travel.

directionY#
directionY: number

Caller-writable. Sets the Y direction in which light rays travel.

directionZ#
directionZ: number

Caller-writable. Sets the Z direction in which light rays travel.

r#
r: number

Caller-writable. Sets non-negative directional red in linear space.

g#
g: number

Caller-writable. Sets non-negative directional green in linear space.

b#
b: number

Caller-writable. Sets non-negative directional blue in linear space.

intensity#
intensity: number

Caller-writable. Scales directional radiance.

ambient#
ambient: number

Caller-writable. Sets uniform ambient irradiance before the cube probe.

fog#
fog: boolean

Caller-writable. Enables linear camera-distance fog for meshes.

fogStart#
fogStart: number

Caller-writable. Sets the world distance where fog begins.

fogFinish#
fogFinish: number

Caller-writable. Sets the world distance where fog becomes opaque.

fogR#
fogR: number

Caller-writable. Sets linear fog red from zero through one.

fogG#
fogG: number

Caller-writable. Sets linear fog green from zero through one.

fogB#
fogB: number

Caller-writable. Sets linear fog blue from zero through one.

probe#
probe: {number}

Caller-writable. Supplies 18 non-negative irradiance values, RGB for positive X, negative X, positive Y, negative Y, positive Z, negative Z. An empty array disables the probe. The normal's squared axes blend faces.

probeIntensity#
probeIntensity: number

Caller-writable. Scales the six ambient-cube faces.

shadows#
shadows: boolean

Caller-writable. Enables three texel-snapped directional shadow cascades.

shadowScale#
shadowScale: number

Caller-writable. Sets shadow-map resolution relative to the larger viewport dimension.

shadowDistance#
shadowDistance: number

Caller-writable. Limits shadow coverage in world units beyond the camera near plane.

shadowSplitLambda#
shadowSplitLambda: number

Caller-writable. Blends uniform and logarithmic cascade spacing from zero through one.

shadowSplitBlend#
shadowSplitBlend: number

Caller-writable. Sets cascade cross-fade width from zero through one half.

shadowDepthPadding#
shadowDepthPadding: number

Caller-writable. Adds non-negative light-space depth for off-camera casters.

shadowStrength#
shadowStrength: number

Caller-writable. Scales shadow occlusion from zero through one.

shadowBias#
shadowBias: number

Caller-writable. Offsets receiver depth to suppress self-shadow acne.

shadowSoftness#
shadowSoftness: number

Caller-writable. Sets the 3 by 3 PCF radius in shadow texels; zero uses one location.

ssao#
ssao: boolean

Caller-writable. Enables mesh-only screen-space ambient occlusion.

ssaoScale#
ssaoScale: number

Caller-writable. Sets AO resolution relative to the viewport, up to one.

ssaoRadius#
ssaoRadius: number

Caller-writable. Sets the positive hemisphere radius in world units.

ssaoBias#
ssaoBias: number

Caller-writable. Offsets the occlusion comparison in world units.

ssaoIntensity#
ssaoIntensity: number

Caller-writable. Scales non-negative ambient occlusion strength.

ssaoPower#
ssaoPower: number

Caller-writable. Sets positive AO contrast before the edge-aware blur.

localShadows#
localShadows: boolean

Caller-writable. Enables shadows for lights carrying LIGHTCASTSSHADOWS.

localShadowSize#
localShadowSize: integer

Caller-writable. Sets each local shadow face edge in pixels.

localShadowCapacity#
localShadowCapacity: integer

Caller-writable. Limits shadow-casting lights in stable extraction order.

localShadowBias#
localShadowBias: number

Caller-writable. Offsets local shadow receiver depth.

localShadowSoftness#
localShadowSoftness: number

Caller-writable. Sets the local-shadow PCF radius in texels.

environment#
environment: string?

Caller-writable. Selects the stable name returned by models.loadEnvironment.

environmentIntensity#
environmentIntensity: number

Caller-writable. Scales non-negative specular environment radiance.

skyboxIntensity#
skyboxIntensity: number

Caller-writable. Scales the sky background; zero hides it while retaining reflections.

environmentRotation#
environmentRotation: number

Caller-writable. Rotates the environment around world Y in radians.