Various BSDF functions available to shader writers. More...

Data Structures
struct	AtBSDFLobeInfo
	BSDF lobe information. More...

struct	AtBSDFLobeSample
	BSDF lobe sample. More...

struct	AtBSDFMethods
	BSDF function table. More...

struct	AtOrenNayarBSDFParams
	AiOrenNayarBSDF parameters. More...

struct	AtMicrofacetBSDFParams
	AiMicrofacetBSDF parameters. More...

struct	AtMicrofacetRefractionBSDFParams
	AiMicrofacetRefractionBSDF parameters. More...

struct	AtMicrofacetThinWallRefractionBSDFParams
	AiMicrofacetThinWallRefractionBSDF parameters. More...

struct	AtMetalBSDFParams
	AiMetalBSDF parameters. More...

Macros
#define	AI_BSDF_EXPORT_METHODS(tag)
	BSDF methods exporter. More...

#define	bsdf_init
	Initialize BSDF when before it is used for the first time. More...

#define	bsdf_eval
	Evaluate BSDF for the given incoming light direction. More...

#define	bsdf_sample
	Sample BSDF for an incoming light direction, and evaluate BSDF. More...

#define	bsdf_albedo
	Compute BSDF albedo for AOVs and importance sampling (optional method) More...

#define	bsdf_merge
	Merge BSDF with another BSDF of the same type (optional method) More...

#define	bsdf_interior
	Return volume closures describing the interior of the object. More...

Typedefs
typedef uint32_t	AtBSDFLobeMask
	BSDF lobe bitmask.

Enumerations
enum	AtBSDFLobeFlags { AI_BSDF_LOBE_SINGULAR = 0x01 , AI_BSDF_LOBE_WAVELENGTH_SAMPLE = 0x02 , AI_BSDF_LOBE_EXIT_BACKGROUND = 0x04 , AI_BSDF_LOBE_EXIT_WHITE = 0x08 }
	BSDF Lobe flags. More...

Functions
AI_DEVICE	AtBSDFLobeSample::AtBSDFLobeSample (AtRGB weight, float reverse_pdf, float pdf)

AI_DEVICE	AtBSDFLobeSample::AtBSDFLobeSample (AtRGB eval)

Variables
uint8_t	AtBSDFLobeInfo::ray_type

uint8_t	AtBSDFLobeInfo::flags

AtString	AtBSDFLobeInfo::label

AtRGB	AtBSDFLobeSample::weight

float	AtBSDFLobeSample::reverse_pdf

float	AtBSDFLobeSample::pdf

int	AtBSDFMethods::version

void(*	AtBSDFMethods::Init )(const AtShaderGlobals sg, AtBSDF bsdf)

AtBSDFLobeMask(*	AtBSDFMethods::Eval )(const AtBSDF *bsdf, const AtVector &wi, const AtBSDFLobeMask lobe_mask, const bool need_pdf, AtBSDFLobeSample out_lobes[])

AtBSDFLobeMask(*	AtBSDFMethods::Sample )(const AtBSDF *bsdf, const AtVector rnd, const float wavelength, const AtBSDFLobeMask lobe_mask, const bool need_pdf, AtVectorDv &out_wi, int &out_lobe_index, AtBSDFLobeSample out_lobes[])

AtRGB(*	AtBSDFMethods::Albedo )(const AtBSDF bsdf, const AtShaderGlobals sg, const AtBSDFLobeMask lobe_mask)

bool(*	AtBSDFMethods::Merge )(AtBSDF bsdf, const AtBSDF other_bsdf)

AtClosureList(*	AtBSDFMethods::Interior )(const AtShaderGlobals sg, AtBSDF bsdf)

AtRGB	AtOrenNayarBSDFParams::weight = AI_RGB_WHITE
	BSDF weight.

AtVector	AtOrenNayarBSDFParams::N = AI_V3_Z
	normal vector that defines the hemisphere of incoming radiance

AtOrenNayarModel	AtOrenNayarBSDFParams::model = AtOrenNayarModel::ENERGY_PRESERVING
	select Oren-Nayar model variant

float	AtOrenNayarBSDFParams::r = 0.0f
	surface roughness, normalized in the [0, 1] range

bool	AtOrenNayarBSDFParams::transmission = false
	use diffuse transmission instead of reflection

AtString	AtOrenNayarBSDFParams::label = AtString()
	string label

AtRGB	AtMicrofacetBSDFParams::weight = AI_RGB_WHITE
	BSDF weight.

int	AtMicrofacetBSDFParams::distribution = AI_MICROFACET_GGX
	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`

AtVector	AtMicrofacetBSDFParams::N = AI_V3_Z
	normal vector that defines the hemisphere of incoming radiance

AtVector	AtMicrofacetBSDFParams::U = AI_V3_ZERO
	surface tangent vector along the U coordinate (the AI_V3_ZERO default auto-generates U from N).

float	AtMicrofacetBSDFParams::ior = 1.5f
	refractive index for Fresnel, use 0 to disable Fresnel

float	AtMicrofacetBSDFParams::rx = 0.f
	specular roughness along the U direction

float	AtMicrofacetBSDFParams::ry = 0.f
	specular roughness along the V direction

float	AtMicrofacetBSDFParams::haze_weight = 0.f
	haze lobe mix weight

float	AtMicrofacetBSDFParams::rx_haze = 0.f
	specular roughness of haze lobe, along the U direction

float	AtMicrofacetBSDFParams::ry_haze = 0.f
	specular roughness of haze lobe, along the V direction

int32_t	AtMicrofacetBSDFParams::dielectric_priority = 0
	user-specified signed-integer dielectric priority, for nested dielectrics

float	AtMicrofacetBSDFParams::thin_walled_transmission = 0.0f
	fraction of the BRDF which represents a thin-walled dielectric (to be used in conjunction with AiMicrofacetThinWallRefractionBSDF)

float	AtMicrofacetBSDFParams::specular_weight = 1.0f
	modulates dielectric Fresnel factor, without disturbing refraction (as described in the OpenPBR >= v1.2 spec)

float	AtMicrofacetBSDFParams::retro_reflectivity = 0.0f
	retro-reflectivity weight

uint8_t	AtMicrofacetBSDFParams::exit_type = 0
	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`

AtString	AtMicrofacetBSDFParams::label = AtString()
	string label

AtRGB	AtMicrofacetRefractionBSDFParams::weight = AI_RGB_WHITE
	BSDF weight.

int	AtMicrofacetRefractionBSDFParams::distribution = AI_MICROFACET_GGX
	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`

AtVector	AtMicrofacetRefractionBSDFParams::N = AI_V3_Z
	normal vector that defines the hemisphere of incoming radiance

AtVector	AtMicrofacetRefractionBSDFParams::U = AI_V3_ZERO
	surface tangent vector along the U coordinate (the AI_V3_ZERO default auto-generates U from N).

float	AtMicrofacetRefractionBSDFParams::ior = 1.5f
	refractive index for Fresnel, use 0 to disable Fresnel

float	AtMicrofacetRefractionBSDFParams::rx = 0.f
	specular roughness along the U direction

float	AtMicrofacetRefractionBSDFParams::ry = 0.f
	specular roughness along the V direction

float	AtMicrofacetRefractionBSDFParams::haze_weight = 0.f
	haze lobe mix weight

float	AtMicrofacetRefractionBSDFParams::rx_haze = 0.f
	specular roughness of haze lobe, along the U direction

float	AtMicrofacetRefractionBSDFParams::ry_haze = 0.f
	specular roughness of haze lobe, along the V direction

float	AtMicrofacetRefractionBSDFParams::dispersion = 0.f
	Cauchy "C" coefficient for dispersion. Zero for no dispersion, higher values give more dispersion.

AtClosureList	AtMicrofacetRefractionBSDFParams::interior_volume = AtClosureList()

bool	AtMicrofacetRefractionBSDFParams::use_fresnel = true
	set to true to include Fresnel term

int32_t	AtMicrofacetRefractionBSDFParams::dielectric_priority = 0
	user-specified signed-integer dielectric priority, for nested dielectrics

float	AtMicrofacetRefractionBSDFParams::specular_weight = 1.0f
	modulates dielectric Fresnel factor, without disturbing refraction (as described in the OpenPBR >= v1.2 spec)

uint8_t	AtMicrofacetRefractionBSDFParams::exit_type = 0
	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`

AtString	AtMicrofacetRefractionBSDFParams::label = AtString()
	label string

AtRGB	AtMicrofacetThinWallRefractionBSDFParams::weight = AI_RGB_WHITE
	BSDF weight.

int	AtMicrofacetThinWallRefractionBSDFParams::distribution = AI_MICROFACET_GGX
	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`

AtVector	AtMicrofacetThinWallRefractionBSDFParams::N = AI_V3_Z
	normal vector that defines the hemisphere of incoming radiance

AtVector	AtMicrofacetThinWallRefractionBSDFParams::U = AI_V3_ZERO
	surface tangent vector along the U coordinate (the AI_V3_ZERO default auto-generates U from N).

float	AtMicrofacetThinWallRefractionBSDFParams::ior = 1.5f
	refractive index of the interior medium

float	AtMicrofacetThinWallRefractionBSDFParams::rx = 0.f
	specular roughness of core lobe, along the U direction

float	AtMicrofacetThinWallRefractionBSDFParams::ry = 0.f
	specular roughness of core lobe, along the V direction

float	AtMicrofacetThinWallRefractionBSDFParams::haze_weight = 0.f
	haze lobe mix weight

float	AtMicrofacetThinWallRefractionBSDFParams::rx_haze = 0.f
	specular roughness of haze lobe, along the U direction

float	AtMicrofacetThinWallRefractionBSDFParams::ry_haze = 0.f
	specular roughness of haze lobe, along the V direction

float	AtMicrofacetThinWallRefractionBSDFParams::specular_weight = 1.0f
	modulates dielectric Fresnel factor, without disturbing refraction (as described in the OpenPBR >= v1.2 spec)

uint8_t	AtMicrofacetThinWallRefractionBSDFParams::exit_type = 0
	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`

AtString	AtMicrofacetThinWallRefractionBSDFParams::label = AtString()
	label string

AtRGB	AtMetalBSDFParams::weight = AI_RGB_WHITE
	BSDF weight.

int	AtMetalBSDFParams::distribution = AI_MICROFACET_GGX
	distribution `AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`

AtVector	AtMetalBSDFParams::N = AI_V3_Z
	normal vector that defines the hemisphere of incoming radiance

AtVector	AtMetalBSDFParams::U = AI_V3_ZERO
	surface tangent vector along the U coordinate (the AI_V3_ZERO default auto-generates U from N).

AtMetalFresnelMode	AtMetalBSDFParams::fresnel_mode = F82_TINT
	specify which Fresnel model to use for the metal (GULBRANDSEN or F82_TINT)

AtRGB	AtMetalBSDFParams::fresnel1 = AI_RGB_50GREY
	either real part of the complex refractive index for Fresnel (GULBRANDSEN), or F0 reflectance at normal incidence (F82_TINT)

