Various utility functions for shader writers. 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...

Lighting Functions
AI_API AI_DEVICE AI_GPU_FORCE_INLINE 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 AI_DEVICE AI_GPU_FORCE_INLINE 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 metallic 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 Functions
AI_API AI_DEVICE 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 AI_DEVICE uint32_t	AiShaderGlobalsGetPolygon (const AtShaderGlobals sg, int key, AtVector p)
	Get polygon vertices at a given motion key. More...

AI_API AI_DEVICE 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 AtNode *	AiShaderGlobalsGetShader (const AtShaderGlobals *sg)
	Get shader assigned to the object at the current shading point. More...

AI_API AI_DEVICE int32_t	AiShaderGlobalsGetSelectedOutput (const AtShaderGlobals *sg)

AI_API AI_DEVICE AI_PURE AtVector	AiShaderGlobalsTransformNormal (const AtShaderGlobals *sg, AtVector N, int space)

AI_API AI_DEVICE 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 AI_DEVICE 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_DEVICE AI_PURE float	AiShaderGlobalsEdgeLength (const AtShaderGlobals *sg)
	Computes the maximum (for now) edge length of a given polygon. More...

AI_API AI_DEVICE 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 AI_DEVICE void	AiCameraToWorldMatrix (const AtNode *node, float time, AtMatrix &out)
	Computes camera to world matrix. More...

AI_API AI_DEVICE void	AiWorldToCameraMatrix (const AtNode *node, float time, AtMatrix &out)
	Computes world to camera matrix. More...

AI_API AI_DEVICE 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...

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.

Detailed Description

Various utility functions for shader writers.

Typedef Documentation

◆ AtFloatBumpEvaluator

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

sg	the current shading context
data	user-defined data pointer

Returns: bump/displacement height for the current shading context

Function Documentation

◆ AiOcclusion()

AI_API AI_DEVICE AI_GPU_FORCE_INLINE 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

	N	normal vector at the shading point
	Ng	geometric normal
	sg	the shader globals context where occlusion is evaluated
	mint	minimum ray distance
	maxt	maximum ray distance
	spread	angular radian spread around the normal vector N, in the range [0,pi/2]
	falloff	exponential falloff rate for the occlusion along the ray distance
	sampler	a two-dimensional AtSampler object that holds the number of samples to take per evaluation
[out]	Nbent	if 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

◆ AiSelfOcclusion()

AI_API AI_DEVICE AI_GPU_FORCE_INLINE 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

	N	normal vector at the shading point
	Ng	geometric normal
	sg	the shader globals context where occlusion is evaluated
	mint	minimum ray distance
	maxt	maximum ray distance
	spread	angular spread around the normal vector N, in the range [0,1], where 1 maps to 90 degrees (the full hemisphere)
	falloff	exponential falloff rate for the occlusion along the ray distance
	sampler	a two-dimensional AtSampler object that holds the number of samples to take per evaluation
[out]	Nbent	if 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

◆ AiDirectDiffuse()

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

N	normal vector that defines the hemisphere of incoming radiance
sg	shader globals context where irradiance is evaluated at

Returns: direct component of diffuse irradiance

◆ AiIndirectDiffuse()

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

N	normal vector that defines the hemisphere of incoming radiance
sg	shader globals context where irradiance is evaluated at
weight	RGB 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

◆ AiReflect()

AI_API AI_DEVICE AtVector AiReflect	(	const AtVector &	I,
		const AtVector &	N
	)

Returns specular direction from incident direction I and normal N.

Parameters

I	incident direction
N	surface normal

◆ AiReflectWithDerivs()

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

I	incident direction
N	surface normal

◆ AiReflectSafe()

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

I	incident direction
N	surface normal
Ng	surface normal

◆ AiRefract()

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

	I	incident direction
	N	surface normal
[out]	T	outgoing transmitted direction with respect to N
	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

Returns: false if total internal reflection (TIR) occurs and there is no transmission

◆ AiRefractWithDerivs()

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

	I	incident direction
	N	surface normal
[out]	T	outgoing transmitted direction with respect to N
	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

