#include <RRLight.h>

Inheritance diagram for rr::RRLight:

Public Types
enum	Type { DIRECTIONAL = 0 , POINT , SPOT }

enum	DistanceAttenuationType { NONE , REALISTIC , POLYNOMIAL , EXPONENTIAL }

Public Member Functions
	RRLight ()

	RRLight (const RRLight &)

const RRLight &	operator= (const RRLight &)

virtual	~RRLight ()

virtual RRVec3	getIrradiance (const RRVec3 &receiverPosition, const RRColorSpace *colorSpace) const

void	blendLinear (const RRLight &sample0, const RRLight &sample1, RRReal blend)

void	blendAkima (unsigned numSamples, const RRLight *samples, const RRReal times, RRReal time)

bool	operator== (const RRLight &a) const

bool	operator!= (const RRLight &a) const

void	fixInvalidValues ()

Public Member Functions inherited from rr::RRUniformlyAllocated
void *	operator new (std::size_t n)

void *	operator new[] (std::size_t n)

void	operator delete (void *p, std::size_t n)

void	operator delete[] (void *p, std::size_t n)

Static Public Member Functions
static RRLight *	createDirectionalLight (const RRVec3 &direction, const RRVec3 &color, bool linear)

static RRLight *	createPointLight (const RRVec3 &position, const RRVec3 &irradianceAtDistance1)

static RRLight *	createPointLightNoAtt (const RRVec3 &position, const RRVec3 &irradianceAtDistance1)

static RRLight *	createPointLightRadiusExp (const RRVec3 &position, const RRVec3 &colorLinear, RRReal radius, RRReal fallOffExponent)

static RRLight *	createPointLightPoly (const RRVec3 &position, const RRVec3 &colorCustom, RRVec4 polynom)

static RRLight *	createSpotLight (const RRVec3 &position, const RRVec3 &irradianceAtDistance1, const RRVec3 &majorDirection, RRReal outerAngleRad, RRReal fallOffAngleRad)

static RRLight *	createSpotLightNoAtt (const RRVec3 &position, const RRVec3 &irradianceAtDistance1, const RRVec3 &majorDirection, RRReal outerAngleRad, RRReal fallOffAngleRad)

static RRLight *	createSpotLightRadiusExp (const RRVec3 &position, const RRVec3 &colorLinear, RRReal radius, RRReal fallOffExponent, const RRVec3 &majorDirection, RRReal outerAngleRad, RRReal fallOffAngleRad)

static RRLight *	createSpotLightPoly (const RRVec3 &position, const RRVec3 &colorCustom, RRVec4 polynom, const RRVec3 &majorDirection, RRReal outerAngleRad, RRReal fallOffAngleRad, RRReal spotExponent)

Public Attributes
Type	type

RRVec3	position

RRVec3	direction

RRReal	outerAngleRad

RRReal	radius

RRVec3	color

RRBuffer *	projectedTexture

DistanceAttenuationType	distanceAttenuationType

RRVec4	polynom

RRReal	fallOffExponent

RRReal	spotExponent

RRReal	fallOffAngleRad

bool	enabled

bool	castShadows

bool	directLambertScaled

unsigned	rtNumShadowmaps

unsigned	rtShadowmapSize

RRVec2	rtShadowmapBias

bool	rtShadowmapAutomaticNearFar

RRReal	rtShadowmapNear

RRReal	rtShadowmapFar

RRString	name

void *	customData

Detailed Description

Direct light source, directional/point/spot light with programmable function.

Standard point/spot/dir lights with realistic, polynomial or exponential distance attenuations are supported via createXxx functions, custom lights with this interface can be created.

All light properties are public and you are free to change them at any moment.

If you wish to control light properties for direct and indirect illumination separately, you can do so by changing properties at the right moment during calculation. For realtime GI, solver->calculate() accesses light to calculate indirect illumination, while solver->renderScene() accesses light to calculate direct illumination. For offline GI, solver->updateLightmaps(-1,-1,-1,nullptr,indirectParams,) accesses light to calculate indirect illumination, while solver->updateLightmaps(,,,directParams,nullptr,) accesses light to calculate direct illumination. Thread safe: yes, may be accessed by any number of threads simultaneously. All custom implementations must be thread safe too.

Member Enumeration Documentation

◆ Type

enum rr::RRLight::Type

Types of lights.

Enumerator
DIRECTIONAL	Infinitely distant light source, all light rays are parallel (direction).
POINT	Point light source, all light rays start in one point (position).
SPOT	Spot light source, all light rays start in one point (position) and leave it in cone (direction).

◆ DistanceAttenuationType

