Unigine.LightWorld Class

Inherits:

This class is used to create world light sources. This type of light source imitates sunlight and uses parallel-split shadow mapping.

Example#

The following code illustrates how to create a world light source and set its parameters (intensity scattering, etc.).

Source code (C#)

/* .. */

// creating a world light source and setting its color to white (1.0f, 1.0f, 1.0f, 1.0f)
LightWorld thesun = new LightWorld(new vec4(1.0f, 1.0f, 1.0f, 1.0f));

// setting the name of the world light
thesun.setName("Sun");
	
// setting disable angle of the world light
thesun.setDisableAngle(90.0f);

// setting light intensity
thesun.setIntensity(1.0f);
	
// setting scattering type to sun scattering
thesun.setScattering(LightWorld.SCATTERING_SUN);

Setting Position#

A world light is an infinitely distant light source, so its physical position is not important, only the direction matters, as it defines orientation of shadows. You can change the light's direction via the setRotation() method.

Let's illustrate that by setting the correct position of the Sun for a certain geographic location (latitude, longitude), date and time. To calculate elevation and azimuth values let's use the following sunPosition() function:

sunPosition() function:

Source code (C#)

/// function calculating azimuth and elevation for the specified date, time (GMT) and geo-coordinates (https://stackoverflow.com/questions/8708048/position-of-the-sun-given-time-of-day-latitude-and-longitude)
void sunPosition(ref double elevation, ref double azimuth, double lat, double lon, int year = 2012, int month = 12, int day = 22, double hour = 12, int min = 00, int sec = 00) 
{
	double pi = 3.141592650f;
	double twopi = 2 * pi;
	double deg2rad = pi / 180.0f;

	// get a day of the year, e.g. Feb 1 = 32, Mar 1 = 61 on leap years
	int[] month_days = new int[] { 0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30 };
	for (int i=0; i<month; i++)
		day += month_days[i];
	bool leapdays = ((year % 4) == 0 && ((year % 400) == 0 || (year % 100) != 0) && day >= 60 && !(month==2 && day==60));
	if (leapdays) day++;

	// Get Julian date - 2400000
	hour += min / 60.0f + sec / 3600.0f; // hour plus fraction
	double delta = year - 1949.0f;
	double leap = Math.Truncate(delta / 4.0f); // former leapyears
	double jd = 32916.5f + delta * 365 + leap + day + hour / 24.0f;

	// calculating input for the Atronomer's almanach as the difference between
	// the Julian date and JD 2451545.0 (noon, 1 January 2000)
	double time = jd - 51545.0f;

	// calculating mean longitude and mean anomaly
	double mnlong = 280.460f + 0.9856474f * time;
	mnlong = mnlong % 360;
	if (mnlong < 0) mnlong += 360;
	double mnanom = 357.528f + 0.9856003f * time;
	mnanom = mnanom %360;
	if (mnanom < 0) mnanom += 360;
	mnanom *= deg2rad;

	// calculating ecliptic longitude and obliquity of ecliptic
	double eclong = mnlong + 1.915f * MathLib.Sin(mnanom) + 0.020f * MathLib.Sin(2 * mnanom);
	eclong = eclong % 360;
	if (eclong < 0) eclong+= 360;
	double oblqec = 23.439f - 0.0000004f * time;
	eclong *= deg2rad;
	oblqec *= deg2rad;
	

	// calculating celestial coordinates: right ascension and declination
	double num = MathLib.Cos(oblqec) * MathLib.Sin(eclong);
	double den = MathLib.Cos(eclong);
	double ra = MathLib.Atan(num / den);
	if (den < 0) ra += pi;
	if (den >= 0 && num < 0) ra += twopi;
	double dec = MathLib.asin(MathLib.Sin(oblqec) * MathLib.Sin(eclong));

	// calculating local coordinates Greenwich mean sidereal time
	double gmst = 6.697375f + 0.0657098242f * time + hour;
	gmst = gmst % 24;
	if (gmst < 0) gmst += 24.0f;

	// calculating local mean sidereal time
	double lmst = gmst + lon / 15.0f;
	lmst = lmst % 24;
	if (lmst < 0) lmst += 24.0f;
	lmst = lmst * 15.0f * deg2rad;

	// calculating hour angle
	double ha = lmst - ra;
	if (ha < -pi) ha += twopi;
	if (ha > pi) ha -= twopi;

	// converting latitude to radians
	lat = lat * deg2rad;

	// calculating zimuth and elevation
	elevation = MathLib.Asin(MathLib.Sin(dec) * MathLib.Sin(lat) + MathLib.Cos(dec) * MathLib.Cos(lat) * MathLib.Cos(ha));
	azimuth = MathLib.Asin(-MathLib.Cos(dec) * MathLib.Sin(ha) / MathLib.Cos(elevation));

	// for logic and names, see Spencer, J.W. 1989. Solar Energy. 42(4):353
	bool cosAzPos = (0 <= MathLib.Sin(dec) - MathLib.Sin(elevation) * MathLib.Sin(lat));
	bool sinAzNeg = (MathLib.Sin(azimuth) < 0);
	if (cosAzPos && sinAzNeg) azimuth +=twopi;
	if (!cosAzPos) azimuth=  pi - azimuth;

	// return elevation and azimuth
	elevation = elevation / deg2rad;
	azimuth = azimuth / deg2rad;
}

Thus, we can simply set the position of the Sun as follows:

Source code (C#)

public override bool Init()
{
	/* ... */
	// geo-coordinates of a point (latitude and longitude)
	double lat = 56.49771;
	double lon = 84.97437;

	// elevation and azimuth to store calculated values
	double elevation=0, azimuth=0;

	LightWorld sun = World.GetNodeByName("sun") as LightWorld;
	if (sun != null)
	{
		// calculating azimuth and elevation
		// for the specified date,
		// GMT time and geo-coordinates
		sunPosition(ref elevation, ref azimuth, lat, lon,
					2019, 2, 5, 				// February 5, 2019
					4, 0, 0);					// 04:00:00 (GMT)

		// setting real Sun position for the calculated azimuth and elevation values 
		sun.Rotation = new quat(90, 270, 270) * (new quat((float)azimuth, 0, 0)) * (new quat(0, 90, 0)) * (new quat((float)elevation, 0, 0)) * (new quat(90, 0, 0));
	}
	
	 
	return 1;
}

Properties:

Name	Description
int Mode	The current rendering mode for the light source.
float ShadowZFar	The current distance to the far clipping plane used for generation of static shadow cascades.
float ShadowWidth	The current view width of the orthographic projection used for generation of static shadow cascades.
float ShadowHeight	The current view height of the orthographic projection used for generation of static shadow cascades.
int NumShadowCascades	The number of shadow cascades with different shadow maps.
LightWorld.SHADOW_CASCADE_MODE ShadowCascadeMode	The current shadow cascade generation mode for the world light source.
float DisableAngle	An angle at which the light source is disabled (shadows and the diffuse component is disabled).
LightWorld.SCATTERING Scattering	A lighting type set for the world light.

Methods:

Name	Description View: Sort by:
LightWorld	Constructor.
SetShadowCascadeBorder	Sets the multiplier for the distance to the border of the specified shadow cascade at which the corresponding shadows are rendered.
GetShadowCascadeBorder	Returns the multiplier for the distance to the border of the specified shadow cascade at which the corresponding shadows are rendered.
type	Returns the type of the node.

LightWorld Class

Enums

SCATTERING#

Name	Description
NONE = 0	Render the atmosphere with no influence of the global lights (sun and moon), i.e. the light gradient won't be changed in any direction.
SUN = 1	Render the atmosphere in accordance with the Sun's lighting.
MOON = 2	Render the atmosphere in accordance with the Moon's lighting.

SHADOW_CASCADE_MODE#

Name	Description
DYNAMIC = 0	Dynamic shadow cascade generation mode. In this mode shadow cascades are built dynamically relative to the camera's position. All shadows are calculated dynamically making it possible to change the time of day (day-night cycle).
STATIC = 1	Static shadow cascade generation mode. In this mode shadow cascades are built and baked relative to the light source's position. This mode is suitable as a performance optimization technique for small-area ArchViz projects where shadow cascades can be divided into 2 sections: walkable area with high-resolution shadows (as they're observed closely) and non-walkable area with low-resolution shadows (as they're observed from a distance). Notice Changing the time of day is not available in this mode, as shadow cascades are baked.

Name

Description

DYNAMIC = 0

Dynamic shadow cascade generation mode. In this mode shadow cascades are built dynamically relative to the camera's position. All shadows are calculated dynamically making it possible to change the time of day (day-night cycle).

STATIC = 1

Static shadow cascade generation mode. In this mode shadow cascades are built and baked relative to the light source's position. This mode is suitable as a performance optimization technique for small-area ArchViz projects where shadow cascades can be divided into 2 sections: walkable area with high-resolution shadows (as they're observed closely) and non-walkable area with low-resolution shadows (as they're observed from a distance).

NoticeChanging the time of day is not available in this mode, as shadow cascades are baked.

Properties

int Mode#

The current rendering mode for the light source. this option determines whether the light is to be rendered as a dynamic or static one.

set

Sets rendering mode for the light source. This option determines whether the light is to be rendered as a dynamic or static one.

set value - Light mode, one of the MODE_* variables.

float ShadowZFar#

The current distance to the far clipping plane used for generation of static shadow cascades. static cascades are generated relative to the world light's position.

Notice