Shader Utility API

Coordinate Transformations

#define AI_WORLD_TO_OBJECT   1
 World-to-object coordinate transformation.
 
#define AI_OBJECT_TO_WORLD   2
 Object-to-world coordinate transformation.
 

Wireframe Types

#define AI_WIREFRAME_TRIANGLES   0
 Tessellated triangles.
 
#define AI_WIREFRAME_POLYGONS   1
 Tessellated polygons.
 
#define AI_WIREFRAME_PATCHES   2
 Patches before subdivision.
 

Lighting Functions

AI_API AtRGB AiOcclusion (const AtVector &N, const AtVector &Ng, AtShaderGlobals *sg, float mint, float maxt, float spread, float falloff, const AtSampler *sampler, AtVector *Nbent)
 Returns the ambient occlusion at a shading point. More...
 
AI_API AtRGB AiSelfOcclusion (const AtVector &N, const AtVector &Ng, AtShaderGlobals *sg, float mint, float maxt, float spread, float falloff, const AtSampler *sampler, AtVector *Nbent)
 Returns the ambient occlusion at a shading point, only considering the same object. More...
 
AI_API AtRGB AiDirectDiffuse (const AtVector &N, AtShaderGlobals *sg)
 Returns the direct-lighting component of the irradiance at a shading point. More...
 
AI_API AtRGB AiIndirectDiffuse (const AtVector &N, AtShaderGlobals *sg, const AtRGB &weight)
 Returns the indirect-lighting component of the irradiance at a shading point. More...
 

BSDF Utility Functions

AI_API AI_DEVICE AtVector AiReflect (const AtVector &I, const AtVector &N)
 Returns specular direction from incident direction I and normal N. More...
 
AI_API AtVectorDv AiReflectWithDerivs (const AtVectorDv &I, const AtVectorDv &N)
 Returns specular direction from incident direction I and normal N, with derivatives. More...
 
AI_API AI_DEVICE AtVector AiReflectSafe (const AtVector &I, const AtVector &N, const AtVector &Ng)
 Returns specular direction from incident direction I and normal N. More...
 
AI_API AI_DEVICE bool AiRefract (const AtVector &I, const AtVector &N, AtVector &T, float n1, float n2)
 Returns transmitted direction T from incident direction I and normal N. More...
 
AI_API bool AiRefractWithDerivs (const AtVectorDv &I, const AtVectorDv &N, AtVectorDv &T, float n1, float n2)
 Returns transmitted direction T from incident direction I and normal N, with derivatives. More...
 
AI_API AI_DEVICE AI_CONST float AiSchlickFresnel (const AtVector &N, const AtVector &Rd, float Krn)
 Computes Fresnel reflectance at an air-dielectric interface for given normal and viewing vectors. More...
 
AI_API AI_CONST AtRGB AiSchlickFresnelRGB (const AtVector &N, const AtVector &Rd, const AtRGB &Krn)
 Optimized version of AiSchlickFresnel() for RGB reflectance. More...
 
AI_API AI_CONST AtRGB AiConductorFresnel (const AtVector &N, const AtVector &Rd, const AtRGB &n, const AtRGB &k)
 Computes Fresnel reflectance at a conductor interface for given normal and viewing vectors. More...
 
AI_API AI_CONST float AiDielectricFresnel (const AtVector &N, const AtVector &Rd, float eta)
 Computes Fresnel reflectance at a dielectric interface for given normal and viewing vectors. More...
 
AI_API AI_DEVICE void AiArtisticToConductorFresnel (const AtRGB &reflectivity, const AtRGB &edgetint, AtRGB &n, AtRGB &k)
 Convert artist friendly metalicl Fresnel parameters to complex refractive indices for conductor Fresnel. More...
 
AI_API AI_DEVICE void AiFaceForward (AtVector &N, const AtVector &I)
 Make a normal vector face forward with respect to a given vector. More...
 

Utility Helper Types

typedef float(* AtFloatBumpEvaluator) (AtShaderGlobals *sg, void *data)
 This function pointer points to float-based bump-mapping function for use by AiShaderGlobalsEvaluateBump(). More...
 

Utility Functions

AI_API bool AiShaderGlobalsGetTriangle (const AtShaderGlobals *sg, int key, AtVector p[3])
 Get triangle vertices at a given motion key. More...
 
