slr::SlrIntegratorContext Class Reference

#include <SlrIntegrator.h>

Public Member Functions
const fdk::Vec2i &	pixelXY () const
int32_t	pixelX () const
int32_t	pixelY () const
bool	isPixel (int32_t x, int32_t y) const
bool	isPixelX (int32_t x) const
bool	isPixelY (int32_t y) const
bool	isDebugPixel () const
bool	isDebugSample () const
const DD::Image::Format &	renderFormat () const
const DD::Image::Box &	renderRegion () const
SlrEngineContext::RenderProjectionMode	renderProjectionMode () const
	Special projection modes. Default SceneCamera is standard lens projection.
const fdk::Mat4d &	globalSceneXform () const
const fdk::Vec3f &	globalSceneOffset () const
	Same as _globalSceneXform but single-precision for ray offset convenience.
bool	deepIgnoreZeroAlphaSamples () const
const ndk::LensProjectionFunction &	cameraLensFunc () const
	Camera projection function renderer is using.
const ndk::CameraSampleList &	cameraMotionSamples () const
	List of per motion sample camera contexts.
const ndk::Camera::Sample &	cameraMotionSample (size_t motionIndex) const
const ndk::ProjectionImageContext &	cameraImageContext () const
	Screen coordinate transformation info.
uint16_t	rayMaxDepth () const
uint16_t	rayDiffuseMaxDepth () const
uint16_t	rayReflectionMaxDepth () const
uint16_t	rayRefractionMaxDepth () const
int32_t	pixelSeed () const
	Random number seed for current pixel.
ndk::SamplingRng &	subpixelRng (int32_t i) const
	Per-subpixel sampling random number generator.
const fdk::Vec2fList &	subpixelXYs () const
const fdk::Vec2f &	subpixelXY (int32_t i) const
int32_t	primaryRayBundleIndex () const
int32_t	nPrimaryRays () const
	Number of primary/camera ray samples.
int32_t	nSamples () const
	Same as nPrimaryRays.
const SampleInfoList &	sampleInfoList () const
	Per primary ray sample info including time, motion step index and step offset t.
const SampleInfo &	sampleInfo (size_t i) const
fdk::TimeValue	time (size_t i) const
	Time value for a primary ray sample.
const fdk::FloatList &	presenceThresholds () const
float	presenceThreshold (size_t i) const
RenderableWeightMap &	renderablesCoverageMap ()
const DD::Image::Pixel &	bgPixel () const
DD::Image::Pixel &	outputPixel () const
	Final integrated & flattened result.
bool	deepOutputEnabled () const
	Are we outputting deep pixel data?
ndk::DeepPixel *	outputDeepPixel () const
	Final integrated deep result. Only valid when deep output is enabled.
bool	haveAovOutputs () const
	Are there active Aov outputs?
bool	motionVectorsOutputRequested () const
const SlrAovLayerList &	aovShadingLayersList () const
const SlrAovLayerList &	aovCustomLayersList () const
const SlrAovIndexMap &	aovLayerMap () const
	The map of Aov names to SlrAovLayer indices.
const SlrAovLayer *	findAovLayer (const char *name) const
	Find an AovLayer by name.
bool	haveActiveRayBundle () const
	True if there's at least one active ray bundle.
bool	haveActiveRayData () const
	True if there's at least one active ray bundle and an active ray in that bundle.
SlrRayBundle &	startNewCameraRayBundle (ndk::RayContext::TypeMask rayType, uint32_t nRaysPresize=0) const
void	selectActiveRayBundle (const SlrRayBundle &rayBundle) const
SlrRayBundle &	activeRayBundle () const
int32_t	activeRayBundleIndex () const
	Index of active bundle. 0 is the default bundle that always exists.