Returns: false if total internal reflection (TIR) occurs and there is no transmission

◆ AiSchlickFresnel()

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

N	surface normal
V	incident viewing direction
Krn	reflectance at normal incidence, derived from the dielectric's IOR

Returns: reflectance value, in [0,1]

◆ AiSchlickFresnelRGB()

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

N	surface normal
V	incident viewing direction
Krn	reflectance at normal incidence, derived from the dielectric's IOR

Returns: reflectance value, in [0,1]

◆ AiConductorFresnel()

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

N	surface normal
V	incident viewing direction
n	real part of the complex refractive index
k	imaginary part of the complex refractive index

Returns: reflectance value, in [0,1]

◆ AiDielectricFresnel()

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

N	surface normal
V	incident viewing direction
eta	index of refraction (IOR)

Returns: reflectance value, in [0,1]

◆ AiArtisticToConductorFresnel()

AI_API AI_DEVICE void AiArtisticToConductorFresnel	(	const AtRGB &	reflectivity,
		const AtRGB &	edgetint,
		AtRGB &	n,
		AtRGB &	k
	)

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

See also: http://jcgt.org/published/0003/04/03/

Parameters

reflectivity	reflectance at normal incidence
edgetint	color bias at edges
n	real part of the complex refractive index
k	imaginary part of the complex refractive index

◆ AiFaceForward()

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]	N	surface normal
	I	incident direction

◆ AiShaderGlobalsGetTriangle()

AI_API AI_DEVICE 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

	sg	a shader globals context of type `AI_CONTEXT_SURFACE`
	key	motion key to get the triangle at (if -1, vertices are interpolated at `sg->time`)
[out]	p	output array of triangle vertices in object-space

Returns: true if success, false if there is no triangle to get vertices from.

See also: AiShaderGlobalsGetPolygon

◆ AiShaderGlobalsGetVertexNormals()

AI_API bool AiShaderGlobalsGetVertexNormals	(	const AtShaderGlobals *	sg,
		int	key,
		AtVector	n[3]
	)

Get normal vectors for all triangle vertices.

Parameters

	sg	a shader globals context of type `AI_CONTEXT_SURFACE`
	key	motion key to get the normals at (if -1, normals are interpolated at `sg->time`)
[out]	n	output 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

◆ AiShaderGlobalsGetVertexUVs()

AI_API bool AiShaderGlobalsGetVertexUVs	(	const AtShaderGlobals *	sg,
		const AtString	uvset,
		AtVector2	uv[3]
	)

Get UV coordinates for all triangle vertices.

Parameters

	sg	a shader globals context of type `AI_CONTEXT_SURFACE`
	uvset	uv set this query refers to, if uvset is NULL or empty the default UVs will be returned
[out]	uv	output 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

◆ AiShaderGlobalsGetPolygon()

AI_API AI_DEVICE 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:

AtUInt32 numvertices = AiShaderGlobalsGetPolygon(sg, key, NULL);
AtVector* vertices   = (AtVector*) AiShaderGlobalsQuickAlloc(sg, np * sizeof(AtVector));
AiShaderGlobalsGetPolygon(sg, key, vertices);
// do whatever process with the vertices

Parameters

	sg	a shader globals context of type `AI_CONTEXT_SURFACE`
	key	motion key to get the polygon at (if -1, vertices are interpolated at `sg->time`)
[out]	p	if 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

◆ AiShaderGlobalsGetUniformID()

AI_API AI_DEVICE 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

sg	shader globals context

Returns: uniform ID

◆ AiShaderGlobalsGetPositionAtTime()

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

	sg	a shader globals context of type `AI_CONTEXT_SURFACE`
	time	time at which `sg->P` will be reprojected
[out]	P	reprojected `sg->P`
[out]	N	reprojected `sg->N` (optional)
[out]	Ng	reprojected `sg->Ng` (optional)
[out]	Ns	reprojected `sg->Ns` (optional)

◆ AiShaderGlobalsGetPixelMotionVector()

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

sg	shader globals for current hit point
time0	time from which to start the vector
time1	time at which to stop the vector

Returns: amount of motion in raster space (pixels)

◆ AiShaderGlobalsGetBBoxLocal()

AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxLocal ( const AtShaderGlobals * sg )

Get the object-space bounds of the current object.

Parameters

sg	a shader globals context of type `AI_CONTEXT_SURFACE`

Returns: the object's bounding box in object-space

◆ AiShaderGlobalsGetBBoxWorld()

AI_API AI_PURE AtBBox AiShaderGlobalsGetBBoxWorld ( const AtShaderGlobals * sg )

Get the world-space bounds of the current object.

Parameters

sg	a shader globals context of type `AI_CONTEXT_SURFACE`

Returns: the object's bounding box in world-space

◆ AiShaderGlobalsGetShader()

AI_API AtNode * AiShaderGlobalsGetShader ( const AtShaderGlobals * sg )

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

Parameters

sg	shader globals context

Returns: root shader node

◆ AiShaderGlobalsSetTraceSet()

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

sg	shader globals context where the trace-set will be stored
set	the trace-set string
inclusive	indicates if the trace-set is to be treated as an inclusive set, as opposed to an exclusive one

See also: AiShaderGlobalsUnsetTraceSet

◆ 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

sg	shader globals context where the trace-set will be removed from

See also: AiShaderGlobalsSetTraceSet

◆ AiShaderGlobalsQuickAlloc()

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

sg	non-NULL shader globals context for the point being shaded
size	number 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

◆ AiShaderGlobalsEvaluateBump()

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

sg	shader globals context for the point whose perturbed normal is being computed
bump_func	a bump-mapping function which returns a float-based displacement amount. This function will be executed three times with three different shading point contexts.
data	an 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

◆ AiShaderGlobalsStochasticOpacity()

AI_API AI_DEVICE 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

sg	shader globals context for the point whose opacity is being applied
opacity	opacity value upon which the optimizations are applied

Returns: modified opacity value

◆ AiShaderGlobalsArea()

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

sg	shader globals context at the shading point

Returns: area at sg

◆ AiShaderGlobalsEdgeLength()

AI_API AI_DEVICE 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

sg	shader globals context at the shading point

Returns: maximum edge length of the polygon at sg

◆ AiWireframe()

AI_API AI_DEVICE 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

sg	shader globals context at the shading point
line_width	the size of the lines in either pixel-space or world-space
raster_space	if enabled, `line_width` works in pixel-space
edge_type	this value should be one of `AI_WIREFRAME_*`

Returns: a number in the range [0,1]

◆ AiShaderGlobalsIsObjectMatte()

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

◆ AiFaceViewer()

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

sg	the current shading context

Returns: viewer-facing normal vector

◆ AiCameraGetShutterStart()

AI_API AI_PURE float AiCameraGetShutterStart ( )

Fetch camera shutter start.

Returns: shutter start time

◆ AiCameraGetShutterEnd()

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

◆ AiCameraToWorldMatrix()

AI_API AI_DEVICE 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

	node	camera node to get matrix from
	time	absolute time at which to calculate the matrix
[out]	out	this matrix will be filled with the camera to world matrix for the requested time

See also: AiCameraGetShutterStart

◆ AiWorldToCameraMatrix()

AI_API AI_DEVICE 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

	node	camera node to get matrix from
	time	absolute time at which to calculate the matrix
[out]	out	this matrix will be filled with the world to camera matrix for the requested time

See also: AiCameraGetShutterStart

◆ AiWorldToScreenMatrix()

AI_API AI_DEVICE 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

	node	camera node to get matrix from
	time	absolute time at which to calculate the matrix
[out]	out	this matrix will be filled with the world to screen matrix for the requested time

See also: AiCameraGetShutterStart

◆ AiMappingMirroredBall()

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

	dir	world-space direction vector
[out]	u	location in which to write u
[out]	v	location in which to write v

◆ AiMappingAngularMap()

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

	dir	world-space direction vector
[out]	u	location in which to write u
[out]	v	location in which to write v

