Ray Tracing API

Creation and manipulation of AtRay objects. More...

Data Structures
struct	AtRay
	Ray data structure. More...

Variables
uint8_t	AtRay::type
	Type of ray (AI_RAY_CAMERA, etc)
uint8_t	AtRay::bounces
	Number of bounces so far (0 for camera rays)
uint8_t	AtRay::bounces_diffuse
	Number of diffuse bounces so far
uint8_t	AtRay::bounces_specular
	Number of specular bounces so far
uint8_t	AtRay::bounces_reflect
	Number of reflection bounces so far
uint8_t	AtRay::bounces_transmit
	Number of transmission bounces so far
uint8_t	AtRay::bounces_volume
	Number of volume bounces so far
bool	AtRay::inclusive_traceset
	Is the trace-set inclusive or exclusive?
AtString	AtRay::traceset
	Trace-set for this ray
uint16_t	AtRay::tid
	Thread ID
uint16_t	AtRay::sindex
	Sub-pixel sample index when supersampling
int	AtRay::x
	Raster-space X coordinate
int	AtRay::y
	Raster-space Y coordinate
float	AtRay::px
	Subpixel X coordinate in [0,1)
float	AtRay::py
	Subpixel Y coordinate in [0,1)
AtVector	AtRay::origin
	Ray origin
AtVector	AtRay::dir
	Unit ray direction
float	AtRay::mindist
	Minimum useful distance from the origin
float	AtRay::maxdist
	Maximum useful distance from the origin (volatile while ray is traced)
const AtShaderGlobals *	AtRay::psg
	Parent shader globals (last shaded)
const AtLightSample *	AtRay::light_sample
	Associated light sample, for shadow rays only
AtRGB	AtRay::weight
	Ray weight, AI_RGB_WHITE for clean camera rays
float	AtRay::time
	Time at which the ray was created, in [0,1)
AtVector	AtRay::dOdx
	Partial derivative of ray origin wrt image-space X coordinate
AtVector	AtRay::dOdy
	Partial derivative of ray origin wrt image-space Y coordinate
AtVector	AtRay::dDdx
	Partial derivative of ray direction wrt image-space X coordinate.
AtVector	AtRay::dDdy
	Partial derivative of ray direction wrt image-space Y coordinate.

Ray Type Masks
AI_API AI_DEVICE AtRay	AiMakeRay (uint8_t type, const AtVector &origin, const AtVector *dir, float maxdist, const AtShaderGlobals *sg)
	Creates a ray for tracing. More...
AI_API void	AiReflectRay (AtRay &ray, const AtVector &normal, const AtShaderGlobals *sg)
	Computes and sets the reflected ray direction and proper ray direction differentials (ray->dDdx and ray->dDdy). More...
AI_API AI_DEVICE bool	AiRefractRay (AtRay &ray, const AtVector &normal, float n1, float n2, const AtShaderGlobals *sg)
	Helps make a refracted ray with high quality ray derivatives when called after AiMakeRay(). More...
AI_API bool	AiTrace (const AtRay &ray, const AtRGB &weight, AtScrSample &sample)
	Traces a ray through the whole scene, and for non-shadow rays, the radiance and first-hit information will be returned. More...
AI_API AI_DEVICE void	AiTraceBackground (const AtRay &ray, AtScrSample &sample)
	Traces a ray against the background without touching the geometry. More...
AI_API bool	AiTraceProbe (const AtRay &ray, AtShaderGlobals *sgout)
	Traces a ray through the whole scene and returns the first intersection, if there is one. More...
#define	AI_RAY_ALL_DIFFUSE   (AI_RAY_DIFFUSE_TRANSMIT | AI_RAY_DIFFUSE_REFLECT)
	all indirect diffuse ray types
#define	AI_RAY_ALL_SPECULAR   (AI_RAY_SPECULAR_TRANSMIT| AI_RAY_SPECULAR_REFLECT)
	all indirect specular ray types
#define	AI_RAY_ALL_REFLECT   (AI_RAY_DIFFUSE_REFLECT | AI_RAY_SPECULAR_REFLECT)
	all reflection ray types
#define	AI_RAY_ALL_TRANSMIT   (AI_RAY_DIFFUSE_TRANSMIT | AI_RAY_SPECULAR_TRANSMIT)
	all transmission specular ray types
#define	AI_RAY_ALL   uint8_t(-1)
	mask for all ray types

Ray Types
#define	AI_RAY_UNDEFINED   0x00
	undefined type
#define	AI_RAY_CAMERA   0x01
	ray originating at the camera
#define	AI_RAY_SHADOW   0x02
	shadow ray towards a light source
#define	AI_RAY_DIFFUSE_TRANSMIT   0x04
	indirect diffuse transmission ray
#define	AI_RAY_SPECULAR_TRANSMIT   0x08
	indirect specular transmission ray
#define	AI_RAY_VOLUME   0x10
	indirect volume scattering ray
#define	AI_RAY_DIFFUSE_REFLECT   0x20
	indirect diffuse reflection ray
#define	AI_RAY_SPECULAR_REFLECT   0x40
	indirect specular reflection ray
#define	AI_RAY_SUBSURFACE   0x80
	subsurface scattering probe ray

Detailed Description

Creation and manipulation of AtRay objects.

