426bcc9941
In many of the XML files it had been noted that when the documentation refers to a return value, both "Return" and "Returns" are used. This has now been fixed to only say "Returns". Fixes #28867
162 lines
7 KiB
XML
162 lines
7 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="MultiMesh" inherits="Resource" category="Core" 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 because each object is submitted to the GPU to be drawn individually.
|
|
MultiMesh is much faster because 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>http://docs.godotengine.org/en/latest/tutorials/3d/vertex_animation/animating_thousands_of_fish.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="get_aabb" qualifiers="const">
|
|
<return type="AABB">
|
|
</return>
|
|
<description>
|
|
Returns the visibility AABB.
|
|
</description>
|
|
</method>
|
|
<method name="get_instance_color" qualifiers="const">
|
|
<return type="Color">
|
|
</return>
|
|
<argument index="0" name="instance" type="int">
|
|
</argument>
|
|
<description>
|
|
Get the color of a specific instance.
|
|
</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>
|
|
Set 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, COLOR_8BIT / CUSTOM_DATA_8BIT is stored as 1 float (4 bytes as is) and COLOR_FLOAT / CUSTOM_DATA_FLOAT 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>
|
|
Set 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>
|
|
Set custom data for a specific instance. Although [Color] is used, it is just a container for 4 numbers.
|
|
</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>
|
|
Set 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>
|
|
Set 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">
|
|
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">
|
|
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">
|
|
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">
|
|
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">
|
|
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.
|
|
</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>
|