BakedLightmap¶

Inherits: VisualInstance < CullInstance < Spatial < Node < Object

Prerendered indirect light map for a scene.

Description¶

Baked lightmaps are an alternative workflow for adding indirect (or baked) lighting to a scene. Unlike the GIProbe approach, baked lightmaps work fine on low-end PCs and mobile devices as they consume almost no resources in run-time.

Procedural generation: Lightmap baking functionality is only available in the editor. This means BakedLightmap is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use GIProbe instead.

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

Tutorials¶

Baked lightmaps

Properties¶

bool	atlas_generate	`true`
int	atlas_max_size	`4096`
float	bias	`0.005`
float	bounce_indirect_energy	`1.0`
int	bounces	`3`
float	capture_cell_size	`0.5`
bool	capture_enabled	`true`
float	capture_propagation	`1.0`
BakeQuality	capture_quality	`1`
float	default_texels_per_unit	`16.0`
Color	environment_custom_color
float	environment_custom_energy
Sky	environment_custom_sky
Vector3	environment_custom_sky_rotation_degrees
Color	environment_min_light	`Color( 0, 0, 0, 1 )`
EnvironmentMode	environment_mode	`0`
Vector3	extents	`Vector3( 10, 10, 10 )`
String	image_path
BakedLightmapData	light_data
BakeQuality	quality	`1`
bool	use_color	`true`
bool	use_denoiser	`true`
bool	use_hdr	`true`

Methods¶

BakeError

bake ( Node from_node=null, String data_save_path="" )

Enumerations¶

enum BakeQuality:

BakeQuality BAKE_QUALITY_LOW = 0

The lowest bake quality mode. Fastest to calculate.

BakeQuality BAKE_QUALITY_MEDIUM = 1

The default bake quality mode.

BakeQuality BAKE_QUALITY_HIGH = 2

A higher bake quality mode. Takes longer to calculate.

BakeQuality BAKE_QUALITY_ULTRA = 3

The highest bake quality mode. Takes the longest to calculate.

enum BakeError:

BakeError BAKE_ERROR_OK = 0

Baking was successful.

BakeError BAKE_ERROR_NO_SAVE_PATH = 1

Returns if no viable save path is found. This can happen where an image_path is not specified or when the save location is invalid.

BakeError BAKE_ERROR_NO_MESHES = 2

Currently unused.

BakeError BAKE_ERROR_CANT_CREATE_IMAGE = 3

Returns when the baker cannot save per-mesh textures to file.

BakeError BAKE_ERROR_LIGHTMAP_SIZE = 4

The size of the generated lightmaps is too large.

BakeError BAKE_ERROR_INVALID_MESH = 5

Some mesh contains UV2 values outside the [0,1] range.

BakeError BAKE_ERROR_USER_ABORTED = 6

Returns if user cancels baking.

BakeError BAKE_ERROR_NO_LIGHTMAPPER = 7

Returns if lightmapper can't be created. Unless you are using a custom lightmapper, please report this as bug.

BakeError BAKE_ERROR_NO_ROOT = 8

There is no root node to start baking from. Either provide from_node argument or attach this node to a parent that should be used as root.

enum EnvironmentMode:

EnvironmentMode ENVIRONMENT_MODE_DISABLED = 0

No environment is used during baking.

EnvironmentMode ENVIRONMENT_MODE_SCENE = 1

The baked environment is automatically picked from the current scene.

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_SKY = 2

A custom sky is used as environment during baking.

EnvironmentMode ENVIRONMENT_MODE_CUSTOM_COLOR = 3

A custom solid color is used as environment during baking.

Property Descriptions¶

bool atlas_generate = true

void set_generate_atlas ( bool value )
bool is_generate_atlas_enabled ( )

If true, the lightmapper will merge the textures for all meshes into one or several large layered textures. If false, every mesh will get its own lightmap texture, which is less efficient.

Note: Atlas lightmap rendering is only supported in GLES3, not GLES2. Non-atlas lightmap rendering is supported by both GLES3 and GLES2. If ProjectSettings.rendering/quality/driver/fallback_to_gles2 is true, consider baking lightmaps with atlas_generate set to false so that the resulting lightmap is visible in both GLES3 and GLES2.

int atlas_max_size = 4096

void set_max_atlas_size ( int value )
int get_max_atlas_size ( )

Maximum size of each lightmap layer, only used when atlas_generate is enabled.

float bias = 0.005

void set_bias ( float value )
float get_bias ( )

Raycasting bias used during baking to avoid floating point precision issues.

float bounce_indirect_energy = 1.0

void set_bounce_indirect_energy ( float value )
float get_bounce_indirect_energy ( )

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 bounce_indirect_energy. Unlike BakedLightmapData.energy, this property does not affect direct lighting emitted by light nodes, emissive materials and the environment.

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