AtRGB	AtMetalBSDFParams::fresnel2 = AI_RGB_WHITE
	either imaginary part of the complex refractive index for Fresnel (GULBRANDSEN), or tint applied at near-grazing (approx. More...

float	AtMetalBSDFParams::specular_weight = 1.0f
	scale factor applied (with a clamp) to the Fresnel factor, in the F82_TINT mode only (as described in the OpenPBR >= v1.2 spec)

float	AtMetalBSDFParams::rx = 0.f
	specular roughness along the U direction

float	AtMetalBSDFParams::ry = 0.f
	specular roughness along the V direction

float	AtMetalBSDFParams::haze_weight = 0.f
	haze lobe mix weight

float	AtMetalBSDFParams::rx_haze = 0.f
	specular roughness of haze lobe, along the U direction

float	AtMetalBSDFParams::ry_haze = 0.f
	specular roughness of haze lobe, along the V direction

float	AtMetalBSDFParams::retro_reflectivity = 0.0f
	retro-reflectivity weight

AtString	AtMetalBSDFParams::label = AtString()
	label string

Diffuse BRDF
enum	AtOrenNayarModel : unsigned char { QUALITATIVE , ENERGY_PRESERVING }
	Oren-Nayar model selection enum. More...

AI_API AI_DEVICE AtBSDF *	AiOrenNayarBSDF_private (const AtShaderGlobals *sg, const AtOrenNayarBSDFParams &params)
	Create Oren-Nayar BSDF. More...

AI_DEVICE AtBSDF *	AiOrenNayarBSDF (const AtShaderGlobals *sg, const AtOrenNayarBSDFParams &params)

AI_API AI_DEVICE AtBSDF *	AiOrenNayarBSDF (const AtShaderGlobals *sg, const AtRGB &weight, const AtVector &N, AtOrenNayarModel model=AtOrenNayarModel::ENERGY_PRESERVING, float r=0.0f, bool transmission=false, const AtString label=AtString())
	Create Oren-Nayar BSDF. More...

Metal BRDF
enum	AtMetalFresnelMode { GULBRANDSEN , F82_TINT }
	Metal Fresnel mode selection enum. More...

AI_API AI_DEVICE AtBSDF *	AiMetalBSDF_private (const AtShaderGlobals *sg, const AtMetalBSDFParams &params)
	Create microfacet BSDF with conductive Fresnel, for metals. More...

AI_DEVICE AtBSDF *	AiMetalBSDF (const AtShaderGlobals *sg, const AtMetalBSDFParams &params)

AI_API AI_DEVICE AtBSDF *	AiMetalBSDF (const AtShaderGlobals sg, const AtRGB &weight, int distribution, const AtVector &N, const AtVector U, AtMetalFresnelMode fresnel_mode, const AtRGB &fresnel1, const AtRGB &fresnel2, float specular_weight, float rx, float ry, const AtString label=AtString())
	Create microfacet BSDF with conductive Fresnel, for metals. More...

Functions for implementing custom BSDFs
AI_API AtBSDF *	AiBSDF (const AtShaderGlobals sg, const AtRGB &weight, const AtBSDFMethods methods, size_t data_size)
	Allocate a BSDF and data memory to store parameters. More...

AI_API const AtBSDFMethods *	AiBSDFGetMethods (const AtBSDF *bsdf)
	Get BSDF methods. More...

AI_API AI_DEVICE void *	AiBSDFGetData (const AtBSDF *bsdf)
	Get BSDF data memory to store BSDF parameters. More...

AI_API const AtBSDFLobeInfo *	AiBSDFGetLobes (const AtBSDF *bsdf)
	Get BSDF lobes, available after the BSDF has been initialized. More...

AI_API int	AiBSDFGetNumLobes (const AtBSDF *bsdf)
	Get the number of BSDF lobes, available after the BSDF has been initialized. More...

AI_API AI_DEVICE AtRGB	AiBSDFGetWeight (const AtBSDF *bsdf)
	Get the BSDF weight. More...

AI_API AI_DEVICE void	AiBSDFSetDirectIndirect (AtBSDF *bsdf, float weight_direct, float weight_indirect)
	Set the BSDF direct and indirect light contribution weights. More...

AI_API AI_DEVICE void	AiBSDFGetDirectIndirect (const AtBSDF *bsdf, float &weight_direct, float &weight_indirect)
	Get the BSDF direct and indirect light contribution weights. More...

AI_API AI_DEVICE void	AiBSDFInitLobes (AtBSDF bsdf, const AtBSDFLobeInfo lobes, int num_lobes)
	Initialize BSDF lobes. More...

AI_API AI_DEVICE void	AiBSDFInitNormal (AtBSDF *bsdf, const AtVector &N, bool bounding)
	Initialize BSDF normal. More...

AI_API AI_DEVICE float	AiBSDFBumpShadow (const AtVector &Ns, const AtVector &N, const AtVector &Ld)
	Compute BSDF shadow factor to solve shading artifacts with bump mapping. More...

AI_API AI_DEVICE float	AiBSDFMinRoughness (const AtShaderGlobals *sg)
	Estimate a minimum roughness for specular BSDFs, to reduce noise from caustics. More...

Microfacet BSDFs
AI_API AI_DEVICE AtBSDF *	AiMicrofacetBSDF_private (const AtShaderGlobals *sg, const AtMicrofacetBSDFParams &params)
	Create microfacet reflection BSDF. More...

AI_DEVICE AtBSDF *	AiMicrofacetBSDF (const AtShaderGlobals *sg, const AtMicrofacetBSDFParams &params)

AI_API AI_DEVICE AtBSDF *	AiMicrofacetBSDF (const AtShaderGlobals sg, const AtRGB &weight, int distribution, const AtVector &N, const AtVector U, float ior, float rx, float ry, uint8_t exit_type=0, int32_t dielectric_priority=0, float thin_walled_transmission=0, const AtString label=AtString())
	Create microfacet reflection BSDF. More...

AI_API AI_DEVICE AtBSDF *	AiMicrofacetRefractionBSDF_private (const AtShaderGlobals *sg, const AtMicrofacetRefractionBSDFParams &params)
	Create microfacet refraction BSDF. More...

AI_DEVICE AtBSDF *	AiMicrofacetRefractionBSDF (const AtShaderGlobals *sg, const AtMicrofacetRefractionBSDFParams &params)

AI_API AI_DEVICE AtBSDF *	AiMicrofacetRefractionBSDF (const AtShaderGlobals sg, const AtRGB &weight, int distribution, const AtVector &N, const AtVector U, float ior, float rx, float ry, float dispersion, bool use_fresnel=true, AtClosureList interior_volume=AtClosureList(), uint8_t exit_type=0, int32_t dielectric_priority=0, const AtString label=AtString())
	Create microfacet refraction BSDF. More...

AI_API AI_DEVICE AtBSDF *	AiMicrofacetThinWallRefractionBSDF_private (const AtShaderGlobals *sg, const AtMicrofacetThinWallRefractionBSDFParams &params)
	Create thin-walled microfacet refraction BSDF. More...

AI_DEVICE AtBSDF *	AiMicrofacetThinWallRefractionBSDF (const AtShaderGlobals *sg, const AtMicrofacetThinWallRefractionBSDFParams &params)

AI_API AI_DEVICE AtBSDF *	AiMicrofacetThinWallRefractionBSDF (const AtShaderGlobals sg, const AtRGB &weight, int distribution, const AtVector &N, const AtVector U, float eta, float rx, float ry, uint8_t exit_type=0, AtString label=AtString())
	Create thin-walled microfacet refraction BSDF. More...

#define	AI_MICROFACET_BECKMANN 0x00
	Beckmann distribution.

#define	AI_MICROFACET_GGX 0x01
	GGX distribution.

Thin-film modifier
AI_API AI_DEVICE void	AiMicrofacetSetThinFilm (AtBSDF *bsdf, float weight, float thickness, float ior)
	Set the thickness and refractive index of a thin film layered on top of a microfacet surface. More...

Hair BSDFs
AI_API AI_DEVICE AtBSDF *	AidEonBSDF (const AtShaderGlobals *sg, const AtRGB &absorption, const AtRGB weights[3], const AtVector &tangent, const float roughness_longitudinal, const float roughness_azimuthal, const float eta, const float tilt, const AtString label=AtString())
	Create d'Eon BSDF for hair. More...

AI_API AI_DEVICE AtBSDF *	AiZinkeBSDF (const AtShaderGlobals *sg, const AtRGB &weight, const AtVector &tangent, const AtString label=AtString())
	Create Zinke BSDF for hair with Lambertian reflectance properties. More...

Sheen/Fuzz BRDFs
AI_API AI_DEVICE AtBSDF *	AiSheenBSDF (const AtShaderGlobals *sg, const AtRGB &weight, const AtVector &N, const float r, const AtString label=AtString())
	Create Sheen BSDF for cloth-like materials. More...

AI_API AI_DEVICE AtBSDF *	AiFuzzBSDF (const AtShaderGlobals *sg, const AtRGB &weight, const AtVector &N, const float r, const AtString label=AtString())
	Create Fuzz BSDF for dusty/fuzzy/textile materials. More...

BSDF integration
AI_API void	AiBSDFIntegrate (AtShaderGlobals sg, AtRGB direct, AtRGB indirect, AtBSDF bsdf)
	Returns the direct and indirect radiance reflected by the provided BSDF. More...

AI_API AI_DEVICE AtRGB	AiBSDFAlbedo (const AtShaderGlobals sg, AtBSDF bsdf)
	Returns BSDF albedo for incident direction sg->Rd, i.e. More...

Detailed Description

Various BSDF functions available to shader writers.

Macro Definition Documentation

◆ AI_BSDF_EXPORT_METHODS

#define AI_BSDF_EXPORT_METHODS ( tag )

Value:

bsdf_init;                               \
bsdf_eval;                               \
bsdf_sample;                             \
static AtBSDFMethods ai_bsdf_methods = { \
   0,                                    \
   Init,                                 \
   Eval,                                 \
   Sample,                               \
   NULL,                                 \
   NULL,                                 \
   NULL,                                 \
};                                       \
AtBSDFMethods* tag = &ai_bsdf_methods;

BSDF methods exporter.

◆ bsdf_init

#define bsdf_init

Value:

static void Init(const AtShaderGlobals* sg, \

AtBSDF* bsdf)

AtShaderGlobals

Shader globals data structure.

Definition: ai_shaderglobals.h:45

Initialize BSDF when before it is used for the first time.

This method must set the BSDF lobes with AiBSDFInitLobes(), and may optionally call AiBSDFInitBounds(). Other typical initializations performed in this method would be ensuring the parameters are withing a valid range, store local geometry data for later evaluation and sampling (geometric normal, outgoing view direction, ..), and precomputing data.

◆ bsdf_eval

#define bsdf_eval

Value:

static AtBSDFLobeMask Eval(const AtBSDF* bsdf,             \
                           const AtVector& wi,             \
                           const AtBSDFLobeMask lobe_mask, \
                           const bool need_pdf,            \
                           AtBSDFLobeSample out_lobes[])

Evaluate BSDF for the given incoming light direction.

If the BSDF consists of multiple lobes, lobe_mask describes which lobes must be evaluated. The result of this evaluation for each lobe is:

RGB weight, defined as BSDF * cos(N.wi) / pdf. The cosine between the surface normal and the incoming light direction must be included, and the weight must be divided by the probability density. For a BSDF that does perfect importance sampling, this weight would be 1.
pdf, the probability density for sampling the the incoming light direction with bsdf_sample.

◆ bsdf_sample

#define bsdf_sample

Value:

static AtBSDFLobeMask Sample(const AtBSDF* bsdf,             \
                             const AtVector rnd,             \
                             const float wavelength,         \
                             const AtBSDFLobeMask lobe_mask, \
                             const bool need_pdf,            \
                             AtVectorDv& out_wi,             \
                             int& out_lobe_index,            \
                             AtBSDFLobeSample out_lobes[])

Sample BSDF for an incoming light direction, and evaluate BSDF.

This function returns:

Sampled incoming light direction wi.
Index of the lobe that was sampled.
RGB weight and pdf, matching bsdf_eval for the same incoming light direction.

◆ bsdf_albedo

#define bsdf_albedo

Value:

static AtRGB Albedo(const AtBSDF* bsdf, const AtShaderGlobals* sg, const AtBSDFLobeMask lobe_mask); \
AI_OPTIONAL_METHOD_INSTALL(ai_bsdf_methods, Albedo)                                                 \
static AtRGB Albedo(const AtBSDF* bsdf, const AtShaderGlobals* sg, const AtBSDFLobeMask lobe_mask)

Compute BSDF albedo for AOVs and importance sampling (optional method)

◆ bsdf_merge

#define bsdf_merge

Value:

static bool Merge(AtBSDF* bsdf, const AtBSDF* other_bsdf); \
AI_OPTIONAL_METHOD_INSTALL(ai_bsdf_methods, Merge)         \
static bool Merge(AtBSDF* bsdf, const AtBSDF* other_bsdf)

Merge BSDF with another BSDF of the same type (optional method)

Before initialization, evaluation and sampling, BSDFs of the same type can be merged if their parameters are equal or close enough that they can be mixed. This can improve rendering performance when mixing shaders.

If this method returns true to indicate the BSDFs can be merged, the weight of the other BSDF is added to this BSDF, and the other BSDF is discarded.

◆ bsdf_interior

#define bsdf_interior

Value:

static AtClosureList Interior(const AtShaderGlobals* sg, AtBSDF* bsdf); \
AI_OPTIONAL_METHOD_INSTALL(ai_bsdf_methods, Interior)                   \
static AtClosureList Interior(const AtShaderGlobals* sg, AtBSDF* bsdf)

Return volume closures describing the interior of the object.

These closures control the volume interior shading after refraction rays enter the object, typically for absorption inside glass.

Enumeration Type Documentation

◆ AtBSDFLobeFlags

enum AtBSDFLobeFlags

BSDF Lobe flags.

Enumerator
AI_BSDF_LOBE_SINGULAR	Sampling the BSDF always returns the same direction.
AI_BSDF_LOBE_WAVELENGTH_SAMPLE	Sampling the BSDF lobe requires a wavelength
AI_BSDF_LOBE_EXIT_BACKGROUND	If ray depth exceeded, use background color
AI_BSDF_LOBE_EXIT_WHITE	If ray depth exceeded, use white color

◆ AtOrenNayarModel

enum AtOrenNayarModel : unsigned char

Oren-Nayar model selection enum.

Enumerator

QUALITATIVE

classic "qualitative" Oren-Nayar model (QON)

ENERGY_PRESERVING

energy preserving Oren-Nayar model (EON).

See "EON: A practical energy-preserving rough diffuse BRDF", Portsmouth et al., 2024

◆ AtMetalFresnelMode

enum AtMetalFresnelMode

Metal Fresnel mode selection enum.

Enumerator
GULBRANDSEN	based on "Artist Friendly Metallic Fresnel", Gulbrandsen, JCGT (2014)
F82_TINT	based on the F82-tint model, from "Novel aspects of the Adobe Standard Material", Kutz et al. (2021)

Function Documentation

◆ AiBSDF()

AI_API AtBSDF * AiBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtBSDFMethods *	methods,
		size_t	data_size
	)