AI_API bool AiShaderGlobalsGetVertexNormals (const AtShaderGlobals *sg, int key, AtVector n[3])
 Get normal vectors for all triangle vertices. More...
 
AI_API bool AiShaderGlobalsGetVertexUVs (const AtShaderGlobals *sg, const AtString uvset, AtVector2 uv[3])
 Get UV coordinates for all triangle vertices. More...
 
AI_API uint32_t AiShaderGlobalsGetPolygon (const AtShaderGlobals *sg, int key, AtVector *p)
 Get polygon vertices at a given motion key. More...
 
AI_API uint32_t AiShaderGlobalsGetUniformID (const AtShaderGlobals *sg)
 Get unique per face, subdivision patch, curve or point ID. More...
 
AI_API void AiShaderGlobalsGetPositionAtTime (const AtShaderGlobals *sg, float time, AtVector &P, AtVector *N, AtVector *Ng, AtVector *Ns)
 Reproject the shading point to a different time. More...
 
AI_API AI_PURE AtVector2 AiShaderGlobalsGetPixelMotionVector (const AtShaderGlobals *sg, float time0, float time1)
 Compute motion vector. More...
 
AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxLocal (const AtShaderGlobals *sg)
 Get the object-space bounds of the current object. More...
 
AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxWorld (const AtShaderGlobals *sg)
 Get the world-space bounds of the current object. More...
 
AI_API AtNodeAiShaderGlobalsGetShader (const AtShaderGlobals *sg)
 Get shader assigned to the object at the current shading point. More...
 
AI_API AI_PURE AtVector AiShaderGlobalsTransformNormal (const AtShaderGlobals *sg, AtVector N, int space)
 
AI_API AI_PURE AtVector AiShaderGlobalsTransformPoint (const AtShaderGlobals *sg, AtVector P, int space)
 
AI_API AI_DEVICE AI_PURE AtVector AiShaderGlobalsTransformVector (const AtShaderGlobals *sg, AtVector V, int space)
 
AI_API void AiShaderGlobalsSetTraceSet (AtShaderGlobals *sg, const AtString set, bool inclusive)
 Takes a trace-set string and assigns it to the shader globals. More...
 
AI_API void AiShaderGlobalsUnsetTraceSet (AtShaderGlobals *sg)
 Resets the trace-set for this shader globals. More...
 
AI_API void * AiShaderGlobalsQuickAlloc (const AtShaderGlobals *sg, uint32_t size)
 Allocates temporary memory for this ray-tree. More...
 
AI_API AI_PURE AtVector AiShaderGlobalsEvaluateBump (AtShaderGlobals *sg, AtFloatBumpEvaluator bump_func, void *data)
 Computes and returns a normal based on the current shading point and the specified bump-function. More...
 
AI_API AtRGB AiShaderGlobalsStochasticOpacity (AtShaderGlobals *sg, const AtRGB &opacity)
 Performs some optimizations and returns a modified opacity value which allows for increased performance. More...
 
AI_API AI_DEVICE AI_PURE float AiShaderGlobalsArea (const AtShaderGlobals *sg)
 Computes the world space area being shaded or displaced. More...
 
AI_API AI_PURE float AiShaderGlobalsEdgeLength (const AtShaderGlobals *sg)
 Computes the maximum (for now) edge length of a given polygon. More...
 
AI_API AI_PURE float AiWireframe (const AtShaderGlobals *sg, float line_width, bool raster_space, int edge_type)
 Computes wireframe shading for a mesh. More...
 
AI_API AI_PURE bool AiShaderGlobalsIsObjectMatte (const AtShaderGlobals *sg)
 Retrieve the matte setting for the current object. More...
 
AI_DEVICE AtVector AiFaceViewer (const AtShaderGlobals *sg)
 Make the surface normal face the viewer. More...
 

Camera Information

AI_API AI_PURE float AiCameraGetShutterStart ()
 Fetch camera shutter start. More...
 
AI_API AI_PURE float AiCameraGetShutterEnd ()
 Fetch camera shutter end. More...
 
AI_API void AiCameraToWorldMatrix (const AtNode *node, float time, AtMatrix &out)
 Computes camera to world matrix. More...
 
AI_API void AiWorldToCameraMatrix (const AtNode *node, float time, AtMatrix &out)
 Computes world to camera matrix. More...
 
AI_API void AiWorldToScreenMatrix (const AtNode *node, float time, AtMatrix &out)
 Computes world to screen matrix. More...
 

Environment Mappings

AI_API void AiMappingMirroredBall (const AtVector &dir, float &u, float &v)
 Maps a world-space direction vector to texture coordinates (u,v) based on the mirrored-ball mapping. More...
 
AI_API void AiMappingAngularMap (const AtVector &dir, float &u, float &v)
 Maps a world-space direction vector to texture coordinates (u,v) based on an angular mapping. More...
 
AI_API void AiMappingLatLong (const AtVector &dir, float &u, float &v)
 Maps a world-space direction vector to texture coordinates (u,v) based on the Latitude/Longitude mapping. More...
 

Derivatives for Environment Mappings

AI_API AI_DEVICE void AiMappingMirroredBallDerivs (const AtVector &dir, const AtVector &dDdx, const AtVector &dDdy, float &u, float &v, float &dudx, float &dudy, float &dvdx, float &dvdy)
 Derivative version of AiMappingMirroredBall(). More...
 
AI_API AI_DEVICE void AiMappingAngularMapDerivs (const AtVector &dir, const AtVector &dDdx, const AtVector &dDdy, float &u, float &v, float &dudx, float &dudy, float &dvdx, float &dvdy)
 Derivative version of AiMappingAngularMap(). More...
 
AI_API AI_DEVICE void AiMappingLatLongDerivs (const AtVector &dir, const AtVector &dDdx, const AtVector &dDdy, float &u, float &v, float &dudx, float &dudy, float &dvdx, float &dvdy)
 Derivative version of AiMappingLatLong(). More...
 

Detailed Description

Typedef Documentation

typedef float(* AtFloatBumpEvaluator) (AtShaderGlobals *sg, void *data)

This function pointer points to float-based bump-mapping function for use by AiShaderGlobalsEvaluateBump().

This function would return the displacement height for the given shading context. This function would be called three times (on three different shading contexts). The returned displacements would be used to generate a triangle from which a normal is calculated.

Parameters
sgthe current shading context
datauser-defined data pointer
Returns
bump/displacement height for the current shading context

Function Documentation

AI_API AtRGB AiOcclusion ( const AtVector N,
const AtVector Ng,
AtShaderGlobals sg,
float  mint,
float  maxt,
float  spread,
float  falloff,
const AtSampler sampler,
AtVector Nbent 
)

Returns the ambient occlusion at a shading point.

Computes an ambient occlusion lookup: fire a number of hemispherical rays, return the ratio of hits/rays and, optionally, also return the bent normal.

Note that if N is set to the mirror direction, you get reflection occlusion. In the extreme, if spread is set to 0, you get sharp mirror occlusion.

The geometric normal is used for detecting occlusion rays that penetrate into the surface, thus biasing the result.

Parameters
Nnormal vector at the shading point
Nggeometric normal
sgthe shader globals context where occlusion is evaluated
mintminimum ray distance
maxtmaximum ray distance
spreadangular spread around the normal vector N, in the range [0,1], where 1 maps to 90 degrees (the full hemisphere)
falloffexponential falloff rate for the occlusion along the ray distance
samplera two-dimensional AtSampler object that holds the number of samples to take per evaluation
[out]Nbentif non-NULL, the average direction to non-occluded areas, or bent normal, will be stored here
Returns
ambient occlusion at {sg->P,N}
See also
AiSampler
AI_API AtRGB AiSelfOcclusion ( const AtVector N,
const AtVector Ng,
AtShaderGlobals sg,
float  mint,
float  maxt,
float  spread,
float  falloff,
const AtSampler sampler,
AtVector Nbent 
)

Returns the ambient occlusion at a shading point, only considering the same object.

Computes an ambient occlusion lookup: fire a number of hemispherical rays, return the ratio of hits/rays and, optionally, also return the bent normal.

Note that if N is set to the mirror direction, you get reflection occlusion. In the extreme, if spread is set to 0, you get sharp mirror occlusion.

The geometric normal is used for detecting occlusion rays that penetrate into the surface, thus biasing the result.

