Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

Unités de lumière et de caméra physiques

Why use physical light and camera units?

Godot uses arbitrary units for many physical properties that apply to light like color, energy, camera field of view, and exposure. By default, these properties use arbitrary units, because using accurate physical units comes with a few tradeoffs that aren't worth it for many games. As Godot favors ease of use by default, physical light units are disabled by default.

Advantages of physical units

If you aim for photorealism in your project, using real world units as a basis can help make things easier to adjust. References for real world materials, lights and scene brightness are wildly available on websites such as Physically Based.

Using real world units in Godot can also be useful when porting a scene from other 3D software that uses physical light units (such as Blender).

Désavantages des unités physiques

The biggest disadvantage of using physical light units is you will have to pay close attention to the dynamic range in use at a given time. You can run into floating point precision errors when mixing very high light intensities with very low light intensities.

In practice, this means that you will have to manually manage your exposure settings to ensure that you aren't over-exposing or under-exposing your scene too much. Auto-exposure can help you balance the light in a scene to bring it into a normal range, but it can't recover lost precision from a dynamic range that is too high.

Using physical light and camera units will not automatically make your project look better. Sometimes, moving away from realism can actually make a scene look better to the human eye. Also, using physical units requires a greater amount of rigor compared to non-physical units. Most benefits of physical units can only be obtained if the units are correctly set to match real world reference.

Note

Physical light units are only available in 3D rendering, not 2D.

Setting up physical light units

Physical light units can be enabled separately from physical camera units.

To enable physical light units correctly, there are 4 steps required:

1. Activez le paramètre du projet.

2. Configurez la caméra.

3. Configurez l'environnement.

4. Configurez les nœuds Light3D.

Since physical light and camera units only require a handful of calculations to handle unit conversion, enabling them doesn't have any noticeable performance impact on the CPU. However, on the GPU side, physical camera units currently enforce depth of field. This has a moderate performance impact. To alleviate this performance impact, depth of field quality can be decreased in the advanced Project Settings.

Enable the project setting

Open the Project Settings, enable the Advanced toggle then enable Rendering > Lights And Shadows > Use Physical Light Units. Restart the editor.

Configure the camera

Avertissement

When physical light units are enabled and if you have a WorldEnvironment node in your scene (i.e. the editor Environment is disabled), you must have a CameraAttributes resource assigned to the WorldEnvironment node. Otherwise, the 3D editor viewport will appear extremely bright if you have a visible DirectionalLight3D node.

On the Camera3D node, you can add a CameraAttributes resource to its Attributes property. This resource is used to control the camera's depth of field and exposure. When using CameraAttributesPhysical, its focal length property is also used to adjust the camera's field of view.

Lorsque les unités de lumière physique sont activées, les propriétés supplémentaires suivantes sont disponibles dans la section Exposure de CameraAttributesPhysical :

• Aperture: The size of the aperture of the camera, measured in f-stops. An f-stop is a unitless ratio between the focal length of the camera and the diameter of the aperture. A high aperture setting will result in a smaller aperture which leads to a dimmer image and sharper focus. A low aperture results in a wide aperture which lets in more light resulting in a brighter, less-focused image.

• Shutter Speed: The time for shutter to open and close, measured in inverse seconds (1/N). A lower value will let in more light leading to a brighter image, while a higher value will let in less light leading to a darker image. When getting or setting this property with a script, the unit is in seconds instead of inverse seconds.

• Sensitivity: The sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. When auto exposure is enabled, this can be used as a method of exposure compensation. Doubling the value will increase the exposure value (measured in EV100) by 1 stop.

• Multiplier: A non-physical exposure multiplier. Higher values will increase the scene's brightness. This can be used for post-processing adjustments or for animation purposes.

The default Aperture value of 16 f-stops is appropriate for outdoors at daytime (i.e. for use with a default DirectionalLight3D). For indoor lighting, a value between 2 and 4 is more appropriate.

Typical shutter speed used in photography and movie production is 1/50 (0.02 seconds). Night-time photography generally uses a shutter around 1/10 (0.1 seconds), while sports photography uses a shutter speed between 1/250 (0.004 seconds) and 1/1000 (0.001 seconds) to reduce motion blur.

In real life, sensitivity is usually set between 50 ISO and 400 ISO for daytime outdoor photography depending on weather conditions. Higher values are used for indoor or night-time photography.

Note

Unlike real life cameras, the adverse effects of increasing ISO sensitivity or decreasing shutter speed (such as visible grain or light trails) are not simulated in Godot.

See Setting up physical camera units for a description of CameraAttributesPhysical properties that are also available when not using physical light units.

Configure the environment

Avertissement

The default configuration is designed for daytime outdoor scenes. Night-time and indoor scenes will need adjustments to the DirectionalLight3D and WorldEnvironment background intensity to look correct. Otherwise, positional lights will be barely visible at their default intensity.

If you haven't added a WorldEnvironment and Camera3D node to the current scene yet, do so now by clicking the 3 vertical dots at the top of the 3D editor viewport. Click Add Sun to Scene, open the dialog again then click Add Environment to Scene.

After enabling physical light units, a new property becomes available to edit in the Environment resource:

