LightmapGI

package
v0.0.0-...-9b8b246 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2025 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

The LightmapGI node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. LightmapGI can also provide rough reflections using spherical harmonics if Directional is enabled. Dynamic objects can receive indirect lighting thanks to light probes, which can be automatically placed by setting GenerateProbesSubdiv to a value other than GenerateProbesDisabled. Additional lightmap probes can also be added by creating LightmapProbe nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a LightmapGI node is also slower compared to VoxelGI.

Procedural generation: Lightmap baking functionality is only available in the editor. This means LightmapGI is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use VoxelGI or SDFGI instead (see Environment.SdfgiEnabled).

Performance: LightmapGI provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices.

Note: Due to how lightmaps work, most properties only have a visible effect once lightmaps are baked again.

Note: Lightmap baking on CSGShape3Ds and PrimitiveMeshes is not supported, as these cannot store UV2 data required for baking.

Note: If no custom lightmappers are installed, LightmapGI can only be baked from devices that support the Forward+ or Mobile renderers.

Note: The LightmapGI node only bakes light data for child nodes of its parent. Nodes further up the hierarchy of the scene will not be baked.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsLightmapGI() Instance
}

type BakeError 

type BakeError int //gd:LightmapGI.BakeError

const (
	// Lightmap baking was successful.
	BakeErrorOk BakeError = 0
	// Lightmap baking failed because the root node for the edited scene could not be accessed.
	BakeErrorNoSceneRoot BakeError = 1
	// Lightmap baking failed as the lightmap data resource is embedded in a foreign resource.
	BakeErrorForeignData BakeError = 2
	// Lightmap baking failed as there is no lightmapper available in this Godot build.
	BakeErrorNoLightmapper BakeError = 3
	// Lightmap baking failed as the [LightmapGIData] save path isn't configured in the resource.
	//
	// [LightmapGIData]: https://pkg.go.dev/graphics.gd/classdb/LightmapGIData
	BakeErrorNoSavePath BakeError = 4
	// Lightmap baking failed as there are no meshes whose [GeometryInstance3D.GiMode] is [Geometryinstance3d.GiModeStatic] and with valid UV2 mapping in the current scene. You may need to select 3D scenes in the Import dock and change their global illumination mode accordingly.
	//
	// [GeometryInstance3D.GiMode]: https://pkg.go.dev/graphics.gd/classdb/GeometryInstance3D#Instance.GiMode
	BakeErrorNoMeshes BakeError = 5
	// Lightmap baking failed as the lightmapper failed to analyze some of the meshes marked as static for baking.
	BakeErrorMeshesInvalid BakeError = 6
	// Lightmap baking failed as the resulting image couldn't be saved or imported by Godot after it was saved.
	BakeErrorCantCreateImage BakeError = 7
	// The user aborted the lightmap baking operation (typically by clicking the Cancel button in the progress dialog).
	BakeErrorUserAborted BakeError = 8
	// Lightmap baking failed as the maximum texture size is too small to fit some of the meshes marked for baking.
	BakeErrorTextureSizeTooSmall BakeError = 9
	// Lightmap baking failed as the lightmap is too small.
	BakeErrorLightmapTooSmall BakeError = 10
	// Lightmap baking failed as the lightmap was unable to fit into an atlas.
	BakeErrorAtlasTooSmall BakeError = 11
)

type BakeQuality 

type BakeQuality int //gd:LightmapGI.BakeQuality