Parameters
Nnormal vector at the shading point
Nggeometric normal
sgthe shader globals context where occlusion is evaluated
mintminimum ray distance
maxtmaximum ray distance
spreadangular spread around the normal vector N, in the range [0,1], where 1 maps to 90 degrees (the full hemisphere)
falloffexponential falloff rate for the occlusion along the ray distance
samplera two-dimensional AtSampler object that holds the number of samples to take per evaluation
[out]Nbentif non-NULL, the average direction to non-occluded areas, or bent normal, will be stored here
Returns
ambient occlusion at {sg->P,N}
See also
AiSampler
AI_API AtRGB AiDirectDiffuse ( const AtVector N,
AtShaderGlobals sg 
)

Returns the direct-lighting component of the irradiance at a shading point.

Computes the irradiance coming directly from all light sources in the scene, at shading point sg->P with normal N.

Note
Deprecated, use shader closures instead of integrating light in shaders.
Parameters
Nnormal vector that defines the hemisphere of incoming radiance
sgshader globals context where irradiance is evaluated at
Returns
direct component of diffuse irradiance
AI_API AtRGB AiIndirectDiffuse ( const AtVector N,
AtShaderGlobals sg,
const AtRGB weight 
)

Returns the indirect-lighting component of the irradiance at a shading point.

Computes the indirect irradiance as an integral of the incident radiance over the hemisphere. The irradiance is computed at surface point sg->P.

This is usually called from shaders that need diffuse global illumination.

Note
Deprecated, use shader closures instead of integrating light in shaders.
Parameters
Nnormal vector that defines the hemisphere of incoming radiance
sgshader globals context where irradiance is evaluated at
weightRGB weight applied to the result and used for Russian roulette termination for more efficient rendering with high GI depth
Returns
indirect component of diffuse irradiance
AI_API AI_DEVICE AtVector AiReflect ( const AtVector I,
const AtVector N 
)

Returns specular direction from incident direction I and normal N.

Parameters
Iincident direction
Nsurface normal
AI_API AtVectorDv AiReflectWithDerivs ( const AtVectorDv I,
const AtVectorDv N 
)

Returns specular direction from incident direction I and normal N, with derivatives.

This function can be used to implement BSDFs, where preserving ray differentials is important for texture filtering.

Parameters
Iincident direction
Nsurface normal
AI_API AI_DEVICE AtVector AiReflectSafe ( const AtVector I,
const AtVector N,
const AtVector Ng 
)

Returns specular direction from incident direction I and normal N.

This function should be used for Phong-smoothed meshes instead of AiReflect(). It makes sure the reflected vector doesn't penetrate below the geometric normal, which happens when the smooth (interpolated) normal points away from the viewing direction near silhouettes.

Parameters
Iincident direction
Nsurface normal
Ngsurface normal
AI_API AI_DEVICE bool AiRefract ( const AtVector I,
const AtVector N,
AtVector T,
float  n1,
float  n2 
)

Returns transmitted direction T from incident direction I and normal N.

Parameters
Iincident direction
Nsurface normal
[out]Toutgoing transmitted direction with respect to N
n1index of refraction (IOR) of the medium the incident ray travels in
n2index of refraction (IOR) of the medium the transmitted ray travels in
Returns
false if total internal reflection (TIR) occurs and there is no transmission
AI_API bool AiRefractWithDerivs ( const AtVectorDv I,
const AtVectorDv N,
AtVectorDv T,
float  n1,
float  n2 
)

Returns transmitted direction T from incident direction I and normal N, with derivatives.

This function can be used to implement BSDFs, where preserving ray differentials is important for texture filtering.

Parameters
Iincident direction
Nsurface normal
[out]Toutgoing transmitted direction with respect to N
n1index of refraction (IOR) of the medium the incident ray travels in
n2index of refraction (IOR) of the medium the transmitted ray travels in
Returns
false if total internal reflection (TIR) occurs and there is no transmission
AI_API AI_DEVICE AI_CONST float AiSchlickFresnel ( const AtVector N,
const AtVector V,
float  Krn 
)

Computes Fresnel reflectance at an air-dielectric interface for given normal and viewing vectors.

Uses Schlick's cos^5 approximation.

Parameters
Nsurface normal
Vincident viewing direction
Krnreflectance at normal incidence, derived from the dielectric's IOR
Returns
reflectance value, in [0,1]
AI_API AI_CONST AtRGB AiSchlickFresnelRGB ( const AtVector N,
const AtVector V,
const AtRGB Krn 
)

Optimized version of AiSchlickFresnel() for RGB reflectance.

Using this function once avoids three calls to the scalar AiSchlickFresnel(), saving a few CPU cycles.

