BabylonJS - Lens Flares

Babylon.js - Lens Flares

Lens flare is an optical effect that occurs when a bright light source (like the sun or a strong lamp) hits the camera lens, causing scattering and internal reflections that appear as streaks, circles, or starburst patterns in the image. Babylon.js allows you to simulate this effect to add realism or a specific visual style to your scenes.

Lens flares are managed by a LensFlareSystem. This system is attached to an emitter, which can be a light source, a camera, or any mesh. The system then renders individual flare elements (textures) along the line of sight between the camera and the emitter when the emitter is visible.

Creating a Lens Flare System

First, you create the LensFlareSystem and associate it with an emitter (like a light).

import * as BABYLON from '@babylonjs/core';

// Assuming 'scene' and 'lightSource' (e.g., a PointLight or DirectionalLight) are defined

const lensFlareSystem = new BABYLON.LensFlareSystem(
    "lensFlareSys",
    lightSource, // The emitter object (Light, Camera, or Mesh)
    scene
);

Adding Individual Flares

A lens flare effect is typically composed of multiple individual flare elements, each represented by a BABYLON.LensFlare object. You add these flares to the system.

// Parameters: size, position, color, texture URL, parent system

// size: Size of the flare element (relative size, e.g., 0.5 means half the system size)
// position: Position along the line from emitter to camera (0 = at emitter, 1 = at camera)
// color: Color tint for the flare texture
// imgUrl: Path to the texture image for this flare element (often PNGs with transparency)
// system: The LensFlareSystem this flare belongs to

// Example: Add a large central flare at the light source position
const flare0 = new BABYLON.LensFlare(0.2, 0, new BABYLON.Color3(1, 1, 1), "textures/flare/flare1.png", lensFlareSystem);

// Example: Add smaller hexagonal flares along the line of sight
const flare1 = new BABYLON.LensFlare(0.5, 0.2, new BABYLON.Color3(0.5, 0.8, 1), "textures/flare/flare2.png", lensFlareSystem);
const flare2 = new BABYLON.LensFlare(0.3, 0.4, new BABYLON.Color3(1, 0.8, 0.8), "textures/flare/flare3.png", lensFlareSystem);
const flare3 = new BABYLON.LensFlare(0.6, 0.6, new BABYLON.Color3(0.7, 1, 0.7), "textures/flare/flare2.png", lensFlareSystem);
const flare4 = new BABYLON.LensFlare(0.4, 0.8, new BABYLON.Color3(0.9, 0.7, 1), "textures/flare/flare1.png", lensFlareSystem);

By combining multiple LensFlare instances with different sizes, positions, colors, and textures, you can build up complex and visually appealing flare effects.

Demo

This demo creates a simple scene with a light source and attaches a multi-element lens flare system to it.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8"/>
    <title>Babylon.js - Lens Flare Demo</title>
    <script src="https://cdn.babylonjs.com/babylon.js"></script>
    <script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
    <style>
        html, body { overflow: hidden; width: 100%; height: 100%; margin: 0; padding: 0; }
        #renderCanvas { width: 100%; height: 100%; touch-action: none; }
    </style>
</head>
<body>
    <canvas id="renderCanvas"></canvas>
    <script type="text/javascript">
        const canvas = document.getElementById("renderCanvas");
        const engine = new BABYLON.Engine(canvas, true);

        const createScene = function () {
            const scene = new BABYLON.Scene(engine);
            scene.clearColor = new BABYLON.Color4(0.05, 0.05, 0.1, 1.0); // Dark blue background

            const camera = new BABYLON.ArcRotateCamera("Camera", Math.PI / 2, Math.PI / 2.5, 20, BABYLON.Vector3.Zero(), scene);
            camera.attachControl(canvas, true);
            camera.wheelPrecision = 100;

            // Use a point light as the emitter for the flare
            const lightSource = new BABYLON.PointLight("lightSource", new BABYLON.Vector3(0, 0, 0), scene);
            lightSource.intensity = 0; // We don't need the light to illuminate, just act as emitter position

            // Optional: Add a mesh to represent the light source visually
            const sunMesh = BABYLON.MeshBuilder.CreateSphere("sun", {diameter: 1}, scene);
            const sunMat = new BABYLON.StandardMaterial("sunMat", scene);
            sunMat.emissiveColor = new BABYLON.Color3(1, 1, 0.8);
            sunMesh.material = sunMat;
            sunMesh.position = lightSource.position; // Position mesh at light source

            // --- Lens Flare Setup ---
            const lensFlareSystem = new BABYLON.LensFlareSystem("lensFlareSys", lightSource, scene);

            // Ensure flare textures exist in 'textures/flare/' folder
            try {
                // Flare definitions (size, position, color, textureURL, system)
                new BABYLON.LensFlare(0.2, 0,    new BABYLON.Color3(1, 1, 1),   "textures/flare/flare1.png", lensFlareSystem);
                new BABYLON.LensFlare(0.5, 0.2,  new BABYLON.Color3(0.5, 0.5, 1),   "textures/flare/flare3.png", lensFlareSystem);
                new BABYLON.LensFlare(0.3, 0.4,  new BABYLON.Color3(1, 0.5, 0.5),   "textures/flare/flare2.png", lensFlareSystem);
                new BABYLON.LensFlare(0.1, 0.6,  new BABYLON.Color3(1, 1, 0.7),   "textures/flare/flare1.png", lensFlareSystem);
                new BABYLON.LensFlare(0.4, 0.8,  new BABYLON.Color3(0.7, 1, 0.7),   "textures/flare/flare3.png", lensFlareSystem);
                new BABYLON.LensFlare(0.25, 1.0, new BABYLON.Color3(0.8, 0.7, 1),   "textures/flare/flare2.png", lensFlareSystem);
                console.log("Lens flare textures presumably loaded (check console for 404s).");
            } catch(err) {
                console.error("Error creating lens flares - likely texture loading issue:", err);
            }
            // ------------------------

            // Animate the light source / sun mesh position
            let angle = 0;
            scene.onBeforeRenderObservable.add(() => {
                angle += 0.01;
                lightSource.position.x = 8 * Math.sin(angle);
                lightSource.position.z = 8 * Math.cos(angle);
                sunMesh.position = lightSource.position; // Keep visual mesh synced
            });

            return scene;
        };

        const scene = createScene();
        engine.runRenderLoop(function () {
            scene.render();
        });
        window.addEventListener("resize", function () {
            engine.resize();
        });
    </script>
</body>
</html>

Texture Requirements

This demo requires several PNG image files (flare1.png, flare2.png, flare3.png) located in a textures/flare/ folder relative to the HTML file. These images should typically be circular or starburst shapes with transparent backgrounds to create the flare effect.

Output Description

The demo displays a dark blue scene with a glowing yellow sphere (representing the sun or light source) moving in a circular path around the center. When the yellow sphere is visible on screen, a lens flare effect appears, originating from the sphere and stretching towards the center of the view. The flare consists of multiple colored, textured elements (circles, hexagons, etc., based on the loaded PNGs) arranged along this line. As the sphere moves and you rotate the camera, the lens flare appears, disappears, and changes intensity based on the sphere’s position relative to the camera’s view.

Performance Considerations

Lens flare systems are relatively inexpensive to render compared to complex geometry or post-processing effects, but having many complex systems or very high-resolution flare textures can still impact performance. Use them where they add significant visual impact.