Allocate a BSDF and data memory to store parameters.

Parameters

sg	Shading globals
methods	BSDF methods created with `AI_BSDF_EXPORT_METHODS`
data_size	size of BSDF data to allocate, retrieved through `AiBSDFGetData()`

Returns: new BSDF

◆ AiBSDFGetMethods()

AI_API const AtBSDFMethods * AiBSDFGetMethods ( const AtBSDF * bsdf )

Get BSDF methods.

Parameters

bsdf BSDF

Returns: BSDF methods

◆ AiBSDFGetData()

AI_API AI_DEVICE void * AiBSDFGetData ( const AtBSDF * bsdf )

Get BSDF data memory to store BSDF parameters.

Parameters

bsdf BSDF

Returns: BSDF data memory

◆ AiBSDFGetLobes()

AI_API const AtBSDFLobeInfo * AiBSDFGetLobes ( const AtBSDF * bsdf )

Get BSDF lobes, available after the BSDF has been initialized.

Parameters

bsdf BSDF

Returns: BSDF lobes

◆ AiBSDFGetNumLobes()

AI_API int AiBSDFGetNumLobes ( const AtBSDF * bsdf )

Get the number of BSDF lobes, available after the BSDF has been initialized.

Parameters

bsdf BSDF

Returns: Number of BSDF lobes

