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 material with a predefined structure, called a target model. The SDK ships with a number of distilling targets as well as the sources to the distiller plugin implementing those targets. The general mechanism by which a distiller plugin simplifies a material is by traversing the call graph of the material's BSDF, analysing the current expression and, potentially, replacing that expression with a different, simpler one. The result is a material with a transformed BSDF graph, typically matching some target material model in structure. The user can now inspect the BSDF parameters and either create compiled code for those expressions or bake the expressions to textures.

Users can implement custom targets by modifying existing replacement rules or writing their own rules.

See also: MDLTL - MDL Transformation Language

The distiller plugin shipped by default supports the following target models:

diffuse: A target model with a singular diffuse BSDF. Useful for extremely simple viewport previews or as a starting point for writing custom targets.
specular_glossy: Target model consisting of a diffuse reflection lobe combined with a glossy lobe layered on top using a custom_curve_layer.
ue4: A generig metallic-roughness material model. Originally developed for supporting UE4 materials, it is a good starting point for all metallic roughness based rasterizer materials. If the source material is transmissive, the distiller maps the transparency to material.geometry.cutout_opacity. This target also supports a secondary dielectric glossy lobe (coat). The MDL BSDF graph has more parameters than the simple metallic roughness material model. The distiller in general tries to retain attachments for those parameters. This can be used to extract values and expressions for more capable models. For example the secondary dielectric glossy lobe is not restricted to white and also anisotropy of glossy lobes is retained. Since metallic roughness workflows support only a single base color, the color of the diffuse lobe and the metallic glossy lobe is averaged into a single color. material.geometry.normal is combined with potential additional layering normals and represented as a dedicated weighted layer with weight 1.
transmissive_pbr: Largely the same as ue4, this target supports a dedicated transmissive lobe. If the source has a diffuse transmission, it will map to a glossy transmission of roughness 1, potentially allowing the reconstruction of diffuse transmissive or SSS contributions.

The following table contains the lists the target BSDF graphs using a pseudo-MDL notation. Note that the distiller is not guaranteed to create lobes not already contained in the source material.

Target model name	Paths available in the target material and their structure
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( // dielectric (coat) weighting parameters layer: bsdf_glossy_ggx_vcavities, // dielectric glossy lobe base: weighted_layer( // add coat normal layer: normalized_mix( // metalness parameter bsdf_glossy_ggx_vcavities // metallic glossy lobe custom_curve_layer( // dielectric weighting parameters layer: bsdf_glossy_ggx_vcavities, // dielectric glossy lobe 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( // dielectric (coat) weighting parameters layer: bsdf_glossy_ggx_vcavities // dielectric glossy lobe base: weighted_layer( // add coat normal layer: normalized_mix( // metalness parameter bsdf_glossy_ggx_vcavities, // metallic glossy lobe custom_curve_layer( // dielectric weighting parameters layer: bsdf_glossy_ggx_vcavities, // dielectric glossy reflection lobe base: normalized_mix( // transparency parameter bsdf_glossy_ggx_vcavities(scatter_transmit) // dielectric glossy transmission lobe 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()