◆ AiMappingLatLong()

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

	dir	World-space direction vector
[out]	u	location in which to write u
[out]	v	location in which to write v

◆ AiMappingMirroredBallDerivs()

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

	dir	world-space direction vector
	dDdx	directional derivative of the ray with respect to the x pixel coordinate
	dDdy	directional derivative of the ray with respect to the y pixel coordinate
[out]	u	location in which to write u
[out]	v	location in which to write v
[out]	dudx	pointer to location in which to write dudx
[out]	dudy	pointer to location in which to write dudy
[out]	dvdx	pointer to location in which to write dvdx
[out]	dvdy	pointer to location in which to write dvdy

◆ AiMappingAngularMapDerivs()

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

	dir	world-space direction vector
	dDdx	directional derivative of the ray with respect to the x pixel coordinate
	dDdy	directional derivative of the ray with respect to the y pixel coordinate
[out]	u	location in which to write u
[out]	v	location in which to write v
[out]	dudx	pointer to location in which to write dudx
[out]	dudy	pointer to location in which to write dudy
[out]	dvdx	pointer to location in which to write dvdx
[out]	dvdy	pointer to location in which to write dvdy

◆ AiMappingLatLongDerivs()

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

	dir	world-space direction vector
	dDdx	directional derivative of the ray with respect to the x pixel coordinate
	dDdy	directional derivative of the ray with respect to the y pixel coordinate
[out]	u	location in which to write u
[out]	v	location in which to write v
[out]	dudx	pointer to location in which to write dudx
[out]	dudy	pointer to location in which to write dudy
[out]	dvdx	pointer to location in which to write dvdx
[out]	dvdy	pointer to location in which to write dvdy

Utility Helper Types

Lighting Functions

BSDF Utility Functions

Utility Functions

Camera Information

Environment Mappings

Derivatives for Environment Mappings

Coordinate Transformations

Wireframe Types

Detailed Description

Typedef Documentation

◆ AtFloatBumpEvaluator

Function Documentation

◆ AiOcclusion()

◆ AiSelfOcclusion()

◆ AiDirectDiffuse()

◆ AiIndirectDiffuse()

◆ AiReflect()

◆ AiReflectWithDerivs()

◆ AiReflectSafe()

◆ AiRefract()

◆ AiRefractWithDerivs()

◆ AiSchlickFresnel()

◆ AiSchlickFresnelRGB()

◆ AiConductorFresnel()

◆ AiDielectricFresnel()

◆ AiArtisticToConductorFresnel()

◆ AiFaceForward()

◆ AiShaderGlobalsGetTriangle()

◆ AiShaderGlobalsGetVertexNormals()

◆ AiShaderGlobalsGetVertexUVs()

◆ AiShaderGlobalsGetPolygon()

◆ AiShaderGlobalsGetUniformID()

◆ AiShaderGlobalsGetPositionAtTime()

◆ AiShaderGlobalsGetPixelMotionVector()

◆ AiShaderGlobalsGetBBoxLocal()

◆ AiShaderGlobalsGetBBoxWorld()

◆ AiShaderGlobalsGetShader()

◆ AiShaderGlobalsSetTraceSet()

◆ AiShaderGlobalsUnsetTraceSet()

◆ AiShaderGlobalsQuickAlloc()

◆ AiShaderGlobalsEvaluateBump()

◆ AiShaderGlobalsStochasticOpacity()

◆ AiShaderGlobalsArea()

◆ AiShaderGlobalsEdgeLength()

◆ AiWireframe()

◆ AiShaderGlobalsIsObjectMatte()

◆ AiFaceViewer()

◆ AiCameraGetShutterStart()

◆ AiCameraGetShutterEnd()

◆ AiCameraToWorldMatrix()

◆ AiWorldToCameraMatrix()

◆ AiWorldToScreenMatrix()

◆ AiMappingMirroredBall()

◆ AiMappingAngularMap()

◆ AiMappingLatLong()

◆ AiMappingMirroredBallDerivs()

◆ AiMappingAngularMapDerivs()

◆ AiMappingLatLongDerivs()