◆ AiBSDFGetWeight()

AI_API AI_DEVICE AtRGB AiBSDFGetWeight ( const AtBSDF * bsdf )

Get the BSDF weight.

Parameters

bsdf BSDF

Returns: BSDF weight

◆ AiBSDFSetDirectIndirect()

AI_API AI_DEVICE void AiBSDFSetDirectIndirect	(	AtBSDF *	bsdf,
		float	weight_direct,
		float	weight_indirect
	)

Set the BSDF direct and indirect light contribution weights.

For physically correct rendering, these must be set to the default 1.0, however for artistic control the direct and indirect light contributions can be scaled independently.

Parameters

bsdf	BSDF
weight_direct	Direct light weight
weight_indirect	Indirect light weight

◆ AiBSDFGetDirectIndirect()

AI_API AI_DEVICE void AiBSDFGetDirectIndirect	(	const AtBSDF *	bsdf,
		float &	weight_direct,
		float &	weight_indirect
	)

Get the BSDF direct and indirect light contribution weights.

For physically correct rendering, these must be set to the default 1.0, however for artistic control the direct and indirect light contributions can be scaled independently.

Parameters

bsdf	BSDF
weight_direct	Direct light weight
weight_indirect	Indirect light weight

◆ AiBSDFInitLobes()