SlrRayBundle &	endRayBundle () const
int32_t	getNearestSurfaceIntersections (const SlrShadingContext &srcStx, const ndk::RayContext *rtxArray, int32_t nRays, StxBundle &stxBundle) const
void	getNearestIntersections (const SlrShadingContext &srcStx, const ndk::RayContext *rtxArray, int32_t nRays, ndk::RayHitPointfList &hitList) const
bool	getNearestIntersection (const SlrShadingContext &srcStx, const ndk::RayContext &Rtx, ndk::RayHitPointf &hitPoint) const
void	getAllIntersections (const SlrShadingContext &srcStx, const ndk::RayContext &Rtx) const
void	getAllIntersections (const SlrShadingContext &srcStx, const ndk::RayContext &Rtx, ndk::RayHitPointfList &hitList) const
bool	getThinTransmissionFactor (const SlrShadingContext &srcStx, const ndk::RayContext &Rtx, fdk::Vec3f &transmissionFactor) const
void	getPathIllumination (const SlrShadingContext &srcStx, const SlrRayBundle &rays, const DD::Image::ChannelSet &get, DD::Image::Pixel &out)
	Perform shading, etc to calculate the final output result for all provided scene rays.
void	getPathTransmission (const SlrShadingContext &surfaceStx, const SlrRayBundle &entryRays, const DD::Image::ChannelSet &get, DD::Image::Pixel &out)
void	getUVIntersections (const SlrShadingContext &srcStx, const SlrRayBundle &rays, const fdk::Vec2f *uvArray) const
int32_t	nRayHitPoints () const
	Retrieve the hit point count from the last ray cast done by this IntegratorContext.
const ndk::RayHitPointf &	getRayHitPoint (int32_t rayHitIndex=0) const
void	sortRayHits (bool nearToFar=true) const
	Sort the hits in desired direction. Ray hit index 0 is either nearest or farthest after sorting.
void	sortRayHitsNearToFar () const
	Ray hit index 0 is nearest after sorting.
void	sortRayHitsFarToNear () const
	Ray hit index 0 is farthest after sorting.
ndk::OpacityTraitsMask	rayHitPointsOpacityOrMask () const
	OpacityTraitsMask of all the hit points OR'd together.
ndk::OpacityTraitsMask	rayHitPointsOpacityAndMask () const
	OpacityTraitsMask of all the hit points AND'd together.
bool	areAllHitsOpaqueSolid () const
bool	doAllHitsBlend () const
bool	doAllHitsBlendToOpaque () const
void	startActiveSurfaceIntersectionBundleGroup () const
void	addSurfaceIntersectionsToActiveGroup () const
StxBundleList &	activeSurfaceIntersectionBundleGroup () const
StxBundle &	startNewSurfaceIntersectionBundle () const
StxBundle &	activeSurfaceIntersectionBundle () const
void	endSurfaceIntersectionBundle () const
void	setSurfaceIntersectionBundleBlendingOrder (BlendingOrder mode) const
void	setSurfaceIntersectionBundleBlendingOrderFrontToBack () const
void	setSurfaceIntersectionBundleBlendingOrderBackToFront () const
void	setSurfaceIntersectionBundleBlendingOrderDisabled () const
SlrShadingContext &	addNewShadingContextToSurfaceIntersectionBundle (const SlrShadingContext &srcStx, int32_t rayIndex=0) const
DD::Image::Pixel &	activeRaySurfaceColor () const
DD::Image::Pixel &	activeRayLayeredColor () const
DD::Image::Pixel &	accumColor () const
DD::Image::Pixel &	accumData () const
ndk::DeepPixel &	accumDeepPixel () const
const DD::Image::ChannelSet &	shaderChannelSet () const
	Global set of all channels that need alpha premult.
const DD::Image::ChannelSet &	surfaceChannelSet () const
	Global set of all channels surface shaders produce.
const DD::Image::ChannelSet &	dataChannelSet () const
	Global set of data channels that don't want blending with alpha (vectors, Z, normals, etc)
const DD::Image::ChannelSet &	requestedOutChannelSet () const
	Global set of requested channels that Slr2 needs to produce.
const DD::Image::ChannelSet &	requestedOutColorChannelSet () const
	Global set of requested channels that need to be premultiplied for alpha compositing.
const DD::Image::ChannelSet &	requestedOutDataChannelSet () const
	Global set of requested Aov data channels that don't need to be premulted/composited.
const DD::Image::ChannelPack &	shaderChannelPack () const
const DD::Image::ChannelPack &	surfaceChannelPack () const
const DD::Image::ChannelPack &	dataChannelPack () const
const DD::Image::ChannelPack &	bgChannelPack () const
const DD::Image::ChannelPack &	requestedOutChannelPack () const
const DD::Image::ChannelPack &	requestedOutColorChannelPack () const
const DD::Image::ChannelPack &	requestedOutDataChannelPack () const
const SlrAovChannelMap &	aovUnpremultByCoverageChannelMap () const
const SlrAovChannelMap &	aovUnpremultByAlphaChannelMap () const

Protected Member Functions
	SlrIntegratorContext (SlrThreadContext *)

Protected Attributes
SlrThreadContext *	_sttx
fdk::Vec2i	_pixelXY
	Current output pixel screen coord.
int32_t	_pixelSeed
	Assigned random seed for current output pixel.
int32_t	_primaryRayBundle
	Index of the bundle containing all the camera rays for current output pixel.
int32_t	_nPrimaryRays
	Number of primary rays in bundle.
fdk::Vec2fList	_subpixelXYs
	All the randomized subpixel uv coords for current output pixel, one per primary ray.
SampleInfoList	_primaryRaySampleInfoList
	All the randomized sample times and motion step info, one per primary ray.
fdk::FloatList	_presenceThresholds
	All the randomized presence thresholds, one per primary ray.
RenderableWeightMap	_renderablesCoverageMap
	To track pixel coverage weight of renderables during subpixel sample integration.
DD::Image::Pixel	_bgPixel
	Background pixel channel data for current output pixel.

Friends
class	SlrThreadContext
class	RenderEngine

Detailed Description

This class is passed to an SlrIntegrator from the renderer pixel loop for each pixel being rendered. It contains all the camera rays being shot for a pixel so the integrator could perform spatial weighting since each ray origin is at a known relative subpixel location inside the pixel.

Member Function Documentation

globalSceneXform()

const fdk::Mat4d & slr::SlrIntegratorContext::globalSceneXform

(

)

const

World-space values are transformed into shading-space by this matrix, which is commonly just a translate.

Note - Shaders that have world-space values passed as inputs from scene shader nodes need to transform those values by this matrix to put them into shading-space. Lights and objects are transformed by the renderer during setup and have this xform applied.

deepIgnoreZeroAlphaSamples()

bool slr::SlrIntegratorContext::deepIgnoreZeroAlphaSamples

(

)

const

Deep option - ignore all channels of samples where alpha is 0. Integrators can respect this global option to remove deep samples that do not significantly contribute to a deep pixel. Note that deep matte samples will likely not have zero alpha and so should not be affected by this option (ie the cutout alpha value is non-zero.)

cameraMotionSample()

const ndk::Camera::Sample & slr::SlrIntegratorContext::cameraMotionSample

(

size_t

motionIndex

)

const

Per motion sample camera context. Note that motionIndex is clamped to the last motion sample. Note that camera transforms are in shading-space so the camera translation from the frame0 motion sample has been removed. For example if the camera translation is [0 0 10] then the sample will be at [0 0 0] and the Z=+10 offset will be in globalSceneXform().

subpixelXY()

const fdk::Vec2f & slr::SlrIntegratorContext::subpixelXY ( int32_t  i ) const

inline

Returns the subpixel XY offset coordinate inside pixelXY where 0,0 is the center of the pixel, -1,-1 is the pixel left/bottom edge, and +1,+1 is the pixel right/top edge.

renderablesCoverageMap()

RenderableWeightMap & slr::SlrIntegratorContext::renderablesCoverageMap ( )

inline

Convenience map for tracking pixel coverage weight of renderables during integration of subpixel samples together. Typically the renderableIndex() from a SlrShadingContext is used as the key for the map, but other indices could be used. Picking the 'dominant' or 'best' surface sample for a data Aov output is usually a matter of finding the nearest renderable surface with the greatest coverage regardless if it is actually the closest surface. For example if the closest surface has 0.1 coverage but the next closest surface has 0.9 coverage, the 0.9 one wins out since it is the 'dominant' surface in the pixel.

bgPixel()

const DD::Image::Pixel & slr::SlrIntegratorContext::bgPixel ( ) const

inline

