Data Structures | Typedefs | Functions
Ray Tracing API

Data Structures

struct  AtRay
 Ray data structure. More...
 

Typedefs

typedef struct AtRay AtRay
 Ray data structure.
 

Functions

AI_API void AiMakeRay (AtRay *ray, AtUInt32 type, const AtPoint *origin, const AtVector *dir, double maxdist, const AtShaderGlobals *sg)
 Initializes a ray, before it can be traced. 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, AtScrSample *sample)
 Traces a ray through the whole scene and returns its radiance. 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_REFLECTED   0x04
 mirror reflection ray
 
#define AI_RAY_REFRACTED   0x08
 mirror refraction ray
 
#define AI_RAY_DIFFUSE   0x20
 indirect diffuse (also known as diffuse GI) ray
 
#define AI_RAY_GLOSSY   0x40
 glossy/blurred reflection ray
 
#define AI_RAY_ALL   0xFF
 mask for all ray types
 
#define AI_RAY_GENERIC   AI_RAY_ALL
 mask for all ray types
 

Detailed Description

Function Documentation

AI_API void AiMakeRay ( AtRay ray,
AtUInt32  type,
const AtPoint origin,
const AtVector dir,
double  maxdist,
const AtShaderGlobals sg 
)

Initializes a ray, before it can be traced.

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

Parameters
[out]raypreviously allocated AtRay structure that will be filled in
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
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(&ray, AI_RAY_REFLECTED, &sg->P, NULL, AI_BIG, sg);
while (condition) {
AiReflectRay(&ray, getNewJitteredNormal(), sg);
AiTrace(&ray, sample);
}
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).

AtRay ray;
AiMakeRay(&ray, AI_RAY_REFRACTED, &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(&ray, AI_RAY_REFRACTED, &sg->P, NULL, AI_BIG, sg);
while (condition) {
AiRefractRay(&ray, getNewJitteredNormal(), n1, n2, sg);
AiTrace(&ray, sample);
}
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,
AtScrSample sample 
)

Traces a ray through the whole scene and returns its radiance.

Parameters
raythe ray to be traced
[out]samplea non-NULL pointer to an AtScrSample structure where the radiance and first-hit information are returned
Returns
true if the ray hit something
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]samplea non-NULL pointer to 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
raythe ray to be traced
[out]sgoutif non-NULL, the first intersection point will be stored here
Returns
true if the ray hit something

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