AI_API AI_DEVICE void AiBSDFInitLobes	(	AtBSDF *	bsdf,
		const AtBSDFLobeInfo *	lobes,
		int	num_lobes
	)

Initialize BSDF lobes.

This function must be called from within the bsdf_init method.

Parameters

bsdf	BSDF
lobes	Information about each BSDF lobe
num_lobes	Number of lobes in the BSDFs

◆ AiBSDFInitNormal()

AI_API AI_DEVICE void AiBSDFInitNormal	(	AtBSDF *	bsdf,
		const AtVector &	N,
		bool	bounding
	)

Initialize BSDF normal.

This normal is used for the builtin N AOV.

If the BSDF only reflects or transmits light within a hemisphere, the normal can also be used to more quickly cull light sources outside the hemisphere around the normal. If the BSDF both reflects and transmits light, no bounds should be set.

This function must be called from within the bsdf_init method.

Parameters

bsdf	BSDF
N	normal
bounding	true if the normal defines a bounding hemisphere

◆ AiBSDFBumpShadow()

AI_API AI_DEVICE float AiBSDFBumpShadow	(	const AtVector &	Ns,
		const AtVector &	N,
		const AtVector &	Ld
	)

Compute BSDF shadow factor to solve shading artifacts with bump mapping.

When a bump map normal is very different from the actual normal, jagged edges can appear. This function returns a factor to add extra shadowing to hide those artifacts.

Parameters

Ns	Smooth normal without bump, facing the viewer, computed as (`sg->Ng` == `sg->Ngf`) ? `sg->Ns` : -`sg->N`;
N	Bump mapped normal, facing the viewer (typically `sg->Nf`)
Ld	Direction vector towards the lights

Returns: Shadow factor to be multipled into AtBSDFLobeSample.weight

◆ AiBSDFMinRoughness()

AI_API AI_DEVICE float AiBSDFMinRoughness ( const AtShaderGlobals * sg )

Estimate a minimum roughness for specular BSDFs, to reduce noise from caustics.

Unidirectional path tracing can't resolve caustics efficiently. To reduce noise the roughness of specular BSDFs behind diffuse and glossy bounces can be artificially increased.

This function can be used in the bsdf_init method, to clamp roughness to be at least the suggested minimum roughness value.

Parameters

sg	shader globals context

Returns: minimum roughness value

◆ AiOrenNayarBSDF_private()

AI_API AI_DEVICE AtBSDF * AiOrenNayarBSDF_private	(	const AtShaderGlobals *	sg,
		const AtOrenNayarBSDFParams &	params
	)

Create Oren-Nayar BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

Parameters

sg	shader globals context
params	AtOrenNayarBSDFParams struct

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

See also: AiOrenNayarBSDF

◆ AiOrenNayarBSDF()

AI_API AI_DEVICE AtBSDF * AiOrenNayarBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtVector &	N,
		AtOrenNayarModel	model,
		float	r,
		bool	transmission,
		const AtString	label
	)

Create Oren-Nayar BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

Parameters

sg	shader globals context
N	normal vector that defines the hemisphere of incoming radiance
model	select Oren-Nayar model variant
r	surface roughness, normalized in the [0, 1] range
transmission	use diffuse transmission instead of reflection

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

See also: AiOrenNayarBSDF

◆ AiMicrofacetBSDF_private()

AI_API AI_DEVICE AtBSDF * AiMicrofacetBSDF_private	(	const AtShaderGlobals *	sg,
		const AtMicrofacetBSDFParams &	params
	)

Create microfacet reflection BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
params	AtMicrofacetBSDFParams struct

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetBSDF()

AI_API AI_DEVICE AtBSDF * AiMicrofacetBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		int	distribution,
		const AtVector &	N,
		const AtVector *	U,
		float	ior,
		float	rx,
		float	ry,
		uint8_t	exit_type,
		int32_t	dielectric_priority,
		float	thin_walled_transmission,
		const AtString	label
	)

Create microfacet reflection BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
distribution	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`
N	normal vector that defines the hemisphere of incoming radiance
U	surface tangent vector along the U coordinate
ior	refractive index for Fresnel, use 0 to disable Fresnel
rx	specular roughness along the U direction
ry	specular roughness along the V direction
exit_type	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`
dielectric_priority	user-specified signed-integer dielectric priority, for nested dielectrics
thin_walled_transmission	fraction of the BRDF which represents a thin-walled dielectric (to be used in conjunction with AiMicrofacetThinWallRefractionBSDF)

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetRefractionBSDF_private()

AI_API AI_DEVICE AtBSDF * AiMicrofacetRefractionBSDF_private	(	const AtShaderGlobals *	sg,
		const AtMicrofacetRefractionBSDFParams &	params
	)

Create microfacet refraction BSDF.

This BSDF currently only support indirect light, any direct light will be ignored.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
params	AtMicrofacetRefractionBSDFParams struct

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetRefractionBSDF()

