mental ray Interface: mi::shader::Bsdf Class Reference

The Bsdf interface represents the concept of a Bidirectional Scattering Distribution Function. The BSDF describes the scattering characteristics of a point, i.e. reflection (the BRDF), and transmission (the BTDF).

This interface allows shaders to interact with BSDFs. It is intended to serve the same purpose as the RC Direction Functions and Shading Models functions (see the manual), but in a generalized way.

    Access_bsdf bsdf(state);
    
    // do light loop
    for (...) {
        direct += light * bsdf->eval(view_dir,light_dir);
    }

If diffuse and specular contributions are needed separately, the BSDF evaluation can be restricted by passing e.g. Bsdf::Reflect_diffuse or Bsdf::All_glossy as the third parameter of the eval function. Note, however, that multiple separate evaluations of components are more expensive than a single evaluation of all components.

Note that specular components cannot be evaluated, they have to be sampled. Thus, reflections of light sources in perfect mirrors can be achieved by code similar to

    double xi[3];
    mi_sample(xi,0,state,3,0);
    if (bsdf->sample(view_dir,&refl_dir,&mirror,xi,Bsdf::Reflect_specular) 
        && mi_trace_reflection(&hit,state,&refl_dir)
        && !state->child->pri) {        // light source hit
        light_hit = mirror * hit;
    }

Member Enumeration Documentation

enum mi::shader::Bsdf::Type

scatter type.

Type flags are bit patterns. Typical binary operations are valid e.g. for component combinations or sample result inspection.

Enumeration values:

Invalid	unknown or absorption
Reflect_diffuse	diffuse reflection
Reflect_glossy	glossy reflection
Reflect_specular	specular reflection
Transmit_diffuse	diffuse transmission
Transmit_glossy	glossy transmission
Transmit_specular	specular transmission
Reflect_regular	non-specular reflection
Transmit_regular	non-specular transmission
All_diffuse	diffuse reflection and transmission
All_glossy	glossy reflection and transmission
All_specular	specular reflection and transmission
All_regular	non-specular reflection and transmission
All_reflect	diffuse, glossy, and specular reflection
All_transmit	diffuse, glossy, and specular transmission
All	all types

Member Function Documentation

virtual bool mi::shader::Bsdf::all_components ( Type type ) const [pure virtual]

Checks if the BSDF supports all of the given components.

If type is a compound type, e.g All_xxx, this function checks if all of the given components are supported. For single types, this function's result is identical to that of Bsdf::any_component.

Parameters:

type

the scatter type to check

Returns:: true if all of the given components are supported by the BSDF, false otherwise.

virtual bool mi::shader::Bsdf::any_component ( Type type ) const [pure virtual]

Checks if the BSDF supports the given component.

If type is a compound type, e.g All_xxx, this function checks if one or more of the given components are supported. For single types, this function's result is identical to that of Bsdf::all_components.

Parameters:

type

the scatter type to check

Returns:: true if any of the given components are supported by the BSDF, false otherwise.

virtual miColor mi::shader::Bsdf::eval	(	const miVector &	ray,
		const miVector &	out,
		Type	flags = `All`,
		Transport	dir = `From_eye`
	)	const `[pure virtual]`

Evaluates the BSDF at the current point.

When tracing rays from the eye towards the scene (the usual case), dir is From_eye, ray is the view direction and out is the light direction. All directions are in world space. The ray direction points towards the intersection, the out direction points away from it.

Because specular components cannot be evaluated (they can only be sampled), this function only evaluates the diffuse and glossy parts. The contribution from specular components is black. Shaders must use sample to obtain a specular direction and contribution.

Parameters:

`[in]`	ray	given direction
`[in]`	out	sampled direction
`[in]`	flags	allowed types
`[in]`	dir	trace direction

Returns:: the value of the BSDF at the current point and for the given pair of directions

virtual Type mi::shader::Bsdf::sample	(	const miVector &	ray,
		miVector *	out,
		miColor *	weight,
		double	xi[3],
		Type	flags = `All`,
		Transport	dir = `From_eye`
	)	const `[pure virtual]`

Importance samples an outgoing direction using the quasirandom numbers supplied in xi and stores it in out.

All directions are in world space. The ray direction points towards the intersection, the out direction points away from it.

The importance sampling weight (i.e. the BSDF value for the sampled direction divided by the probability of sampling the direction) will be written to weight. Note that the weight result contains the probability density in projected solid angle measure. One implication of this is that the weight does not have to be multiplied by $\cos\theta$ when tracing secondary rays.

This function returns the type of the component that was sampled. Note that, while this function may return Bsdf::Invalid in some cases, it does not perform Russian roulette for absorption. If Russian roulette is needed, $\min\{1,\|\mathtt{weight}\|\}$ , is a good candidate for the continuation probability. Usually, the maximum norm yields the best results.

Suitable values for xi can be acquired e.g. by calling mi_sample.

Parameters:

`[in]`	ray	known direction
`[out]`	out	sampled direction
`[out]`	weight	sample weight
`[in]`	xi	sample in [0,1)^3
`[in]`	flags	allowed types
`[in]`	dir	trace direction

Returns:: the sampled component type


Public Types
typedef bool	Transport
	sampling/evaluation direction
enum	Type { Invalid = 0x00, Reflect_diffuse = 0x01, Reflect_glossy = 0x02, Reflect_specular = 0x04, Transmit_diffuse = 0x10, Transmit_glossy = 0x20, Transmit_specular = 0x40, Reflect_regular, Transmit_regular, All_diffuse, All_glossy, All_specular, All_regular, All_reflect, All_transmit, All }
Public Member Functions
virtual miColor	eval (const miVector &ray, const miVector &out, Type flags=All, Transport dir=From_eye) const =0
virtual Type	sample (const miVector &ray, miVector out, miColor weight, double xi[3], Type flags=All, Transport dir=From_eye) const =0
virtual bool	all_components (Type type) const =0
virtual bool	any_component (Type type) const =0
Static Public Attributes
const Transport	From_eye = false
	rendering from the camera
const Transport	From_light = true
	from the light, e.g. photons

mi::shader::Bsdf Class Reference

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation