Provides access to various functionality related to MDL distilling. More...

#include <imdl_distiller_api.h>

Inheritance diagram for mi::neuraylib::IMdl_distiller_api:

Public Member Functions
virtual Size	get_target_count () const =0
	Returns the number of targets supported for distilling. More...

virtual const char *	get_target_name (Size index) const =0
	Returns the `index` -th target name supported for distilling, or `nullptr` if `index` is out of bounds. More...

virtual ICompiled_material *	distill_material (const ICompiled_material material, const char target, const IMap distiller_options=nullptr, Sint32 errors=nullptr) const =0
	Distills a material. More...

virtual const IBaker *	create_baker (const ICompiled_material material, const char path, Baker_resource resource=BAKE_ON_CPU, Uint32 gpu_device_id=0) const =0
	Creates a baker for texture baking. More...

virtual Size	get_required_module_count (const char *target) const =0
	Returns the number of required MDL modules for the given target. More...

virtual const char *	get_required_module_name (const char *target, Size index) const =0
	Returns the MDL name of the required MDL module with the given index for the given target. More...

virtual const char *	get_required_module_code (const char *target, Size index) const =0
	Returns the MDL source code of the required MDL module with the given index for the given target. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x074709ef, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x074709ef, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

Provides access to various functionality related to MDL distilling.

Member Function Documentation

^◆ create_baker()

virtual const IBaker * mi::neuraylib::IMdl_distiller_api::create_baker	(	const ICompiled_material *	material,
		const char *	path,
		Baker_resource	resource = `BAKE_ON_CPU`,
		Uint32	gpu_device_id = `0`
	)		const

pure virtual

Creates a baker for texture baking.

Parameters

material	The material of which a subexpression is to be baked.
path	The path from the material root to the expression that should be baked, e.g., `"surface.scattering.tint"`. The supported expression types are mi::neuraylib::IType::TK_FLOAT, mi::neuraylib::IType::TK_COLOR, mi::neuraylib::IType::TK_BOOL, and mi::neuraylib::IType::TK_VECTOR with up to four components of type mi::neuraylib::IType::TK_FLOAT.
resource	The resource to be used for baking.
gpu_device_id	The device ID of the GPU to be used for baking (as identified by the CUDA runtime or driver API). Ignored if `resource` is BAKE_ON_CPU.

Returns: A baker for the expression of the given material identified by path, or nullptr in case of failure. Note that the returned baker depends on the transaction that was used to access the material.

^◆ distill_material()

virtual ICompiled_material * mi::neuraylib::IMdl_distiller_api::distill_material	(	const ICompiled_material *	material,
		const char *	target,
		const IMap *	distiller_options = `nullptr`,
		Sint32 *	errors = `nullptr`
	)		const

pure virtual

Distills a material.

Material distilling refers to the translation of an arbitrary input material to a predefined target model. Supported target models are

diffuse
specular_glossy
ue4
transmissive_pbr

Depending on the structure of the input material and the complexity of the target model the resulting material can be as simple as a single bsdf or a set of bsdfs combined using layerers and mixes as illustrated in the table below using a pseudo-mdl notation.

diffuse	surface.scattering = diffuse_reflection_bsdf geometry.normal = ()
specular_glossy	surface.scattering = custom_curve_layer(layer: bsdf_glossy_ggx_vcavities, base: diffuse_reflection_bsdf) geometry.normal = ()
	surface.scattering = bsdf_glossy_ggx_vcavities geometry.normal = ()
	surface.scattering = diffuse_reflection_bsdf geometry.normal = ()
ue4	surface.scattering = custom_curve_layer( // clearcoat layer: bsdf_glossy_ggx_vcavities, base: weighted_layer( layer: normalized_mix( bsdf_glossy_ggx_vcavities, custom_curve_layer( layer: bsdf_glossy_ggx_vcavities, base: diffuse_reflection_bsdf ), ), normal: () // under-clearcoat normal ), normal: () // clearcoat normal )
ue4	A weighted_layer of any subset of the above construct with an optional clearcoat on top.
transmissive_pbr	surface.scattering = custom_curve_layer( // clearcoat layer: bsdf_glossy_ggx_vcavities, base: weighted_layer( layer: normalized_mix( bsdf_glossy_ggx_vcavities, custom_curve_layer( layer: bsdf_glossy_ggx_vcavities, base: normalized_mix( bsdf_glossy_ggx_vcavities(scatter_transmit) diffuse_reflection_bsdf ), ), ), normal: () // under-clearcoat normal ), normal: () // clearcoat normal )
transmissive_pbr	A weighted_layer of any subset of the above construct with an optional clearcoat on top.

Parameters

material	The material to be distilled.
target	The target model. See get_target_count() and get_target_name().
distiller_options	Options for the distiller. Supported options are: `"top_layer_weight"` of type mi::IFloat32. This weight is given to the top layer if a Fresnel layered BSDF is simplified to a single diffuse BSDF in the 'diffuse' distilling target. The base layer uses one minus this weight. Default: 0.04. `"layer_normal"` of type mi::IBoolean. If `true`, it enables the aggregation of the local normal maps of BSDF layerers to combine them with the global normal map. Default: `true`.
errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`nullptr`). -2: Invalid target model. -3: Unspecified failure.

Returns: The distilled material, or nullptr in case of failure.

^◆ get_required_module_code()

virtual const char * mi::neuraylib::IMdl_distiller_api::get_required_module_code	(	const char *	target,
		Size	index
	)		const

pure virtual

Returns the MDL source code of the required MDL module with the given index for the given target.

See also: get_required_module_count()

Parameters

target	The target material model to distill to.
index	The index of the required module for the given target.

Returns: The MDL source code of the required module.

^◆ get_required_module_count()

virtual Size mi::neuraylib::IMdl_distiller_api::get_required_module_count ( const char * target ) const

pure virtual

Returns the number of required MDL modules for the given target.

If a target reports any required modules, the integrating application must query the name and MDL code for each of them using get_required_module_name() and get_required_module_code() and load them using mi::neuraylib::IMdl_impexp_api::load_module_from_string() before distilling any material to that target, otherwise distilling will fail.

Parameters

target The target material model to distill to.

Returns: The number of required MDL modules for that target.

^◆ get_required_module_name()

virtual const char * mi::neuraylib::IMdl_distiller_api::get_required_module_name	(	const char *	target,
		Size	index
	)		const

pure virtual

Returns the MDL name of the required MDL module with the given index for the given target.

See also: get_required_module_count()

Parameters

target	The target material model to distill to.
index	The index of the required module for the given target.

Returns: The MDL name of the required module.

^◆ get_target_count()

virtual Size mi::neuraylib::IMdl_distiller_api::get_target_count ( ) const

pure virtual

Returns the number of targets supported for distilling.

^◆ get_target_name()

virtual const char * mi::neuraylib::IMdl_distiller_api::get_target_name ( Size index ) const

pure virtual

Returns the index -th target name supported for distilling, or nullptr if index is out of bounds.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ create_baker()

◆ distill_material()

◆ get_required_module_code()

◆ get_required_module_count()

◆ get_required_module_name()

◆ get_target_count()

◆ get_target_name()

^◆ create_baker()

^◆ distill_material()

^◆ get_required_module_code()

^◆ get_required_module_count()

^◆ get_required_module_name()

^◆ get_target_count()

^◆ get_target_name()