HomeWeb Components API Reference - v0.30.0
    Preparing search index...

    Class LightComponentElement

    The LightComponentElement interface provides properties and methods for manipulating <pc-light> elements. The LightComponentElement interface also inherits the properties and methods of the HTMLElement interface.

    Engine component: LightComponent (light).

    Hierarchy (View Summary)

    Index
    • get cascadeBlend(): number

      Gets the cascade blend factor of the light, from 0 (no blending) to 1, which applies only to directional lights with num-cascades greater than 1.

      Returns number

      The cascade blend factor.

    • set cascadeBlend(value: number): void

      Sets the fraction of each shadow cascade that is blended into the next one, from 0 (no blending) to 1, which applies only to directional lights with num-cascades greater than

      1. Defaults to 0.

      Parameters

      • value: number

        The cascade blend factor.

      Returns void

    • get cascadeDistribution(): number

      Gets the cascade distribution of the light, from 0 (linear split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which applies only to directional lights with num-cascades greater than 1.

      Returns number

      The cascade distribution.

    • set cascadeDistribution(value: number): void

      Sets the distribution of the camera frustum split between shadow cascades, from 0 (linear split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which applies only to directional lights with num-cascades greater than 1. Defaults to 0.5.

      Parameters

      • value: number

        The cascade distribution.

      Returns void

    • get closestApp(): AppElement | null

      The nearest ancestor <pc-app> element, or null if this element has no <pc-app> ancestor. The search starts at the parent, so an element never resolves to itself.

      Returns AppElement | null

      The closest app element, or null.

    • get closestEntity(): EntityBaseElement | null

      The nearest ancestor element that fronts an entity — <pc-entity>, <pc-model> or <pc-node> — or null if this element has no such ancestor. The search starts at the parent, so an element never resolves to itself.

      Returns EntityBaseElement | null

      The closest entity-fronting element, or null.

    • get enabled(): boolean

      Gets the enabled state of the component.

      Returns boolean

      The enabled state of the component.

    • set enabled(value: boolean): void

      Sets the enabled state of the component.

      Parameters

      • value: boolean

        The enabled state of the component.

      Returns void

    • get numCascades(): number

      Gets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which applies only to directional lights.

      Returns number

      The number of shadow cascades.

    • set numCascades(value: number): void

      Sets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which applies only to directional lights. Defaults to 1.

      Parameters

      • value: number

        The number of shadow cascades.

      Returns void

    • get shadowBlockerSamples(): number

      Gets the number of shadow blocker samples.

      Returns number

      The number of shadow blocker samples.

    • set shadowBlockerSamples(value: number): void

      Sets the number of shadow blocker samples. Used for PCSS shadows.

      Parameters

      • value: number

        The number of shadow blocker samples.

      Returns void

    • get shadowBounds(): BoundingBox | null

      Gets the world space box that the shadow of a directional light is fitted to.

      Returns BoundingBox | null

      The shadow bounds, or null when there are none.

    • set shadowBounds(value: BoundingBox | null): void

      Sets a world space box that the shadow of a directional light is fitted to, in place of cascades fitted to each camera. The whole shadow map then covers the box as seen from the light, which concentrates its resolution on part of a large scene. The box only needs to enclose the shadow casters: receivers further along the light, such as the ground below them, are still shadowed. While it is set, num-cascades, shadow-distance, cascade-blend and cascade-distribution are not used. Defaults to null, which fits the shadow to each camera as usual.

      Parameters

      • value: BoundingBox | null

        The shadow bounds, or null for none.

      Returns void

    • get shadowSamples(): number

      Gets the number of shadow samples.

      Returns number

      The number of shadow samples.

    • set shadowSamples(value: number): void

      Sets the number of shadow samples. Used for PCSS shadows.

      Parameters

      • value: number

        The number of shadow samples.

      Returns void

    • get shadowType(): | "pcf1-16f"
      | "pcf1-32f"
      | "pcf3-16f"
      | "pcf3-32f"
      | "pcf5-16f"
      | "pcf5-32f"
      | "vsm-16f"
      | "vsm-32f"
      | "pcss-32f"

      Gets the shadow type of the light.

      Returns
          | "pcf1-16f"
          | "pcf1-32f"
          | "pcf3-16f"
          | "pcf3-32f"
          | "pcf5-16f"
          | "pcf5-32f"
          | "vsm-16f"
          | "vsm-32f"
          | "pcss-32f"

      The shadow type.

    • set shadowType(
          value:
              | "pcf1-16f"
              | "pcf1-32f"
              | "pcf3-16f"
              | "pcf3-32f"
              | "pcf5-16f"
              | "pcf5-32f"
              | "vsm-16f"
              | "vsm-32f"
              | "pcss-32f",
      ): void

      Sets the shadow type of the light.

      Parameters

      • value:
            | "pcf1-16f"
            | "pcf1-32f"
            | "pcf3-16f"
            | "pcf3-32f"
            | "pcf5-16f"
            | "pcf5-32f"
            | "vsm-16f"
            | "vsm-32f"
            | "pcss-32f"

        The shadow type. Can be:

        • pcf1-16f - 1-tap percentage-closer filtered shadow map with 16-bit depth.
        • pcf1-32f - 1-tap percentage-closer filtered shadow map with 32-bit depth.
        • pcf3-16f - 3-tap percentage-closer filtered shadow map with 16-bit depth.
        • pcf3-32f - 3-tap percentage-closer filtered shadow map with 32-bit depth.
        • pcf5-16f - 5-tap percentage-closer filtered shadow map with 16-bit depth.
        • pcf5-32f - 5-tap percentage-closer filtered shadow map with 32-bit depth.
        • vsm-16f - Variance shadow map with 16-bit depth.
        • vsm-32f - Variance shadow map with 32-bit depth.
        • pcss-32f - Percentage-closer soft shadow with 32-bit depth.

      Returns void

    • get shape(): LightShape

      Gets the shape of the light source: punctual, or an area light shaped as a rect, disk or sphere that takes its size from the entity's scale and needs the lookup tables loaded by area-light-luts on <pc-app>.

      Returns LightShape

      The light shape.

    • set shape(value: LightShape): void

      Sets the shape of the light source: punctual for a point, or an area light shaped as a rect, disk or sphere that takes its size from the entity's scale and needs the lookup tables loaded by area-light-luts on <pc-app>. Defaults to punctual.

      Parameters

      • value: LightShape

        The light shape. Can be:

        • punctual - An infinitesimally small point.
        • rect - A rectangle in the entity's local XZ plane, 1 by 1 at unit scale.
        • disk - A disk in the entity's local XZ plane, 1 across at unit scale.
        • sphere - A sphere, 1 across at unit scale.

        Area shapes fall off with their size and distance, so range is only a cutoff for them.

      Returns void

    • get type(): "directional" | "omni" | "spot"

      Gets the type of the light.

      Returns "directional" | "omni" | "spot"

      The type.

    • set type(value: "directional" | "omni" | "spot"): void

      Sets the type of the light. Can be directional, omni or spot. Defaults to directional.

      Parameters

      • value: "directional" | "omni" | "spot"

        The type.

      Returns void

    • get volumetricScattering(): number

      Gets how strongly the light scatters into volumetric fog, which applies only to omni and spot lights while a camera frame renders volumetric fog with local lights.

      Returns number

      The volumetric scattering multiplier.

    • set volumetricScattering(value: number): void

      Sets how strongly the light scatters into volumetric fog, as a multiplier on its contribution, which applies only to omni and spot lights while a camera frame renders volumetric fog with local lights. 0 leaves the light out of the fog. Defaults to 1.

      Parameters

      • value: number

        The volumetric scattering multiplier.

      Returns void

    • Called when the element is fully initialized and ready. Subclasses should call this when they're ready. Resolves the ready promise and dispatches a bubbling, composed ready event. Signals at most once per readiness cycle: a repeat call before _resetReady has re-armed the promise does nothing.

      Returns void

    • Returns the ready promise to its pending state. Subclasses should call this when the resource their readiness announced is torn down (typically from disconnectedCallback), so that a later re-initialization can signal readiness again. Does nothing while the promise is still pending — an in-flight waiter carries over to the next readiness cycle rather than being stranded on a promise nothing will ever resolve.

      Returns void

    • Returns the data the component is created with. Overridden by subclasses to supply the initial values of their cached properties. The element's enabled state is not among them: the base class adds it when it creates the component.

      Returns {
          cascadeBlend: number;
          cascadeDistribution: number;
          castShadows: boolean;
          color: Color;
          innerConeAngle: number;
          intensity: number;
          normalOffsetBias: number;
          numCascades: number;
          outerConeAngle: number;
          penumbraFalloff: number;
          penumbraSize: number;
          range: number;
          shadowBias: number;
          shadowBlockerSamples: number;
          shadowBounds: BoundingBox | null;
          shadowDistance: number;
          shadowIntensity: number;
          shadowResolution: number;
          shadowSamples: number;
          shadowType: number;
          shape: number;
          type: "directional" | "omni" | "spot";
          volumetricScattering: number;
          vsmBias: number;
          vsmBlurSize: number;
      }

      The initial component data.

    • Returns a promise that resolves with this element when it's ready. This is the low-level primitive underlying whenReady, which is the recommended way to wait for elements.

      Readiness tracks the element's current lifecycle: once a ready element is torn down (for example by removing it from the document), this returns a fresh promise that resolves when the element is next ready. A promise obtained earlier stays resolved — call this again after re-inserting an element rather than reusing a promise from before its removal.

      Returns Promise<LightComponentElement>

      A promise that resolves with this element when it's ready.