Back to main page

Light source

This engine is using depth based shadow mapping because it is fast and can cast shadows from almost anything.

Depth based shadows can't cast shadows using a point light with only one planar projection. You can use 2 to 6 spot lights in different directions to make them look like one point light.

2 types of shadow filtering is used at the same time to give smooth edges without visible acne.

The illustration is making the errors larger to show how it works.

The depth atlas is used to store depth maps for shadow casting light sources.

The illustration is showing resolution groups 1 to 4 but you can use resolution group 0 if you only need one light source.

To save space for mutually exclusive properties, some variables have multiple names. Radius and far clip share memory. Half width and width slope share memory. Half height and height slope share memory.

Colors in the light source system does not use the alpha channel because light that affect opacity makes no sense.

The visible range for the colors goes from 0 to 1 but because of distance, angle and diffuse colors, you can use much higher values.

The collection will give up to 64 light sources that passed the culling test to the graphics card.

Version specific functions in the material shader's built in header gives you the light from position, normal and other things.

See the documentation about material shaders for more information.

The ambient light is added to the diffuse light from all directions.

void LightSource_SetAmbientLight(float Red, float Green, float Blue);

Sets the ambient light to (Red,Green,Blue).

void LightSource_GetAmbientLight_OutV3(void);

Writes the ambient light to (X1,Y1,Z1).

int LightSource_Create_Point_Shadowless(float Pos_X, float Pos_Y, float Pos_Z, float Radius, float Red, float Green, float Blue);

Creates a new shadowless point light.

Returns a reference to the new light source.

int LightSource_Create_Sun_Shadowless(float Dir_X, float Dir_Y, float Dir_Z, float Red, float Green, float Blue);

Creates a new shadowless sun light.

Returns a reference to the new light source.

int LightSource_Create_Sun_Shadowcasting_SingleLayer(float Pos_X, float Pos_Y, float Pos_Z, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z, float NearClip, float FarClip, float Red, float Green, float Blue, float HalfWidth, float HalfHeight, float ShadowTransparency, int ResolutionGroup, float OutsideIntensity, float FadeSize);

FarClipPlane is another name for radius with the same get/set methods.

HalfWidth is sharing memory with Widthslope and have the same get/set methods.

HalfHeight is sharing memory with Heightslope and have the same get/set methods.

It is recomended that NearClipPlane = -FarClipPlane so that the light can be placed at the things that the camera is looking at. This would be impossible without an orthogonal projection.

Creates a new shadowcasting sun light.

0 <= ShadowTransparency <= 1, 0 <= OutsideIntensity <= 1, 0.001 <= FadeSize <= 1. Invalid values are clamped without a warning.

Returns a reference to the new light source.

int LightSource_Create_Spotlight_RoundAndSoft_Shadowless(float Pos_X, float Pos_Y, float Pos_Z, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z, float Radius, float WidthSlope, float HeightSlope, float Red, float Green, float Blue);

This is the shadowless version of Spotlight_RoundAndSoft_Shadowcasting

Creates a new shadowless spot light using a round and soft shape instead of an image from the atlas.

Returns a reference to the new light source.

int LightSource_Create_Spotlight_Atlas_Shadowless(float Pos_X, float Pos_Y, float Pos_Z, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z, float Radius, float Red, float Green, float Blue, float WidthSlope, float HeightSlope, float MinU, float MaxU, float MinV, float MaxV);

This is the shadowless version of Spotlight_Atlas_Shadowcasting

Creates a new shadowless spot light using a rectangle region from the light projection atlas to project on surfaces.

Returns a reference to the new light source.

int LightSource_Create_Spotlight_RoundAndSoft_Shadowcasting(float Pos_X, float Pos_Y, float Pos_Z, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z, float Radius, float WidthSlope, float HeightSlope, float Red, float Green, float Blue, float NearClip, float ShadowTransparency);

This is the shadowcasting version of Spotlight_RoundAndSoft_Shadowless

Creates a new shadowcasting spot light using a round and soft shape instead of an image from the atlas.

0.001 <= NearClip and 0 <= ShadowTransparency <= 1. Invalid values are clamped without a warning.

Returns a reference to the new light source.

int LightSource_Create_Spotlight_Atlas_Shadowcasting(float Pos_X, float Pos_Y, float Pos_Z, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z, float Radius, float Red, float Green, float Blue, float WidthSlope, float HeightSlope, float MinU, float MaxU, float MinV, float MaxV, float NearClip, float ShadowTransparency);

This is the shadowcasting version of Spotlight_Atlas_Shadowless

Creates a new shadowcasting spot light using a rectangle region from the light projection atlas to project on surfaces.