Parameters
Nsurface normal
Vincident viewing direction
Krnreflectance at normal incidence, derived from the dielectric's IOR
Returns
reflectance value, in [0,1]
AI_API AI_CONST AtRGB AiConductorFresnel ( const AtVector N,
const AtVector V,
const AtRGB n,
const AtRGB k 
)

Computes Fresnel reflectance at a conductor interface for given normal and viewing vectors.

Parameters
Nsurface normal
Vincident viewing direction
nreal part of the complex refractive index
kimaginary part of the complex refractive index
Returns
reflectance value, in [0,1]
AI_API AI_CONST float AiDielectricFresnel ( const AtVector N,
const AtVector V,
float  eta 
)

Computes Fresnel reflectance at a dielectric interface for given normal and viewing vectors.

Parameters
Nsurface normal
Vincident viewing direction
etaindex of refraction (IOR)
Returns
reflectance value, in [0,1]
AI_API AI_DEVICE void AiArtisticToConductorFresnel ( const AtRGB reflectivity,
const AtRGB edgetint,
AtRGB n,
AtRGB k 
)

Convert artist friendly metalicl Fresnel parameters to complex refractive indices for conductor Fresnel.

See also
http://jcgt.org/published/0003/04/03/
Parameters
reflectivityreflectance at normal incidence
edgetintcolor bias at edges
nreal part of the complex refractive index
kimaginary part of the complex refractive index
AI_API AI_DEVICE void AiFaceForward ( AtVector N,
const AtVector I 
)

Make a normal vector face forward with respect to a given vector.

Reverses vector N if needed, in order to make it face forward with respect to vector I.

Parameters
[in,out]Nsurface normal
Iincident direction
AI_API bool AiShaderGlobalsGetTriangle ( const AtShaderGlobals sg,
int  key,
AtVector  p[3] 
)

Get triangle vertices at a given motion key.

Return object-space triangle vertices at this shading context, at a given motion key. It is up to the caller to transform the vertices to world-space as needed.

Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
keymotion key to get the triangle at (if -1, vertices are interpolated at sg->time)
[out]poutput array of triangle vertices in object-space
Returns
true if success, false if there is no triangle to get vertices from.
See also
AiShaderGlobalsGetPolygon
AI_API bool AiShaderGlobalsGetVertexNormals ( const AtShaderGlobals sg,
int  key,
AtVector  n[3] 
)

Get normal vectors for all triangle vertices.

Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
keymotion key to get the normals at (if -1, normals are interpolated at sg->time)
[out]noutput array of triangle vertex normals
Returns
true if success, false if there is no triangle to get normals from or if the mesh doesn't have vertex normals, or during displacement.
Note
Not available during displacement.
See also
AiShaderGlobalsGetTriangle
AiShaderGlobalsGetVertexUVs
AI_API bool AiShaderGlobalsGetVertexUVs ( const AtShaderGlobals sg,
const AtString  uvset,
AtVector2  uv[3] 
)

Get UV coordinates for all triangle vertices.

Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
uvsetuv set this query refers to, if uvset is NULL or empty the default UVs will be returned
[out]uvoutput array of UV coordinates
Returns
true if success, false if there is no triangle to get UVs from or if the mesh doesn't have UV coordinates.
See also
AiShaderGlobalsGetTriangle
AiShaderGlobalsGetVertexNormals
AI_API uint32_t AiShaderGlobalsGetPolygon ( const AtShaderGlobals sg,
int  key,
AtVector p 
)

Get polygon vertices at a given motion key.

Return object-space polygon vertices at this shading context, at a given motion key. It is up to the caller to transform the vertices to world-space as needed.

Usage example:

1 AtUInt32 numvertices = AiShaderGlobalsGetPolygon(sg, key, NULL);
2 AtVector* vertices = (AtVector*) AiShaderGlobalsQuickAlloc(sg, np * sizeof(AtVector));
3 AiShaderGlobalsGetPolygon(sg, key, vertices);
4 // do whatever process with the vertices
Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
keymotion key to get the polygon at (if -1, vertices are interpolated at sg->time)
[out]pif non-null, it will be filled with polygon vertices in object-space
Returns
number of polygon vertices, or 0 if there is no polygon in sg
See also
AiShaderGlobalsGetTriangle
AI_API uint32_t AiShaderGlobalsGetUniformID ( const AtShaderGlobals sg)

