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 | |
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.
[out] | ray | previously allocated AtRay structure that will be filled in |
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, |
AtScrSample * | sample | ||
) |
Traces a ray through the whole scene and returns its radiance.
ray | the ray to be traced | |
[out] | sample | a non-NULL pointer to an AtScrSample structure where the radiance and first-hit information are returned |
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 | a 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.
ray | the ray to be traced | |
[out] | sgout | if non-NULL, the first intersection point will be stored here |