0.001 <= NearClip and 0 <= ShadowTransparency <= 1. Invalid values are clamped without a warning.

Returns a reference to the new light source.

void LightSource_Delete(int LightSource);

LightSource is a valid light source.

Removes LightSource.

void LightSource_SetRadius(int LightSource, float NewValue);

The radius is the longest distance from the center that the light source can affect the world. In reality, the intensity in divided by the distance squared but that takes too much performance for computer games.

For light attenuation, this engine is using the formula Intensity = (1 - (Distance / MaxDistance))² to make a soft but early end where Distance = MaxDistance.

Radius and far clip share memory.

LightSource is a valid light source and NewValue > 0.

Sets LightSource's radius to NewValue.

float LightSource_GetRadius(int LightSource);

LightSource is a valid light source.

Returns LightSource's radius.

void LightSource_SetNearClip(int LightSource, float NewValue);

The near clip plane decides how far away something have to be from the light source to cast a shadow. This can both increase performance and exclude things who's shadow is already painted on a projected image for a higher quality.

LightSource is a valid light source. 0.001 <= NewValue or the light source is orthogonal. Invalid values are clamped without a warning.

Sets LightSource's near clip depth to NewValue.

float LightSource_GetNearClip(int LightSource);

LightSource is a valid light source.

Returns LightSource's near clip depth.

void LightSource_SetWidthSlope(int LightSource, float NewValue);

WidthSlope = tan(VerticalFOV / 2)

VerticalFOV = arctan(WidthSlope) * 2

Setting the slope to 0 or lower for a spot light will make the light fail the culling test and save as much time as disabling the light.

Half width and width slope share memory.

LightSource is a valid light source and NewValue > 0.

Sets LightSource's width slope to NewValue.

float LightSource_GetWidthSlope(int LightSource);

LightSource is a valid light source.

Returns LightSource's width slope.

void LightSource_SetHeightSlope(int LightSource, float NewValue);

HeightSlope = tan(HorizontalFOV / 2)

HorizontalFOV = arctan(HeightSlope) * 2

Setting the slope to 0 or lower for a spot light will make the light fail the culling test and save as much time as disabling the light.

Half height and height slope share memory.

LightSource is a valid light source and NewValue > 0.

Sets LightSource's height slope to NewValue.

float LightSource_GetHeightSlope(int LightSource);

LightSource is a valid light source.

Returns LightSource's height slope.

void LightSource_SetShadowTransparency(int LightSource, float NewValue);

This method does nothing for lightsources that are not shadowcasting.

You should use this to fade away shadows for lesser important lightsources at a long distance.

If the shadow transparency equals 0 then no light will leak to the shadow.

If the shadow transparency equals 0.5 then half of the light will leak to the shadow but this won't save any performance.

If the shadow transparency equals 1 then no shadow will be created and you save a lot of performance.

LightSource is a valid light source and 0 <= NewValue <= 1. Invalid values are clamped without a warning.

Sets LightSource's shadow transparency to NewValue. If NewValue >= 0.999 then the shadows are assumed to be impossible to see and you save a lot of performance.

float LightSource_GetShadowTransparency(int LightSource);

LightSource is a valid light source.

Returns LightSource's shadow transparency.

void LightSource_SetResolutionGroup(int LightSource, int NewValue);

The resolution group is a relative size of the depth map that is allocated in the depth atlas.

The value represent how much of the depth atlas that is allocated by this light source when it is casting shadows.

0 allocates the entire depth atlas so that 1 light can cast shadows at once.

1 allocates 1/4 of the depth atlas so that 4 lights of this size can cast shadows at once.

2 allocates 1/16 of the depth atlas so that 16 lights of this size can cast shadows at once.

3 allocates 1/64 of the depth atlas so that 64 lights of this size can cast shadows at once.

4 allocates 1/256 of the depth atlas.

You can combine different sizes for different light sources and there is no time penalty for changing the size.

My quad heap allocation method is proven to deliver the wanted size if the total amount of remaining space is enough.

LightSource is a valid light source and 0 <= NewValue <= 4.

Sets LightSource's resolution group to NewValue. If the value is outside of the [0..4] interval, the closest value inside is assigned.

int LightSource_GetResolutionGroup(int LightSource);

LightSource is a valid light source.

Returns LightSource's resolution group.

void LightSource_SetColor(int LightSource, float Red, float Green, float Blue);

This is the color that the light source will add to the world where material shaders are recieving shadows.

If you wand a brighter or weaker light, just multiply the color with a scalar. You can even use a negative light intensity for surreal effects or cheap ambient occlusion.

Setting the color very close to (0,0,0) will make the light fail the culling test and save as much time as disabling the light.

LightSource is a valid light source.