• Background Intensity: The background sky's intensity in nits (candelas per square meter). This also affects ambient and reflected light if their respective modes are set to Background. If a custom Background Energy is set, this energy is multiplied by the intensity.

Configure the light nodes

After enabling physical light units, 2 new properties become available in Light3D nodes:

• Intensité : L'intensité de la lumière en`lux <https://fr.wikipedia.org/wiki/Lux_(unit%C3%A9)>`__ (DirectionalLight3D) ou en lumens (OmniLight3D/SpotLight3D). Si une Energy personnalisée est définie, cette énergie est multipliée par l'intensité.

• Température : La température de couleur de la lumière définie en Kelvin. Si une Color personnalisée est définie, cette couleur est multipliée par la température de couleur.

Intensité OmniLight3D/SpotLight3D

Les lumens sont une mesure du flux lumineux, qui est la quantité totale de lumière visible émise par une source lumineuse par unité de temps.

Pour les SpotLight3D, nous supposons que la zone à l'extérieur du cône visible est entourée d'un matériau absorbant parfaitement la lumière. Par conséquent, la luminosité apparente de la zone de cône ne change pas quand le cône augmente et diminue de taille.

Une lampe de maison typique peut aller de 600 lumens à 1200 lumens. Une bougie est d'environ 13 lumens, tandis qu'un réverbère peut être d'environ 60000 lumens.

DirectionalLight3D intensity

Le lux est une mesure de flux lumineux par zone unitaire, il est égal à un lumen par mètre carré. Le lux est la mesure de combien de lumière frappe une surface à un moment donné.

With DirectionalLight3D, on a clear sunny day, a surface in direct sunlight may receive approximately 100000 lux. A typical room in a home may receive approximately 50 lux, while the moonlit ground may receive approximately 0.1 lux.

Color temperature

6500 Kelvin est blanc. Des valeurs plus élevées entraînent des couleurs plus froides (plus bleues), tandis que des valeurs plus basses entraînent des couleurs plus chaudes (plus orange).

Le soleil sur une journée nuageuse est d'environ 6500 Kelvin. En jour clair, le soleil se situe entre 5500 et 6000 Kelvin. En jour clair au lever du soleil ou au coucher du soleil, le soleil se trouve à environ 1850 Kelvin.

Diagramme de température de couleur de 1 000 Kelvin (à gauche) à 12 500 Kelvin (à droite)

Other Light3D properties such as Energy and Color remain editable for animation purposes, and when you occasionally need to create lights with non-realistic properties.

Setting up physical camera units

Physical camera units can be enabled separately from physical light units.

After adding a CameraAttributesPhysical resource to the Camera Attributes property of a Camera3D nodes, some properties such as FOV will no longer be editable. Instead, these properties are now governed by the CameraAttributesPhysical's properties, such as focal length and aperture.

CameraAttributesPhysical offers the following properties in its Frustum section:

• Focus Distance: Distance from camera of object that will be in focus, measured in meters. Internally, this will be clamped to be at least 1 millimeter larger than the Focal Length.

• Focal Length: Distance between camera lens and camera aperture, measured in millimeters. Controls field of view and depth of field. A larger focal length will result in a smaller field of view and a narrower depth of field meaning fewer objects will be in focus. A smaller focal length will result in a wider field of view and a larger depth of field, which means more objects will be in focus. This property overrides the Camera3D's FOV and Keep Aspect properties, making them read-only in the inspector.

• Near/Far: The near and far clip distances in meters. These behave the same as the Camera3D properties of the same name. Lower Near values allow the camera to display objects that are very close, at the cost of potential precision (Z-fighting) issues in the distance. Higher Far values allow the camera to see further away, also at the cost of potential precision (Z-fighting) issues in the distance.

The default focal length of 35 mm corresponds to a wide angle lens. It still results in a field of view that is noticeably narrower compared to the default "practical" vertical FOV of 75 degrees. This is because non-gaming use cases such as filmmaking and photography favor using a narrower field of view for a more cinematic appearance.

Common focal length values used in filmmaking and photography are:

• Fisheye (ultrawide angle): Below 15 mm. Nearly no depth of field visible.

• Wide angle: Between 15 mm and 50 mm. Reduced depth of field.

• Standard: Between 50 mm and 100 mm. Standard depth of field.

• Telephoto: Greater than 100 mm. Increased depth of field.

Like when using the Keep Height aspect mode, the effective field of view depends on the viewport's aspect ratio, with wider aspect ratios automatically resulting in a wider horizontal field of view.

Automatic exposure adjustment based on the camera's average brightness level can also be enabled in the Auto Exposure section, with the following properties:

• Min Sensitivity: The darkest brightness the camera is allowed to get to, measured in EV100.

• Max Sensitivity: The brightest the camera is allowed to get to, measured in EV100.

• Speed: The speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure. Higher values allow for faster transitions, but the resulting adjustments may look distracting depending on the scene.

• Scale: The scale of the auto exposure effect. Affects the intensity of auto exposure.

EV100 is an exposure value (EV) measured at an ISO sensitivity of 100. See this table for common EV100 values found in real life.