dao::lights

Declared in dao/Lights.h.

Classes

Class
Ambient	One object’s ambient light, as the engine has just worked it out.
PointLight	One point light’s colour, as the engine takes it to light an object.
ProbeLight	One light state’s light probe, as the engine has just handed it the probe’s irradiance.
SceneLight	A point light of the area’s scene, as the engine has it this frame.
SceneProbe	A light probe of the area’s scene.
SunShare	One object’s share of the sun, as the engine chooses its lights.

Type aliases

Color

using Color = std::array<float, 4>

A colour: red, green, blue and a fourth.

Enumerations

Chosen

enum class Chosen : std::uint8_t

Which of the engine’s choosers last chose the lights of an object.

Value
Unknown	not seen chosen since the callback was added
ForLevel	a placed piece of the level: a mesh, the terrain, a prop
ForMoving	something that moves: a figure, or whatever the engine lights as one

LightList

enum class LightList : std::uint8_t

Which of the light manager’s lists a point light is in.

The level’s are the lights placed with the level and its effects, the figures’ those that move with a creature; a flagged light is one its model marks (BlueprintFlag), which the engine lights fewer objects with.

Value
LevelsUnflagged
LevelsFlagged
FiguresFlagged
FiguresUnflagged

Functions

AreaProbes()

std::vector<SceneProbe> AreaProbes()

Returns every light probe of the current area’s scene. Call it on the game thread.

OnAmbient()

void OnAmbient(std::function<void(Ambient &)> callback)

Adds a callback to run each time the engine works out an object’s ambient light, at most once per object and frame, before the object is drawn.

Call it when the plugin loads or later. Callbacks run on the render thread, many times a frame, so keep them short and call no script commands from them.

Parameter
callback	may change color; the rest is for reading, and lights lasts the call alone

OnPointLight()

void OnPointLight(std::function<void(PointLight &)> callback)

Adds a callback to run each time the engine takes a point light’s colour, once for each object the light reaches, every frame.

Nothing is kept: a callback that stops changing the colour leaves the light as vanilla has it. Callbacks run on the render thread, many times a frame, so keep them short.

Parameter
callback	may change color; the rest is for reading

OnProbe()

void OnProbe(std::function<void(ProbeLight &)> callback)

Adds a callback to run each time the engine hands an object its light probe’s irradiance, at most once per object and frame, after the engine’s copy and before the object is drawn.

Objects with no probe chosen are not passed. Call it when the plugin loads or later. Callbacks run on the render thread, many times a frame, so keep them short and call no script commands from them.

Parameter
callback	may change irradiance; the rest is for reading

OnSunShare()

void OnSunShare(std::function<void(SunShare &)> callback)

Adds a callback to run each time the engine chooses an object’s lights and sets the share of the sun it eases the object toward: about once a frame for each object drawn, paused or not.

The object’s sun reaches a changed share over a moment, as vanilla’s does. Call it when the plugin loads or later. Callbacks run on the render thread, so keep them short and call no script commands from them.

Parameter
callback	may change share

PointLights()

std::vector<SceneLight> PointLights()

Returns every point light of the current area’s scene, from the light manager’s lists.

Call it on the game thread, for example from a frame callback (dao/Frame.h). Lights of other scenes (a portrait’s, an area fast load keeps) are not in it.

Returns none with no area loaded, or off the game thread

Probes()

std::vector<SceneProbe> Probes(std::uintptr_t state)

Returns the probes a light state chose: the object’s, from which the engine hands it one.

Parameter
state	a light state, as OnAmbient, OnProbe and OnSunShare give it

Returns none for no state, or off the game and render threads

SetObjectsTakeUnflagged()

void SetObjectsTakeUnflagged(bool take)

Stops, or lets again, the engine giving objects the lights of the two unflagged lists: the lights the level and its effects place, and those that move with figures.

A plugin that lights every surface with them itself (from PointLights) turns them off so they are not added twice. It lasts for every area loaded after, until changed. Call it on the game thread.

Parameter
take	false to give objects none of them, true for vanilla’s