939de03db7
This also clarifies that `get_aabb()` returns the AABB in local space.
See https://github.com/godotengine/godot/issues/42095.
(cherry picked from commit 9712f8fd2d)
164 lines
7.5 KiB
XML
164 lines
7.5 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="MultiMesh" inherits="Resource" version="3.2">
|
|
<brief_description>
|
|
Provides high-performance mesh instancing.
|
|
</brief_description>
|
|
<description>
|
|
MultiMesh provides low-level mesh instancing. Drawing thousands of [MeshInstance] nodes can be slow, since each object is submitted to the GPU then drawn individually.
|
|
MultiMesh is much faster as it can draw thousands of instances with a single draw call, resulting in less API overhead.
|
|
As a drawback, if the instances are too far away of each other, performance may be reduced as every single instance will always rendered (they are spatially indexed as one, for the whole object).
|
|
Since instances may have any behavior, the AABB used for visibility must be provided by the user.
|
|
</description>
|
|
<tutorials>
|
|
<link>https://docs.godotengine.org/en/latest/tutorials/3d/vertex_animation/animating_thousands_of_fish.html</link>
|
|
<link>https://docs.godotengine.org/en/latest/tutorials/optimization/using_multimesh.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="get_aabb" qualifiers="const">
|
|
<return type="AABB">
|
|
</return>
|
|
<description>
|
|
Returns the visibility axis-aligned bounding box in local space. See also [method VisualInstance.get_transformed_aabb].
|
|
</description>
|
|
</method>
|
|
<method name="get_instance_color" qualifiers="const">
|
|
<return type="Color">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<description>
|
|
Gets a specific instance's color.
|
|
</description>
|
|
</method>
|
|
<method name="get_instance_custom_data" qualifiers="const">
|
|
<return type="Color">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<description>
|
|
Returns the custom data that has been set for a specific instance.
|
|
</description>
|
|
</method>
|
|
<method name="get_instance_transform" qualifiers="const">
|
|
<return type="Transform">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<description>
|
|
Returns the [Transform] of a specific instance.
|
|
</description>
|
|
</method>
|
|
<method name="get_instance_transform_2d" qualifiers="const">
|
|
<return type="Transform2D">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<description>
|
|
Returns the [Transform2D] of a specific instance.
|
|
</description>
|
|
</method>
|
|
<method name="set_as_bulk_array">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="array" type="PoolRealArray">
|
|
</argument>
|
|
<description>
|
|
Sets all data related to the instances in one go. This is especially useful when loading the data from disk or preparing the data from GDNative.
|
|
All data is packed in one large float array. An array may look like this: Transform for instance 1, color data for instance 1, custom data for instance 1, transform for instance 2, color data for instance 2, etc...
|
|
[Transform] is stored as 12 floats, [Transform2D] is stored as 8 floats, [code]COLOR_8BIT[/code] / [code]CUSTOM_DATA_8BIT[/code] is stored as 1 float (4 bytes as is) and [code]COLOR_FLOAT[/code] / [code]CUSTOM_DATA_FLOAT[/code] is stored as 4 floats.
|
|
</description>
|
|
</method>
|
|
<method name="set_instance_color">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<argument index="1" name="color" type="Color">
|
|
</argument>
|
|
<description>
|
|
Sets the color of a specific instance.
|
|
For the color to take effect, ensure that [member color_format] is non-[code]null[/code] on the [MultiMesh] and [member SpatialMaterial.vertex_color_use_as_albedo] is [code]true[/code] on the material.
|
|
</description>
|
|
</method>
|
|
<method name="set_instance_custom_data">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<argument index="1" name="custom_data" type="Color">
|
|
</argument>
|
|
<description>
|
|
Sets custom data for a specific instance. Although [Color] is used, it is just a container for 4 floating point numbers. The format of the number can change depending on the [enum CustomDataFormat] used.
|
|
</description>
|
|
</method>
|
|
<method name="set_instance_transform">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<argument index="1" name="transform" type="Transform">
|
|
</argument>
|
|
<description>
|
|
Sets the [Transform] for a specific instance.
|
|
</description>
|
|
</method>
|
|
<method name="set_instance_transform_2d">
|
|
<return type="void">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<argument index="1" name="transform" type="Transform2D">
|
|
</argument>
|
|
<description>
|
|
Sets the [Transform2D] for a specific instance.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="color_format" type="int" setter="set_color_format" getter="get_color_format" enum="MultiMesh.ColorFormat" default="0">
|
|
Format of colors in color array that gets passed to shader.
|
|
</member>
|
|
<member name="custom_data_format" type="int" setter="set_custom_data_format" getter="get_custom_data_format" enum="MultiMesh.CustomDataFormat" default="0">
|
|
Format of custom data in custom data array that gets passed to shader.
|
|
</member>
|
|
<member name="instance_count" type="int" setter="set_instance_count" getter="get_instance_count" default="0">
|
|
Number of instances that will get drawn. This clears and (re)sizes the buffers. By default, all instances are drawn but you can limit this with [member visible_instance_count].
|
|
</member>
|
|
<member name="mesh" type="Mesh" setter="set_mesh" getter="get_mesh">
|
|
Mesh to be drawn.
|
|
</member>
|
|
<member name="transform_format" type="int" setter="set_transform_format" getter="get_transform_format" enum="MultiMesh.TransformFormat" default="0">
|
|
Format of transform used to transform mesh, either 2D or 3D.
|
|
</member>
|
|
<member name="visible_instance_count" type="int" setter="set_visible_instance_count" getter="get_visible_instance_count" default="-1">
|
|
Limits the number of instances drawn, -1 draws all instances. Changing this does not change the sizes of the buffers.
|
|
</member>
|
|
</members>
|
|
<constants>
|
|
<constant name="TRANSFORM_2D" value="0" enum="TransformFormat">
|
|
Use this when using 2D transforms.
|
|
</constant>
|
|
<constant name="TRANSFORM_3D" value="1" enum="TransformFormat">
|
|
Use this when using 3D transforms.
|
|
</constant>
|
|
<constant name="COLOR_NONE" value="0" enum="ColorFormat">
|
|
Use when you are not using per-instance [Color]s.
|
|
</constant>
|
|
<constant name="COLOR_8BIT" value="1" enum="ColorFormat">
|
|
Compress [Color] data into 8 bits when passing to shader. This uses less memory and can be faster, but the [Color] loses precision.
|
|
</constant>
|
|
<constant name="COLOR_FLOAT" value="2" enum="ColorFormat">
|
|
The [Color] passed into [method set_instance_color] will use 4 floats. Use this for highest precision [Color].
|
|
</constant>
|
|
<constant name="CUSTOM_DATA_NONE" value="0" enum="CustomDataFormat">
|
|
Use when you are not using per-instance custom data.
|
|
</constant>
|
|
<constant name="CUSTOM_DATA_8BIT" value="1" enum="CustomDataFormat">
|
|
Compress custom_data into 8 bits when passing to shader. This uses less memory and can be faster, but loses precision and range. Floats packed into 8 bits can only represent values between 0 and 1, numbers outside that range will be clamped.
|
|
</constant>
|
|
<constant name="CUSTOM_DATA_FLOAT" value="2" enum="CustomDataFormat">
|
|
The [Color] passed into [method set_instance_custom_data] will use 4 floats. Use this for highest precision.
|
|
</constant>
|
|
</constants>
|
|
</class>
|