Package eu.svjatoslav.sixth.e3d.renderer.raster.gi

Class Lightmap

java.lang.Object
eu.svjatoslav.sixth.e3d.renderer.raster.gi.Lightmap
public class Lightmap extends Object
Per-triangle lightmap: a small generated texture whose texels map onto the triangle surface. The triangle's UVs (in texture pixel units) are (0,0), (width,0), (0,height), so the valid texel region is the half where u+v <= 1 in normalized coordinates; the other half is filled by mirroring to keep mipmaps and edge sampling clean.

What you trace is what you see: the composite texture the painter samples IS the lightmap, at native texel resolution. Shadow-edge smoothness comes from tracing at finer resolution (smaller unitsPerTexel), never from upsampling.

The GI system stores per-texel indirect irradiance and per-texel per-light visibility here, and periodically regenerates the premultiplied composite texture (baseColor x lighting) into the back buffer, then swaps it onto the rendered triangle — painters never see a half-updated texture.

Gradual convergence: what reaches the texture is never the raw computed irradiance but a persistent per-texel exponential moving average (estimateR/estimateG/estimateB) over the complete sum ambient+direct+indirect. The estimate starts at a uniform medium value (INITIAL_IRRADIANCE), so the world is visible from frame one; lit areas then brighten and unlit areas sink to darkness gradually — no black-to-lit flash is possible, since the texture can only move a fixed alpha fraction per composite update.

