From 05820d257f7f1ec119f7dff375e0ce962394a018 Mon Sep 17 00:00:00 2001 From: Godot Organization Date: Sat, 19 Oct 2024 03:32:38 +0000 Subject: [PATCH] classref: Sync with current master branch (44fa552) --- classes/class_cpuparticles3d.rst | 14 ++++++++++++++ classes/class_editorexportplatformmacos.rst | 19 +++++++++++++++++++ classes/class_environment.rst | 4 +++- classes/class_fastnoiselite.rst | 4 ++-- classes/class_fileaccess.rst | 4 ++-- classes/class_filedialog.rst | 2 +- classes/class_packedvector2array.rst | 2 +- classes/class_projectsettings.rst | 20 ++++++++++++++------ classes/class_renderingserver.rst | 10 +++++----- classes/class_viewport.rst | 18 ++++++++++++++---- 10 files changed, 75 insertions(+), 22 deletions(-) diff --git a/classes/class_cpuparticles3d.rst b/classes/class_cpuparticles3d.rst index 503f30806ec..15a207367c0 100644 --- a/classes/class_cpuparticles3d.rst +++ b/classes/class_cpuparticles3d.rst @@ -198,6 +198,8 @@ Methods .. table:: :widths: auto + +---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`AABB` | :ref:`capture_aabb`\ (\ ) |const| | +---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`convert_from_particles`\ (\ particles\: :ref:`Node`\ ) | +---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -1813,6 +1815,18 @@ Grow the box if particles suddenly appear/disappear when the node enters/exits t Method Descriptions ------------------- +.. _class_CPUParticles3D_method_capture_aabb: + +.. rst-class:: classref-method + +:ref:`AABB` **capture_aabb**\ (\ ) |const| :ref:`🔗` + +Returns the axis-aligned bounding box that contains all the particles that are active in the current frame. + +.. rst-class:: classref-item-separator + +---- + .. _class_CPUParticles3D_method_convert_from_particles: .. rst-class:: classref-method diff --git a/classes/class_editorexportplatformmacos.rst b/classes/class_editorexportplatformmacos.rst index 911bc2c7c7d..0c91acdf243 100644 --- a/classes/class_editorexportplatformmacos.rst +++ b/classes/class_editorexportplatformmacos.rst @@ -70,6 +70,8 @@ Properties +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`codesign/custom_options` | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`codesign/entitlements/additional` | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`codesign/entitlements/address_book` | +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`codesign/entitlements/allow_dyld_environment_variables` | @@ -753,6 +755,23 @@ Array of the additional command line arguments passed to the code signing tool. ---- +.. _class_EditorExportPlatformMacOS_property_codesign/entitlements/additional: + +.. rst-class:: classref-property + +:ref:`String` **codesign/entitlements/additional** :ref:`🔗` + +Additional data added to the root ```` section of the `.entitlements `__ file. The value should be an XML section with pairs of key-value elements, e.g.: + +.. code:: text + + key_name + value + +.. rst-class:: classref-item-separator + +---- + .. _class_EditorExportPlatformMacOS_property_codesign/entitlements/address_book: .. rst-class:: classref-property diff --git a/classes/class_environment.rst b/classes/class_environment.rst index a4da483fba9..63f7a9487d9 100644 --- a/classes/class_environment.rst +++ b/classes/class_environment.rst @@ -840,10 +840,12 @@ The background mode. See :ref:`BGMode` for possible val - |void| **set_fog_aerial_perspective**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_fog_aerial_perspective**\ (\ ) -If set above ``0.0`` (exclusive), blends between the fog's color and the color of the background :ref:`Sky`. This has a small performance cost when set above ``0.0``. Must have :ref:`background_mode` set to :ref:`BG_SKY`. +If set above ``0.0`` (exclusive), blends between the fog's color and the color of the background :ref:`Sky`, as read from the radiance cubemap. This has a small performance cost when set above ``0.0``. Must have :ref:`background_mode` set to :ref:`BG_SKY`. This is useful to simulate `aerial perspective `__ in large scenes with low density fog. However, it is not very useful for high-density fog, as the sky will shine through. When set to ``1.0``, the fog color comes completely from the :ref:`Sky`. If set to ``0.0``, aerial perspective is disabled. +Notice that this does not sample the :ref:`Sky` directly, but rather the radiance cubemap. The cubemap is sampled at a mipmap level depending on the depth of the rendered pixel; the farther away, the higher the resolution of the sampled mipmap. This results in the actual color being a blurred version of the sky, with more blur closer to the camera. The highest mipmap resolution is used at a depth of :ref:`Camera3D.far`. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_fastnoiselite.rst b/classes/class_fastnoiselite.rst index 130ca392e4e..e7281aea36f 100644 --- a/classes/class_fastnoiselite.rst +++ b/classes/class_fastnoiselite.rst @@ -130,7 +130,7 @@ Cellular includes both Worley noise and Voronoi diagrams which creates various r :ref:`NoiseType` **TYPE_SIMPLEX** = ``0`` -As opposed to :ref:`TYPE_PERLIN`, gradients exist in a simplex lattice rather than a grid lattice, avoiding directional artifacts. +As opposed to :ref:`TYPE_PERLIN`, gradients exist in a simplex lattice rather than a grid lattice, avoiding directional artifacts. Internally uses FastNoiseLite's OpenSimplex2 noise type. .. _class_FastNoiseLite_constant_TYPE_SIMPLEX_SMOOTH: @@ -138,7 +138,7 @@ As opposed to :ref:`TYPE_PERLIN`, grad :ref:`NoiseType` **TYPE_SIMPLEX_SMOOTH** = ``1`` -Modified, higher quality version of :ref:`TYPE_SIMPLEX`, but slower. +Modified, higher quality version of :ref:`TYPE_SIMPLEX`, but slower. Internally uses FastNoiseLite's OpenSimplex2S noise type. .. rst-class:: classref-item-separator diff --git a/classes/class_fileaccess.rst b/classes/class_fileaccess.rst index 73a099ac549..40dc2c1bee5 100644 --- a/classes/class_fileaccess.rst +++ b/classes/class_fileaccess.rst @@ -1185,7 +1185,7 @@ Stores a floating-point number as 32 bits in the file. |void| **store_line**\ (\ line\: :ref:`String`\ ) :ref:`🔗` -Appends ``line`` to the file followed by a line return character (``\n``), encoding the text as UTF-8. +Stores ``line`` in the file followed by a newline character (``\n``), encoding the text as UTF-8. .. rst-class:: classref-item-separator @@ -1223,7 +1223,7 @@ Stores a floating-point number in the file. |void| **store_string**\ (\ string\: :ref:`String`\ ) :ref:`🔗` -Appends ``string`` to the file without a line return, encoding the text as UTF-8. +Stores ``string`` in the file without a newline character (``\n``), encoding the text as UTF-8. \ **Note:** This method is intended to be used to write text files. The string is stored as a UTF-8 encoded buffer without string length or terminating zero, which means that it can't be loaded back easily. If you want to store a retrievable string in a binary file, consider using :ref:`store_pascal_string` instead. For retrieving strings from a text file, you can use ``get_buffer(length).get_string_from_utf8()`` (if you know the length) or :ref:`get_as_text`. diff --git a/classes/class_filedialog.rst b/classes/class_filedialog.rst index 4ba9e0555a8..b5c7225d626 100644 --- a/classes/class_filedialog.rst +++ b/classes/class_filedialog.rst @@ -496,7 +496,7 @@ If ``true``, the dialog will show hidden files. - |void| **set_use_native_dialog**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **get_use_native_dialog**\ (\ ) -If ``true``, :ref:`access` is set to :ref:`ACCESS_FILESYSTEM`, and it is supported by the current :ref:`DisplayServer`, OS native dialog will be used instead of custom one. +If ``true``, and if supported by the current :ref:`DisplayServer`, OS native dialog will be used instead of custom one. \ **Note:** On Linux and macOS, sandboxed apps always use native dialogs to access the host file system. diff --git a/classes/class_packedvector2array.rst b/classes/class_packedvector2array.rst index 242e8505bd0..d9c5ea19fb6 100644 --- a/classes/class_packedvector2array.rst +++ b/classes/class_packedvector2array.rst @@ -19,7 +19,7 @@ Description An array specifically designed to hold :ref:`Vector2`. Packs data tightly, so it saves memory for large array sizes. -\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. :ref:`PackedVector3Array` versus ``Array[Vector2]``). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as :ref:`Array.map`. Typed arrays are in turn faster to iterate on and modify than untyped arrays. +\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. **PackedVector2Array** versus ``Array[Vector2]``). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as :ref:`Array.map`. Typed arrays are in turn faster to iterate on and modify than untyped arrays. \ **Note:** Packed arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use :ref:`duplicate`. This is *not* the case for built-in properties and methods. The returned packed array of these are a copies, and changing it will *not* affect the original value. To update a built-in property you need to modify the returned array, and then assign it to the property again. diff --git a/classes/class_projectsettings.rst b/classes/class_projectsettings.rst index 61386b707ca..ded3b5d3e1e 100644 --- a/classes/class_projectsettings.rst +++ b/classes/class_projectsettings.rst @@ -9782,10 +9782,12 @@ If ``true``, vertices of :ref:`CanvasItem` nodes will snap to :ref:`int` **rendering/anti_aliasing/quality/msaa_2d** = ``0`` :ref:`🔗` -Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. This has no effect on shader-induced aliasing or texture aliasing. +Sets the number of multisample antialiasing (MSAA) samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. This has no effect on shader-induced aliasing or texture aliasing. \ **Note:** MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. +\ **Note:** This property is only read when the project starts. To set the number of 2D MSAA samples at runtime, set :ref:`Viewport.msaa_2d` or use :ref:`RenderingServer.viewport_set_msaa_2d`. + .. rst-class:: classref-item-separator ---- @@ -9796,7 +9798,9 @@ Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of tw :ref:`int` **rendering/anti_aliasing/quality/msaa_3d** = ``0`` :ref:`🔗` -Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. See also :ref:`rendering/scaling_3d/mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. +Sets the number of multisample antialiasing (MSAA) samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. See also :ref:`rendering/scaling_3d/mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. + +\ **Note:** This property is only read when the project starts. To set the number of 3D MSAA samples at runtime, set :ref:`Viewport.msaa_3d` or use :ref:`RenderingServer.viewport_set_msaa_3d`. .. rst-class:: classref-item-separator @@ -9814,6 +9818,8 @@ Another way to combat specular aliasing is to enable :ref:`rendering/anti_aliasi \ **Note:** Screen-space antialiasing is only supported in the Forward+ and Mobile rendering methods, not Compatibility. +\ **Note:** This property is only read when the project starts. To set the screen-space antialiasing mode at runtime, set :ref:`Viewport.screen_space_aa` on the root :ref:`Viewport` instead, or use :ref:`RenderingServer.viewport_set_screen_space_aa`. + .. rst-class:: classref-item-separator ---- @@ -9828,7 +9834,7 @@ If ``true``, uses a fast post-processing filter to make banding significantly le In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. -\ **Note:** This property is only read when the project starts. To set debanding at run-time, set :ref:`Viewport.use_debanding` on the root :ref:`Viewport` instead. +\ **Note:** This property is only read when the project starts. To set debanding at runtime, set :ref:`Viewport.use_debanding` on the root :ref:`Viewport` instead, or use :ref:`RenderingServer.viewport_set_use_debanding`. .. rst-class:: classref-item-separator @@ -9840,12 +9846,14 @@ In some cases, debanding may introduce a slightly noticeable dithering pattern. :ref:`bool` **rendering/anti_aliasing/quality/use_taa** = ``false`` :ref:`🔗` -Enables Temporal Anti-Aliasing for the default screen :ref:`Viewport`. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. Enabling TAA can make the image blurrier, which is partially counteracted by automatically using a negative mipmap LOD bias (see :ref:`rendering/textures/default_filters/texture_mipmap_bias`). +Enables temporal antialiasing for the default screen :ref:`Viewport`. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. Enabling TAA can make the image blurrier, which is partially counteracted by automatically using a negative mipmap LOD bias (see :ref:`rendering/textures/default_filters/texture_mipmap_bias`). \ **Note:** The implementation is not complete yet. Some visual instances such as particles and skinned meshes may show ghosting artifacts in motion. \ **Note:** TAA is only supported in the Forward+ rendering method, not Mobile or Compatibility. +\ **Note:** This property is only read when the project starts. To set TAA at runtime, set :ref:`Viewport.use_taa` on the root :ref:`Viewport` instead, or use :ref:`RenderingServer.viewport_set_use_taa`. + .. rst-class:: classref-item-separator ---- @@ -11780,9 +11788,9 @@ If ``true``, the GPU texture compressor will cache the local RenderingDevice and If ``true``, the texture importer will utilize the GPU for compressing textures, improving the import time of large images. -\ **Note:** This setting requires either Vulkan or D3D12 available as a rendering backend. +\ **Note:** This only functions on a device which supports either Vulkan, D3D12, or Metal available as a rendering backend. -\ **Note:** Currently this only affects BC1 and BC6H compression, which are used on Desktop and Console for fully opaque and HDR images respectively. +\ **Note:** Currently this only affects certain compressed formats (BC1, BC4, and BC6), all of which are exclusive to desktop platforms and consoles. .. rst-class:: classref-item-separator diff --git a/classes/class_renderingserver.rst b/classes/class_renderingserver.rst index b5473b3b97a..6e5226a106d 100644 --- a/classes/class_renderingserver.rst +++ b/classes/class_renderingserver.rst @@ -11854,7 +11854,7 @@ Sets the measurement for the given ``viewport`` RID (obtained using :ref:`Viewpo |void| **viewport_set_msaa_2d**\ (\ viewport\: :ref:`RID`, msaa\: :ref:`ViewportMSAA`\ ) :ref:`🔗` -Sets the multisample anti-aliasing mode for 2D/Canvas on the specified ``viewport`` RID. See :ref:`ViewportMSAA` for options. +Sets the multisample antialiasing mode for 2D/Canvas on the specified ``viewport`` RID. See :ref:`ViewportMSAA` for options. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/msaa_2d` or :ref:`Viewport.msaa_2d`. .. rst-class:: classref-item-separator @@ -11866,7 +11866,7 @@ Sets the multisample anti-aliasing mode for 2D/Canvas on the specified ``viewpor |void| **viewport_set_msaa_3d**\ (\ viewport\: :ref:`RID`, msaa\: :ref:`ViewportMSAA`\ ) :ref:`🔗` -Sets the multisample anti-aliasing mode for 3D on the specified ``viewport`` RID. See :ref:`ViewportMSAA` for options. +Sets the multisample antialiasing mode for 3D on the specified ``viewport`` RID. See :ref:`ViewportMSAA` for options. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/msaa_3d` or :ref:`Viewport.msaa_3d`. .. rst-class:: classref-item-separator @@ -11990,7 +11990,7 @@ Sets a viewport's scenario. The scenario contains information about environment |void| **viewport_set_screen_space_aa**\ (\ viewport\: :ref:`RID`, mode\: :ref:`ViewportScreenSpaceAA`\ ) :ref:`🔗` -Sets the viewport's screen-space antialiasing mode. +Sets the viewport's screen-space antialiasing mode. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa` or :ref:`Viewport.screen_space_aa`. .. rst-class:: classref-item-separator @@ -12088,7 +12088,7 @@ Sets when the viewport should be updated. See :ref:`ViewportUpdateMode`, enable\: :ref:`bool`\ ) :ref:`🔗` -If ``true``, enables debanding on the specified viewport. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding`. +If ``true``, enables debanding on the specified viewport. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding` or :ref:`Viewport.use_debanding`. .. rst-class:: classref-item-separator @@ -12126,7 +12126,7 @@ If ``true``, enables occlusion culling on the specified viewport. Equivalent to |void| **viewport_set_use_taa**\ (\ viewport\: :ref:`RID`, enable\: :ref:`bool`\ ) :ref:`🔗` -If ``true``, use Temporal Anti-Aliasing. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_taa`. +If ``true``, use temporal antialiasing. Equivalent to :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_taa` or :ref:`Viewport.use_taa`. .. rst-class:: classref-item-separator diff --git a/classes/class_viewport.rst b/classes/class_viewport.rst index 1d9186aed07..305cd1bdbdf 100644 --- a/classes/class_viewport.rst +++ b/classes/class_viewport.rst @@ -1337,7 +1337,9 @@ To control this property on the root viewport, set the :ref:`ProjectSettings.ren - |void| **set_msaa_2d**\ (\ value\: :ref:`MSAA`\ ) - :ref:`MSAA` **get_msaa_2d**\ (\ ) -The multisample anti-aliasing mode for 2D/Canvas rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of 2 or 4 is best unless targeting very high-end systems. This has no effect on shader-induced aliasing or texture aliasing. +The multisample antialiasing mode for 2D/Canvas rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of :ref:`MSAA_2X` or :ref:`MSAA_4X` is best unless targeting very high-end systems. This has no effect on shader-induced aliasing or texture aliasing. + +See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/msaa_2d` and :ref:`RenderingServer.viewport_set_msaa_2d`. .. rst-class:: classref-item-separator @@ -1354,7 +1356,9 @@ The multisample anti-aliasing mode for 2D/Canvas rendering. A higher number resu - |void| **set_msaa_3d**\ (\ value\: :ref:`MSAA`\ ) - :ref:`MSAA` **get_msaa_3d**\ (\ ) -The multisample anti-aliasing mode for 3D rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of 2 or 4 is best unless targeting very high-end systems. See also bilinear scaling 3d :ref:`scaling_3d_mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. +The multisample antialiasing mode for 3D rendering. A higher number results in smoother edges at the cost of significantly worse performance. A value of :ref:`MSAA_2X` or :ref:`MSAA_4X` is best unless targeting very high-end systems. See also bilinear scaling 3d :ref:`scaling_3d_mode` for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. + +See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/msaa_3d` and :ref:`RenderingServer.viewport_set_msaa_3d`. .. rst-class:: classref-item-separator @@ -1595,6 +1599,8 @@ To control this property on the root viewport, set the :ref:`ProjectSettings.ren Sets the screen-space antialiasing method used. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry. +See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa` and :ref:`RenderingServer.viewport_set_screen_space_aa`. + .. rst-class:: classref-item-separator ---- @@ -1720,10 +1726,12 @@ If ``true``, the viewport should render its background as transparent. - |void| **set_use_debanding**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_using_debanding**\ (\ ) -If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode` is :ref:`Environment.BG_CANVAS`. See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding`. +If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode` is :ref:`Environment.BG_CANVAS`. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger. +See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_debanding` and :ref:`RenderingServer.viewport_set_use_debanding`. + .. rst-class:: classref-item-separator ---- @@ -1779,10 +1787,12 @@ If ``true``, :ref:`OccluderInstance3D` nodes will be u - |void| **set_use_taa**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_using_taa**\ (\ ) -Enables Temporal Anti-Aliasing for this viewport. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. +Enables temporal antialiasing for this viewport. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. \ **Note:** The implementation is not complete yet, some visual instances such as particles and skinned meshes may show artifacts. +See also :ref:`ProjectSettings.rendering/anti_aliasing/quality/use_taa` and :ref:`RenderingServer.viewport_set_use_taa`. + .. rst-class:: classref-item-separator ----