const (
	// Low bake quality (fastest bake times). The quality of this preset can be adjusted by changing [ProjectSettings] "rendering/lightmapping/bake_quality/low_quality_ray_count" and [ProjectSettings] "rendering/lightmapping/bake_quality/low_quality_probe_ray_count".
	//
	// [ProjectSettings]: https://pkg.go.dev/graphics.gd/classdb/ProjectSettings
	BakeQualityLow BakeQuality = 0
	// Medium bake quality (fast bake times). The quality of this preset can be adjusted by changing [ProjectSettings] "rendering/lightmapping/bake_quality/medium_quality_ray_count" and [ProjectSettings] "rendering/lightmapping/bake_quality/medium_quality_probe_ray_count".
	//
	// [ProjectSettings]: https://pkg.go.dev/graphics.gd/classdb/ProjectSettings
	BakeQualityMedium BakeQuality = 1
	// High bake quality (slow bake times). The quality of this preset can be adjusted by changing [ProjectSettings] "rendering/lightmapping/bake_quality/high_quality_ray_count" and [ProjectSettings] "rendering/lightmapping/bake_quality/high_quality_probe_ray_count".
	//
	// [ProjectSettings]: https://pkg.go.dev/graphics.gd/classdb/ProjectSettings
	BakeQualityHigh BakeQuality = 2
	// Highest bake quality (slowest bake times). The quality of this preset can be adjusted by changing [ProjectSettings] "rendering/lightmapping/bake_quality/ultra_quality_ray_count" and [ProjectSettings] "rendering/lightmapping/bake_quality/ultra_quality_probe_ray_count".
	//
	// [ProjectSettings]: https://pkg.go.dev/graphics.gd/classdb/ProjectSettings
	BakeQualityUltra BakeQuality = 3
)

type EnvironmentMode 

type EnvironmentMode int //gd:LightmapGI.EnvironmentMode

const (
	// Ignore environment lighting when baking lightmaps.
	EnvironmentModeDisabled EnvironmentMode = 0
	// Use the scene's environment lighting when baking lightmaps.
	//
	// Note: If baking lightmaps in a scene with no [WorldEnvironment] node, this will act like [EnvironmentModeDisabled]. The editor's preview sky and sun is not taken into account by [LightmapGI] when baking lightmaps.
	//
	// [LightmapGI]: https://pkg.go.dev/graphics.gd/classdb/LightmapGI
	// [WorldEnvironment]: https://pkg.go.dev/graphics.gd/classdb/WorldEnvironment
	EnvironmentModeScene EnvironmentMode = 1
	// Use [EnvironmentCustomSky] as a source of environment lighting when baking lightmaps.
	//
	// [EnvironmentCustomSky]: https://pkg.go.dev/graphics.gd/classdb/#Instance.EnvironmentCustomSky
	EnvironmentModeCustomSky EnvironmentMode = 2
	// Use [EnvironmentCustomColor] multiplied by [EnvironmentCustomEnergy] as a constant source of environment lighting when baking lightmaps.
	//
	// [EnvironmentCustomColor]: https://pkg.go.dev/graphics.gd/classdb/#Instance.EnvironmentCustomColor
	// [EnvironmentCustomEnergy]: https://pkg.go.dev/graphics.gd/classdb/#Instance.EnvironmentCustomEnergy
	EnvironmentModeCustomColor EnvironmentMode = 3
)

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsLightmapGI 

func (self *Extension[T]) AsLightmapGI() Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode3D 

func (self *Extension[T]) AsNode3D() Node3D.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

func (*Extension[T]) AsVisualInstance3D 

func (self *Extension[T]) AsVisualInstance3D() VisualInstance3D.Instance

type GenerateProbes 

type GenerateProbes int //gd:LightmapGI.GenerateProbes

const (
	// Don't generate lightmap probes for lighting dynamic objects.
	GenerateProbesDisabled GenerateProbes = 0
	// Lowest level of subdivision (fastest bake times, smallest file sizes).
	GenerateProbesSubdiv4 GenerateProbes = 1
	// Low level of subdivision (fast bake times, small file sizes).
	GenerateProbesSubdiv8 GenerateProbes = 2
	// High level of subdivision (slow bake times, large file sizes).
	GenerateProbesSubdiv16 GenerateProbes = 3
	// Highest level of subdivision (slowest bake times, largest file sizes).
	GenerateProbesSubdiv32 GenerateProbes = 4
)

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.LightmapGI

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AsLightmapGI 

func (self Instance) AsLightmapGI() Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode3D 