enum rr::RRLight::DistanceAttenuationType

Types of distance attenuation. Defines how light color is computed for given distance.

Enumerator
NONE	Linear intensity is color, i.e. no attenuation with distance. Good approximation of sunlight.
REALISTIC	Linear intensity is color/distance^2. This is how real world works.
POLYNOMIAL	Custom color space intensity is color/MAX(polynom[0]+polynom[1]distance+polynom[2]distance^2,polynom[3]). Used in fixed pipeline engines. polynom[3] was added to support Gamebryo.
EXPONENTIAL	Linear intensity is color*pow(MAX(0,1-(distance/radius)^2),fallOffExponent). Used in UE3.

Constructor & Destructor Documentation

◆ RRLight() [1/2]

rr::RRLight::RRLight ( )

Initialize light to defaults.

◆ RRLight() [2/2]

rr::RRLight::RRLight ( const RRLight & )

Copy ctor (default one would not increase projected texture refcount).

◆ ~RRLight()

virtual rr::RRLight::~RRLight ( )

inlinevirtual

Destruct light.

Member Function Documentation

◆ operator=()

const RRLight & rr::RRLight::operator= ( const RRLight & )

Assignment (default one would not increase projected texture refcount).

◆ getIrradiance()

virtual RRVec3 rr::RRLight::getIrradiance	(	const RRVec3 &	receiverPosition,
		const RRColorSpace *	colorSpace
	)		const

virtual

Returns irradiance as linear color, implements various attenuation functions.

Parameters

receiverPosition Position of point in world space illuminated by this light.

colorSpace Currently active color space, provided for your convenience. You can compute irradiance directly in linear colors and don't use it, which is the most efficient way, but if you calculate in custom color space, convert your result to linear using colorSpace->toLinear() before returning it.
Lightsprint calculates internally in linear colors, that's why it's more efficient to expect linear result rather than in screen colors or any other custom color space.

Returns: Irradiance at receiverPosition as linear color, assuming that receiver is oriented towards light. Lights must return finite number, even when lighting model predicts infinite number (some types of attenuation + zero distance).

◆ blendLinear()

void rr::RRLight::blendLinear	(	const RRLight &	sample0,
		const RRLight &	sample1,
		RRReal	blend
	)

Fills this with linear interpolation of two samples; sample0 if blend=0, sample1 if blend=1.

◆ blendAkima()

void rr::RRLight::blendAkima	(	unsigned	numSamples,
		const RRLight **	samples,
		const RRReal *	times,
		RRReal	time
	)

Fills this with Akima interpolation of samples, non uniformly scattered on time scale.

Parameters

numSamples	Number of elements in samples and times arrays. Interpolations uses at most 3 preceding and 3 following samples, providing more does not increase quality.
samples	Pointers to numSamples samples.
times	Array of times assigned to samples.
time	Time assigned to sample generated by this function.

◆ operator==()

bool rr::RRLight::operator== ( const RRLight & a ) const

Returns true if member variables of both lights match (even if class differs).

◆ operator!=()

bool rr::RRLight::operator!= ( const RRLight & a ) const

◆ createDirectionalLight()

static RRLight * rr::RRLight::createDirectionalLight	(	const RRVec3 &	direction,
		const RRVec3 &	color,
		bool	linear
	)

static

Creates directional light without distance attenuation.

It is good approximation of sun, which is so distant, that its distance attenuation is hardly visible on our small scale.

Parameters

direction	Direction of light in world space.
color	Irradiance at receiver, assuming it is oriented towards light.
linear	True for linear color, false for custom color space (usually sRGB, screen color).

◆ createPointLight()

static RRLight * rr::RRLight::createPointLight	(	const RRVec3 &	position,
		const RRVec3 &	irradianceAtDistance1
	)

static

Creates omnidirectional point light with realistic distance attenuation.

Parameters

position	Position of light source in world space, start of all light rays.
irradianceAtDistance1	Irradiance as linear color at distance 1, assuming that receiver is oriented towards light.

◆ createPointLightNoAtt()

static RRLight * rr::RRLight::createPointLightNoAtt	(	const RRVec3 &	position,
		const RRVec3 &	irradianceAtDistance1
	)

static

Creates omnidirectional point light without distance attenuation.

Parameters

position	Position of light source in world space, start of all light rays.
irradianceAtDistance1	Irradiance as linear color at distance 1, assuming that receiver is oriented towards light.

◆ createPointLightRadiusExp()

static RRLight * rr::RRLight::createPointLightRadiusExp	(	const RRVec3 &	position,
		const RRVec3 &	colorLinear,
		RRReal	radius,
		RRReal	fallOffExponent
	)

