Usage

#include <RixLighting.h>

Classes
class	SampleMode
	Deprecated, always use default-constructed object. More...

Public Types
enum	IntegratorIntent { k_LightSamples, k_MaterialSamples, k_MaterialAndLightSamples }

enum	FixedSampleCountMode { k_IgnoreFixedSampleCount = 0, k_RespectFixedSampleCount = 1, k_ReducedFixedSampleCount = 2 }

typedef FixedSampleCountMode	Mode

enum	Type { k_Float, k_Integer, k_StringV, k_Color, k_Normal, k_Vector, k_Point, k_HPoint, k_MPoint, k_Matrix }

Public Member Functions
	RixLightingServices ()

virtual void	Begin (RixShadingContext const shadingContext, RixRNG rixRNG, RixBXEvaluateDomain evaluationDomain, IntegratorIntent integratorIntent, FixedSampleCountMode fixedSampleCountMode, SampleMode sampleMode, int *fixedSampleCount=nullptr, int depth=0, int parentIndirectCount=1)=0
	Initializes the lighting services for a given shading context. More...

virtual void	GenerateSamples (int numLightSamples, RixRNG rixRNG, int lightGroupIds, RixLPEToken lightLpeTokens, RtVector3 directionsToSamples, RtNormal3 lightNormals, float distancesToSamples, RixBXLobeWeights lightContributions, RtColorRGB transmissions, RtColorRGB volumeEmissions, float directLightingPdfs, float selectionProbs, RixBXLobeTraits const materialLobesWanted, RixBXLobeWeights evaluatedMaterialWeights, float evaluatedMaterialFPdfs, float evaluatedMaterialRPdfs, RixBXLobeTraits evaluatedMaterialLobes, RixLight *sampledLights, RtColorRGB const pathThroughputs=nullptr, RixMWConnectionResult *mwConnectionResult=nullptr)=0
	Generates light samples for the shading points encapsulated by the RixShadingContext given to Begin(). More...

virtual void	GenerateSamples (int numLightSamples, RixRNG rixRNG, int lightGroupIds, RixLPEToken lightLpeTokens, RtVector3 directionsToSamples, RtNormal3 lightNormals, float distancesToSamples, RixBXLobeWeights lightContributions, RtColorRGB transmissions, RtColorRGB volumeEmissions, float directLightingPdfs, float selectionProbs, float emissionPositionPdfs, float emissionDirectionPdfs, float solidAngleToAreaFactors, RixBXLobeTraits const materialLobesWanted, RixBXLobeWeights evaluatedMaterialWeights, float evaluatedMaterialFPdfs, float evaluatedMaterialRPdfs, RixBXLobeTraits evaluatedMaterialLobes, RixLight sampledLights, RtColorRGB const pathThroughputs=nullptr, RixPhotonGuiding const photonGuide=nullptr, RixMWConnectionResult mwConnectionResult=nullptr)=0
	Generates light samples for the shading points encapsulated by the RixShadingContext given to Begin(). More...

