Engine API Reference - v2.24.0-beta.16
    Preparing search index...

    Class LensFlareEffect

    The lens flare effect: draws the flares of the lights, or of any positions, in the scene. A flare is a LensFlare, following its light, whose look places shapes along the axis from the light through the centre of the screen. The shapes are textures, given to the effect as a LensFlareShapeLibrary it copies into one texture array shared by all its flares. The flares fade as their source is covered by the scene, measured against the scene depth, as it leaves the screen, and for a spot light as the camera leaves its cone.

    The flares are drawn by passes the effect owns, at the resolution LensFlareEffect#scale gives, half of the scene's by default, and added to the scene in linear HDR space, before tone mapping.

    Add one to a camera frame with CameraFrame#addEffect; it is not a built-in effect.

    const lensFlare = new LensFlareEffect(app.graphicsDevice);
    lensFlare.shapes = {
        shapes: {
            glow: glowAsset.resource,
            star: starAsset.resource,
            disc: discAsset.resource
        }
    };
    cameraFrame.addEffect(lensFlare);

    const sun = new LensFlare({
        elements: [
            { shape: 'glow', size: 0.5, color: [1, 0.9, 0.7], intensity: 0.5 },
            { shape: 'star', size: 1.2, intensity: 0.4 },
            { shape: 'disc', offset: 0.5, size: 0.08, color: [0.4, 0.8, 1], count: 4, spread: 0.4 }
        ]
    }, { light: sunEntity.light });
    lensFlare.add(sun);

    cameraFrame.update();

    Hierarchy (View Summary)

    Index
    constructor
    cameraFrame device enabled flares intensity scale
    active cameraExposureScale chunkName debugViews defineName entryPoint glsl id requires shapes slot wgsl
    add destroy frameUpdate getChunk remove setDefine setUniform update
    cameraFrame: CameraFrame | null = null

    The camera frame the effect is registered with, or null.

    device: GraphicsDevice

    The graphics device.

    enabled: boolean = true

    Whether the effect is enabled. An effect can additionally disable itself from its own parameters, see CameraFrameEffect#active.

    flares: LensFlare[] = []

    The flares registered with the effect, in the order they are drawn. Treat the array as read-only; use LensFlareEffect#add and LensFlareEffect#remove to change it.

    intensity: number = 1

    The brightness of all flares. Zero disables the effect. Defaults to 1.

    scale: number = 0.5

    The resolution the flares are drawn at, relative to the resolution of the scene, 0.25-1 range. Lower values are cheaper and soften the elements slightly, which suits soft shapes, while 1 keeps small sharp elements crisp. Defaults to 0.5.

    • get active(): boolean

      Gets whether the effect contributes to the frame: when it is enabled, its intensity is positive and it has flares.

      Returns boolean

    • get cameraExposureScale(): number

      Gets the scale the effect applies to the exposure of the camera this frame, multiplying the exposure of the scene, or of the physical camera with physical units - for effects adapting the exposure to what the camera sees. Read every frame while the effect takes part, after CameraFrameEffect#frameUpdate; the camera frame applies the product of the scales of the effects taking part, and the camera renders with its own exposure again once none does. Defaults to 1.

      // an effect brightening the image by one stop
      get cameraExposureScale() {
          return 2;
      }

      Returns number

    • get chunkName(): string

      Gets the name the compose chunk can be overridden under in ShaderChunks, the same way as the built-in chunks. Derived from the id as compose<Id>PS unless given.

      Returns string

    • get defineName(): string

      Gets the define set on the compose shader while the effect is active: the id in upper snake case, colorEnhance giving COLOR_ENHANCE.

      Returns string

    • get entryPoint(): string

      Gets the name of the function the composition calls at the effect's slot. Derived from the id as apply<Id> unless given. The signature depends on the slot: colour slots take (vec3 color, vec2 uv) and return the colour, COMPOSESLOT_SCENE takes and returns a vec4.

      Returns string

    • get requires(): string[]

      Gets the frame resources the effect needs, the FRAMERESOURCE_* constants - for its passes, or for its compose chunk, such as the scene depth. The camera frame provides them while the effect is active. Requirements which depend on the device are computed when constructing the effect; override this as a getter when they depend on a parameter, and the camera frame provides what it returns from the next CameraFrame#update.

      Returns string[]

    • get slot(): string | null

      Gets the compose slot the entry function is called at, or null for an effect that does not take part in the composition.

      Returns string | null

    • Destroys the effect, removing it from its camera frame if it is still registered and releasing everything it owns, the passes it created included. Subclasses which create resources in their constructor release them in an override, calling super.destroy(). The removal takes effect for the frames rendered after the next CameraFrame#update, which is due before the next frame renders.

      Returns void

    • Sets a define on the compose shader. The define persists until changed, so fixed defines can be set once in the constructor and those depending on the parameters from CameraFrameEffect#update. A value of false, null or undefined removes it. Changing a define rebuilds the compose shader.

      Parameters

      • name: string

        The define name.

      • value: any

        The value.

      Returns void

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Accessors
    Methods