Sets LightSource's color to (Red,Green,Blue).

void LightSource_GetColor_OutV3(int LightSource);

LightSource is a valid light source.

Writes LightSource's color to (X1,Y1,Z1).

void LightSource_SetPos(int LightSource, float X, float Y, float Z);

This is the point that the light is projected from if the lightsource is a point light or a spot light.

LightSource is a valid light source.

Sets LightSource's position to (X,Y,Z).

void LightSource_GetPos_OutV3(int LightSource);

LightSource is a valid light source.

Writes LightSource's position to (X1,Y1,Z1).

void LightSource_SetDirection(int LightSource, float Dir_X, float Dir_Y, float Dir_Z, float Up_X, float Up_Y, float Up_Z);

This is an orthogonalizing method for directing the light source. The Up vector is usefull when projecting shadows or an image.

LightSource is a valid light source and (Up_X,Up_Y,Up_Z) may not be parallel with (Up_X,Up_Y,Up_Z).

Sets LightSource's direction to (Dir_X,Dir_Y,Dir_Z) while keeping the Y axis as close to (Up_X,Up_Y,Up_Z) as possible using cross products to orthogonalize.

void LightSource_GetAxisSystem_OutM3(int LightSource);

LightSource is a valid light source.

Writes the light source's axis system to ((X1,Y1,Z1),(X2,Y2,Z2),(X3,Y3,Z3))

See Texture_UseAsLightProjectionAtlas to read about how to use a texture as a light projection atlas.

void LightSource_SetTextureAtlasRect(int LightSource, float MinU, float MaxU, float MinV, float MaxV);

LightSource is a valid light source.

Sets LightSource's texture atlas rectangle to (MinU,MaxU,MinV,MaxV) so that ([MinU to MaxU],[MinV to MaxV]) will be used as a texture if LightSource's type is projecting an image from the light projection atlas.

void LightSource_GetTextureAtlasRect_OutV4(int LightSource);

LightSource is a valid light source.

Writes LightSource's texture atlas rectangle to (X1,Y1,Z1,W1).

void LightSource_ClearShadows(void);

If you use shadowcasting light sources, this must be done before a group of render calls when something has changed in the scene.

If you use it before every render in a scene with multiple cameras, the exact same depth tile might be rendered multiple times the same frame.

If you forget to call this at all, new depthmaps can not replace the old ones and the light may look bad if something has moved.

Clears the depth atlas and deallocates all depth tiles used by shadowcasting lightsources.

void LightSource_SetDepthAtlasResolution(int WidthAndHeight);

The depth atlas is used when rendering depth based shadows from shadow casting light sources.

WidthAndHeight = 1024, 2048, 4096 or 8192.

Sets the depth atlas resolution to (WidthAndHeight x WidthAndHeight) and LightSource_ClearShadows is called.

int LightSource_GetDepthAtlasResolution(void);

Returns the current width and height of the depth atlas. -1 is returned if there is no depth atlas.

void LightSource_SetOutsideIntensity(int LightSource, float NewValue);

0 means that everything too far away from the center of the light is not affected. This is good for indoor enviroments where light leak in at a few places.

0.5 means that the outside have 50% of the light. This is good for a forest where 50% of the light reach the ground.

1 means that no shadows are used outside. This is good for open outdoor worlds.

LightSource is a valid light source and 0 <= NewValue <= 1. The outside intensity will be clamped to the valid range if a bad value is given.

Sets LightSource's OutsideIntensity to NewValue.

float LightSource_GetOutsideIntensity(int LightSource);

LightSource is a valid light source.

Returns LightSource's OutsideIntensity.

void LightSource_SetFadeSize(int LightSource, float NewValue);

When a type of light is using this property, the shadows are faded on the edges.

0.1 means that 10% of the radius on the outside is fading to the outside intensity.

0.5 means that 50% of the radius on the outside is fading to the outside intensity.

1.0 means that there is is fading to the outside intensity.

LightSource is a valid light source and 0.001 <= NewValue <= 1. The fade size will be clamped to the valid range if a bad value is given.

Sets LightSource's FadeSize to NewValue.

float LightSource_GetFadeSize(int LightSource);

LightSource is a valid light source.

Returns LightSource's FadeSize.

void LightSource_SetEnabled(int LightSource, bool Enabled);

New light sources are enabled by default.

Disabled light sources take almost no performance in the engine by skipping the culling test.

LightSource is a valid light source.

If Enabled is true then LightSource is turned on. If Enabled is false then LightSource is turned off.

int LightSource_GetEnabled(int LightSource);

LightSource is a valid light source.

Returns 1 if LightSource is enabled and 0 if LightSource is disabled.