Get unique per face, subdivision patch, curve or point ID.

This uniform ID may for example be used for randomizing colors per hair curve.

Parameters
sgshader globals context
Returns
uniform ID
AI_API void AiShaderGlobalsGetPositionAtTime ( const AtShaderGlobals sg,
float  time,
AtVector P,
AtVector N,
AtVector Ng,
AtVector Ns 
)

Reproject the shading point to a different time.

The function will take in a shader globals and output a new position, smooth and geometric normal. Note that the normals are optional, if any of them is not needed, you may pass NULL to avoid their calculation.

A typical use of this function is to reproject the shading point to time=0, so that the new point can be used to index into a user-created spatial data structure that was built at time=0 and thus has no support for motion-blur. For example, a static, octree-based irradiance cache.

Note
Normals not available during displacement (will not be computed).
Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
timetime at which sg->P will be reprojected
[out]Preprojected sg->P
[out]Nreprojected sg->N (optional)
[out]Ngreprojected sg->Ng (optional)
[out]Nsreprojected sg->Ns (optional)
AI_API AI_PURE AtVector2 AiShaderGlobalsGetPixelMotionVector ( const AtShaderGlobals sg,
float  time0,
float  time1 
)

Compute motion vector.

Measures the motion of the hit point in screen space during the given time interval. This can be used to implement screen space motion vector shaders.

Parameters
sgshader globals for current hit point
time0time from which to start the vector
time1time at which to stop the vector
Returns
amount of motion in raster space (pixels)
AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxLocal ( const AtShaderGlobals sg)

Get the object-space bounds of the current object.

Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
Returns
the object's bounding box in object-space
AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxWorld ( const AtShaderGlobals sg)

Get the world-space bounds of the current object.

Parameters
sga shader globals context of type AI_CONTEXT_SURFACE
Returns
the object's bounding box in world-space
AI_API AtNode* AiShaderGlobalsGetShader ( const AtShaderGlobals sg)

Get shader assigned to the object at the current shading point.

Parameters
sgshader globals context
Returns
root shader node
AI_API void AiShaderGlobalsSetTraceSet ( AtShaderGlobals sg,
const AtString  set,
bool  inclusive 
)

Takes a trace-set string and assigns it to the shader globals.

Any ray created on the basis of this shader globals, will use this trace-set.

Warning
Since sg->traceset can be accessed after the assignment, it's possible (but unlikely) that someone will change the contents of the string.
Parameters
sgshader globals context where the trace-set will be stored
setthe trace-set string
inclusiveindicates if the trace-set is to be treated as an inclusive set, as opposed to an exclusive one
See also
AiShaderGlobalsUnsetTraceSet
AI_API void AiShaderGlobalsUnsetTraceSet ( AtShaderGlobals sg)

Resets the trace-set for this shader globals.

Sets the trace-set to NULL which indicates that trace-sets are to be ignored. While the same behavior can be achieved by calling AiShaderGlobalsSetTraceSet() and either passing in a NULL, or passing the name of a trace-set that doesn't exist and setting inclusive to false, it is both cleaner and more efficient to use this function instead.

Parameters
sgshader globals context where the trace-set will be removed from
See also
AiShaderGlobalsSetTraceSet
AI_API void* AiShaderGlobalsQuickAlloc ( const AtShaderGlobals sg,
uint32_t  size 
)

Allocates temporary memory for this ray-tree.

This function returns a block of memory that will be accessible until the camera ray for this sample is done. The memory is allocated from an internal memory pool that is flushed after each sub-pixel sample. This is much faster than allocating memory via malloc() or AiMalloc(). This can be useful to exchange data of type pointer or string within shader networks or across rays by using message passing.

Parameters
sgnon-NULL shader globals context for the point being shaded
sizenumber of bytes to allocate
Returns
a pointer to a block of memory at least size bytes long or NULL if either parameter was NULL or 0
AI_API AI_PURE AtVector AiShaderGlobalsEvaluateBump ( AtShaderGlobals sg,
AtFloatBumpEvaluator  bump_func,
void *  data 
)

Computes and returns a normal based on the current shading point and the specified bump-function.

This function will compute and return a perturbed normal based on the specified shading point and bump-mapping function. This function will create three new shader-globals contexts surrounding the shading point, and call the supplied bump-mapping function with the three new displaced shading contexts. Given a particular shading context, the bump-mapping function should return its associated displacement value (a float). The new normal is calculated based on a forward differencing of the the values returned by this bump-mapping function.