AI_API AI_DEVICE AtBSDF * AiMicrofacetRefractionBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		int	distribution,
		const AtVector &	N,
		const AtVector *	U,
		float	ior,
		float	rx,
		float	ry,
		float	dispersion,
		bool	use_fresnel,
		AtClosureList	interior_volume,
		uint8_t	exit_type,
		int32_t	dielectric_priority,
		const AtString	label
	)

Create microfacet refraction BSDF.

This BSDF currently only support indirect light, any direct light will be ignored.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
distribution	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`
N	normal vector that defines the hemisphere of incoming radiance
U	surface tangent vector along the U coordinate
ior	refractive index
rx	specular roughness along the U direction
ry	specular roughness along the V direction
dispersion	Cauchy coefficient for dispersion. Zero for no dispersion, higher values give more dispersion
use_fresnel	set to true to include Fresnel term
interior_volume	volumetric closure giving the (optional) embedded scattering/absorbing medium of the dielectric
exit_type	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`
dielectric_priority	user-specified signed-integer dielectric priority, for nested dielectrics

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetThinWallRefractionBSDF_private()

AI_API AI_DEVICE AtBSDF * AiMicrofacetThinWallRefractionBSDF_private	(	const AtShaderGlobals *	sg,
		const AtMicrofacetThinWallRefractionBSDFParams &	params
	)

Create thin-walled microfacet refraction BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

Parameters

sg	shader globals context
params	AtMicrofacetThinWallRefractionBSDFParams struct

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetThinWallRefractionBSDF()

AI_API AI_DEVICE AtBSDF * AiMicrofacetThinWallRefractionBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		int	distribution,
		const AtVector &	N,
		const AtVector *	U,
		float	ior,
		float	rx,
		float	ry,
		uint8_t	exit_type,
		AtString	label
	)

Create thin-walled microfacet refraction BSDF.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

Parameters