Background for final integrated result. The output pixel of the integrator is expected to incorporate the background into its final result. This is provided as a separate value as an integrator may need this value first in the integration vs. compositing the integrated result at the end.

motionVectorsOutputRequested()

bool slr::SlrIntegratorContext::motionVectorsOutputRequested

(

)

const

Motion vector output has been requested. This is only true if the render controls have a valid output channel routing for the motion vector data, to save the cost of calculating them.

aovShadingLayersList()

const SlrAovLayerList & slr::SlrIntegratorContext::aovShadingLayersList

(

)

const

List of shading data Aovs to output. These Aovs are copied directly from SlrShadingContext shading data and are faster to access.

aovCustomLayersList()

const SlrAovLayerList & slr::SlrIntegratorContext::aovCustomLayersList

(

)

const

List of custom-handler Aovs to output. These Aovs have a custom SlrAovLayer::Handler that must be called individually and is thus slower than iterating across the aovShadingLayers list.

startNewCameraRayBundle()

SlrRayBundle & slr::SlrIntegratorContext::startNewCameraRayBundle	(	ndk::RayContext::TypeMask	rayType,
		uint32_t	nRaysPresize = 0
	)		const

Start a new RayContext bundle of camera rays making it the active bundle and returning a reference to it. If nRaysPresize is > 0 then the bundle is pre-sized to that number of rays.

selectActiveRayBundle()

void slr::SlrIntegratorContext::selectActiveRayBundle

(

const SlrRayBundle &

rayBundle

)

const

Make rayBundle be the active one that intersection testing is done on and store in. If the bundle has rays in it the active ray will be set to the first in the bundle. This is not required if startNewRayBundle() was just called.

activeRayBundle()

SlrRayBundle & slr::SlrIntegratorContext::activeRayBundle

(

)

const

Access the currently active RayContext bundle which can be added to. Note that only one bundle may be active at a time.

endRayBundle()

SlrRayBundle & slr::SlrIntegratorContext::endRayBundle

(

)

const

End ray bundle, releasing all the ray, intersection and shading info created for that bundle and changing the current bundle to the previous one in the list. If this is the first bundle nothing happens as there always needs to be one default bundle. Returns the new current ray bundle.

getNearestSurfaceIntersections()

int32_t slr::SlrIntegratorContext::getNearestSurfaceIntersections	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext *	rtxArray,
		int32_t	nRays,
		StxBundle &	stxBundle
	)		const

Intersect a bundle of rays with the closest surfaces to the ray origins, filling in shading contexts. There will only be one shading context created per ray, so the size of the StxBundle will never exceed nRays. If the rays are a coherent set the hits can be described as a 'wavefront' pushed out from the ray origins along the ray directions.

Building surface shading contexts requires evaluating additional surface properties so is more costly than getting the raw geometric hit info.

Note that stxBundle is -not- cleared before adding hits to it.

Returns the number of hits added to stxBundle.

getNearestIntersections()

void slr::SlrIntegratorContext::getNearestIntersections	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext *	rtxArray,
		int32_t	nRays,
		ndk::RayHitPointfList &	hitList
	)		const

Intersect a bundle of rays with the closest surfaces to the ray origins, filling in geometric hit infos. There will only be one hit info created per ray, so the size of the hit list will never exceed nRays. If the rays are a coherent set the hits can be described as a 'wavefront' pushed out from the ray origins along the ray directions.

Note - hitList -is- cleared before adding the hits.

getNearestIntersection()

bool slr::SlrIntegratorContext::getNearestIntersection	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext &	Rtx,
		ndk::RayHitPointf &	hitPoint
	)		const

Intersect a single RayContext Rtx with the closest surface with presence to Rtx's origin within its distance range, and filling in hitPoint with the information about the hit object.

This is a convenience method and may not be as efficient as using getNearestSurfaceIntersections() since finding the closest surface with presence means checking all other surfaces along the ray path, so the cost of getting surface information for all the surfaces is marginally more than just getting one.

Returns false if there was no intersection.

getAllIntersections() [1/2]

void slr::SlrIntegratorContext::getAllIntersections	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext &	Rtx
	)		const

