Ray Tracing API

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

Functions
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 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 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...

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

Ray Type Masks
#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

Detailed Description

Function Documentation

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

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

AI_API 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

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

AI_API 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

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