sg	shader globals context
distribution	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`
N	normal vector that defines the hemisphere of incoming radiance
U	surface tangent vector along the U coordinate
ior	refractive index of the interior medium
rx	specular roughness along the U direction
ry	specular roughness along the V direction
exit_type	zero, `AI_BSDF_LOBE_EXIT_BACKGROUND` or `AI_BSDF_LOBE_EXIT_WHITE`

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMicrofacetSetThinFilm()

AI_API AI_DEVICE void AiMicrofacetSetThinFilm	(	AtBSDF *	bsdf,
		float	weight,
		float	thickness_nm,
		float	ior
	)

Set the thickness and refractive index of a thin film layered on top of a microfacet surface.

This replaces the classic Fresnel term with a new Airy reflectance term, which is applied per microfacet.

See also: https://belcour.github.io/blog/research/2017/05/01/brdf-thin-film.html

Parameters

bsdf	BSDF
thickness	Thickness of thin film in nanometers, typically in the 0 to 2000nm range
ior	Refractive index of thin film

◆ AiMetalBSDF_private()

AI_API AI_DEVICE AtBSDF * AiMetalBSDF_private	(	const AtShaderGlobals *	sg,
		const AtMetalBSDFParams &	params
	)

Create microfacet BSDF with conductive Fresnel, for metals.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
params	AtMetalBSDFParams struct

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiMetalBSDF()

AI_API AI_DEVICE AtBSDF * AiMetalBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		int	distribution,
		const AtVector &	N,
		const AtVector *	U,
		AtMetalFresnelMode	fresnel_mode,
		const AtRGB &	fresnel1,
		const AtRGB &	fresnel2,
		float	specular_weight,
		float	rx,
		float	ry,
		const AtString	label
	)

Create microfacet BSDF with conductive Fresnel, for metals.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Microfacet Models for Refraction through Rough Surfaces", Walter et. al, Eurographics 2007

Parameters

sg	shader globals context
distribution	`AI_MICROFACET_BECKMANN` or `AI_MICROFACET_GGX`
N	normal vector that defines the hemisphere of incoming radiance
U	surface tangent vector along the U coordinate
fresnel_mode	specify which Fresnel model to use for the metal (GULBRANDSEN or F82_TINT)
fresnel1	either real part of the complex refractive index for Fresnel (GULBRANDSEN), or F0 reflectance at normal incidence (F82_TINT)
fresnel2	either imaginary part of the complex refractive index for Fresnel (GULBRANDSEN), or tint applied at near-grazing (approx. 82 degrees) incidence (F82_TINT)
specular_weight	scale factor applied (with a clamp) to the Fresnel factor, in the F82_TINT mode only
rx	specular roughness along the U direction
ry	specular roughness along the V direction

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AidEonBSDF()

AI_API AI_DEVICE AtBSDF * AidEonBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	absorption,
		const AtRGB	weights[3],
		const AtVector &	tangent,
		const float	roughness_longitudinal,
		const float	roughness_azimuthal,
		const float	eta,
		const float	tilt,
		const AtString	label
	)

Create d'Eon BSDF for hair.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

Note: Absorption value is referenced in the linear sRGB color space, as per the paper. (overridden when options.enable_deprecated_hair_absorption = true)

See also: "An Energy-Conserving Hair Reflectance Model" by Eugene d'Eon et al.

Parameters

sg	shader globals context
absorption	absorption inside hair (in linear sRGB color space)
weights	weights for R, TT, and TRT paths
tangent	hair tangent vector, pointing from root to tip
roughness_longitudinal	specular roughness for longitudinal scattering
roughness_azimuthal	specular roughness for azimuthal scattering
eta	refractive index of hair fiber
tilt	scale tilt angle in radians [-pi/2, pi/2]

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiZinkeBSDF()

AI_API AI_DEVICE AtBSDF * AiZinkeBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtVector &	tangent,
		const AtString	label
	)

Create Zinke BSDF for hair with Lambertian reflectance properties.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: http://cg.cs.uni-bonn.de/project-pages/hairmodeling/documents/BFSDF_preprint_with_copyright_notice.pdf

Parameters

sg	shader globals context
tangent	hair tangent vector, pointing from root to tip

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiSheenBSDF()

AI_API AI_DEVICE AtBSDF * AiSheenBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtVector &	N,
		const float	r,
		const AtString	label
	)

Create Sheen BSDF for cloth-like materials.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: http://blog.selfshadow.com/publications/s2017-shading-course/imageworks/s2017_pbs_imageworks_sheen.pdf

Parameters

	sg	shader globals context
	N	normal vector that defines the hemisphere of incoming radiance
	r	surface roughness, normalized in the [0, 1] range
[out]	albedo	albedo in the [0, 1] range, which can be used to layer sheen onto other closures

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiFuzzBSDF()

AI_API AI_DEVICE AtBSDF * AiFuzzBSDF	(	const AtShaderGlobals *	sg,
		const AtRGB &	weight,
		const AtVector &	N,
		const float	r,
		const AtString	label
	)

Create Fuzz BSDF for dusty/fuzzy/textile materials.

The material becomes more "textile/fiber"-like at low roughness.

The returned data is allocated in a pixel pool and does not need to be freed by the caller.

See also: "Practical Multiple-Scattering Sheen Using Linearly Transformed Cosines", Zeltner et al., SIGGRAPH 2022

Parameters

	sg	shader globals context
	N	normal vector that defines the hemisphere of incoming radiance
	r	surface roughness, normalized in the [0, 1] range
[out]	albedo	albedo in the [0, 1] range, which can be used to layer fuzz onto other closures

Returns: pointer to the AtBSDF required by AiBSDFIntegrate()

◆ AiBSDFIntegrate()

AI_API void AiBSDFIntegrate	(	AtShaderGlobals *	sg,
		AtRGB *	direct,
		AtRGB *	indirect,
		AtBSDF *	bsdf
	)

Returns the direct and indirect radiance reflected by the provided BSDF.

Applies the importance sampling Monte Carlo integration technique and multiple importance sampling (MIS) to compute light coming from all objects and light sources in the scene.

The eval_pdf and eval_sample parameters are a matching pair of functions that describe a sample probability density and its corresponding quantile function, respectively. Any pair of PDF and quantile functions that sample the entire non-zero region of the BSDF should in theory converge upon the same result given enough samples, however sample distributions that are specifically tuned to the provided BSDF should have a much faster rate of convergence.

It is possible to compute only the direct or indirect radiance, however if both are needed it is faster to compute them at the same time.

Note: Deprecated, use shader closures instead of integrating light in shaders.

Parameters

sg	Shading globals
bsdf	BSDF
direct	returned direct radiance, coming from lights sources
indirect	returned indirect radiance, coming from other objects

◆ AiBSDFAlbedo()

AI_API AI_DEVICE AtRGB AiBSDFAlbedo	(	const AtShaderGlobals *	sg,
		AtBSDF *	bsdf
	)

Returns BSDF albedo for incident direction sg->Rd, i.e.

the fraction of light not absorbed by it. This can for example be used for weighting a diffuse BSDF below a specular one.

Parameters

sg	shader globals context
bsdf	pointer to the AtBSDF

Returns: directional albedo

Variable Documentation

◆ fresnel2

AtRGB AtMetalBSDFParams::fresnel2 = AI_RGB_WHITE

either imaginary part of the complex refractive index for Fresnel (GULBRANDSEN), or tint applied at near-grazing (approx.

82 degrees) incidence (F82_TINT)

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Diffuse BRDF

Metal BRDF

Functions for implementing custom BSDFs

Microfacet BSDFs

Thin-film modifier

Hair BSDFs

Sheen/Fuzz BRDFs

BSDF integration

Detailed Description

Macro Definition Documentation

◆ AI_BSDF_EXPORT_METHODS

◆ bsdf_init

◆ bsdf_eval

◆ bsdf_sample

◆ bsdf_albedo

◆ bsdf_merge

◆ bsdf_interior

Enumeration Type Documentation

◆ AtBSDFLobeFlags

◆ AtOrenNayarModel

◆ AtMetalFresnelMode

Function Documentation

◆ AiBSDF()

◆ AiBSDFGetMethods()

◆ AiBSDFGetData()

◆ AiBSDFGetLobes()

◆ AiBSDFGetNumLobes()

◆ AiBSDFGetWeight()

◆ AiBSDFSetDirectIndirect()

◆ AiBSDFGetDirectIndirect()

◆ AiBSDFInitLobes()

◆ AiBSDFInitNormal()

◆ AiBSDFBumpShadow()

◆ AiBSDFMinRoughness()

◆ AiOrenNayarBSDF_private()

◆ AiOrenNayarBSDF()

◆ AiMicrofacetBSDF_private()

◆ AiMicrofacetBSDF()

◆ AiMicrofacetRefractionBSDF_private()

◆ AiMicrofacetRefractionBSDF()

◆ AiMicrofacetThinWallRefractionBSDF_private()

◆ AiMicrofacetThinWallRefractionBSDF()

◆ AiMicrofacetSetThinFilm()

◆ AiMetalBSDF_private()

◆ AiMetalBSDF()

◆ AidEonBSDF()

◆ AiZinkeBSDF()

◆ AiSheenBSDF()

◆ AiFuzzBSDF()

◆ AiBSDFIntegrate()

◆ AiBSDFAlbedo()

Variable Documentation

◆ fresnel2