MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::IMdl_distiller_api Class Referenceabstract

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 NULL if index is out of bounds. More...
 
virtual ICompiled_materialdistill_material (const ICompiled_material *material, const char *target, const IMap *distiller_options=0, Sint32 *errors=0) const =0
 Distills a material. More...
 
virtual const IBakercreate_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 IInterfaceget_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 IInterfaceget_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, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> IID
 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
materialThe material of which a subexpression is to be baked.
pathThe path from the material root to the expression that should be baked, e.g., "surface.scattering.tint".
resourceThe resource to be used for baking.
gpu_device_idThe 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 NULL in case of failure. Note that 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 = 0,
Sint32 errors = 0 
) 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
)
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
)
A weighted_layer of any subset of the above construct with an optional clearcoat on top.
Parameters
materialThe material to be distilled.
targetThe target model. See get_target_count() and get_target_name().
distiller_optionsOptions 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.
errorsAn 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 (NULL pointer).
  • -2: Invalid target model.
  • -3: Unspecified failure.
Returns
The distilled material, or NULL 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
targetThe target material model to distill to.
indexThe 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
targetThe 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
targetThe target material model to distill to.
indexThe 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 NULL if index is out of bounds.