func (self Instance) AsNode3D() Node3D.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AsVisualInstance3D 

func (self Instance) AsVisualInstance3D() VisualInstance3D.Instance

func (Instance) Bias 

func (self Instance) Bias() Float.X

The bias to use when computing shadows. Increasing Bias can fix shadow acne on the resulting baked lightmap, but can introduce peter-panning (shadows not connecting to their casters). Real-time Light3D shadows are not affected by this Bias property.

func (Instance) BounceIndirectEnergy 

func (self Instance) BounceIndirectEnergy() Float.X

The energy multiplier for each bounce. Higher values will make indirect lighting brighter. A value of 1.0 represents physically accurate behavior, but higher values can be used to make indirect lighting propagate more visibly when using a low number of bounces. This can be used to speed up bake times by lowering the number of Bounces then increasing BounceIndirectEnergy.

Note: BounceIndirectEnergy only has an effect if Bounces is set to a value greater than or equal to 1.

func (Instance) Bounces 

func (self Instance) Bounces() int

Number of light bounces that are taken into account during baking. Higher values result in brighter, more realistic lighting, at the cost of longer bake times. If set to 0, only environment lighting, direct light and emissive lighting is baked.

func (Instance) CameraAttributes 

func (self Instance) CameraAttributes() CameraAttributes.Instance

The CameraAttributes resource that specifies exposure levels to bake at. Auto-exposure and non exposure properties will be ignored. Exposure settings should be used to reduce the dynamic range present when baking. If exposure is too high, the LightmapGI will have banding artifacts or may have over-exposure artifacts.

func (Instance) DenoiserRange 

func (self Instance) DenoiserRange() int

The distance in pixels from which the denoiser samples. Lower values preserve more details, but may give blotchy results if the lightmap quality is not high enough. Only effective if UseDenoiser is true and ProjectSettings "rendering/lightmapping/denoising/denoiser" is set to JNLM.

func (Instance) DenoiserStrength 

func (self Instance) DenoiserStrength() Float.X

The strength of denoising step applied to the generated lightmaps. Only effective if UseDenoiser is true and ProjectSettings "rendering/lightmapping/denoising/denoiser" is set to JNLM.

func (Instance) Directional 

func (self Instance) Directional() bool

If true, bakes lightmaps to contain directional information as spherical harmonics. This results in more realistic lighting appearance, especially with normal mapped materials and for lights that have their direct light baked (Light3D.LightBakeMode set to [Light3d.BakeStatic] and with Light3D.EditorOnly set to false). The directional information is also used to provide rough reflections for static and dynamic objects. This has a small run-time performance cost as the shader has to perform more work to interpret the direction information from the lightmap. Directional lightmaps also take longer to bake and result in larger file sizes.

Note: The property's name has no relationship with DirectionalLight3D. Directional works with all light types.

func (Instance) EnvironmentCustomColor 

func (self Instance) EnvironmentCustomColor() Color.RGBA

The color to use for environment lighting. Only effective if EnvironmentMode is EnvironmentModeCustomColor.

func (Instance) EnvironmentCustomEnergy 

func (self Instance) EnvironmentCustomEnergy() Float.X

The color multiplier to use for environment lighting. Only effective if EnvironmentMode is EnvironmentModeCustomColor.

func (Instance) EnvironmentCustomSky 

func (self Instance) EnvironmentCustomSky() Sky.Instance

The sky to use as a source of environment lighting. Only effective if EnvironmentMode is EnvironmentModeCustomSky.

func (Instance) EnvironmentMode 

func (self Instance) EnvironmentMode() EnvironmentMode

The environment mode to use when baking lightmaps.

func (Instance) GenerateProbesSubdiv 

func (self Instance) GenerateProbesSubdiv() GenerateProbes

The level of subdivision to use when automatically generating LightmapProbes for dynamic object lighting. Higher values result in more accurate indirect lighting on dynamic objects, at the cost of longer bake times and larger file sizes.