static

Creates omnidirectional point light with radius/exponent based distance attenuation (physically incorrect).

Parameters

position	Position of light source in world space, start of all light rays.
colorLinear	Linear color of light, irradiance of lit surface before applying distance attenuation.
radius	Distance in world space, where light disappears due to its distance attenuation. Light has effect in sphere of given radius.
fallOffExponent	Distance attenuation in custom scale is computed as pow(MAX(0,1-(distance/radius)^2),fallOffExponent).

◆ createPointLightPoly()

static RRLight * rr::RRLight::createPointLightPoly	(	const RRVec3 &	position,
		const RRVec3 &	colorCustom,
		RRVec4	polynom
	)

static

Creates omnidirectional point light with polynom based distance attenuation (physically incorrect).

Parameters

position	Position of light source in world space, start of all light rays.
colorCustom	Irradiance in custom scale (usually screen color) of lit surface before applying distance attenuation.
polynom	Distance attenuation in custom scale is computed as 1/MAX(polynom[0]+polynom[1]distance+polynom[2]distance^2,polynom[3]).

◆ createSpotLight()

static RRLight * rr::RRLight::createSpotLight	(	const RRVec3 &	position,
		const RRVec3 &	irradianceAtDistance1,
		const RRVec3 &	majorDirection,
		RRReal	outerAngleRad,
		RRReal	fallOffAngleRad
	)

static

Creates spot light with realistic distance attenuation.

Light rays start in position and go in directions up to outerAngleRad diverting from major direction.

Parameters

