Up to date

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

Physical light and camera units

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).

Disadvantages of physical units

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. Enable the project setting.

  2. Configure the camera.

  3. Configure the environment.

  4. Configure Light3D nodes.

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

Warning

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.

When physical light units are enabled, the following additional properties become available in CameraAttributesPhysical's Exposure section:

  • 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