Note: Automatically generated LightmapProbes are not visible as nodes in the Scene tree dock, and cannot be modified this way after they are generated.

Note: Regardless of GenerateProbesSubdiv, direct lighting on dynamic objects is always applied using Light3D nodes in real-time.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) Interior 

func (self Instance) Interior() bool

If true, ignore environment lighting when baking lightmaps.

func (Instance) LightData 

func (self Instance) LightData() LightmapGIData.Instance

The LightmapGIData associated to this LightmapGI node. This resource is automatically created after baking, and is not meant to be created manually.

func (Instance) MaxTextureSize 

func (self Instance) MaxTextureSize() int

The maximum texture size for the generated texture atlas. Higher values will result in fewer slices being generated, but may not work on all hardware as a result of hardware limitations on texture sizes. Leave MaxTextureSize at its default value of 16384 if unsure.

func (Instance) Quality 

func (self Instance) Quality() BakeQuality

The quality preset to use when baking lightmaps. This affects bake times, but output file sizes remain mostly identical across quality levels.

To further speed up bake times, decrease Bounces, disable UseDenoiser and/or decrease TexelScale.

To further increase quality, enable Supersampling and/or increase TexelScale.

func (Instance) SetBias 

func (self Instance) SetBias(value Float.X)

SetBias sets the property returned by [GetBias].

func (Instance) SetBounceIndirectEnergy 

func (self Instance) SetBounceIndirectEnergy(value Float.X)

SetBounceIndirectEnergy sets the property returned by [GetBounceIndirectEnergy].

func (Instance) SetBounces 

func (self Instance) SetBounces(value int)

SetBounces sets the property returned by [GetBounces].

func (Instance) SetCameraAttributes 

func (self Instance) SetCameraAttributes(value CameraAttributes.Instance)

SetCameraAttributes sets the property returned by [GetCameraAttributes].

func (Instance) SetDenoiserRange 

func (self Instance) SetDenoiserRange(value int)

SetDenoiserRange sets the property returned by [GetDenoiserRange].

func (Instance) SetDenoiserStrength 

func (self Instance) SetDenoiserStrength(value Float.X)

SetDenoiserStrength sets the property returned by [GetDenoiserStrength].

func (Instance) SetDirectional 

func (self Instance) SetDirectional(value bool)

SetDirectional sets the property returned by [IsDirectional].

func (Instance) SetEnvironmentCustomColor 

func (self Instance) SetEnvironmentCustomColor(value Color.RGBA)

SetEnvironmentCustomColor sets the property returned by [GetEnvironmentCustomColor].

func (Instance) SetEnvironmentCustomEnergy 

func (self Instance) SetEnvironmentCustomEnergy(value Float.X)

SetEnvironmentCustomEnergy sets the property returned by [GetEnvironmentCustomEnergy].

func (Instance) SetEnvironmentCustomSky 

func (self Instance) SetEnvironmentCustomSky(value Sky.Instance)

SetEnvironmentCustomSky sets the property returned by [GetEnvironmentCustomSky].

func (Instance) SetEnvironmentMode 

func (self Instance) SetEnvironmentMode(value EnvironmentMode)

SetEnvironmentMode sets the property returned by [GetEnvironmentMode].

func (Instance) SetGenerateProbesSubdiv 

func (self Instance) SetGenerateProbesSubdiv(value GenerateProbes)

SetGenerateProbesSubdiv sets the property returned by [GetGenerateProbes].

func (Instance) SetInterior 

func (self Instance) SetInterior(value bool)

SetInterior sets the property returned by [IsInterior].

func (Instance) SetLightData 

func (self Instance) SetLightData(value LightmapGIData.Instance)

SetLightData sets the property returned by [GetLightData].

func (Instance) SetMaxTextureSize 

func (self Instance) SetMaxTextureSize(value int)

SetMaxTextureSize sets the property returned by [GetMaxTextureSize].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetQuality 

func (self Instance) SetQuality(value BakeQuality)