int bounces = 3

void set_bounces ( int value )
int get_bounces ( )

Number of light bounces that are taken into account during baking. See also bounce_indirect_energy.

float capture_cell_size = 0.5

void set_capture_cell_size ( float value )
float get_capture_cell_size ( )

Grid size used for real-time capture information on dynamic objects.

bool capture_enabled = true

void set_capture_enabled ( bool value )
bool get_capture_enabled ( )

When enabled, an octree containing the scene's lighting information will be computed. This octree will then be used to light dynamic objects in the scene.

float capture_propagation = 1.0

void set_capture_propagation ( float value )
float get_capture_propagation ( )

Bias value to reduce the amount of light propagation in the captured octree.

BakeQuality capture_quality = 1

void set_capture_quality ( BakeQuality value )
BakeQuality get_capture_quality ( )

Bake quality of the capture data.

float default_texels_per_unit = 16.0

void set_default_texels_per_unit ( float value )
float get_default_texels_per_unit ( )

If a baked mesh doesn't have a UV2 size hint, this value will be used to roughly compute a suitable lightmap size.

Color environment_custom_color

void set_environment_custom_color ( Color value )
Color get_environment_custom_color ( )

The environment color when environment_mode is set to ENVIRONMENT_MODE_CUSTOM_COLOR.

float environment_custom_energy

void set_environment_custom_energy ( float value )
float get_environment_custom_energy ( )

The energy scaling factor when when environment_mode is set to ENVIRONMENT_MODE_CUSTOM_COLOR or ENVIRONMENT_MODE_CUSTOM_SKY.

Sky environment_custom_sky

void set_environment_custom_sky ( Sky value )
Sky get_environment_custom_sky ( )

The Sky resource to use when environment_mode is set o ENVIRONMENT_MODE_CUSTOM_SKY.

Vector3 environment_custom_sky_rotation_degrees

void set_environment_custom_sky_rotation_degrees ( Vector3 value )
Vector3 get_environment_custom_sky_rotation_degrees ( )

The rotation of the baked custom sky.

Color environment_min_light = Color( 0, 0, 0, 1 )

void set_environment_min_light ( Color value )
Color get_environment_min_light ( )

Minimum ambient light for all the lightmap texels. This doesn't take into account any occlusion from the scene's geometry, it simply ensures a minimum amount of light on all the lightmap texels. Can be used for artistic control on shadow color.

EnvironmentMode environment_mode = 0

void set_environment_mode ( EnvironmentMode value )
EnvironmentMode get_environment_mode ( )

Decides which environment to use during baking.

Vector3 extents = Vector3( 10, 10, 10 )

void set_extents ( Vector3 value )
Vector3 get_extents ( )

Size of the baked lightmap. Only meshes inside this region will be included in the baked lightmap, also used as the bounds of the captured region for dynamic lighting.

String image_path

void set_image_path ( String value )
String get_image_path ( )

Deprecated, in previous versions it determined the location where lightmaps were be saved.

BakedLightmapData light_data

void set_light_data ( BakedLightmapData value )
BakedLightmapData get_light_data ( )

The calculated light data.

BakeQuality quality = 1

void set_bake_quality ( BakeQuality value )
BakeQuality get_bake_quality ( )

Determines the amount of samples per texel used in indirect light baking. The amount of samples for each quality level can be configured in the project settings.

bool use_color = true

void set_use_color ( bool value )
bool is_using_color ( )

Store full color values in the lightmap textures. When disabled, lightmap textures will store a single brightness channel. Can be disabled to reduce disk usage if the scene contains only white lights or you don't mind losing color information in indirect lighting.

bool use_denoiser = true

void set_use_denoiser ( bool value )
bool is_using_denoiser ( )

When enabled, a lightmap denoiser will be used to reduce the noise inherent to Monte Carlo based global illumination.

bool use_hdr = true

void set_use_hdr ( bool value )
bool is_using_hdr ( )

If true, stores the lightmap textures in a high dynamic range format (EXR). If false, stores the lightmap texture in a low dynamic range PNG image. This can be set to false to reduce disk usage, but light values over 1.0 will be clamped and you may see banding caused by the reduced precision.

Note: Setting use_hdr to true will decrease lightmap banding even when using the GLES2 backend or if ProjectSettings.rendering/quality/depth/hdr is false.

Method Descriptions¶

BakeError bake ( Node from_node=null, String data_save_path="" )

Bakes the lightmap, scanning from the given from_node root and saves the resulting BakedLightmapData in data_save_path. If no root node is provided, parent of this node will be used as root instead. If no save path is provided it will try to match the path from the current light_data.