Data Structures | Functions
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
typethe type of ray that we want to create, one of AI_RAY_*
originthe origin of the ray
dirthe direction of the ray (or NULL if not yet available)
maxdistthe maximum distance that the ray will travel
sgthe 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:

1 AtRay ray = AiMakeRay(AI_RAY_SPECULAR_REFLECT, sg->P, NULL, AI_BIG, sg);
2 while (condition) {
3  AiReflectRay(ray, getNewJitteredNormal(), sg);
4  AiTrace(ray, sample);
5 }
Parameters
[out]raythe AtRay which will contain the reflection direction
normalthe shading normal
sgthe 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).

1 AtRay ray = AiMakeRay(AI_RAY_SPECULAR_TRANSMIT, sg->P, NULL, AI_BIG, sg);
2 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:

1 AtRay ray = AiMakeRay(AI_RAY_SPECULAR_TRANSMIT, sg->P, NULL, AI_BIG, sg);
2 while (condition) {
3  AiRefractRay(ray, getNewJitteredNormal(), n1, n2, sg);
4  AiTrace(ray, sample);
5 }
Parameters
[out]raythe AtRay which will contain the refraction/TIR ray direction
normalthe shading normal
n1index of refraction (IOR) of the medium the incident ray travels in
n2index of refraction (IOR) of the medium the transmitted ray travels in
sgthe 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
raythe ray to be traced
weightRGB weight applied to the result color, and used for Russian roulette termination for more efficient rendering with high GI depth
[out]resultan 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
raythe ray to be traced
[out]samplean 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
raythe ray to be traced
[out]sgoutif non-NULL, the first intersection point will be stored here
Returns
true if the ray hit some non-volumetric geometry

© 2009-2018 Solid Angle SL · all rights reserved · www.solidangle.com