position	Position of light source in world space, start of all light rays.
irradianceAtDistance1	Irradiance as linear color at distance 1, assuming that receiver is oriented towards light.
majorDirection	Major direction of light in world space.
outerAngleRad	Insight: This is half width of spot, FOV/2. Angle in radians, (0,pi/2) range. Light rays go in directions up to outerAngleRad far from major majorDirection.
fallOffAngleRad	Insight: This is width of blurry part. Angle in radians, (0,outerAngleRad> range. Light rays with direction diverted less than outerAngleRad from majorDirection, but more than outerAngleRad-fallOffAngleRad, are attenuated. If your data contain innerAngle, set fallOffAngle=outerAngle-innerAngle.

◆ createSpotLightNoAtt()

static RRLight * rr::RRLight::createSpotLightNoAtt	(	const RRVec3 &	position,
		const RRVec3 &	irradianceAtDistance1,
		const RRVec3 &	majorDirection,
		RRReal	outerAngleRad,
		RRReal	fallOffAngleRad
	)

static

Creates spot light without distance attenuation.

Light rays start in position and go in directions up to outerAngleRad diverting from major direction.

Parameters

position	Position of light source in world space, start of all light rays.
irradianceAtDistance1	Irradiance as linear color at distance 1, assuming that receiver is oriented towards light.
majorDirection	Major direction of light in world space.
outerAngleRad	Insight: This is half width of spot, FOV/2. Angle in radians, (0,pi/2) range. Light rays go in directions up to outerAngleRad far from major majorDirection.
fallOffAngleRad	Insight: This is width of blurry part. Angle in radians, (0,outerAngleRad> range. Light rays with direction diverted less than outerAngleRad from majorDirection, but more than outerAngleRad-fallOffAngleRad, are attenuated. If your data contain innerAngle, set fallOffAngle=outerAngle-innerAngle.

◆ createSpotLightRadiusExp()

static RRLight * rr::RRLight::createSpotLightRadiusExp	(	const RRVec3 &	position,
		const RRVec3 &	colorLinear,
		RRReal	radius,
		RRReal	fallOffExponent,
		const RRVec3 &	majorDirection,
		RRReal	outerAngleRad,
		RRReal	fallOffAngleRad
	)

static

Creates spot light with radius/exponent based distance attenuation (physically incorrect).

Light rays start in position and go in directions up to outerAngleRad diverting from major direction.

Parameters

position	Position of light source in world space, start of all light rays.
colorLinear	Linear light color, irradiance of lit surface before applying distance attenuation.
radius	Distance in world space, where light disappears due to its distance attenuation. Light has effect in sphere of given radius.
fallOffExponent	Distance attenuation in custom scale is computed as pow(MAX(0,1-(distance/radius)^2),fallOffExponent).
majorDirection	Major direction of light in world space.
outerAngleRad	Insight: This is half width of spot, FOV/2. Angle in radians, (0,pi/2) range. Light rays go in directions up to outerAngleRad far from major majorDirection.
fallOffAngleRad	Insight: This is width of blurry part. Angle in radians, (0,outerAngleRad> range. Light rays with direction diverted less than outerAngleRad from majorDirection, but more than outerAngleRad-fallOffAngleRad, are attenuated. If your data contain innerAngle, set fallOffAngle=outerAngle-innerAngle.

◆ createSpotLightPoly()

static RRLight * rr::RRLight::createSpotLightPoly	(	const RRVec3 &	position,
		const RRVec3 &	colorCustom,
		RRVec4	polynom,
		const RRVec3 &	majorDirection,
		RRReal	outerAngleRad,
		RRReal	fallOffAngleRad,
		RRReal	spotExponent
	)

static

Creates spot light with polynom based distance attenuation (physically incorrect).

Light rays start in position and go in directions up to outerAngleRad diverting from major direction.

Parameters

position	Position of light source in world space, start of all light rays.
colorCustom	Irradiance in custom scale (usually screen color) of lit surface before applying distance attenuation.
polynom	Distance attenuation in custom scale is computed as 1/MAX(polynom[0]+polynom[1]distance+polynom[2]distance^2,polynom[3]).
majorDirection	Major direction of light in world space.
outerAngleRad	Insight: This is half width of spot, FOV/2. Angle in radians, (0,pi/2) range. Light rays go in directions up to outerAngleRad far from major majorDirection.
fallOffAngleRad	Insight: This is width of blurry part. Angle in radians, (0,outerAngleRad> range. Light rays with direction diverted less than outerAngleRad from majorDirection, but more than outerAngleRad-fallOffAngleRad, are attenuated. If your data contain innerAngle, set fallOffAngle=outerAngle-innerAngle.
spotExponent	Insight: This is how intensity changes in blurry part. Default 1 makes it linear in custom/sRGB scale. Exponent in (0,inf) range. Changes attenuaton from linear with 0 in outerAngle and 1 in innerAngle to exponential: linearAttenuation^spotExponent.

◆ fixInvalidValues()

void rr::RRLight::fixInvalidValues ( )

Fixes NaN/INF/IND and out of range values found in light.

It is important before serializing light into text stream that can't handle infinite numbers.

Member Data Documentation

◆ type

Type rr::RRLight::type

Type of light source.

◆ position

RRVec3 rr::RRLight::position

Position of light source in world space. Relevant only for POINT and SPOT light.

◆ direction

RRVec3 rr::RRLight::direction

Normalized direction of light in world space. Relevant only for DIRECTIONAL and SPOT light. Be careful, setting unnormalized value would break lightmap building.

◆ outerAngleRad

RRReal rr::RRLight::outerAngleRad

Outer cone angle in radians. Relevant only for SPOT light.

Insight: This is half width of spot, FOV/2.
Light rays go in directions up to outerAngleRad far from direction.
Valid range: (0,pi/2). Out of range values are clamped at construction time, changes you make later are accepted without checks.

◆ radius

RRReal rr::RRLight::radius

Relevant only for distanceAttenuation==EXPONENTIAL. Distance in world space, where light disappears due to its distance attenuation. Light has effect in sphere of given radius.

◆ color

RRVec3 rr::RRLight::color

Light color. Interpretation depends on distanceAttenuationType.

◆ projectedTexture

RRBuffer* rr::RRLight::projectedTexture

Projected texture.

Relevant only for type=SPOT. You may set/change it at any time, renderer updates automatically.

Works as a replacement for spotlight parameters outerAngleRad, fallOffAngleRad, spotExponent. When set, spotlight is modulated by both texture and color.

When you set texture, ownership is passed to light, light deletes texture in destructor.

◆ distanceAttenuationType

DistanceAttenuationType rr::RRLight::distanceAttenuationType

Type of distance attenuation.

◆ polynom

RRVec4 rr::RRLight::polynom

Relevant only for distanceAttenuation==POLYNOMIAL. Distance attenuation in custom scale is computed as colorCustom/MAX(polynom[0]+polynom[1]*distance+polynom[2]*distance^2,polynom[3])

◆ fallOffExponent

RRReal rr::RRLight::fallOffExponent

Relevant only for distanceAttenuation==EXPONENTIAL. Distance attenuation in custom scale is computed as colorCustom*pow(MAX(0,1-(distance/radius)^2),fallOffExponent).

◆ spotExponent

RRReal rr::RRLight::spotExponent

Exponent that controls attenuation from innerAngle to outerAngle in spotlight.

Relevant only for type=SPOT. Default exponent 1 makes attenuation linear in custom/sRGB scale.

◆ fallOffAngleRad

RRReal rr::RRLight::fallOffAngleRad

Outer-inner cone angle in radians. Relevant only for SPOT light.

Light rays with direction diverted less than outerAngleRad from direction, but more than outerAngleRad-fallOffAngleRad, are attenuated. If your data contain innerAngle, set fallOffAngle=outerAngle-innerAngle.
Valid range: (0,innerAngleRad>. Out of range values are clamped at construction time, changes you make later are accepted without checks.

◆ enabled

bool rr::RRLight::enabled

Enables/disables light.

There are other slower ways to enable/disable light:

Add/remove light from solver. But it takes longer to add/remove light than to flip flag.
Set light color to 0. But it does not speed up calculation/rendering, light is not optimized out.

◆ castShadows

bool rr::RRLight::castShadows

Whether light casts shadows.

Shadows are enabled by default, so light behaves realistically. You can disable shadows and break realism. But then, you should consider what is purpose of disabled shadows. Global illumination replaces fill lights, ambient lights and other fakes, you should remove such lights.

◆ directLambertScaled

bool rr::RRLight::directLambertScaled

Enables workaround for error in game engines.

False = realistic lighting, default. True = copy error that used to be present in 99% of game engines, calculate direct Lambertian reflection in sRGB, make offline calculated lightmaps more similar to realtime lighting in game engines. Affects offline solver only, realtime solvers integrate with arbitrary direct lighting without need for extra settings.

◆ rtNumShadowmaps

unsigned rr::RRLight::rtNumShadowmaps

How many shadowmaps realtime renderer should use. More = higher quality, slower.

Relevant only for realtime renderer (has rt prefix). You may set/change it at any time, renderer updates automatically. 1 or 2 is optimal for small scenes and for viewing scenes from distance where additional details that 3 provides are hardly visible.

◆ rtShadowmapSize

unsigned rr::RRLight::rtShadowmapSize

How large (width=height) shadowmaps realtime renderer should use. More = higher quality, slower.

Relevant only for realtime renderer (has rt prefix). You may set/change it at any time, renderer updates automatically. Set higher resolution for hard and sharper shadows, lower for area and more blurry shadows.

◆ rtShadowmapBias

RRVec2 rr::RRLight::rtShadowmapBias

Shadowmap bias multiplier.

Relevant only for realtime renderer (has rt prefix). You may set/change it at any time, renderer updates automatically.

x controls slope/factor part of bias, y controls fixed part. Set 1 for default automatic bias, more for larger bias, less for smaller.

◆ rtShadowmapAutomaticNearFar

bool rr::RRLight::rtShadowmapAutomaticNearFar

Enables automatic update of shadowmap near/far.

◆ rtShadowmapNear

RRReal rr::RRLight::rtShadowmapNear

Shadowmap near plane distance.

Relevant only for realtime renderer (has rt prefix). Only shadow casters in near..far distance cast shadows. Ignored for directional light. Ignored if rtShadowmapAutomaticNearFar is false.

◆ rtShadowmapFar

RRReal rr::RRLight::rtShadowmapFar

Shadowmap far plane distance.

Relevant only for realtime renderer (has rt prefix). Only shadow casters in near..far distance cast shadows. Ignored for directional light. Ignored if rtShadowmapAutomaticNearFar is false.

◆ name

RRString rr::RRLight::name

Optional name of light.

◆ customData

void* rr::RRLight::customData

Custom data, initialized to nullptr, never accessed by LightsprintCore again.

Adapters may use it to store pointer to original structure that was adapted for Lightsprint.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Type

◆ DistanceAttenuationType

Constructor & Destructor Documentation

◆ RRLight() [1/2]

◆ RRLight() [2/2]

◆ ~RRLight()

Member Function Documentation

◆ operator=()

◆ getIrradiance()

◆ blendLinear()

◆ blendAkima()

◆ operator==()

◆ operator!=()

◆ createDirectionalLight()

◆ createPointLight()

◆ createPointLightNoAtt()

◆ createPointLightRadiusExp()

◆ createPointLightPoly()

◆ createSpotLight()

◆ createSpotLightNoAtt()

◆ createSpotLightRadiusExp()

◆ createSpotLightPoly()

◆ fixInvalidValues()

Member Data Documentation

◆ type

◆ position

◆ direction

◆ outerAngleRad

◆ radius

◆ color

◆ projectedTexture

◆ distanceAttenuationType

◆ polynom

◆ fallOffExponent

◆ spotExponent

◆ fallOffAngleRad

◆ enabled

◆ castShadows

◆ directLambertScaled

◆ rtNumShadowmaps

◆ rtShadowmapSize

◆ rtShadowmapBias

◆ rtShadowmapAutomaticNearFar

◆ rtShadowmapNear

◆ rtShadowmapFar

◆ name

◆ customData