godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

classref: Sync with current master branch (f87858a8f)

Browse Source
This commit is contained in:
Yuri Sizov
2022-12-05 20:38:58 +03:00
parent 913ff5e602
commit a7745c4cc4
843 changed files with 158186 additions and 80821 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
classes/class_cameraattributesphysical.rst
View File

@@ -14,182 +14,214 @@ CameraAttributesPhysical
Physically-based camera settings.
.. rst-class:: classref-introduction-group
Description
-----------
``CameraAttributesPhysical`` is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field.
**CameraAttributesPhysical** is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field.
When used in a :ref:`WorldEnvironment<class_WorldEnvironment>` it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own :ref:`CameraAttributes<class_CameraAttributes>`, including the editor camera. When used in a :ref:`Camera3D<class_Camera3D>` it will override any :ref:`CameraAttributes<class_CameraAttributes>` set in the :ref:`WorldEnvironment<class_WorldEnvironment>` and will override the :ref:`Camera3D<class_Camera3D>`\ s :ref:`Camera3D.far<class_Camera3D_property_far>`, :ref:`Camera3D.near<class_Camera3D_property_near>`, :ref:`Camera3D.fov<class_Camera3D_property_fov>`, and :ref:`Camera3D.keep_aspect<class_Camera3D_property_keep_aspect>` properties. When used in :ref:`VoxelGI<class_VoxelGI>` or :ref:`LightmapGI<class_LightmapGI>`, only the exposure settings will be used.
The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation.
.. rst-class:: classref-reftable-group
Properties
----------
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`auto_exposure_max_exposure_value<class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value>` | ``10.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`auto_exposure_min_exposure_value<class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value>` | ``-8.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`exposure_aperture<class_CameraAttributesPhysical_property_exposure_aperture>` | ``16.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`exposure_shutter_speed<class_CameraAttributesPhysical_property_exposure_shutter_speed>` | ``100.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_far<class_CameraAttributesPhysical_property_frustum_far>` | ``4000.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_focal_length<class_CameraAttributesPhysical_property_frustum_focal_length>` | ``35.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_focus_distance<class_CameraAttributesPhysical_property_frustum_focus_distance>` | ``10.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_near<class_CameraAttributesPhysical_property_frustum_near>` | ``0.05`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
.. table::
:widths: auto
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`auto_exposure_max_exposure_value<class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value>` | ``10.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`auto_exposure_min_exposure_value<class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value>` | ``-8.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`exposure_aperture<class_CameraAttributesPhysical_property_exposure_aperture>` | ``16.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`exposure_shutter_speed<class_CameraAttributesPhysical_property_exposure_shutter_speed>` | ``100.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_far<class_CameraAttributesPhysical_property_frustum_far>` | ``4000.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_focal_length<class_CameraAttributesPhysical_property_frustum_focal_length>` | ``35.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_focus_distance<class_CameraAttributesPhysical_property_frustum_focus_distance>` | ``10.0`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>` | :ref:`frustum_near<class_CameraAttributesPhysical_property_frustum_near>` | ``0.05`` |
+---------------------------+-------------------------------------------------------------------------------------------------------------------+------------+
.. rst-class:: classref-reftable-group
Methods
-------
+---------------------------+-----------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_fov<class_CameraAttributesPhysical_method_get_fov>` **(** **)** |const| |
+---------------------------+-----------------------------------------------------------------------------------+
.. table::
:widths: auto
+---------------------------+-----------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_fov<class_CameraAttributesPhysical_method_get_fov>` **(** **)** |const| |
+---------------------------+-----------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Property Descriptions
---------------------
.. _class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value:
- :ref:`float<class_float>` **auto_exposure_max_exposure_value**
.. rst-class:: classref-property
+-----------+---------------------------------------------+
| *Default* | ``10.0`` |
+-----------+---------------------------------------------+
| *Setter* | set_auto_exposure_max_exposure_value(value) |
+-----------+---------------------------------------------+
| *Getter* | get_auto_exposure_max_exposure_value() |
+-----------+---------------------------------------------+
:ref:`float<class_float>` **auto_exposure_max_exposure_value** = ``10.0``
.. rst-class:: classref-property-setget
- void **set_auto_exposure_max_exposure_value** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_auto_exposure_max_exposure_value** **(** **)**
The maximum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value:
- :ref:`float<class_float>` **auto_exposure_min_exposure_value**
.. rst-class:: classref-property
+-----------+---------------------------------------------+
| *Default* | ``-8.0`` |
+-----------+---------------------------------------------+
| *Setter* | set_auto_exposure_min_exposure_value(value) |
+-----------+---------------------------------------------+
| *Getter* | get_auto_exposure_min_exposure_value() |
+-----------+---------------------------------------------+
:ref:`float<class_float>` **auto_exposure_min_exposure_value** = ``-8.0``
.. rst-class:: classref-property-setget
- void **set_auto_exposure_min_exposure_value** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_auto_exposure_min_exposure_value** **(** **)**
The minimum luminance luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_exposure_aperture:
- :ref:`float<class_float>` **exposure_aperture**
.. rst-class:: classref-property
+-----------+---------------------+
| *Default* | ``16.0`` |
+-----------+---------------------+
| *Setter* | set_aperture(value) |
+-----------+---------------------+
| *Getter* | get_aperture() |
+-----------+---------------------+
:ref:`float<class_float>` **exposure_aperture** = ``16.0``
.. rst-class:: classref-property-setget
- void **set_aperture** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_aperture** **(** **)**
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. Default is appropriate for outdoors at daytime (i.e. for use with a default :ref:`DirectionalLight3D<class_DirectionalLight3D>`), for indoor lighting, a value between 2 and 4 is more appropriate.
Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units<class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units>` is enabled.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_exposure_shutter_speed:
- :ref:`float<class_float>` **exposure_shutter_speed**
.. rst-class:: classref-property
+-----------+--------------------------+
| *Default* | ``100.0`` |
+-----------+--------------------------+
| *Setter* | set_shutter_speed(value) |
+-----------+--------------------------+
| *Getter* | get_shutter_speed() |
+-----------+--------------------------+
:ref:`float<class_float>` **exposure_shutter_speed** = ``100.0``
.. rst-class:: classref-property-setget
- void **set_shutter_speed** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_shutter_speed** **(** **)**
Time for shutter to open and close, measured in seconds. A higher value will let in more light leading to a brighter image, while a lower amount will let in less light leading to a darker image.
Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units<class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units>` is enabled.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_frustum_far:
- :ref:`float<class_float>` **frustum_far**
.. rst-class:: classref-property
+-----------+----------------+
| *Default* | ``4000.0`` |
+-----------+----------------+
| *Setter* | set_far(value) |
+-----------+----------------+
| *Getter* | get_far() |
+-----------+----------------+
:ref:`float<class_float>` **frustum_far** = ``4000.0``
.. rst-class:: classref-property-setget
- void **set_far** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_far** **(** **)**
Override value for :ref:`Camera3D.far<class_Camera3D_property_far>`. Used internally when calculating depth of field. When attached to a :ref:`Camera3D<class_Camera3D>` as its :ref:`Camera3D.attributes<class_Camera3D_property_attributes>`, it will override the :ref:`Camera3D.far<class_Camera3D_property_far>` property.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_frustum_focal_length:
- :ref:`float<class_float>` **frustum_focal_length**
.. rst-class:: classref-property
+-----------+-------------------------+
| *Default* | ``35.0`` |
+-----------+-------------------------+
| *Setter* | set_focal_length(value) |
+-----------+-------------------------+
| *Getter* | get_focal_length() |
+-----------+-------------------------+
:ref:`float<class_float>` **frustum_focal_length** = ``35.0``
.. rst-class:: classref-property-setget
- void **set_focal_length** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_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 meaning more objects will be in focus. When attached to a :ref:`Camera3D<class_Camera3D>` as its :ref:`Camera3D.attributes<class_Camera3D_property_attributes>`, it will override the :ref:`Camera3D.fov<class_Camera3D_property_fov>` property and the :ref:`Camera3D.keep_aspect<class_Camera3D_property_keep_aspect>` property.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_frustum_focus_distance:
- :ref:`float<class_float>` **frustum_focus_distance**
.. rst-class:: classref-property
+-----------+---------------------------+
| *Default* | ``10.0`` |
+-----------+---------------------------+
| *Setter* | set_focus_distance(value) |
+-----------+---------------------------+
| *Getter* | get_focus_distance() |
+-----------+---------------------------+
:ref:`float<class_float>` **frustum_focus_distance** = ``10.0``
.. rst-class:: classref-property-setget
- void **set_focus_distance** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_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 :ref:`frustum_focal_length<class_CameraAttributesPhysical_property_frustum_focal_length>`.
.. rst-class:: classref-item-separator
----
.. _class_CameraAttributesPhysical_property_frustum_near:
- :ref:`float<class_float>` **frustum_near**
.. rst-class:: classref-property
+-----------+-----------------+
| *Default* | ``0.05`` |
+-----------+-----------------+
| *Setter* | set_near(value) |
+-----------+-----------------+
| *Getter* | get_near() |
+-----------+-----------------+
:ref:`float<class_float>` **frustum_near** = ``0.05``
.. rst-class:: classref-property-setget
- void **set_near** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_near** **(** **)**
Override value for :ref:`Camera3D.near<class_Camera3D_property_near>`. Used internally when calculating depth of field. When attached to a :ref:`Camera3D<class_Camera3D>` as its :ref:`Camera3D.attributes<class_Camera3D_property_attributes>`, it will override the :ref:`Camera3D.near<class_Camera3D_property_near>` property.
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Method Descriptions
-------------------
.. _class_CameraAttributesPhysical_method_get_fov:
- :ref:`float<class_float>` **get_fov** **(** **)** |const|
.. rst-class:: classref-method
:ref:`float<class_float>` **get_fov** **(** **)** |const|
Returns the vertical field of view that corresponds to the :ref:`frustum_focal_length<class_CameraAttributesPhysical_property_frustum_focal_length>`. This value is calculated internally whenever :ref:`frustum_focal_length<class_CameraAttributesPhysical_property_frustum_focal_length>` is changed.