captureEnvironment method

EnvironmentMap captureEnvironment({
  1. required Vector3 position,
  2. int faceResolution = 128,
  3. int equirectWidth = 512,
  4. int layerMask = 0xFFFFFFFF,
})

Captures the scene's linear HDR lighting at position into a new EnvironmentMap: renders the scene into six cube faces (with shadows and analytic lights, without screen-space effects or post-processing), then prefilters the result like any other environment.

The returned environment reflects the scene at the moment of capture; nothing re-captures it. For a node-anchored probe with parallax-corrected sampling and automatic blending, use ReflectionProbeComponent instead.

The engine resources must be loaded (isReadyToRender); throws StateError otherwise.

Implementation

EnvironmentMap captureEnvironment({
  required Vector3 position,
  int faceResolution = 128,
  int equirectWidth = 512,
  int layerMask = 0xFFFFFFFF,
}) {
  if (!isReadyToRender) {
    throw StateError(
      'Scene.captureEnvironment requires the engine resources; await '
      'Scene.initializeStaticResources() first.',
    );
  }
  assert(() {
    if (_awaitingPhysicalResources) {
      debugPrint(
        'Scene.captureEnvironment ran while the physical material shaders '
        'were still loading, so materials that need them drew without '
        'them. Await Scene.preload() first.',
      );
    }
    return true;
  }());
  renderScene.rebuildIfDirty();
  final lightComponent = renderScene.primaryDirectionalLight;
  final spotShadowFrame = collectSpotShadows(renderScene.spotLights);
  final pointShadowFrame = collectPointShadows(renderScene.pointLights);
  final punctualLighting = _punctualLightBuffer.build(
    directionals: renderScene.directionalLights,
    primaryDirectional: lightComponent,
    points: renderScene.pointLights,
    spots: renderScene.spotLights,
    areas: renderScene.rectAreaLights,
    items: renderScene.items,
    bvh: renderScene.bvh,
    spotShadows: spotShadowFrame,
    pointShadows: pointShadowFrame,
    enableFroxels: punctualLightClustering,
  );
  return _captureEnvironmentAt(
    position: position,
    faceResolution: faceResolution,
    equirectWidth: equirectWidth,
    layerMask: layerMask,
    environmentMap: environment ?? Material.getDefaultEnvironmentMap(),
    transientsBuffer: uniformTransients,
    lightComponent: lightComponent,
    punctualLighting: punctualLighting,
    spotShadowFrame: spotShadowFrame,
    pointShadowFrame: pointShadowFrame,
  );
}