Threading: texel state arrays are written by GI worker threads and read by whoever holds the snapshot; element-wise racy access is benign for progressive refinement. Texture buffer swaps are volatile/atomic via TexturedTriangle.setTexture(eu.svjatoslav.sixth.e3d.renderer.raster.texture.Texture).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final Color
    baseColor
    Unlit surface color of the triangle.
    final double
    edge1X
     
    final double
    edge1Y
     
    final double
    edge1Z
     
    final double
    edge2X
     
    final double
    edge2Y
     
    final double
    edge2Z
     
    final float[]
    estimateB
     
    final float[]
    estimateG
     
    final float[]
    estimateR
    Per-texel EMA estimate of TOTAL irradiance (ambient + direct + indirect), the only value ever written to the composite texture.
    final int
    height
     
    final float[]
    indirectB
     
    final float[]
    indirectG
     
    final float[]
    indirectR
    Per-texel indirect irradiance (light units, pre-albedo).
    static final double
    INITIAL_IRRADIANCE
    Uniform irradiance the composite estimate starts at (light units, display scale 0..255): the world begins medium-lit and visible, then fades toward the traced solution.
    int
    lightCount
     
    byte[]
    lightVisibility
    Per-texel per-light visibility: texelCount * lightCount bytes.
    int
    nextLight
    Round-robin light cursor for shadow sampling (GI threads only).
    final double
    normalX
    Unit surface normal.
    final double
    normalY
    Unit surface normal.
    final double
    normalZ
    Unit surface normal.
    final double
    originX
     
    final double
    originY
     
    final double
    originZ
     
    LightmappedTriangle
    owner
    The triangle currently displaying this lightmap (for texture swaps).
    final short[]
    sampleCounts
    Per-texel sample counters.
    final int[]
    validTexels
    Valid (u+v <= 1) texel indices, for round-robin sampling.
    static final byte
    VISIBILITY_OCCLUDED
    Visibility value: shadow ray was blocked.
    static final byte
    VISIBILITY_UNKNOWN
    Visibility value: not yet computed.
    static final byte
    VISIBILITY_VISIBLE
    Visibility value: shadow ray reached the light.
    final int
    width
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Lightmap(Point3D a, Point3D b, Point3D c, Color baseColor, double unitsPerTexel, double normalX, double normalY, double normalZ)
    Creates a lightmap for a triangle.

  • Method Summary

    Modifier and Type
    Method
    Description
    Texture
    backTexture()
    The texture GI should write the next composite into.
    void
    ensureLightCapacity(int lights)
    Ensures the per-texel visibility array matches the light count.
    Texture
    shownTexture()
    The texture the triangle should show right now.
    void
    swapBuffers()
    Flips the buffers after the back texture has been regenerated.
    int
    texelAt(double px, double py, double pz)
    Texel index nearest to a world point on the triangle plane.
    void
    texelWorldPosition(int texel, double[] out)
    World position of a texel center.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • VISIBILITY_UNKNOWN

      public static final byte VISIBILITY_UNKNOWN
      Visibility value: not yet computed.
      See Also:

    • VISIBILITY_VISIBLE

      public static final byte VISIBILITY_VISIBLE
      Visibility value: shadow ray reached the light.
      See Also:

    • VISIBILITY_OCCLUDED

      public static final byte VISIBILITY_OCCLUDED
      Visibility value: shadow ray was blocked.
      See Also:

    • INITIAL_IRRADIANCE

      public static final double INITIAL_IRRADIANCE
      Uniform irradiance the composite estimate starts at (light units, display scale 0..255): the world begins medium-lit and visible, then fades toward the traced solution. -De3d.gi.initialIrradiance.

    • width

      public final int width

    • height

      public final int height

    • baseColor

      public final Color baseColor
      Unlit surface color of the triangle.

    • originX

      public final double originX

    • originY

      public final double originY

    • originZ

      public final double originZ

    • edge1X

      public final double edge1X

    • edge1Y

      public final double edge1Y

    • edge1Z

      public final double edge1Z

    • edge2X

      public final double edge2X

    • edge2Y

      public final double edge2Y

    • edge2Z

      public final double edge2Z

    • normalX

      public final double normalX
      Unit surface normal.

    • normalY

      public final double normalY
      Unit surface normal.

    • normalZ

      public final double normalZ
      Unit surface normal.

    • validTexels

      public final int[] validTexels
      Valid (u+v <= 1) texel indices, for round-robin sampling.

    • indirectR

      public final float[] indirectR
      Per-texel indirect irradiance (light units, pre-albedo).

    • indirectG

      public final float[] indirectG

    • indirectB

      public final float[] indirectB

    • estimateR

      public final float[] estimateR
      Per-texel EMA estimate of TOTAL irradiance (ambient + direct + indirect), the only value ever written to the composite texture. Initialized to INITIAL_IRRADIANCE (uniform medium start); each composite update blends the freshly computed irradiance in with a fixed alpha, so both brightening and fading to darkness stay alive forever and no single-frame jump can occur.

    • estimateG

      public final float[] estimateG

    • estimateB

      public final float[] estimateB

    • sampleCounts

      public final short[] sampleCounts
      Per-texel sample counters. In "adaptive" alpha mode they drive the decaying EMA weight; in the default "fixed" mode they only mark first-visit texels (all-lights shadow test on the first sweep).

    • lightVisibility

      public byte[] lightVisibility
      Per-texel per-light visibility: texelCount * lightCount bytes.

    • lightCount

      public int lightCount

    • owner

      public volatile LightmappedTriangle owner
      The triangle currently displaying this lightmap (for texture swaps).

    • nextLight

      public int nextLight
      Round-robin light cursor for shadow sampling (GI threads only).

  • Constructor Details

    • Lightmap

      public Lightmap(Point3D a, Point3D b, Point3D c, Color baseColor, double unitsPerTexel, double normalX, double normalY, double normalZ)
      Creates a lightmap for a triangle.
      Parameters:
      a - first vertex (UV 0,0)
      b - second vertex (UV 1,0)
      c - third vertex (UV 0,1)
      baseColor - unlit surface color
      unitsPerTexel - world units per lightmap texel (resolution knob)
      normalX - unit normal x
      normalY - unit normal y
      normalZ - unit normal z

  • Method Details

    • texelWorldPosition

      public void texelWorldPosition(int texel, double[] out)
      World position of a texel center.
      Parameters:
      texel - texel index (j * width + i)
      out - receives x, y, z

    • texelAt

      public int texelAt(double px, double py, double pz)
      Texel index nearest to a world point on the triangle plane.
      Parameters:
      px - world x
      py - world y
      pz - world z
      Returns:
      texel index, clamped into the texture

    • ensureLightCapacity

      public void ensureLightCapacity(int lights)
      Ensures the per-texel visibility array matches the light count. Called from GI threads during sampling.
      Parameters:
      lights - number of lights in the snapshot

    • shownTexture

      public Texture shownTexture()
      The texture the triangle should show right now.
      Returns:
      the front composite texture

    • backTexture

      public Texture backTexture()
      The texture GI should write the next composite into.
      Returns:
      the back composite texture

    • swapBuffers

      public void swapBuffers()
      Flips the buffers after the back texture has been regenerated.