virtual void	GenerateSamplesForRaySegments (int numLightSamples, RixRNG rixRNG, float maxDistances, RtVector3 samplePositions, float selectionProbs, float segmentMinT, float segmentMaxT)=0
	Generates light samples for the line segments encapsulated by the RixShadingContext given to Begin() (P denotes the origin of the ray, Vn its direction and VLen its length. More...

virtual void	EvaluateSamples (int numMaterialSamples, RixRNG rixRNG, RtVector3 const directions, float distances, float const materialPdfs, RixBXLobeWeights const materialWeights, RixBXLobeSampled const materialLobeSampled, int lightGroupIds, RixLPEToken lightLpeTokens, RixBXLobeWeights lightContributions, RtColorRGB transmissions, RtColorRGB volumeEmissions, float directLightingPdfs, float selectionProbs, RtNormal3 lightNormals, RixLight *evaluatedLights, RtColorRGB const pathThroughputs=nullptr)=0
	Evaluate light contributions for the provided directions, w.r.t. More...

virtual void	EvaluateSamples (int numMaterialSamples, RixRNG rixRNG, RtVector3 const directions, float distances, float const materialPdfs, RixBXLobeWeights const materialWeights, RixBXLobeSampled const materialLobeSampled, int lightGroupIds, RixLPEToken lightLpeTokens, RixBXLobeWeights lightContributions, RtColorRGB transmissions, RtColorRGB volumeEmissions, float directLightingPdfs, float selectionProbs, float emissionPositionPdfs, float emissionDirectionPdfs, float solidAngleToAreaFactors, RtNormal3 lightNormals, RixLight evaluatedLights, RtColorRGB const pathThroughputs=nullptr, RixPhotonGuiding const *photonGuide=nullptr)=0
	Evaluate light contribution for the provided directions, w.r.t. More...

virtual void	BeginEmission (FixedSampleCountMode mode, int *fixedSampleCount=nullptr)=0
	Initializes the lighting services for photon emission. More...

virtual void	GenerateEmission (int numPts, int const integratorContextIndices, int const rayIds, int numSamples, RixRNG rixRNG, int lightGroupIds, RixLPEToken lightLpeTokens, RixBXLobeWeights lightContributions, RtColorRGB transmissions, RtColorRGB volumeEmissions, int numShadingContexts, RixShadingContext const *shadingContexts, RtPoint3 emissionPositions, RtVector3 emissionNormals, float distances, float directLightingPdfs, float selectionProbs, float emissionPositionsPdfs, RtVector3 emissionDirections, float emissionCosines, float emissionDirectionPdfs, float solidAngleToAreaFactors, RixPhotonGuiding const photonGuide=nullptr)=0
	Generates photons on the surface of the lights, then trace them through the scene. More...

virtual void	End ()=0
	Must be call in pair with `Begin()`. More...

virtual void	EndEmission ()=0
	Must be call in pair with `BeginEmission()`. More...

virtual int	GetNumLightGroups ()=0

virtual int	GetLightGroup (RtUString const name)=0

virtual RtUString	GetLightGroupName (int i)=0

virtual int	GetTotalNumLights ()=0

virtual int	GetTotalNumLightsWithFixedSamples ()=0

virtual int	GetTotalFixedSamples ()=0

virtual void	UpdateWithResults (int nSamples, RixBXLobeWeights const contribution, RtColorRGB const trans, float const lPdfDirect, float const lightSelectionProbs, float const distances, RixBXLobeWeights const evaluatedMaterialWeights, const RixLight const lights)=0
	Optional function to update the lighting services with results after the caller has independently computed material weights and/or visibility. More...

virtual void	IrradianceEstimate (uint32_t lightSetId, RtPoint3 const points, int numPts, float estimates, float *confidences)=0
	Return an estimates of the irridiance incident on a set of points in space This will be zero if no estimate is available. More...

virtual int	GetVersion () const
	Get the version number of this interface. More...

Protected Member Functions
virtual	~RixLightingServices ()

Protected Attributes
RixShadingContext const *	shadingCtx

RixBXEvaluateDomain	domain

int	m_version
	Version number of this interface. More...

Detailed Description

Usage

A RixLightingServices object has to be obtained via RixIntegratorContext::GetLightingServices().

Call sequence for Unidirectional integrators:

Begin(shadingCtx, ...) // for direct lighting to RixShadingContext
GenerateSamples()
EvaluateSamples()
End()

Call sequence for Bidirectional integrators:

BeginEmission() // for "photon" generation
GenerateEmission()
End()
Begin(shadingCtx, ...) // for direct lighting to RixShadingContext
GenerateSamples()
EvaluateSamples()
End()

Random number contexts

When creating a RNG for use by GenerateSamples, either pass the inherited (passed-in) RNG or make a new one with RixRNG::NewDomain().

Fixed sample count lights

Individual lights may be configured to have a fixed sample count, in which case their sample budget is fixed and not statistically chosen from the global count. In order to support this, FixedSampleCountMode::k_RespectFixedSampleCount should be passed to the Begin() method. In addition, the caller must provide a pointer into which we return the total required number of fixed samples.

In order for MIS weights to be correctly computed, the evaluation of material samples needs to be aware of whether fixed sample counts were satisfied or not, which is why Begin() has to be provided with this information. Passing FixedSampleCountMode::k_IgnoreFixedSampleCount permits sample counts to be tailored down as the trace depth increases.

Subsequent lighting services calls should be invoked with at least that number of samples in order for the fixed sample count requests to be satisfied. Generally, the caller would also add a non-zero number of 'global budget' samples (i.e. samples to be shared by the lights without a fixed sample count). If the number of samples is smaller that the fixed sample requirement then we fall back to statistical (globally-budgeted) sampling.

Note: passing FixedSampleCountMode::k_RespectFixedSampleCount to the BeginEmission() method does not dictate sample counts but rather indicates that the count would have / will be respected for the GenerateSamples() calls that will be made in subsequent Begin()-End() pairs. The information returned by BeginEmission() indicates the fixed sampling requests to expect for subsequent (non-global) Begin() calls, and is not an indication to pass at least that many samples to GenerateEmission().

Bidirectional variants

Two versions of GenerateSamples() and EvaluateSamples() are provided. The bidirectional variants have additional outputs and will compute emission pdfs and other quantities relevant for bidirectional transport. To use them, the integrator must specify bidirectional requirements when it configures itself.

`GenerateSamples()` and Bxdf evaluation

GenerateSamples() can trigger evaluation of the Bxdf, by providing optional arguments that are traditionally passed to RixBxdf::EvaluateSample(). When provided, the RixLightingServices will take over the task of invoking the bxdf to evaluate the generated light samples. This will return the same results that would have been obtained by a loop over Bxdf::EvaluateSample().

By doing so the per-light sample bxdf weights can be known by the lighting services. This information can be used to reduce the transmission computations (e.g. not tracing transmission for samples with zero material response), therefore it is strongly advised that integrators allow lighting services to perform the bxdf evaluation.

This behavior is requested by passing non-nullptr values for these parameters:

materialLobesWanted
evaluatedMaterialWeights
evaluatedMaterialFPdf
evaluatedMaterialRPdf (for bidirectional)
evaluatedMaterialLobes

Member Typedef Documentation

◆ Mode

typedef FixedSampleCountMode RixLightingServices::Mode

Member Enumeration Documentation

◆ FixedSampleCountMode

enum RixLightingServices::FixedSampleCountMode

Enumerator
k_IgnoreFixedSampleCount
k_RespectFixedSampleCount
k_ReducedFixedSampleCount

◆ IntegratorIntent

enum RixLightingServices::IntegratorIntent

Enumerator
k_LightSamples
k_MaterialSamples
k_MaterialAndLightSamples

◆ Type

enum RixInterface::Type

inherited

Enumerator
k_Float
k_Integer
k_StringV
k_Color
k_Normal
k_Vector
k_Point
k_HPoint
k_MPoint
k_Matrix

Constructor & Destructor Documentation

◆ RixLightingServices()

RixLightingServices::RixLightingServices ( )

inline

◆ ~RixLightingServices()

virtual RixLightingServices::~RixLightingServices ( )

inlineprotectedvirtual

Member Function Documentation

◆ Begin()

virtual void RixLightingServices::Begin	(	RixShadingContext const *	shadingContext,
		RixRNG *	rixRNG,
		RixBXEvaluateDomain	evaluationDomain,
		IntegratorIntent	integratorIntent,
		FixedSampleCountMode	fixedSampleCountMode,
		SampleMode	sampleMode,
		int *	fixedSampleCount = `nullptr`,
		int	depth = `0`,
		int	parentIndirectCount = `1`
	)

pure virtual

Initializes the lighting services for a given shading context.

Following calls to GenerateSamples() and EvaluateSamples() are relative to the shading context provided to the associated Begin() call. In particular, the 'number of points' referred to by these methods is the shading context's ‘numPts’.

Parameters

[in]	shadingContext	Shading context encapsulating the points to be lit. The lighting services will retrieve various quantities from this shading context (`P`, `Nn`, bxdf, etc.)
[in]	rixRNG	Pointer to a single RixRNG object.
[in]	evaluationDomain	Describes the domain that needs to be considered by the lighting services. Light samples will not be generated outside of this domain.
[in]	integratorIntent	Indicates if only `GenerateSamples()`, `EvaluateSamples()`, or both will be called.
[in]	fixedSampleCountMode	Indicates if the lights' fixed sample count should be used.
[in]	sampleMode	Deprecated. Use a default-constructed `SampleMode` object.
[out]	fixedSampleCount	Number of fixed samples required by the lights (for the currently linked light set).
[in]	depth	Indicates the depth of the lighting computations. 0 means the shading context encapsulate camera ray hit points.
[in]	parentIndirectCount	Deprecated and ignored.

◆ BeginEmission()

virtual void RixLightingServices::BeginEmission	(	FixedSampleCountMode	mode,
		int *	fixedSampleCount = `nullptr`
	)

pure virtual

Initializes the lighting services for photon emission.

Photon emission is a global process, so there is no associated shading context.

Parameters

[in]	fixedSampleCountMode	Indicates if the lights' fixed sample count should be used. Note that the fixed sample counts are not taken into account during photon emission, and only affect direct lighting methods (`GenerateSamples()` and `EvaluateSamples()`).
[out]	fixedSampleCount	Number of fixed samples required by all the lights in the scene.

◆ End()

virtual void RixLightingServices::End ( )

pure virtual

Must be call in pair with Begin().

◆ EndEmission()

virtual void RixLightingServices::EndEmission ( )

pure virtual

Must be call in pair with BeginEmission().

◆ EvaluateSamples() [1/2]

virtual void RixLightingServices::EvaluateSamples	(	int	numMaterialSamples,
		RixRNG *	rixRNG,
		RtVector3 const *	directions,
		float *	distances,
		float const *	materialPdfs,
		RixBXLobeWeights const *	materialWeights,
		RixBXLobeSampled const *	materialLobeSampled,
		int *	lightGroupIds,
		RixLPEToken *	lightLpeTokens,
		RixBXLobeWeights *	lightContributions,
		RtColorRGB *	transmissions,
		RtColorRGB *	volumeEmissions,
		float *	directLightingPdfs,
		float *	selectionProbs,
		RtNormal3 *	lightNormals,
		RixLight **	evaluatedLights,
		RtColorRGB const *	pathThroughputs = `nullptr`
	)

pure virtual

Evaluate light contributions for the provided directions, w.r.t.

shading points encapsulated by the RixShadingContext given to Begin(). This is the unidirectional version.

Can optionally:

trace transmision rays
evaluate participating medium emission

For each shading point and material sample configuration, we describe the corresponding intersection point with a light, and its associated contributions and geometric properties as the 'evaluated light sample'. If multiple lights can be hit for a given configuration, only one evaluated light sample is returned (stochastically chosen).

In the following section, numPts refers to the number of points on the shading context given to Begin() (shadingContext->numPts). Additionally, for this section, the expression 'light samples' is meant to be read as 'evaluated light samples'.

Unless explicitly specified otherwise, the pointer parameters are arrays of size numPts * numMaterialSamples (i.e. the total number of samples being evaluated for the batch of shading points).

Shading points and light samples (potentially more than one sample per shading point) are associated in the following way: for a given shading point with (shading context) index i, the corresponding light sample properties are stored at indices i + j * numPts, where j is a number between 0 and numMaterialSamples.

The RixBXLobeWeights objects must encapsulate arrays of length numPts * numMaterialSamples (for each required lobe).

Optional pointer parameters can be set to nullptr if the associated quantity isn't needed.

Parameters

[in]	numMaterialSamples	Number of material samples to be evaluated for each point.
[in]	rixRNG	Pointer to a single RixRNG object.
[in,out]	distances	Input: maximum distances to consider when searching for light samples. Output: distances to the light samples.
[in]	materialFPdfs	Forward pdfs of the sampled material samples.
[in]	materialWeights	Pointer to a single RixBXLobeWeights object, that contains the material responses of the sampled material samples.
[in]	materialLobeSampled	Lobe traits of the sampled material samples.
[out]	lightGroupIds	Light group ids of the lights associated with each light sample. These ids can be given to `GetLightGroupName()`.
[out]	lightLpeTokens	Lpe tokens of the lights associated with each light sample. These lpe tokens can be given to the `RixLPE::SplatHelper()` constructor.
[out]	lightContributions	Pointer to a single RixBXLobeWeights object, where the light samples contributions will be stored.
[out]	transmissions	Transmissions between each shading point and the light samples. Optional.
[out]	volumeEmissions	Emissions due to participating medium along the segments between the shading points and the light sample positions. Optional.
[out]	directLightingPdfs	Light samples pdfs, expressed in solid angle measure w.r.t. the shading points.
[out]	lightNormals	Light surface normals at the evaluated sample positions.
[out]	evaluatedLights	Pointers to the lights associated with the light samples. Optional.
[in]	pathThroughputs	Throughputs associated with the shading points. May be used to help culling transmission rays. Array of size `numPts`. Optional.

◆ EvaluateSamples() [2/2]

virtual void RixLightingServices::EvaluateSamples	(	int	numMaterialSamples,
		RixRNG *	rixRNG,
		RtVector3 const *	directions,
		float *	distances,
		float const *	materialPdfs,
		RixBXLobeWeights const *	materialWeights,
		RixBXLobeSampled const *	materialLobeSampled,
		int *	lightGroupIds,
		RixLPEToken *	lightLpeTokens,
		RixBXLobeWeights *	lightContributions,
		RtColorRGB *	transmissions,
		RtColorRGB *	volumeEmissions,
		float *	directLightingPdfs,
		float *	selectionProbs,
		float *	emissionPositionPdfs,
		float *	emissionDirectionPdfs,
		float *	solidAngleToAreaFactors,
		RtNormal3 *	lightNormals,
		RixLight **	evaluatedLights,
		RtColorRGB const *	pathThroughputs = `nullptr`,
		RixPhotonGuiding const *	photonGuide = `nullptr`
	)

pure virtual

Evaluate light contribution for the provided directions, w.r.t.

shading points encapsulated by the RixShadingContext given to Begin(). This is the bidirectional version.

The bidirectional version of this method directly extends the unidirectional version, and produces additional emission pdfs.

Can optionally:

evaluate volumetric pdfs

Parameters

[in]	numMaterialSamples
[in]	rixRNG
[in,out]	distances
[in]	materialFPdfs
[in]	materialWeights
[in]	materialLobeSampled
[out]	lightGroupIds
[out]	lightLpeTokens
[out]	lightContributions
[out]	transmissions
[out]	volumeEmissions
[out]	directLightingPdfs
[out]	emissionPositionPdfs	Positional pdfs of the light samples, expressed in area measure. For samples evaluated for infinite lights (for which area is not well-defined), the value FLT_MAX is returned.
[out]	emissionDirectionPdfs	Directional pdfs of the light samples, expressed in solid angle measure, w.r.t. emission position. These are conditional pdfs, knowing the emission positions. For samples evaluated for infinite lights, the value 1.0f is returned.
[out]	solidAngleToAreaFactor	Conversion factors from solid angle measure (w.r.t. the shading points) to area measure.
[out]	lightNormals
[out]	evaluatedLights
[in]	pathThroughputs
[in]	photonGuide	Pointer to a single RixPhotonGuide object. If photon guiding is used when calling `GenerateEmission()`, the same object needs to be used here in order to get consistent emission pdfs across the various `GenerateSamples()` and `EvaluateSamples()` calls. Optional.

◆ GenerateEmission()

virtual void RixLightingServices::GenerateEmission	(	int	numPts,
		int const *	integratorContextIndices,
		int const *	rayIds,
		int	numSamples,
		RixRNG *	rixRNG,
		int *	lightGroupIds,
		RixLPEToken *	lightLpeTokens,
		RixBXLobeWeights *	lightContributions,
		RtColorRGB *	transmissions,
		RtColorRGB *	volumeEmissions,
		int *	numShadingContexts,
		RixShadingContext const ***	shadingContexts,
		RtPoint3 *	emissionPositions,
		RtVector3 *	emissionNormals,
		float *	distances,
		float *	directLightingPdfs,
		float *	selectionProbs,
		float *	emissionPositionsPdfs,
		RtVector3 *	emissionDirections,
		float *	emissionCosines,
		float *	emissionDirectionPdfs,
		float *	solidAngleToAreaFactors,
		RixPhotonGuiding const *	photonGuide = `nullptr`
	)

pure virtual

Generates photons on the surface of the lights, then trace them through the scene.

The resulting hits are returned in the form of RixShadingContext objects.

Caller is responsible for freeing the returned RixShadingContext pointers via a calls to RixIntegratorContext::ReleaseShadingContexts().

Number of emitted photons

This function needs to be provided with a number of 'points' (numPts), where each point represents a configuration composed of:

the index of a primary ray
a user-provided ray id The primary ray index will be used to retrieve properties, like emission time. The ray id will be return as rayId in the shading context associated with all the photons generated for this point.

For each point configuration, numSamples photons will be generated. These photons will share some properties, such as their emission time. However, they will have independent emission positions, directions and properties.

As a consequence, a total number of numPts * numSamples photons will be generated.

The RixBXLobeWeights objects must encapsulate arrays of length numPts * numSamples (for each required lobe).

Photon hits

Each photon hit is returned in its own shading context. The numSamples hits found for the photons associated with the 'point' of index i are stored in shadingContexts[i]. The shading context associated with sample j of point i is shadingContexts[i][j].

This means that shadingContexts has to be an array of size numPts (element type is RixShadingContext**). And each array element has to be an array of size numSamples (element type is RixShadingContext*).

Because photons can entirely miss the scene geometry, the actual number of valid shading contexts for a given point i may be less than numSamples. This number will be returned in the array numShadingContexts[i]. A value of zero indicates that all photon emitted for the corresponding point have missed.

Light linking

Because photon emission is a global process, light linking isn't known at the moment of photon creation and emission. However, after a photon has hit an object, light linking checked. If the light that emitted the photon isn't part of the linked light set of the hit object, the corresponding direct lighting pdf will be set to zero, and all other quantities for this hit should be considered invalid.

Parameters

[in]	numPts	Number of point configurations for which to generate photons.
[in]	integratorContextIndices	Integrator context indices associated with each point configuration.
[in]	rayIds	User-provided ray ids associated with each point configuration.
[in]	numSamples	Number of photons to generate for each point configuration.
[in]	rixRNG	Pointer to a single RixRNG object.
[out]	lightGroupIds	Light group ids of the lights associated with each photon. These ids can be given to `GetLightGroupName()`.
[out]	lightLpeTokens	Lpe tokens of the lights associated with each photon. These lpe tokens can be given to the `RixLPE::SplatHelper()` constructor.
[out]	lightContributions	Pointer to a single RixBXLobeWeights object, where the photon contributions will be stored.
[out]	transmissions	Transmissions between the photon emission positions and their associated hit points.
[out]	volumeEmissions	Emissions due to participating medium along the segments between the photon emission positions and their associated hit points. Optional.
[out]	numShadingContexts	Number of valid shading contexts returned for each point configuration. Must be an array of size `numPts`. Returned values will be a number between `0` and `numSamples`. See method description for more details.
[out]	shadingContexts	Shading contexts associated with each photon hit. Must be an array of size ‘numPts’, of arrays of size 'numSamples'. See method description for more details.
[out]	emissionPositions	Photon emission positions.
[out]	emissionNormals	Light surface normals at the photon emission positions.
[out]	distances	Distances between the photon emission positions and photon hits. These are also valid for infinite lights, since the actual photon emission positions and distances to hits may be needed by some light transport algorithms.
[out]	directLightingPdfs	Direct light sampling pdfs, expressed in solid angle measure w.r.t. the photon hits. These are the `directLightingPdfs` quantities that would have been returned by the `GenerateSamples()` and `EvaluateSamples()` when generating or evaluating light samples at the photon emission position.
[out]	emissionPositionPdfs	Positional pdfs of the light samples, expressed in area measure. For samples evaluated for infinite lights (for which area is not well-defined), the value FLT_MAX is returned.
[out]	emissionDirections	Photon emission direction. Oriented from the photon emission position to the photon hit.
[out]	emissionCosines	Cosine between the photon emission direction and the photon emission normal. position to the photon hit.
[out]	emissionDirectionPdfs	Directional pdfs of the light samples, expressed in solid angle measure, w.r.t. emission position. These are conditional pdfs, knowing the emission positions. For samples evaluated for infinite lights, the value 1.0f is returned.
[out]	solidAngleToAreaFactor	Conversion factors from solid angle measure (w.r.t. the photon hits) to area measure.
[in]	photonGuide	Pointer to a single RixPhotonGuide object. If photon guiding is used when calling `GenerateEmission()`, the same object needs to be used here in order to get consistent emission pdfs across the various `GenerateSamples()` and `EvaluateSamples()` calls. Optional.

◆ GenerateSamples() [1/2]

virtual void RixLightingServices::GenerateSamples	(	int	numLightSamples,
		RixRNG *	rixRNG,
		int *	lightGroupIds,
		RixLPEToken *	lightLpeTokens,
		RtVector3 *	directionsToSamples,
		RtNormal3 *	lightNormals,
		float *	distancesToSamples,
		RixBXLobeWeights *	lightContributions,
		RtColorRGB *	transmissions,
		RtColorRGB *	volumeEmissions,
		float *	directLightingPdfs,
		float *	selectionProbs,
		RixBXLobeTraits const *	materialLobesWanted,
		RixBXLobeWeights *	evaluatedMaterialWeights,
		float *	evaluatedMaterialFPdfs,
		float *	evaluatedMaterialRPdfs,
		RixBXLobeTraits *	evaluatedMaterialLobes,
		RixLight **	sampledLights,
		RtColorRGB const *	pathThroughputs = `nullptr`,
		RixMWConnectionResult *	mwConnectionResult = `nullptr`
	)

pure virtual

Generates light samples for the shading points encapsulated by the RixShadingContext given to Begin().

This is the unidirectional version.

Can optionally:

evaluate material responses
trace transmision rays
evaluate participating medium emission

In the following section, numPts refers to the number of points on the shading context given to Begin() (shadingContext->numPts). Additionally, the expression 'light samples' is meant to be read as 'generated light samples'.

Unless explicitly specified otherwise, pointer parameters are arrays of size numPts * numLightSamples (i.e. the total number of light samples being generated for the batch of shading points).

Shading points and light samples (potentially more than one sample per shading point) are associated in the following way: for a given shading point with (shading context) index i, the corresponding light samples properties are stored at indices i + j * numPts, where j is a number between 0 and numLightSamples.

The RixBXLobeWeights objects must encapsulate arrays of length numPts * numLightSamples (for each required lobe).

Optional pointer parameters can be set to nullptr if the associated quantity isn't needed.

Parameters

[in]	numLightSamples	Number of light samples to be generated for each point. Depending on the `FixedSampleCountMode` passed to `Begin()`, this number must at least be equal to the number of fixed samples `fixedSampleCount` returned by `Begin()`.
[in]	rixRNG	Pointer to a single RixRNG object.
[out]	lightGroupIds	Light group ids of the lights associated with each light sample. These ids can be given to `GetLightGroupName()`.
[out]	lightLpeTokens	Lpe tokens of the lights associated with each light sample. These lpe tokens can be given to the `RixLPE::SplatHelper()` constructor.
[out]	directionsToSamples	Normalized directions to the light samples. For local lights, the sample positions are `P + directionToSample * distanceToSample` (where `P` is obtained from the shading context).
[out]	lightNormals	Light surface normals at the sample positions.
[out]	distancesToSamples	Distances to the light samples. For local lights, this is exactly the distance to the light sample. For infinite lights, this will be set to a value that is larger that the scene extent.
[out]	lightContributions	Pointer to a single RixBXLobeWeights object, where the light samples contributions will be stored.
[out]	transmissions	Transmissions between each shading point and the light samples. Optional.
[out]	volumeEmissions	Emissions due to participating medium along the segments between the shading points and the light sample positions. Optional.
[out]	directLightingPdfs	Light samples pdfs, expressed in solid angle measure w.r.t. the shading points.
[out]	selectionProbs	The probability assigned by light selection for the chosen light being selected.
[in]	materialLobesWanted	Provides restrictions on the lobes that will be considered when the lighting services evaluate material responses. Array of size `numPts`. Optional.
[out]	evaluatedMaterialWeights	Pointer to a single RixBXLobeWeights object, where the material responses for the samples will be stored. The bxdf is retrieved from the shading context. Optional.
[out]	evaluatedMaterialFPdfs	Forward pdfs of the evaluated material responses. Optional.
[out]	evaluatedMaterialRPdfs	Reverse pdfs of the evaluated material responses. Optional.
[out]	evaluatedMaterialLobes	Lobe traits of the evaluated material responses. Optional.
[out]	sampledLights	Pointers to the lights associated with the light samples. Optional.
[in]	pathThroughputs	Throughputs associated with the shading points. May be used to help culling transmission rays. Array of size `numPts`. Optional.

◆ GenerateSamples() [2/2]

virtual void RixLightingServices::GenerateSamples	(	int	numLightSamples,
		RixRNG *	rixRNG,
		int *	lightGroupIds,
		RixLPEToken *	lightLpeTokens,
		RtVector3 *	directionsToSamples,
		RtNormal3 *	lightNormals,
		float *	distancesToSamples,
		RixBXLobeWeights *	lightContributions,
		RtColorRGB *	transmissions,
		RtColorRGB *	volumeEmissions,
		float *	directLightingPdfs,
		float *	selectionProbs,
		float *	emissionPositionPdfs,
		float *	emissionDirectionPdfs,
		float *	solidAngleToAreaFactors,
		RixBXLobeTraits const *	materialLobesWanted,
		RixBXLobeWeights *	evaluatedMaterialWeights,
		float *	evaluatedMaterialFPdfs,
		float *	evaluatedMaterialRPdfs,
		RixBXLobeTraits *	evaluatedMaterialLobes,
		RixLight **	sampledLights,
		RtColorRGB const *	pathThroughputs = `nullptr`,
		RixPhotonGuiding const *	photonGuide = `nullptr`,
		RixMWConnectionResult *	mwConnectionResult = `nullptr`
	)

pure virtual

Generates light samples for the shading points encapsulated by the RixShadingContext given to Begin().

This is the bidirectional version.

The bidirectional version of this method directly extends the unidirectional version, and produces additional emission pdfs.

Can optionally:

evaluate volumetric pdfs

Parameters

[in]	numLightSamples
[in]	rixRNG
[out]	lightGroupIds
[out]	lightLpeTokens
[out]	directionsToSamples
[out]	lightNormals
[out]	distancesToSamples
[out]	lightContributions
[out]	transmissions
[out]	volumeEmissions
[out]	directLightingPdfs
[out]	selectionProbs	The probability assigned by light selection for the chosen light being selected.
[out]	emissionPositionPdfs	Positional pdfs of the light samples, expressed in area measure. For samples generated by infinite lights (for which area is not well-defined), the value FLT_MAX is returned.
[out]	emissionDirectionPdfs	Directional pdfs of the light samples, expressed in solid angle measure, w.r.t. emission position. These are conditional pdfs, knowing the emission positions. For samples generated by infinite lights, the value 1.0f is returned.
[out]	solidAngleToAreaFactor	Conversion factors from solid angle measure (w.r.t. the shading points) to area measure.
[in]	materialLobesWanted
[out]	evaluatedMaterialWeights
[out]	evaluatedMaterialFPdfs
[out]	evaluatedMaterialRPdfs
[out]	evaluatedMaterialLobes
[out]	sampledLights
[in]	pathThroughputs
[in]	photonGuide	Pointer to a single RixPhotonGuide object. If photon guiding is used when calling `GenerateEmission()`, the same object needs to be used here in order to get consistent emission pdfs across the various `GenerateSamples()` and `EvaluateSamples()` calls. Optional.

◆ GenerateSamplesForRaySegments()

virtual void RixLightingServices::GenerateSamplesForRaySegments	(	int	numLightSamples,
		RixRNG *	rixRNG,
		float *	maxDistances,
		RtVector3 *	samplePositions,
		float *	selectionProbs,
		float *	segmentMinT,
		float *	segmentMaxT
	)

pure virtual

Generates light samples for the line segments encapsulated by the RixShadingContext given to Begin() (P denotes the origin of the ray, Vn its direction and VLen its length.

Note that Vn is in this usage is pointing along the direction of travel of the ray. This function is used to help a volume integrator perform equiangular sampling on rays travelling through the volume

Parameters

[in]	numLightsSamples	Number of light samples to be generated for each ray.
[in]	maxDistances	May be null. Otherwise, specifies the maximum distance a light can be from a line segment and still be considered a valid candidate.
[out]	samplePositions	The positions on the selected lights to be used as apexes for subsequent equiangular sampling
[out]	selectionProbs	The probability assigned by light selection for the chosen light being selected.
[out]	segmentMinT	May be null. A number in the range 0-1 specifying the start of the subset of the input ray that is actually illuminated if the selected light has a spot cone.
[out]	segmentMaxT	May be null. A number in the range 0-1 specifying the end of the subset of the input ray that is actually illuminated if the selected light has a spot cone.

◆ GetLightGroup()

virtual int RixLightingServices::GetLightGroup ( RtUString const name )

pure virtual

Returns: The light group ids associated with a given light group name.

◆ GetLightGroupName()

virtual RtUString RixLightingServices::GetLightGroupName ( int i )

pure virtual

Returns: The light group name associated with a given light group id.

◆ GetNumLightGroups()

virtual int RixLightingServices::GetNumLightGroups ( )

pure virtual

Returns: The total number of distinct light groups in use.

◆ GetTotalFixedSamples()

virtual int RixLightingServices::GetTotalFixedSamples ( )

pure virtual

Returns: The total number of fixed samples.

◆ GetTotalNumLights()

virtual int RixLightingServices::GetTotalNumLights ( )

pure virtual

Returns: The total number of lights.

◆ GetTotalNumLightsWithFixedSamples()

virtual int RixLightingServices::GetTotalNumLightsWithFixedSamples ( )

pure virtual

Returns: The total number of lights with non-zero fixed sample count.

◆ GetVersion()

virtual int RixInterface::GetVersion ( ) const

inlinevirtualinherited

Get the version number of this interface.

Different interfaces might have different version numbers in a given release.

References RixInterface::m_version.

◆ IrradianceEstimate()

virtual void RixLightingServices::IrradianceEstimate	(	uint32_t	lightSetId,
		RtPoint3 const *	points,
		int	numPts,
		float *	estimates,
		float *	confidences
	)

pure virtual

Return an estimates of the irridiance incident on a set of points in space This will be zero if no estimate is available.

The confidence will likewise be set to zero. Confidence is higher the more results have contributed to the learning node closest to each shading point

◆ UpdateWithResults()

virtual void RixLightingServices::UpdateWithResults	(	int	nSamples,
		RixBXLobeWeights const *	contribution,
		RtColorRGB const *	trans,
		float const *	lPdfDirect,
		float const *	lightSelectionProbs,
		float const *	distances,
		RixBXLobeWeights const *	evaluatedMaterialWeights,
		const RixLight const	lights
	)

pure virtual

Optional function to update the lighting services with results after the caller has independently computed material weights and/or visibility.

Member Data Documentation

◆ domain

RixBXEvaluateDomain RixLightingServices::domain

protected

◆ m_version

int RixInterface::m_version

protectedinherited

Version number of this interface.

Referenced by RixInterface::GetVersion().

◆ shadingCtx

RixShadingContext const* RixLightingServices::shadingCtx

protected

The documentation for this class was generated from the following file:

RixLighting.h

Usage

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Usage

Random number contexts

Fixed sample count lights

Bidirectional variants

GenerateSamples() and Bxdf evaluation

Member Typedef Documentation

◆ Mode

Member Enumeration Documentation

◆ FixedSampleCountMode

◆ IntegratorIntent

◆ Type

Constructor & Destructor Documentation

◆ RixLightingServices()

◆ ~RixLightingServices()

Member Function Documentation

◆ Begin()

◆ BeginEmission()

◆ End()

◆ EndEmission()

◆ EvaluateSamples() [1/2]

◆ EvaluateSamples() [2/2]

◆ GenerateEmission()

Number of emitted photons

Photon hits

Light linking

◆ GenerateSamples() [1/2]

◆ GenerateSamples() [2/2]

◆ GenerateSamplesForRaySegments()

◆ GetLightGroup()

◆ GetLightGroupName()

◆ GetNumLightGroups()

◆ GetTotalFixedSamples()

◆ GetTotalNumLights()

◆ GetTotalNumLightsWithFixedSamples()

◆ GetVersion()

◆ IrradianceEstimate()

◆ UpdateWithResults()

Member Data Documentation

◆ domain

◆ m_version

◆ shadingCtx

`GenerateSamples()` and Bxdf evaluation