This function itself will not modify the incoming AtShaderGlobals, but it is possible that the bump-mapping function itself, or those functions that it might call, will modify the incoming 'sg'.

Parameters
sgshader globals context for the point whose perturbed normal is being computed
bump_funca bump-mapping function which returns a float-based displacement amount. This function will be executed three times with three different shading point contexts.
dataan opaque user-pointer which is passed on to the bump-mapping function in order to help pass on state information.
Returns
a perturbed normal for the current shading point
AI_API AtRGB AiShaderGlobalsStochasticOpacity ( AtShaderGlobals sg,
const AtRGB opacity 
)

Performs some optimizations and returns a modified opacity value which allows for increased performance.

The opacity value is equivalent and can be used instead of the provided opacity.

Parameters
sgshader globals context for the point whose opacity is being applied
opacityopacity value upon which the optimizations are applied
Returns
modified opacity value
AI_API AI_DEVICE AI_PURE float AiShaderGlobalsArea ( const AtShaderGlobals sg)

Computes the world space area being shaded or displaced.

Area differential on the shaded surface:

area = ||dPdx x dPdy||
Parameters
sgshader globals context at the shading point
Returns
area at sg
AI_API AI_PURE float AiShaderGlobalsEdgeLength ( const AtShaderGlobals sg)

Computes the maximum (for now) edge length of a given polygon.

This is currently used by the heatmap code in the utility node.

Parameters
sgshader globals context at the shading point
Returns
maximum edge length of the polygon at sg
AI_API AI_PURE float AiWireframe ( const AtShaderGlobals sg,
float  line_width,
bool  raster_space,
int  edge_type 
)

Computes wireframe shading for a mesh.

Returns 0 when the current point is close to the triangle's edges and 1 otherwise. A fractional value may be returned in between for anti-aliasing purposes. This can be used to render the wireframe of a mesh.

Parameters
sgshader globals context at the shading point
line_widththe size of the lines in either pixel-space or world-space
raster_spaceif enabled, line_width works in pixel-space
edge_typethis value should be one of AI_WIREFRAME_*
Returns
a number in the range [0,1]
AI_API AI_PURE bool AiShaderGlobalsIsObjectMatte ( const AtShaderGlobals sg)

Retrieve the matte setting for the current object.

The matte setting when turned on will force the object to have an RGBA of zero. Surface shaders are not run when the object is both opaque and matte at the same time, and when it is not opaque the shaders will be run only to retrieve opacity for blending purposes.

Returns
matte status for the object
AI_DEVICE AtVector AiFaceViewer ( const AtShaderGlobals sg)
inline

Make the surface normal face the viewer.

Returns a reversed vector sg->N if needed, in order to make it face forward with respect to viewing vector sg->Rd (not necessarily a camera ray).

Parameters
sgthe current shading context
Returns
viewer-facing normal vector
AI_API AI_PURE float AiCameraGetShutterStart ( )

Fetch camera shutter start.

Returns
shutter start time
AI_API AI_PURE float AiCameraGetShutterEnd ( )

Fetch camera shutter end.

This function correctly accounts for closed shutters and disabled motion blur.

Returns
shutter end time
AI_API void AiCameraToWorldMatrix ( const AtNode node,
float  time,
AtMatrix out 
)

Computes camera to world matrix.

Computes the matrix that transforms between camera space and world space. Camera space is defined such that +x is right, +y is up and looks down -z. This function accounts for camera motion blur by calculating the matrix at the requested time. If you are not interested in motion information, you can use options.reference_time or AiCameraGetShutterStart() for time.

If the provided node is invalid, not a camera or otherwise not initialized this function will return the identity matrix.

Parameters
nodecamera node to get matrix from
timeabsolute time at which to calculate the matrix
[out]outthis matrix will be filled with the camera to world matrix for the requested time
See also
AiCameraGetShutterStart
AI_API void AiWorldToCameraMatrix ( const AtNode node,
float  time,
AtMatrix out 
)

Computes world to camera matrix.

Computes the matrix that transforms between world space and camera space. Camera space is defined such that +x is right, +y is up and looks down -z. This function accounts for camera motion blur by calculating the matrix at the requested time. If you are not interested in motion information, you can use options.reference_time or AiCameraGetShutterStart() for time.

