From 77d4c814c3b53d943eada5b4a59181cd6a265b75 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 27 Jan 2026 18:23:54 +0100 Subject: [PATCH] Complete RenderingServer, ArrayMesh and VoxelGIData class documentation This also updates various related descriptions in other classes. Co-authored-by: Joon --- doc/classes/ArrayMesh.xml | 9 ++ doc/classes/GPUParticles3D.xml | 4 + doc/classes/ImporterMesh.xml | 2 +- doc/classes/OS.xml | 4 +- doc/classes/ParticleProcessMaterial.xml | 5 ++ doc/classes/ProjectSettings.xml | 1 + doc/classes/RenderingServer.xml | 114 +++++++++++++++++++++++- doc/classes/VoxelGIData.xml | 6 ++ 8 files changed, 140 insertions(+), 5 deletions(-) diff --git a/doc/classes/ArrayMesh.xml b/doc/classes/ArrayMesh.xml index 36185dbedf..7e0b418b55 100644 --- a/doc/classes/ArrayMesh.xml +++ b/doc/classes/ArrayMesh.xml @@ -186,6 +186,9 @@ + Updates the attribute buffer of this mesh's surface with the given [param data]. The expected data per attribute is 12 or 8 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector3] or [Vector2] vertices. This value can be determined with [method RenderingServer.mesh_surface_get_format_attribute_stride]. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each attribute. + A [PackedVector3Array] of attribute locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. @@ -194,6 +197,9 @@ + Updates the skin buffer of this mesh's surface with the given [param data]. The expected data per skin is 12 or 8 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector3] or [Vector2] vertices. This value can be determined with [method RenderingServer.mesh_surface_get_format_skin_stride]. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each skin. + A [PackedVector3Array] of skin locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. @@ -202,6 +208,9 @@ + Updates the vertex buffer of this mesh's surface with the given [param data]. The expected data per vertex is 12 or 8 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector3] or [Vector2] vertices. This value can be determined with [method RenderingServer.mesh_surface_get_format_vertex_stride]. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each vertex. + A [PackedVector3Array] of vertex locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index 1dc64c7f63..6e3fae4f47 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -216,12 +216,16 @@ Maximum number of draw passes supported. + Do not align particle transforms relative to the camera or velocity. + Align each particle's Z axis to face the camera. + Align each particle's Y axis to the velocity vector. + Align each particle's Z axis to face the camera and Y axis to the velocity vector. diff --git a/doc/classes/ImporterMesh.xml b/doc/classes/ImporterMesh.xml index 8d4bc028a0..a9c31f0b7e 100644 --- a/doc/classes/ImporterMesh.xml +++ b/doc/classes/ImporterMesh.xml @@ -5,7 +5,7 @@ ImporterMesh is a type of [Resource] analogous to [ArrayMesh]. It contains vertex array-based geometry, divided in [i]surfaces[/i]. Each surface contains a completely separate array and a material used to draw it. Design wise, a mesh with multiple surfaces is preferred to a single surface, because objects created in 3D editing software commonly contain multiple materials. - Unlike its runtime counterpart, [ImporterMesh] contains mesh data before various import steps, such as lod and shadow mesh generation, have taken place. Modify surface data by calling [method clear], followed by [method add_surface] for each surface. + Unlike its runtime counterpart, [ImporterMesh] contains mesh data before various import steps, such as LOD and shadow mesh generation, have taken place. Modify surface data by calling [method clear], followed by [method add_surface] for each surface. diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index ec935fb9d9..0dafc94947 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -910,13 +910,13 @@ - The Vulkan rendering driver. It requires Vulkan 1.0 support and automatically uses features from Vulkan 1.1 and 1.2 if available. + The Vulkan rendering driver. It requires Vulkan 1.0 support and automatically uses features from Vulkan 1.1, 1.2, and 1.3 if available. The OpenGL 3 rendering driver. It uses OpenGL 3.3 Core Profile on desktop platforms, OpenGL ES 3.0 on mobile devices, and WebGL 2.0 on Web. - The Direct3D 12 rendering driver. + The Direct3D 12 rendering driver. It requires the 12_0 feature level and Shader Model 6.0 support. The Metal rendering driver. diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml index 245982bbf5..9c48482f92 100644 --- a/doc/classes/ParticleProcessMaterial.xml +++ b/doc/classes/ParticleProcessMaterial.xml @@ -519,14 +519,19 @@ Use with [method set_param_texture] to set the turbulence influence over the particles life time. + The subemitter is disabled. + The submitter is emitted on the constant interval defined by [member sub_emitter_frequency]. + The subemitter is emitted at the end of the particle's lifetime. + The subemitter is emitted when the particle collides. + The subemitter is emitted when the particle spawns. Represents the size of the [enum SubEmitterMode] enum. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 05d213bbfa..651a246b7b 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -3107,6 +3107,7 @@ The framerate-independent update speed when representing dynamic object lighting from [LightmapProbe]s. Higher values make dynamic object lighting update faster. Higher values can prevent fast-moving objects from having "outdated" indirect lighting displayed on them, at the cost of possible flickering when an object moves from a bright area to a shaded area. + [b]Note:[/b] This property is only read when the project starts. To adjust the BVH build quality at runtime, use [method RenderingServer.lightmap_set_probe_capture_update_speed]. Use 16 bits for the directional shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 50dbb3259c..5b45d7320b 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -739,6 +739,7 @@ + Enables or disables using the light occluder as a signed distance field for 2D particle collision. @@ -990,6 +991,9 @@ + If [param disable] is [code]true[/code], makes 2D rendering ignore the canvas scale defined for each canvas layer. This affects [CanvasLayer]s with the [member CanvasLayer.follow_viewport_enabled] property set to [code]true[/code]. + In the editor, this is set to [code]true[/code] by default, and set to [code]false[/code] when [b]View > Preview Canvas Scale[/b] is enabled at the top of the 2D editor viewport. + [b]Note:[/b] Setting this to [code]true[/code] does not impact the behavior of [member CanvasLayer.scale], [member Node2D.scale], or [member Control.scale]. @@ -2243,24 +2247,28 @@ + Returns the BSP tree data used for accelerating probe lookups. The BSP data is structured as a series of six signed 32-bit values per BSP node in this order: [code]float plane_x[/code], [code]float plane_y[/code], [code]float plane_z[/code], [code]float plane_distance[/code], [code]int32_t over[/code], [code]int32_t under[/code]. An empty leaf is denoted by the value [code]-2147483648[/code] (the minimum 32-bit signed integer). See also [method lightmap_set_probe_capture_data]. + Returns the [i]local space[/i] positions of each lightmap probe capture point. Keep in mind the lightmap instance may have a non-zero transform, which will affect the position of the probe capture points. See also [method lightmap_set_probe_capture_data]. + Returns the L0, L1, and L2 [url=https://en.wikipedia.org/wiki/Spherical_harmonics]spherical harmonics[/url] data for each lightmap probe capture point. This is specified as 9 [Color] values per probe, which means the size of the returned data is always 9 times the number of probe points. See also [method lightmap_set_probe_capture_data]. + Returns the tetrahedralization data used for interpolating between lightmap probe capture points. Each tetrahedron is specified as a series of 4 numbers, each being an index into the probe capture points array returned by [method lightmap_get_probe_capture_points]. See also [method lightmap_set_probe_capture_data]. @@ -2276,6 +2284,7 @@ + Sets the bounds that this lightmap instance should visually affect, both in terms of static lightmap baking and probe-based global illumination. @@ -2286,12 +2295,14 @@ + Sets the probe capture data for the given lightmap instance. See [method lightmap_get_probe_capture_points], [method lightmap_get_probe_capture_sh], [method lightmap_get_probe_capture_tetrahedra], and [method lightmap_get_probe_capture_bsp_tree] for the expected data formats. + The framerate-independent update speed when representing dynamic object lighting from [LightmapProbe]s. Higher values make dynamic object lighting update faster. Higher values can prevent fast-moving objects from having "outdated" indirect lighting displayed on them, at the cost of possible flickering when an object moves from a bright area to a shaded area. See also [member ProjectSettings.rendering/lightmapping/probe_capture/update_speed]. @@ -2299,6 +2310,7 @@ + Sets whether the lightmap instance should be considered as interior (when [param interior] is [code]true[/code]). If the lightmap is marked as interior, environment lighting is ignored when baking lightmaps. @@ -2389,6 +2401,35 @@ + Creates a new surface on the given [param mesh]. Equivalent to [method mesh_add_surface_from_arrays], but takes a single [Dictionary] argument instead of separate arguments. The dictionary must follow this structure: + [codeblock] + { + # Required: + "primitive": RenderingServer.PrimitiveType, + "format": RenderingServer.ArrayFormat, + "vertex_data": PackedByteArray, + "vertex_count": int, + "aabb": AABB, + + # Optional: + "attribute_data": PackedByteArray, + "skin_data": PackedByteArray, + "index_data": PackedByteArray, + "index_count": int, # Required if `index_data` is specified. + "uv_scale": Vector4, + "lods": [ + # Both values are required for each LOD level. + { + "edge_length": float, + "index_data": PackedByteArray, + }, + ], + "bone_aabbs": Array[AABB], + "blend_shape_data": PackedByteArray, + "material": Material, + } + [/codeblock] + See also [method mesh_get_surface], which returns data in the same structure defined above. @@ -2400,6 +2441,14 @@ + Creates a new surface on the given [param mesh]. [method mesh_get_surface_count] will become the surface index for this new surface. + Surfaces are created to be rendered using a [param primitive], which may be any of the values defined in [enum Mesh.PrimitiveType]. + The [param arrays] argument is an array of arrays. Each of the [constant Mesh.ARRAY_MAX] elements contains an array with some of the mesh data for this surface as described by the corresponding member of [enum Mesh.ArrayType] or [code]null[/code] if it is not used by the surface. For example, [code]arrays[0][/code] is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for [constant Mesh.ARRAY_INDEX] if it is used. + The [param blend_shapes] argument is an array of vertex data for each blend shape. Each element is an array of the same structure as [param arrays], but [constant Mesh.ARRAY_VERTEX], [constant Mesh.ARRAY_NORMAL], and [constant Mesh.ARRAY_TANGENT] are set if and only if they are set in [param arrays] and all other entries are [code]null[/code]. + The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used. + The [param compress_format] argument is the bitwise OR of, as required: One value of [enum ArrayFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY]. + See [method ArrayMesh.add_surface_from_arrays] and [method ImporterMesh.add_surface] for higher-level equivalents of this method. + [b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles. @@ -2423,6 +2472,11 @@ + Creates a new mesh with predefined surfaces for it and adds the mesh to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]mesh_*[/code] RenderingServer functions. This method is more efficient for creating meshes with multiple surfaces compared to creating an empty mesh with [method mesh_create] and adding surfaces one by one with [method mesh_add_surface]. + Each element in the [param surfaces] array must follow the same structure as described in [method mesh_add_surface]. The [param blend_shape_count] parameter must match the blend shape data defined in all surfaces. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + To place in a scene, attach this mesh to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent resource is [Mesh]. @@ -2451,6 +2505,7 @@ + Returns a mesh's surface as a dictionary following the same structure as described in [method mesh_add_surface]. @@ -2481,6 +2536,8 @@ + Sets an optional second mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.). + [b]Note:[/b] This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly. @@ -2580,6 +2637,9 @@ + Updates the attribute buffer of the mesh surface with the given [param data]. The expected data per attribute is 8 or 12 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector2] or [Vector3] vertices. This value can be determined with [method mesh_surface_get_format_attribute_stride] instead. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each attribute. + A [PackedVector3Array] of attribute locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. @@ -2599,6 +2659,9 @@ + Updates the skin buffer of the mesh surface with the given [param data]. The expected data per skin is 8 or 12 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector2] or [Vector3] vertices. This value can be determined with [method mesh_surface_get_format_skin_stride] instead. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each skin. + A [PackedVector3Array] of skin locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. @@ -2608,6 +2671,9 @@ + Updates the vertex buffer of the mesh surface with the given [param data]. The expected data per vertex is 8 or 12 bytes (4 bytes per float, 2 floats per [Vector2], and 3 floats per [Vector3]) depending on if the mesh is using [Vector2] or [Vector3] vertices. This value can be determined with [method mesh_surface_get_format_vertex_stride] instead. + The starting point of the updates can be changed with [param offset]. The value of [param offset] should be a multiple of 12 bytes in most cases to align to each vertex. + A [PackedVector3Array] of vertex locations can be converted into a [PackedByteArray] using [method PackedVector3Array.to_byte_array] for use in [param data]. @@ -2619,6 +2685,7 @@ + Sets up the multimesh using the specified data. The number of instances is set by [param instances]. The format of the instance transforms is set by [param transform_format], which should be set according to whether the multimesh is meant to be rendered in 2D or 3D. If [param color_format] is [code]true[/code], each instance will have a color associated with it. If [param custom_data_format] is [code]true[/code], each instance will have a custom data vector associated with it. If [param use_indirect] is [code]true[/code], an indirect command buffer will be created for this multimesh, allowing the instance count to be modified directly on the GPU. See also [method multimesh_get_command_buffer_rd_rid]. @@ -2666,7 +2733,7 @@ 2 - firstIndex; 3 - vertexOffset; 4 - firstInstance; - Non Indexed: + Non-indexed: 0 - vertexCount; 1 - instanceCount; 2 - firstVertex; @@ -3069,6 +3136,7 @@ + Sets the base size for particle collision. Equivalent to [member GPUParticles3D.collision_base_size]. @@ -3165,6 +3233,7 @@ + Sets whether particles should use interpolation between fixed steps. Equivalent to [member GPUParticles3D.interpolate]. @@ -3229,6 +3298,7 @@ + Sets the subemitter particles for the particle system. Equivalent to [member GPUParticles3D.sub_emitter]. @@ -3236,6 +3306,7 @@ + Sets the trail bind poses for the particle system. This specified as an array of [Transform3D]s representing the bind pose for each draw pass. See [member GPUParticles3D.draw_skin], [method Skin.get_bind_count], and [method Skin.get_bind_pose]. Set the value for each draw pass to [constant Transform3D.IDENTITY] to use the default behavior, which is what built-in trails use ([RibbonTrailMesh] and [TubeTrailMesh]). @@ -3252,6 +3323,7 @@ + Sets the transform alignment for the particle system. Equivalent to [member GPUParticles3D.transform_align]. @@ -3563,6 +3635,7 @@ + Allocates data for this skeleton using the number of bones specified in [param bones]. If [param is_2d_skeleton] is [code]true[/code], the skeleton will be treated as a 2D skeleton instead of a 3D skeleton. See also [method skeleton_get_bone_count]. @@ -3610,7 +3683,7 @@ - Returns the number of bones allocated for this skeleton. + Returns the number of bones allocated for this skeleton. See also [method skeleton_allocate_data]. @@ -3618,6 +3691,7 @@ + Sets the base [Transform2D] to use for the specified skeleton. @@ -3825,6 +3899,7 @@ + Returns the resource path (starting with [code]res://[/code] or [code]uid://[/code]) for the specified texture RID. Returns an empty [String] if the resource is built-in. See also [method texture_set_path]. @@ -3874,6 +3949,7 @@ + Sets whether the texture RID should force redrawing when it's visible on screen when [member OS.low_processor_usage_mode] is [code]true[/code]. This is used by [AnimatedTexture] to force redrawing. @@ -3881,6 +3957,8 @@ + Sets the resource path for this texture RID. See also [method texture_get_path]. + [b]Note:[/b] This is purely a hint and does not cause the texture to be automatically saved when set to a [code]res://[/code] path. @@ -3889,6 +3967,7 @@ + Sets the size at which the texture should be [i]displayed[/i] in 2D, ignoring its original size. This does not rescale the texture data itself, only how it is drawn in 2D. Set [param width] and [param height] to 0 to disable the size override. @@ -4367,6 +4446,7 @@ + Sets the AABB of the specified visibility notifier. @@ -4375,6 +4455,7 @@ + Sets the methods to be called when the notifier enters or exits the view. @@ -4388,6 +4469,7 @@ + Allocates and initializes the voxel GI data for the specified [param voxel_gi] RID. [param octree_cells] must be a multiple of 32. [param octree_cells] must be double the size of [param data_cells]. The allocated data can be retrieved later using the various [code]voxel_gi_get_*[/code] methods. @@ -4402,36 +4484,42 @@ + Returns the data cells for the specified voxel GI data instance. See also [method voxel_gi_allocate_data]. + Returns the distance field data for the specified voxel GI data instance. See also [method voxel_gi_allocate_data]. + Returns the level counts for the specified voxel GI data instance. See also [method voxel_gi_allocate_data]. + Returns the octree cell data for the specified voxel GI data instance. See also [method voxel_gi_allocate_data]. + Returns the octree size for the specified voxel GI data instance, which corresponds to the number of subdivisions per axis. This can be viewed in the editor by hovering the [b]Bake VoxelGI[/b] button at the top of the 3D editor viewport when a [VoxelGI] node is selected and looking at the [b]Subdivisions[/b] field in the tooltip. + Returns the transform to cell space for the specified voxel GI data instance. See also [method voxel_gi_allocate_data]. @@ -5028,22 +5116,31 @@ 3D particles. + Do not align particle transforms relative to the camera or velocity. + Align each particle's Z axis to face the camera. + Align each particle's Y axis to the velocity vector. + Align each particle's Z axis to face the camera and Y axis to the velocity vector. + Particle starts at the specified position. + Particle starts with specified rotation and scale. + Particle starts with the specified velocity vector, which defines the emission direction and speed. + Particle starts with specified color. + Particle starts with specified [code]CUSTOM[/code] data. Draw particles in the order that they appear in the particles array. @@ -5058,30 +5155,43 @@ Sort particles based on their distance to the camera. + Sphere attractor type for [GPUParticles3D] (see [GPUParticlesAttractorSphere3D]). + Box attractor type for [GPUParticles3D] (see [GPUParticlesAttractorBox3D]). + Vector field attractor type for [GPUParticles3D] (see [GPUParticlesAttractorVectorField3D]). + Sphere collision type for [GPUParticles3D] (see [GPUParticlesCollisionSphere3D]). + Box collision type for [GPUParticles3D] (see [GPUParticlesCollisionBox3D]). + Signed distance field collision type for [GPUParticles3D] (see [GPUParticlesCollisionSDF3D]). + Heightfield collision type for [GPUParticles3D] (see [GPUParticlesCollisionHeightField3D]). + 256×256 heightfield resolution for [GPUParticlesCollisionHeightField3D]. + 512×512 heightfield resolution for [GPUParticlesCollisionHeightField3D]. + 1024×1024 heightfield resolution for [GPUParticlesCollisionHeightField3D]. + 2048×2048 heightfield resolution for [GPUParticlesCollisionHeightField3D]. + 4096×4096 heightfield resolution for [GPUParticlesCollisionHeightField3D]. + 8192×8192 heightfield resolution for [GPUParticlesCollisionHeightField3D]. Represents the size of the [enum ParticlesCollisionHeightfieldResolution] enum. diff --git a/doc/classes/VoxelGIData.xml b/doc/classes/VoxelGIData.xml index 43bf04b1f5..6889f271ce 100644 --- a/doc/classes/VoxelGIData.xml +++ b/doc/classes/VoxelGIData.xml @@ -21,6 +21,7 @@ + Initializes this [VoxelGIData] with the specified data. [param octree_cells] must be a multiple of 32. [param octree_cells] must be double the size of [param data_cells]. The allocated data can be retrieved later using the various getter methods. @@ -33,26 +34,31 @@ + Returns the baked cell data for this [VoxelGIData]. + Returns the baked level counts for this [VoxelGIData]. + Returns the baked octree cell data for this [VoxelGIData]. + Returns the baked octree size for this [VoxelGIData], which corresponds to the number of subdivisions per axis. This can be viewed in the editor by hovering the [b]Bake VoxelGI[/b] button at the top of the 3D editor viewport when a [VoxelGI] node is selected and looking at the [b]Subdivisions[/b] field in the tooltip. + Returns the baked cell transform for this [VoxelGIData].