Function Documentation

AiMakeRay()

AI_API AI_DEVICE AtRay AiMakeRay	(	uint8_t	type,
		const AtVector &	origin,
		const AtVector *	dir,
		float	maxdist,
		const AtShaderGlobals *	sg
	)

Creates a ray for tracing.

Returns an AtRay with user-provided origin and direction, plus information stored in a shader globals context.

Parameters

type	the type of ray that we want to create, one of AI_RAY_*
origin	the origin of the ray
dir	the direction of the ray (or NULL if not yet available)
maxdist	the maximum distance that the ray will travel
sg	the shader globals context where the ray is created

Returns

filled in AtRay

AiReflectRay()

AI_API void AiReflectRay	(	AtRay &	ray,
		const AtVector &	normal,
		const AtShaderGlobals *	sg
	)

Computes and sets the reflected ray direction and proper ray direction differentials (ray->dDdx and ray->dDdy).

Note that AiMakeRay() already computes proper ray direction differentials, so usually it is not necessary to also call AiReflectRay and instead it is more efficient to just use AiReflect() followed by AiMakeRay(). However, if the ray direction and derivatives need to be updated, such as might happen when computing glossy reflections where only the shading normal is jittered for each ray, then it is more efficient to use the lighter weight AiReflectRay() instead of AiReflect()+AiMakeRay().

An example usage is the following:

AtRay ray = AiMakeRay(AI_RAY_SPECULAR_REFLECT, sg->P, NULL, AI_BIG, sg);
while (condition) {
   AiReflectRay(ray, getNewJitteredNormal(), sg);
   AiTrace(ray, sample);
}

Parameters

[out]	ray	the AtRay which will contain the reflection direction
	normal	the shading normal
	sg	the shader globals context for this shader evaluation

AiRefractRay()

AI_API AI_DEVICE bool AiRefractRay	(	AtRay &	ray,
		const AtVector &	normal,
		float	n1,
		float	n2,
		const AtShaderGlobals *	sg
	)

Helps make a refracted ray with high quality ray derivatives when called after AiMakeRay().

Note, if called before AiMakeRay() instead of after, then the correctly computed ray derivatives will be overwritten by the low quality ray derivatives created by AiMakeRay()! AiMakeRay() cannot produce high quality ray derivatives because it does not have access to the indices of refraction.

This will update the AtRay to contain the refracted (or total internal reflection) ray direction and also set the proper ray direction differentials (ray->dDdx and ray->dDdy) for refraction (or total internal reflection).

AtRay ray = AiMakeRay(AI_RAY_SPECULAR_TRANSMIT, sg->P, NULL, AI_BIG, sg);
AiRefractRay(ray, sg->Nf, n1, n2, sg);

If many reflected rays will be cast from the same shading point, but say with a different normal each time, it is more efficient to reuse the ray:

AtRay ray = AiMakeRay(AI_RAY_SPECULAR_TRANSMIT, sg->P, NULL, AI_BIG, sg);
while (condition) {
   AiRefractRay(ray, getNewJitteredNormal(), n1, n2, sg);
   AiTrace(ray, sample);
}

Parameters

[out]	ray	the AtRay which will contain the refraction/TIR ray direction
	normal	the shading normal
	n1	index of refraction (IOR) of the medium the incident ray travels in
	n2	index of refraction (IOR) of the medium the transmitted ray travels in
	sg	the shader globals context for this shader evaluation

Returns

a boolean which is true if refraction occurred or false if TIR occurred

AiTrace()

AI_API bool AiTrace	(	const AtRay &	ray,
		const AtRGB &	weight,
		AtScrSample &	result
	)

Traces a ray through the whole scene, and for non-shadow rays, the radiance and first-hit information will be returned.

Shadow rays only return opacity.

Parameters

	ray	the ray to be traced
	weight	RGB weight applied to the result color, and used for Russian roulette termination for more efficient rendering with high GI depth
[out]	result	an AtScrSample structure where the radiance and first-hit information of non-shadow rays are returned. Shadow rays will only have opacity filled in.

Returns

true if the ray hit some non-volumetric geometry

AiTraceBackground()

AI_API AI_DEVICE void AiTraceBackground	(	const AtRay &	ray,
		AtScrSample &	sample
	)

Traces a ray against the background without touching the geometry.

Allows shader writers to easily trace a ray against the background, without intersecting geometry first. This can be useful when implementing limited ray-length effects or environment mapped reflections. Note that this function includes the contribution from the atmosphere shader.

Parameters

	ray	the ray to be traced
[out]	sample	an AtScrSample structure where the radiance and opacity are returned

AiTraceProbe()

AI_API bool AiTraceProbe	(	const AtRay &	ray,
		AtShaderGlobals *	sgout
	)

Traces a ray through the whole scene and returns the first intersection, if there is one.

The ray will stop at the first geometric intersection. This function does not take transparency into account.

Note: If the ray type is specifically set to AI_RAY_SHADOW, this function will return the first intersection found as the ray traverses the scene hierarchy. This is faster if you just want to know if the ray hits any object, but it might not be the closest intersection along the ray path.

Parameters

	ray	the ray to be traced
[out]	sgout	if non-NULL, the first intersection point will be stored here

Returns

true if the ray hit some non-volumetric geometry