Environment

The Environment class generates and manages HDR lighting maps from an equirectangular environment texture. It creates three cubemaps:

• environmentMap — Direct environment lighting (used for reflections)
• specularMap — Pre-integrated BRDF specular map for PBR rendering (used via SkyCube as a sky background)
• irradianceMap — Diffuse irradiance map for indirect lighting in PBR shaders

Access the environment via renderer.factory.environment().

import Environment from "bg2e-js/ts/render/Environment.js";
import WebGLRenderer from "bg2e-js/ts/render/webgl/Renderer.js";

const environment = myRenderer.factory.environment();
await environment.load({ textureUrl: '../resources/sky.jpg' }); // Load from URL

// Update cubemaps (calls skySphere.draw() for each face):
environment.updateMaps();

// Access generated maps:
const envMap = environment.environmentMap;  // For reflections

Example: Generating Environment Maps from an Equirectangular Image

import WebGLRenderer from "bg2e-js/ts/render/webgl/Renderer.js";
import Environment from "bg2e-js/ts/render/Environment.js";
import Mat4 from "bg2e-js/ts/math/Mat4.ts";

class MyApp extends AppController {
    private _skyCube;  // SkyCube for visualizing the environment

    async init() {
        const env = myRenderer.factory.environment();
        await env.load({ urlTexture: '../resources/environment.jpg', environmentMapSize:[512, 512] }); // Generate maps from a single image

        const skyCube = myRenderer.factory.skyCube();
        await skyCube.load(env.environmentMap);  // Load the generated environment map for display

        this._skyCube = skyCube;
    }

    resize() {
        const w = this.canvas.domElement.clientWidth;
        const h = this.canvas.domElement.clientHeight;
        state.viewport = new Vec(w, h);
    }

    display() {
        const gl = this.renderer.getContext();
        state.clearColor([0.1, 0.1, 0.1]); // Clear background
        state.clear();

        this._env.updateMaps();  // Update cubemaps with current view
        this._skyCube.draw();    // Render the sky sphere
    }

    destroy() {
        this._skyCube?.destroy();  // Free resources
        environment.destroy();     // Destroy cubemaps and internal state
    }
}

See also samples/16_env_renderer.

Properties (Read)

Property	Type	Description
renderer	Renderer	The renderer instance managing this environment.
updatedMap	boolean	Returns true if the map has been successfully generated by updateMaps().
environmentMap	Texture | null (read)	The environment map texture generated from the source equirectangular image.
specularMap	Texture | null (read)	The specular/BRDF map for direct lighting calculations.
irradianceMap	Texture | null (read)	The irradiance/diffuse map for indirect lighting.

Methods

async load({ textureUrl, environmentMapSize, specularMapSize, irradianceMapSize }): Promise<void>

Generates all three maps for the given source texture URL. This loads the equirectangular image, and creates internal sky geometries for each of the maps by setting up sky spheres/cubes with appropriate texture sizes.

await environment.load({
    textureUrl: '../resources/sky.jpg',           // Required for map generation (equirectangular image)
    environmentMapSize: [512, 512],              // Output cubemap resolution (default)
    specularMapSize: [128, 128],                 // Specular map resolution (default)
    irradianceMapSize: [32, 32]                  // Irradiance map resolution (default)
});

updateMaps(): void

Updates all three cubemaps and sets each sky map’s texture. Use this every frame (or only when needed) to refresh the environment based on current camera/view direction.

// Call this in your frame() or display():
this._env.updateMaps();  // Update env texture, specular and irradiance maps every frame

async reloadImage(imageUrl: string): Promise<void> | void

Reloads the environment and re-generates all maps from a new equirectangular image:

await environment.reloadImage('../resources/new-sky.jpg');  // Change the environment on the fly

See samples/18_pbr_ibl for an example where images are swapped with keys.

destroy(): void

Frees all GPU resources associated with the environment (maps, sky sphere/cube geometries):

environment.destroy();  // Must be called to clean up maps and resources