Intersect a single ray with all surfaces, filling in the ray hit points list in this SlrIntegratorContext. Retrieve the hit points via hit point list methods like getRayHitPoint() and nRayHitPoints().

This is the most expensive intersection method as all intersectable surfaces are retrieved, even potentially hidden ones, and building surface shading contexts requires evaluating additional surface properties.

Note that the active surface intersection bundle is -not- cleared before adding hits to it.

getAllIntersections() [2/2]

void slr::SlrIntegratorContext::getAllIntersections	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext &	Rtx,
		ndk::RayHitPointfList &	hitList
	)		const

Intersect a single ray with the all surfaces, filling in geometric hit infos. Note - hitList is -not- cleared before adding the hits.

getThinTransmissionFactor()

bool slr::SlrIntegratorContext::getThinTransmissionFactor	(	const SlrShadingContext &	srcStx,
		const ndk::RayContext &	Rtx,
		fdk::Vec3f &	transmissionFactor
	)		const

Find the 'thin' transmission factor for all surfaces between Rtx.minT and Rtx.maxT, which is most commonly used for direct lighting occlusion (shadow) testing. Only materials with the thinInterfaceTransmission() trait enabled are fully evaluated for opacity (transmission amount,) otherwise only the material's presence is considered to determine the solidity factor. If the material's presence is derived from its opacity then opacity will be calculated as a byproduct but will not contribute to the material's occlusion factor unless thinInterfaceTransmission() is enabled.

Returns false on trivial 0% transmission, or a 100% occluded path.

transmissionFactor is a Vec3 so that colorized shadows can be supported. It will contain the total occlusion from all surfaces and volumes along the ray path up to 100% occlusion or Rtx.maxT, whichever comes first.

Transmission factor is only valid between 0..1, or 0%..100% transmission, so usually this factor is a weight multiplied against a light's emission to determine the total amount of light reaching srcStx.

Note that thin transmission is an efficiency to speed up direct shadow calculations without needing to calculate expensive object qualities like scatter, refraction, etc. During thin transmission path evalation the ray is never bent so a single set of intersections between ray minT and maxT is all that is ever considered.

getPathTransmission()

void slr::SlrIntegratorContext::getPathTransmission	(	const SlrShadingContext &	surfaceStx,
		const SlrRayBundle &	entryRays,
		const DD::Image::ChannelSet &	get,
		DD::Image::Pixel &	out
	)

Perform transmission shading on the surface, assuming entryStx represents the entry interface pointer of the object. If the object is marked as double-sided then the entry interface is assumed to also be the exit interface. In this case there's no possibility of object overlap resolution via dielectric priority so the surface is interpreted as warping surface with no thickness. If single-sided the surface is assumed to have a back surface that terminates the interior of the surface.

getUVIntersections()

void slr::SlrIntegratorContext::getUVIntersections	(	const SlrShadingContext &	srcStx,
		const SlrRayBundle &	rays,
		const fdk::Vec2f *	uvArray
	)		const

Intersect 2d UV points with surface UV coords, filling in geometric hit infos. Size of uvArray must match size of rays bundle - no check is performed! There will only be one hit info created per ray/UV, so the size of the hit list will never exceed the size of the rays bundle.

Note that the active surface intersection bundle is -not- cleared before adding hits to it.

getRayHitPoint()

const ndk::RayHitPointf & slr::SlrIntegratorContext::getRayHitPoint

(

int32_t

rayHitIndex = 0

)

const

Retrieve a hit point from the last ray cast from 0..nRayHitPoints(). No range checking is done - the index is assumed to be within nRayHitPoints().

areAllHitsOpaqueSolid()

bool slr::SlrIntegratorContext::areAllHitsOpaqueSolid

(

)

const

All hits are opaque-solid, that is we cannot see through the first surface and if desired can skip all the other hits.

doAllHitsBlend()

bool slr::SlrIntegratorContext::doAllHitsBlend

(

)

const

If false then only the first hit matters since we should never see through it. If true then all the hits need to be blended, and if doAllHitsBlendToOpaque() is also true then blending can be done front-to-back.

doAllHitsBlendToOpaque()

bool slr::SlrIntegratorContext::doAllHitsBlendToOpaque

(

)

const

