Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

VoxelGI

繼承： VisualInstance3D < Node3D < Node < Object

即時全域光照（GI）探測。

說明

VoxelGI 用於為場景提供高品質的即時的間接光照和反射。它們預先計算發光物體的效果和靜態幾何體的效果，以即時模擬複雜光線的行為。VoxelGI 需要經過烘焙才能產生可見的效果。然而，一旦烘焙，動態物件將接收來自它們的光。此外，燈光可以是完全動態的，也可以是烘焙的。

注意：VoxelGI 只支援 Forward+ 算繪方式，不支援 Mobile 或 Compatibility。

程式生成：VoxelGI 可以在匯出的專案中烘焙，這使得它適用於程式生成或用戶建構的關卡，只要所有幾何體都預先生成即可。對於在遊戲過程中隨時生成幾何圖形的遊戲，SDFGI 更合適（參見 Environment.sdfgi_enabled）。

性能：VoxelGI 對 GPU 要求比較高，不適合集成顯卡等低端硬體（可以考慮改用 LightmapGI）。要提高性能，請在專案設定中，調整 ProjectSettings.rendering/global_illumination/voxel_gi/quality，並啟用 ProjectSettings.rendering/global_illumination/gi/use_half_resolution。要為低端硬體提供後備方案，請考慮在專案的選項功能表中，添加一個選項，以禁用 VoxelGI。VoxelGI 節點可以通過隱藏而禁用。

注意：網格應該有足夠厚的壁（避免單面牆）以避免漏光。對於內部關卡，請將關卡幾何體封裝在一個足夠大的盒子中，並橋接迴圈邊以閉合網格。為了進一步防止漏光，還可以策略性地放置臨時 MeshInstance3D 節點，並將其 GeometryInstance3D.gi_mode 設定為 GeometryInstance3D.GI_MODE_STATIC。然後可以在烘焙 VoxelGI 節點後，隱藏這些臨時節點。

教學

屬性

CameraAttributes	camera_attributes
VoxelGIData	data
Vector3	size	`Vector3(20, 20, 20)`
Subdiv	subdiv	`1`

方法

void	bake(from_node: Node = null, create_visual_debug: bool = false)
void	debug_bake()

列舉

enum Subdiv: 🔗

Subdiv SUBDIV_64 = 0

使用 64 分區，這是最低的品質設定，但也是最快的。如果你能使用它，特別是在低端硬體上使用它。

Subdiv SUBDIV_128 = 1

使用 128 個分區。這是預設的品質設定。

Subdiv SUBDIV_256 = 2

使用 256 個分區。

Subdiv SUBDIV_512 = 3

使用 512 個分區。這是最高的品質設定，但也是最慢的。在低端硬體上，這可能會導致 GPU 停頓。

Subdiv SUBDIV_MAX = 4

代表 Subdiv 舉的大小。

屬性說明

CameraAttributes camera_attributes 🔗

void set_camera_attributes(value: CameraAttributes)
CameraAttributes get_camera_attributes()

指定烘焙所使用的曝光級別的 CameraAttributes 資源。自動曝光和非曝光屬性會被忽略。曝光設定應當用於降低烘焙時的動態範圍。如果曝光過高，VoxelGI 會產生色帶問題，也可能出現過曝問題。

VoxelGIData data 🔗

void set_probe_data(value: VoxelGIData)
VoxelGIData get_probe_data()

為該 VoxelGI 存放資料的 VoxelGIData 資源。

Vector3 size = Vector3(20, 20, 20) 🔗

void set_size(value: Vector3)
Vector3 get_size()

The size of the area covered by the VoxelGI. This must be 1.0 or greater on each axis.

Note: If you make the size larger without increasing the number of subdivisions with subdiv, the size of each cell will increase and result in less detailed lighting.

Subdiv subdiv = 1 🔗

void set_subdiv(value: Subdiv)
Subdiv get_subdiv()

對 VoxelGI 操作的柵格進行細分的次數。數位越大，細節越精細，因此視覺品質越高，而數位越小則性能越好。

方法說明

void bake(from_node: Node = null, create_visual_debug: bool = false) 🔗

烘焙來自所有標記為 GeometryInstance3D.GI_MODE_STATIC 的 GeometryInstance3D 以及標記為 Light3D.BAKE_STATIC 或 Light3D.BAKE_DYNAMIC 的 Light3D 的效果。如果 create_visual_debug 為 true，則烘焙光照後會生成一個 MultiMesh，用立方體代表各個實體儲存格，每個立方體都使用對應儲存格的反照率顏色著色。這樣就對 VoxelGI 的數據進行了視覺化，可以用來除錯可能發生的問題。

注意：編輯器和匯出後的專案中都可以使用 bake()。因此可用於程式式生成或使用者建構的關卡。對於大多數場景，烘焙 VoxelGI 節點一般需要 5 到 20 秒。降低 subdiv 可以加速烘焙。

注意：GeometryInstance3D 和 Light3D 節點必須在呼叫 bake() 前完全就緒。如果這些節點是程式式生成的，而烘焙後的 VoxelGI 中缺失部分網格和燈光，請使用 call_deferred("bake")，不要直接呼叫 bake()。

void debug_bake() 🔗

在啟用 create_visual_debug 的情況下呼叫 bake() 。