b087538119
This makes it easier to spot syntax errors when editing the class reference. The schema is referenced locally so validation can still work offline. Each class XML's schema conformance is also checked on GitHub Actions.
86 lines
7.1 KiB
XML
86 lines
7.1 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="GIProbe" inherits="VisualInstance" version="3.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
Real-time global illumination (GI) probe.
|
|
</brief_description>
|
|
<description>
|
|
[GIProbe]s are used to provide high-quality real-time indirect light to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. [GIProbe]s need to be baked before using, however, once baked, dynamic objects will receive light from them. Further, lights can be fully dynamic or baked.
|
|
Having [GIProbe]s in a scene can be expensive, the quality of the probe can be turned down in exchange for better performance in the [ProjectSettings] using [member ProjectSettings.rendering/quality/voxel_cone_tracing/high_quality].
|
|
[b]Procedural generation:[/b] [GIProbe] can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance.
|
|
[b]Performance:[/b] [GIProbe] is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider [BakedLightmap] instead). To provide a fallback for low-end hardware, consider adding an option to disable [GIProbe] in your project's options menus. A [GIProbe] node can be disabled by hiding it.
|
|
[b]Note:[/b] Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. To further prevent light leaks, you can also strategically place temporary [MeshInstance] nodes with [member GeometryInstance.use_in_baked_light] enabled. These temporary nodes can then be hidden after baking the [GIProbe] node.
|
|
[b]Note:[/b] Due to a renderer limitation, emissive [ShaderMaterial]s cannot emit light when used in a [GIProbe]. Only emissive [SpatialMaterial]s can emit light in a [GIProbe].
|
|
</description>
|
|
<tutorials>
|
|
<link title="GI probes">$DOCS_URL/tutorials/3d/gi_probes.html</link>
|
|
<link title="Third Person Shooter Demo">https://godotengine.org/asset-library/asset/678</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="bake">
|
|
<return type="void" />
|
|
<argument index="0" name="from_node" type="Node" default="null" />
|
|
<argument index="1" name="create_visual_debug" type="bool" default="false" />
|
|
<description>
|
|
Bakes the effect from all [GeometryInstance]s marked with [member GeometryInstance.use_in_baked_light] and [Light]s marked with either [constant Light.BAKE_INDIRECT] or [constant Light.BAKE_ALL]. If [code]create_visual_debug[/code] is [code]true[/code], after baking the light, this will generate a [MultiMesh] that has a cube representing each solid cell with each cube colored to the cell's albedo color. This can be used to visualize the [GIProbe]'s data and debug any issues that may be occurring.
|
|
[b]Note:[/b] [method bake] works from the editor and in exported projects. This makes it suitable for procedurally generated or user-built levels. Baking a [GIProbe] generally takes from 5 to 20 seconds in most scenes. Reducing [member subdiv] can speed up baking.
|
|
[b]Note:[/b] [GeometryInstance]s and [Light]s must be fully ready before [method bake] is called. If you are procedurally creating those and some meshes or lights are missing from your baked [GIProbe], use [code]call_deferred("bake")[/code] instead of calling [method bake] directly.
|
|
</description>
|
|
</method>
|
|
<method name="debug_bake">
|
|
<return type="void" />
|
|
<description>
|
|
Calls [method bake] with [code]create_visual_debug[/code] enabled.
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<members>
|
|
<member name="bias" type="float" setter="set_bias" getter="get_bias" default="1.5">
|
|
Offsets the lookup of the light contribution from the [GIProbe]. This can be used to avoid self-shadowing, but may introduce light leaking at higher values. This and [member normal_bias] should be played around with to minimize self-shadowing and light leaking.
|
|
[b]Note:[/b] [code]bias[/code] should usually be above 1.0 as that is the size of the voxels.
|
|
</member>
|
|
<member name="compress" type="bool" setter="set_compress" getter="is_compressed" default="false">
|
|
[i]Deprecated.[/i] This property has been deprecated due to known bugs and no longer has any effect when enabled.
|
|
</member>
|
|
<member name="data" type="GIProbeData" setter="set_probe_data" getter="get_probe_data">
|
|
The [GIProbeData] resource that holds the data for this [GIProbe].
|
|
</member>
|
|
<member name="dynamic_range" type="int" setter="set_dynamic_range" getter="get_dynamic_range" default="4">
|
|
The maximum brightness that the [GIProbe] will recognize. Brightness will be scaled within this range.
|
|
</member>
|
|
<member name="energy" type="float" setter="set_energy" getter="get_energy" default="1.0">
|
|
Energy multiplier. Makes the lighting contribution from the [GIProbe] brighter.
|
|
</member>
|
|
<member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3( 10, 10, 10 )">
|
|
The size of the area covered by the [GIProbe]. If you make the extents larger without increasing the subdivisions with [member subdiv], the size of each cell will increase and result in lower detailed lighting.
|
|
</member>
|
|
<member name="interior" type="bool" setter="set_interior" getter="is_interior" default="false">
|
|
If [code]true[/code], ignores the sky contribution when calculating lighting.
|
|
</member>
|
|
<member name="normal_bias" type="float" setter="set_normal_bias" getter="get_normal_bias" default="0.0">
|
|
Offsets the lookup into the [GIProbe] based on the object's normal direction. Can be used to reduce some self-shadowing artifacts.
|
|
</member>
|
|
<member name="propagation" type="float" setter="set_propagation" getter="get_propagation" default="0.7">
|
|
How much light propagates through the probe internally. A higher value allows light to spread further.
|
|
</member>
|
|
<member name="subdiv" type="int" setter="set_subdiv" getter="get_subdiv" enum="GIProbe.Subdiv" default="1">
|
|
Number of times to subdivide the grid that the [GIProbe] operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.
|
|
</member>
|
|
</members>
|
|
<constants>
|
|
<constant name="SUBDIV_64" value="0" enum="Subdiv">
|
|
Use 64 subdivisions. This is the lowest quality setting, but the fastest. Use it if you can, but especially use it on lower-end hardware.
|
|
</constant>
|
|
<constant name="SUBDIV_128" value="1" enum="Subdiv">
|
|
Use 128 subdivisions. This is the default quality setting.
|
|
</constant>
|
|
<constant name="SUBDIV_256" value="2" enum="Subdiv">
|
|
Use 256 subdivisions.
|
|
</constant>
|
|
<constant name="SUBDIV_512" value="3" enum="Subdiv">
|
|
Use 512 subdivisions. This is the highest quality setting, but the slowest. On lower-end hardware, this could cause the GPU to stall.
|
|
</constant>
|
|
<constant name="SUBDIV_MAX" value="4" enum="Subdiv">
|
|
Represents the size of the [enum Subdiv] enum.
|
|
</constant>
|
|
</constants>
|
|
</class>
|