diff --git a/tutorials/3d/environment_and_post_processing.rst b/tutorials/3d/environment_and_post_processing.rst index 0785f2f0c..f6ca1d865 100644 --- a/tutorials/3d/environment_and_post_processing.rst +++ b/tutorials/3d/environment_and_post_processing.rst @@ -173,6 +173,11 @@ The tone mapping options are: between ``6.0`` and ``8.0``. Higher values result in less blown out highlights, but make the scene appear slightly darker as a whole. +.. seealso:: + + See :ref:`doc_physical_light_and_camera_units` if you wish to use real world + units to configure your camera's exposure, field of view and depth of field. + Auto Exposure (HDR) ^^^^^^^^^^^^^^^^^^^ diff --git a/tutorials/3d/img/physical_light_units_color_temperature_chart.webp b/tutorials/3d/img/physical_light_units_color_temperature_chart.webp new file mode 100644 index 000000000..f06f3f884 Binary files /dev/null and b/tutorials/3d/img/physical_light_units_color_temperature_chart.webp differ diff --git a/tutorials/3d/index.rst b/tutorials/3d/index.rst index ae9b30b5d..9e0c23a93 100644 --- a/tutorials/3d/index.rst +++ b/tutorials/3d/index.rst @@ -10,6 +10,7 @@ 3d_rendering_limitations standard_material_3d lights_and_shadows + physical_light_and_camera_units reflection_probes gi_probes baked_lightmaps diff --git a/tutorials/3d/lights_and_shadows.rst b/tutorials/3d/lights_and_shadows.rst index a14bed8f3..fb766abaf 100644 --- a/tutorials/3d/lights_and_shadows.rst +++ b/tutorials/3d/lights_and_shadows.rst @@ -41,6 +41,11 @@ Each one has a specific function: If you don't want disabled objects to cast shadows, adjust the ``cast_shadow`` property on the GeometryInstance to the desired value. +.. seealso:: + + See :ref:`doc_physical_light_and_camera_units` if you wish to use real world + units to configure your lights' intensity and color temperature. + Shadow mapping ^^^^^^^^^^^^^^ diff --git a/tutorials/3d/physical_light_and_camera_units.rst b/tutorials/3d/physical_light_and_camera_units.rst new file mode 100644 index 000000000..a41f0a50a --- /dev/null +++ b/tutorials/3d/physical_light_and_camera_units.rst @@ -0,0 +1,279 @@ +.. _doc_physical_light_and_camera_units: + +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 :ref:`class_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 :ref:`class_CameraAttributes` +resource to its **Attributes** property. This resource is used to control the +camera's depth of field and exposure. When using +:ref:`class_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``). 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 :ref:`doc_physical_light_and_camera_units_setting_up_physical_camera_units` +for a description of CameraAttributesPhysical properties that are also available when +**not** using physical light units. + +Configure the environment +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. warning:: + + 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 :ref:`class_WorldEnvironment` and :ref:`class_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 :ref:`class_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: + +- **Intensity:** The light's intensity in `lux + `__ (DirectionalLight3D) or + `lumens `__ (OmniLight3D/SpotLight3D). + If a custom **Energy** is set, this energy is multiplied by the intensity. +- **Temperature:** The light's *color temperature* defined in Kelvin. + If a custom **Color** is set, this color is multiplied by the color temperature. + +**OmniLight3D/SpotLight3D intensity** + +Lumens are a measure of luminous flux, which is the total amount of visible +light emitted by a light source per unit of time. + +For SpotLight3Ds, we assume that the area outside the visible cone is surrounded +by a perfect light absorbing material. Accordingly, the apparent brightness of +the cone area does *not* change as the cone increases and decreases in size. + +A typical household lightbulb can range from around 600 lumens to 1200 lumens. +A candle is about 13 lumens, while a streetlight can be approximately 60000 lumens. + +**DirectionalLight3D intensity** + +Lux is a measure pf luminous flux per unit area, it is equal to one lumen per +square metre. Lux is the measure of how much light hits a surface at a given +time. + +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 is white. Higher values result in colder (bluer) colors, while lower +values result in warmer (more orange) colors. + +The sun on a cloudy day is approximately 6500 Kelvin. On a clear day, the sun is +between 5500 to 6000 Kelvin. On a clear day at sunrise or sunset, the sun ranges +to around 1850 Kelvin. + +.. figure:: img/physical_light_units_color_temperature_chart.webp + :align: center + :alt: Color temperature chart from 1,000 Kelvin (left) to 12,500 Kelvin (right) + + Color temperature chart from 1,000 Kelvin (left) to 12,500 Kelvin (right) + +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. + +.. _doc_physical_light_and_camera_units_setting_up_physical_camera_units: + +Setting up physical camera units +-------------------------------- + +Physical camera units can be enabled separately from physical light units. + +After adding a :ref:`class_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.