Light QML Type | Qt Quick 3D | Qt 6.12.0
Description: An uncreatable abstract base type for all lights.
Keywords: qmltype

- Qt 6.12
- Qt Quick 3D
- QML Types
- Light
- Qt Quick 3D | Commercial or GPLv3

# Light QML Type

An uncreatable abstract base type for all lights. More...

Import Statement: | `import QtQuick3D`
Inherits: | Node
Inherited By: | DirectionalLight, PointLight, and SpotLight

- List of all members, including inherited members
- Deprecated members

## Properties

- ambientColor : color
- bakeMode : enumeration
- brightness : real
- castsShadow : bool
- color : color
- pcfFactor : real `(since 6.8)`
- scope : Node
- shadowBias : real
- shadowFactor : real
- shadowMapFar : real
- shadowMapQuality : enumeration
- softShadowQuality : enumeration `(since 6.8)`
- use32BitShadowmap : bool `(since 6.9)`

## Detailed Description

Light itself is an uncreatable base for all of its subtypes. The subtypes provide multiple options to determine the style of the light.

For usage examples, see Qt Quick 3D - Lights Example.

See also DirectionalLight and PointLight.

## Property Documentation

### ambientColor : color

The property defines the ambient color applied to materials before being lit by this light. The default value is black, rgb(0, 0, 0).

### bakeMode : enumeration

The property controls if the light is active in baked lighting, such as when generating lightmaps.

Constant | Description
--- | ---
`Light.BakeModeDisabled` | The light is not used in baked lighting.
`Light.BakeModeIndirect` | Indirect lighting contribution (for global illumination) is baked for this light. Direct lighting (diffuse, specular, real-time shadow mapping) is calculated normally for the light at run time. At run time, when not in baking mode, the renderer will attempt to sample the lightmap to get the indirect lighting data and combine that with the results of the real-time calculations.
`Light.BakeModeAll` | Both direct (diffuse, shadow) and indirect lighting is baked for this light. The light will not have a specular contribution and will not generate realtime shadow maps, but it will always have baked shadows. At run time, when not in baking mode, the renderer will attempt to sample the lightmap in place of the standard, real-time calculations for diffuse lighting and shadow mapping.

The default value is `Light.BakeModeDisabled`

Note: Just as with Model::usedInBakedLighting, designers and developers must always evaluate on a per-light basis if the light is suitable to take part in baked lighting.

Warning: Lights with dynamically changing properties, for example, animated position, rotation, or other properties, are not suitable for participating in baked lighting.

This property is relevant both when baking and when using lightmaps. A consistent state between the baking run and the subsequent runs that use the generated data is essential. Changing to a different value will not change the previously generated and persistently stored data in the lightmaps, the engine's rendering behavior will however follow the property's current value.

For more information on how to bake lightmaps, see the Lightmaps and Global Illumination.

See also Model::usedInBakedLighting, Model::bakedLightmap, Lightmapper, and Lightmaps and Global Illumination.

### brightness : real

This property defines an overall multiplier for this light’s effects. The default value is 1.

### castsShadow : bool

When this property is enabled, the light will cast (real-time) shadows. The default value is false.

Note: When bakeMode is set to Light.BakeModeAll, this property has no effect. A fully baked light always has baked shadows, but it will never participate in real-time shadow mapping.

### color : color

This property defines the color applied to models illuminated by this light. The default value is white, rgb(255, 255, 255).

### pcfFactor : real `[since 6.8]`

The property controls the PCF (percentage-closer filtering) factor. This value tries to approximate the radius of a PCF filtering in world space.

Note: PCF needs to be set in softShadowQuality for this property to have an effect.

Default value: `2.0`

This property was introduced in Qt 6.8.

See also Light::softShadowQuality.

### scope : Node

The property allows the selection of a Node in the scene. Only that node and its children are affected by this light. By default the value is null, which indicates no scope selected.

Note: Scoped lights cannot cast real-time shadows, meaning a Light with a scope set should not set castsShadow to true. They can however generate baked shadows when bakeMode is set to Light.BakeModeAll.

### shadowBias : real

This property is used to tweak the shadowing effect when objects are casting shadows on themselves. The value tries to approximate the offset in world space so it needs to be tweaked depending on the size of your scene.

The default value is `10`

### shadowFactor : real

This property determines how dark the cast shadows should be. The value range is [0, 100], where 0 means no shadows and 100 means the light is fully shadowed.

The default value is `75`.

### shadowMapFar : real

The property determines the maximum distance for the shadow map. Smaller values improve the precision and effects of the map. The default value is 5000. Unit is points in local coordinate space.

### shadowMapQuality : enumeration

The property sets the quality of the shadow map created for shadow rendering. Lower quality uses less resources, but produces lower quality shadows while higher quality uses more resources, but produces better quality shadows.

Supported quality values are:

Constant | Description
--- | ---
`Light.ShadowMapQualityLow` | Render shadowmap using a 256x256 texture.
`Light.ShadowMapQualityMedium` | Render shadowmap using a 512x512 texture.
`Light.ShadowMapQualityHigh` | Render shadowmap using a 1024x1024 texture.
`Light.ShadowMapQualityVeryHigh` | Render shadowmap using a 2048x2048 texture.
`Light.ShadowMapQualityUltra` | Render shadowmap using a 4096x4096 texture.

The default value is `Light.ShadowMapQualityLow`

### softShadowQuality : enumeration `[since 6.8]`

The property suggests the soft shadow quality that should be used when shadows are enabled. The actual number of samples used when rendering shadows is determined by highest quality set by any light used by a material.

Constant | Description
--- | ---
`Light.Hard` | No soft shadows.
`Light.PCF4` | Percentage-closer filtering soft shadows with 4 samples.
`Light.PCF8` | Percentage-closer filtering soft shadows with 8 samples.
`Light.PCF16` | Percentage-closer filtering soft shadows with 16 samples.
`Light.PCF32` | Percentage-closer filtering soft shadows with 32 samples.
`Light.PCF64` | Percentage-closer filtering soft shadows with 64 samples.

Default value: `Light.PCF4`

Note: Currently values larger than 16 samples will be treated as 16 samples.

This property was introduced in Qt 6.8.

See also Light::pcfFactor and Light::shadowFilter.

### use32BitShadowmap : bool `[since 6.9]`

The property controls if a 32-bit shadowmap depth buffer should be used for the light.

Default value: `false`

This property was introduced in Qt 6.9.

See also Light::castsShadow.