SetQuality sets the property returned by [GetBakeQuality].

func (Instance) SetShadowmaskMode 

func (self Instance) SetShadowmaskMode(value LightmapGIData.ShadowmaskMode)

SetShadowmaskMode sets the property returned by [GetShadowmaskMode].

func (Instance) SetSupersampling 

func (self Instance) SetSupersampling(value bool)

SetSupersampling sets the property returned by [IsSupersamplingEnabled].

func (Instance) SetSupersamplingFactor 

func (self Instance) SetSupersamplingFactor(value Float.X)

SetSupersamplingFactor sets the property returned by [GetSupersamplingFactor].

func (Instance) SetTexelScale 

func (self Instance) SetTexelScale(value Float.X)

SetTexelScale sets the property returned by [GetTexelScale].

func (Instance) SetUseDenoiser 

func (self Instance) SetUseDenoiser(value bool)

SetUseDenoiser sets the property returned by [IsUsingDenoiser].

func (Instance) SetUseTextureForBounces 

func (self Instance) SetUseTextureForBounces(value bool)

SetUseTextureForBounces sets the property returned by [IsUsingTextureForBounces].

func (Instance) ShadowmaskMode 

func (self Instance) ShadowmaskMode() LightmapGIData.ShadowmaskMode

The shadowmasking policy to use for directional shadows on static objects that are baked with this LightmapGI instance.

Shadowmasking allows DirectionalLight3D nodes to cast shadows even outside the range defined by their DirectionalLight3D.DirectionalShadowMaxDistance property. This is done by baking a texture that contains a shadowmap for the directional light, then using this texture according to the current shadowmask mode.

Note: The shadowmask texture is only created if ShadowmaskMode is not [Lightmapgidata.ShadowmaskModeNone]. To see a difference, you need to bake lightmaps again after switching from [Lightmapgidata.ShadowmaskModeNone] to any other mode.

func (Instance) Supersampling 

func (self Instance) Supersampling() bool

If true, lightmaps are baked with the texel scale multiplied with SupersamplingFactor and downsampled before saving the lightmap (so the effective texel density is identical to having supersampling disabled).

Supersampling provides increased lightmap quality with less noise, smoother shadows and better shadowing of small-scale features in objects. However, it may result in significantly increased bake times and memory usage while baking lightmaps. Padding is automatically adjusted to avoid increasing light leaking.

func (Instance) SupersamplingFactor 

func (self Instance) SupersamplingFactor() Float.X

The factor by which the texel density is multiplied for supersampling. For best results, use an integer value. While fractional values are allowed, they can result in increased light leaking and a blurry lightmap.

Higher values may result in better quality, but also increase bake times and memory usage while baking.

See Supersampling for more information.

func (Instance) TexelScale 

func (self Instance) TexelScale() Float.X

Scales the lightmap texel density of all meshes for the current bake. This is a multiplier that builds upon the existing lightmap texel size defined in each imported 3D scene, along with the per-mesh density multiplier (which is designed to be used when the same mesh is used at different scales). Lower values will result in faster bake times.

For example, doubling TexelScale doubles the lightmap texture resolution for all objects on each axis, so it will quadruple the texel count.

func (Instance) UseDenoiser 

func (self Instance) UseDenoiser() bool

If true, uses a GPU-based denoising algorithm on the generated lightmap. This eliminates most noise within the generated lightmap at the cost of longer bake times. File sizes are generally not impacted significantly by the use of a denoiser, although lossless compression may do a better job at compressing a denoised image.

func (Instance) UseTextureForBounces 

func (self Instance) UseTextureForBounces() bool

If true, a texture with the lighting information will be generated to speed up the generation of indirect lighting at the cost of some accuracy. The geometry might exhibit extra light leak artifacts when using low resolution lightmaps or UVs that stretch the lightmap significantly across surfaces. Leave UseTextureForBounces at its default value of true if unsure.

Note: UseTextureForBounces only has an effect if Bounces is set to a value greater than or equal to 1.

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.