If the provided node is invalid, not a camera or otherwise not initialized this function will return the identity matrix.

Parameters
nodecamera node to get matrix from
timeabsolute time at which to calculate the matrix
[out]outthis matrix will be filled with the world to camera matrix for the requested time
See also
AiCameraGetShutterStart
AI_API void AiWorldToScreenMatrix ( const AtNode node,
float  time,
AtMatrix out 
)

Computes world to screen matrix.

Computes the matrix that transforms between world space and screen space. Screen space is defined such that +x is right, +y is up and looks down +z. After a homogenous transform and normalization by w, you will have x and y in [-1,+1] and z in [0,1] (which correspond to near and far clipping planes).

This function accounts for camera motion blur by calculating the matrix at the requested time. If you are not interested in motion information, you can use options.reference_time or AiCameraGetShutterStart() for time.

If the provided node is invalid, not a camera or otherwise not initialized this function will return the identity matrix.

Parameters
nodecamera node to get matrix from
timeabsolute time at which to calculate the matrix
[out]outthis matrix will be filled with the world to screen matrix for the requested time
See also
AiCameraGetShutterStart
AI_API void AiMappingMirroredBall ( const AtVector dir,
float &  u,
float &  v 
)

Maps a world-space direction vector to texture coordinates (u,v) based on the mirrored-ball mapping.

Parameters
dirworld-space direction vector
[out]ulocation in which to write u
[out]vlocation in which to write v
AI_API void AiMappingAngularMap ( const AtVector dir,
float &  u,
float &  v 
)

Maps a world-space direction vector to texture coordinates (u,v) based on an angular mapping.

Parameters
dirworld-space direction vector
[out]ulocation in which to write u
[out]vlocation in which to write v
AI_API void AiMappingLatLong ( const AtVector dir,
float &  u,
float &  v 
)

Maps a world-space direction vector to texture coordinates (u,v) based on the Latitude/Longitude mapping.

Parameters
dirWorld-space direction vector
[out]ulocation in which to write u
[out]vlocation in which to write v
AI_API AI_DEVICE void AiMappingMirroredBallDerivs ( const AtVector dir,
const AtVector dDdx,
const AtVector dDdy,
float &  u,
float &  v,
float &  dudx,
float &  dudy,
float &  dvdx,
float &  dvdy 
)

Derivative version of AiMappingMirroredBall().

Parameters
dirworld-space direction vector
dDdxdirectional derivative of the ray with respect to the x pixel coordinate
dDdydirectional derivative of the ray with respect to the y pixel coordinate
[out]ulocation in which to write u
[out]vlocation in which to write v
[out]dudxpointer to location in which to write dudx
[out]dudypointer to location in which to write dudy
[out]dvdxpointer to location in which to write dvdx
[out]dvdypointer to location in which to write dvdy
AI_API AI_DEVICE void AiMappingAngularMapDerivs ( const AtVector dir,
const AtVector dDdx,
const AtVector dDdy,
float &  u,
float &  v,
float &  dudx,
float &  dudy,
float &  dvdx,
float &  dvdy 
)

Derivative version of AiMappingAngularMap().

Parameters
dirworld-space direction vector
dDdxdirectional derivative of the ray with respect to the x pixel coordinate
dDdydirectional derivative of the ray with respect to the y pixel coordinate
[out]ulocation in which to write u
[out]vlocation in which to write v
[out]dudxpointer to location in which to write dudx
[out]dudypointer to location in which to write dudy
[out]dvdxpointer to location in which to write dvdx
[out]dvdypointer to location in which to write dvdy
AI_API AI_DEVICE void AiMappingLatLongDerivs ( const AtVector dir,
const AtVector dDdx,
const AtVector dDdy,
float &  u,
float &  v,
float &  dudx,
float &  dudy,
float &  dvdx,
float &  dvdy 
)

Derivative version of AiMappingLatLong().

Parameters
dirworld-space direction vector
dDdxdirectional derivative of the ray with respect to the x pixel coordinate
dDdydirectional derivative of the ray with respect to the y pixel coordinate
[out]ulocation in which to write u
[out]vlocation in which to write v
[out]dudxpointer to location in which to write dudx
[out]dudypointer to location in which to write dudy
[out]dvdxpointer to location in which to write dvdx
[out]dvdypointer to location in which to write dvdy

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