If true all the hits do 'standard' blending that can result in 1.0 opacity. If false then at least one of the hits needs to do 'non-standard' blending (like min, max, plus) and blending should be done back-to-front.

startActiveSurfaceIntersectionBundleGroup()

void slr::SlrIntegratorContext::startActiveSurfaceIntersectionBundleGroup

(

)

const

Clear the active surface intersection bundle collection in preparation for creating a series of new surface intersections. Usually at the spawn of a new ray bundle to store the resulting intersections from each ray in the bundle.

Same as calling activeSurfaceIntersectionBundleGroup().clear().

addSurfaceIntersectionsToActiveGroup()

void slr::SlrIntegratorContext::addSurfaceIntersectionsToActiveGroup

(

)

const

Add the currently selected surface intersection bundle to the active surface intersection bundle collection. Do this -after- calling a ray intersection method to store the results of each ray bundle.

activeSurfaceIntersectionBundleGroup()

StxBundleList & slr::SlrIntegratorContext::activeSurfaceIntersectionBundleGroup

(

)

const

Current active surface intersection bundle collection that can be used by an integrator to build up a list of StxBundles generated by startNewSurfaceIntersectionBundle().

Note - there is only one of these for each RayBundle.

startNewSurfaceIntersectionBundle()

StxBundle & slr::SlrIntegratorContext::startNewSurfaceIntersectionBundle

(

)

const

Start a new surface intersection bundle stored in the currently active ray data cache. Use this when doing ad-hoc intersection testing with temp RayContexts or when building a list of bundles where all the bundles need to remain valid.

activeSurfaceIntersectionBundle()

StxBundle & slr::SlrIntegratorContext::activeSurfaceIntersectionBundle

(

)

const

Access the currently selected surface intersection bundle. Change the selected bundle via SlrRayBundle::selectActiveRay(), startNewSurfaceIntersectionBundle(), and endShadingIntersectionBundle().

Note - this will return an invalid, junk StxBundle if selectActiveRayBundle() has never been called and if used may cause a crash.

endSurfaceIntersectionBundle()

void slr::SlrIntegratorContext::endSurfaceIntersectionBundle

(

)

const

Removes the last added bundle from the active list. Will never remove the first bundle in the active list.

setSurfaceIntersectionBundleBlendingOrder()

void slr::SlrIntegratorContext::setSurfaceIntersectionBundleBlendingOrder

(

BlendingOrder

mode

)

const

Set blending order of the active surface intersection bundle. Do this before adding shading contexts as they inherit the bundle's blending order. Alternatively you can set it on the activeSurfaceIntersectionBundle() after all shading contexts have been added.

addNewShadingContextToSurfaceIntersectionBundle()

SlrShadingContext & slr::SlrIntegratorContext::addNewShadingContextToSurfaceIntersectionBundle	(	const SlrShadingContext &	srcStx,
		int32_t	rayIndex = 0
	)		const

Construct and add a new shading context in the current StxBundle from the RayHitPoint for rayHitIndex. This assumes you've started a new bundle and are incrementing its current size. The new shading context will inherit the blending order of the current bundle. No range checking is done on rayHitIndex! srcStx is the shading context from the last hit, or the camera.

activeRaySurfaceColor()

DD::Image::Pixel & slr::SlrIntegratorContext::activeRaySurfaceColor

(

)

const

Per-ray - for surface shader calls - defaults to RGBA. Warning - this will be invalid memory if there's no active ray data!

activeRayLayeredColor()

DD::Image::Pixel & slr::SlrIntegratorContext::activeRayLayeredColor

(

)

const

Per-ray - for layering multiple surfaces along the same depth segment - defaults to RGBA. Warning - this will be invalid memory if there's no active ray data!

accumColor()

DD::Image::Pixel & slr::SlrIntegratorContext::accumColor

(

)

const

Thread-context color accumulator Pixel - for accumulating/blending samples together - defaults to RGBA. This is a convenience for Integrators to use.

accumData()

DD::Image::Pixel & slr::SlrIntegratorContext::accumData

(

)

const

Thread-context data Aov accumulator Pixel, usually selected from the nearest sample with largest coverage. Defaults to Chan_Z. This is a convenience for Integrators to use.