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 | |
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.
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 |
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:
[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).
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:
[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 |
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.
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. |
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.
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.
ray | the ray to be traced | |
[out] | sgout | if non-NULL, the first intersection point will be stored here |