EnvironmentMap class base Lighting and environment

A source of image-based lighting: diffuse irradiance plus prefiltered specular radiance, both derived from an equirectangular environment.

Diffuse is stored as 9 L2 spherical-harmonic RGB coefficients (cheap, no texture fetch, seam-free); specular is a GPU-prefiltered "PMREM" roughness-band atlas (see prefilterEquirectRadiance). Both are computed up front, so constructing an environment from images does GPU work and is best done once.

Construct one with EnvironmentMap.fromEquirectImageAsset / EnvironmentMap.fromEquirectImageBytes (which detect HDR, EXR, or sRGB sources and compute the SH and prefilter the radiance for you), EnvironmentMap.studio (the built-in procedural default), EnvironmentMap.fromGpuTextures when you already hold a prefiltered atlas, or EnvironmentMap.empty for a no-op black environment.

Set one on a Scene via Scene.environment (it defaults to EnvironmentMap.studio); an individual PhysicallyBasedMaterial can override it via PhysicallyBasedMaterial.environment.

Constructors

EnvironmentMap.empty(): A black environment that contributes no image-based lighting.
factory
EnvironmentMap.fromGpuTextures({required Texture prefilteredRadiance, List<Vector3>? diffuseSphericalHarmonics, Texture? diffuseShTexture}): Wraps an already-built prefiltered radiance texture.
factory

Properties

backgroundIsLinear → bool: Whether backgroundTexture holds linear radiance (an HDR source) rather than sRGB-encoded color.
no setter
backgroundTexture → Texture: The full-res source equirect sampled for the visible background, or a dummy when hasBackgroundTexture is false (the sampler must still be bound).
no setter
diffuseShTexture → Texture: The diffuse SH coefficients as a kDiffuseShCoefficientCount-by-1 r16g16b16a16Float texture (coefficient i at texel i, RGB used).
no setter
diffuseSphericalHarmonics → List<Vector3>: The kDiffuseShCoefficientCount RGB L2 spherical-harmonic coefficients describing the diffuse (Lambertian) irradiance.
no setter
hasBackgroundTexture → bool: Whether this environment has a full-resolution source equirect for its background (image environments do; sky-baked / GPU-supplied ones do not).
no setter
hashCode → int: The hash code for this object.
no setterinherited
prefilteredRadianceCube → Texture: The prefiltered radiance cubemap (roughness band per mip), or a dummy when the radiance is the equirect 2D layout.
no setter
prefilteredRadianceTexture → Texture: The 2D prefiltered radiance for the equirect layouts, or a dummy when the radiance is a cube (the material's samplerCube is used instead). Both the 2D and cube samplers are always bound; the layout flag selects one.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
usesCubeRadianceLayout → bool: Whether the radiance is stored as a roughness-mip cubemap (sampled with samplerCube) rather than an equirect 2D layout. Detected from the texture, so an environment built either way binds correctly.
no setter
usesMipRadianceLayout → bool: Whether the 2D prefilteredRadianceTexture stores its roughness bands as mip levels (see useMipRadianceLayout). Always false for the cube layout.
no setter

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

mipRadianceLayoutSupported → bool: Whether the active Flutter GPU backend can build and sample the mip radiance layout: rendering into non-zero mip levels plus sampling hand-written mip chains.
no setter
radianceCubeSize ↔ int: Base-mip face size of the prefiltered radiance cubemap new environments build (the convolved reflection/ambient cube, not the visible background). Higher is sharper reflections at more memory (a cube is 6 * size^2 texels plus mips); 256-512 is a good default, up to ~2048. Equivalent to Godot's Sky.radiance_size. Applies only on backends that build the cube (see effectiveMipRadianceLayout); affects environments built afterward.
getter/setter pair
useMipRadianceLayout ↔ bool: Whether newly built environments store their prefiltered roughness bands as mip levels of one equirect (sampled with hardware trilinear textureLod) rather than the legacy vertically stacked band atlas. Defaults to true, and applies only where the backend supports the layout (see mipRadianceLayoutSupported).
getter/setter pair

Static Methods

computeDiffuseSphericalHarmonics(Image equirectangular) → Future<List<Vector3>>: Projects an equirectangular radiance image onto 9 L2 spherical- harmonic coefficients suitable for diffuse irradiance.
fromAssets({required String radianceImagePath, List<Vector3>? diffuseSphericalHarmonics}) → Future<EnvironmentMap>: Loads an EnvironmentMap from an equirectangular sRGB radiance image in the asset bundle (see fromUIImages).
fromEquirectHdr({required Float32List linearPixels, required int width, required int height, List<Vector3>? diffuseSphericalHarmonics}) → Future<EnvironmentMap>: Builds an EnvironmentMap from a high-dynamic-range equirectangular radiance map: linear (not sRGB) RGBA float pixels, row-major, width by height. Row 0 is the top of the image (the up pole), the standard equirectangular convention.
fromEquirectImageAsset({required String assetPath, int maxWidth = 4096, List<Vector3>? diffuseSphericalHarmonics, AssetBundle? bundle}) → Future<EnvironmentMap>: Loads an EnvironmentMap from an equirectangular image in the asset bundle, detecting Radiance HDR (.hdr), OpenEXR (.exr), or a standard sRGB image (.png/.jpg) from its contents. HDR and EXR are read as linear radiance, so bright skies and the sun keep their true intensity; LDR images are interpreted as sRGB.
fromEquirectImageBytes({required Uint8List bytes, int maxWidth = 4096, List<Vector3>? diffuseSphericalHarmonics}) → Future<EnvironmentMap>: Builds an EnvironmentMap from the raw bytes of an equirectangular image, detecting Radiance HDR, OpenEXR, or a standard sRGB image (see fromEquirectImageAsset). Useful for an image fetched over the network or picked by the user.
fromSky(SkySource source, {int faceResolution = 128, int equirectWidth = 512}) → EnvironmentMap: Bakes a sky into an environment for image-based lighting.
fromUIImages({required Image radianceImage, List<Vector3>? diffuseSphericalHarmonics}) → Future<EnvironmentMap>: Builds an EnvironmentMap from an already-decoded equirectangular dart:ui radiance image: uploads it, GPU-prefilters it for roughness-aware specular, and projects it onto diffuse SH.
studio() → EnvironmentMap: Builds the package's built-in procedural "studio" environment.