mdl_distiller_plugin_api.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2025 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
 
#ifndef MDL_DISTILLER_PLUGIN_API_H
#define MDL_DISTILLER_PLUGIN_API_H
 
#include <mi/mdl/mdl_streams.h>
#include <mi/mdl/mdl_generated_dag.h>
#include <mi/mdl/mdl_distiller_rules.h>
 
namespace mi {
namespace mdl {
 
class ICall_name_resolver;
 
#define MI_MDL_DISTILLER_PLUGIN_API_VERSION 6
 
class IDistiller_plugin_api
{
public:
    virtual IMaterial_instance *apply_rules(
        IMaterial_instance const *inst,
        IRule_matcher            &matcher,
        IRule_matcher_event      *event_handler,
        const Distiller_options  *options,
        mi::Sint32               &error) = 0;
 
 
    struct strcmp_string_less {
        bool operator()(char const *a, char const *b) const
        {
            return strcmp(a, b) < 0;
        }
    };
 
    virtual void dump_attributes(
        IMaterial_instance const *inst) = 0;
    virtual void dump_attributes(
        IMaterial_instance const *inst,
        DAG_node const           *node) = 0;
 
    virtual void set_attribute(
        DAG_node const *node,
        char const     *name,
        DAG_node const *value) = 0;
    virtual void set_attribute(
        IMaterial_instance const *inst,
        DAG_node const           *node,
        char const               *name,
         mi::Float32             value) = 0;
    virtual void set_attribute(
        IMaterial_instance const *inst,
        DAG_node const           *node,
        char const               *name,
        mi::Sint32               value) = 0;
 
    virtual void remove_attributes(
        DAG_node const *node) = 0;
 
    virtual DAG_node const *get_attribute(
        DAG_node const *node,
        char const     *name) = 0;
 
    virtual bool attribute_exists(
        DAG_node const *node,
        char const     *name) = 0;
 
    virtual void move_attributes(
        DAG_node const *to_node,
        DAG_node const *from_node) = 0;
 
 
 
    enum Field_selector {
        FS_NONE                                   = 0x0000, 
        //
        FS_MATERIAL_THIN_WALLED                   = 0x0001, 
        //
        FS_MATERIAL_SURFACE_SCATTERING            = 0x0002, 
        FS_MATERIAL_SURFACE_EMISSION_EMISSION     = 0x0004, 
        FS_MATERIAL_SURFACE_EMISSION_INTENSITY    = 0x0008, 
        FS_MATERIAL_SURFACE_EMISSION_MODE         = 0x0010, 
        FS_MATERIAL_SURFACE_EMISSION              = 0x001c, 
        FS_MATERIAL_SURFACE                       = 0x001e, 
        //
        FS_MATERIAL_BACKFACE_SCATTERING           = 0x0020, 
        FS_MATERIAL_BACKFACE_EMISSION_EMISSION    = 0x0040, 
        FS_MATERIAL_BACKFACE_EMISSION_INTENSITY   = 0x0080, 
        FS_MATERIAL_BACKFACE_EMISSION_MODE        = 0x0100, 
        FS_MATERIAL_BACKFACE_EMISSION             = 0x01c0, 
        FS_MATERIAL_BACKFACE                      = 0x01e0, 
        //
        FS_MATERIAL_IOR                           = 0x0200, 
        //
        FS_MATERIAL_VOLUME_SCATTERING             = 0x0400, 
        FS_MATERIAL_VOLUME_ABSORPTION_COEFFICIENT = 0x0800, 
        FS_MATERIAL_VOLUME_SCATTERING_COEFFICIENT = 0x1000, 
        FS_MATERIAL_VOLUME                        = 0x1c00, 
        //
        FS_MATERIAL_GEOMETRY_DISPLACEMENT         = 0x2000, 
        FS_MATERIAL_GEOMETRY_CUTOUT_OPACITY       = 0x4000, 
        FS_MATERIAL_GEOMETRY_NORMAL               = 0x8000, 
        FS_MATERIAL_GEOMETRY                      = 0xe000, 
        FS_MATERIAL_HAIR                          = 0x10000 
    };
 
    virtual IMaterial_instance *merge_materials(
        IMaterial_instance const *m0,
        IMaterial_instance const *m1,
        Field_selector           field_selector) = 0;
 
    virtual DAG_constant const *create_constant(
        IValue const *value) = 0;
 
    virtual DAG_temporary const *create_temporary(
        DAG_node const *node,
        int            index) = 0;
 
    virtual DAG_node const *create_call(
        char const                    *name,
        IDefinition::Semantics        sema,
        DAG_call::Call_argument const call_args[],
        size_t                        num_call_args,
        IType const                   *ret_type,
        DAG_DbgInfo                   dbg_info) = 0;
 
    virtual DAG_node const *create_function_call(
        char const             *name,
        DAG_node const * const call_args[],
        size_t                 num_call_args,
        DAG_DbgInfo            dbg_info) = 0;
 
    virtual DAG_node const *create_mixer_call(
        DAG_call::Call_argument const call_args[],
        int                           num_call_args) = 0;
 
    virtual DAG_node const *create_color_mixer_call(
        DAG_call::Call_argument const call_args[],
        int                           num_call_args) = 0;
 
    virtual DAG_parameter const *create_parameter(
        IType const *type,
        int         index,
        DAG_DbgInfo dbg_info) = 0;
 
    virtual IType_factory *get_type_factory() = 0;
 
    virtual IValue_factory *get_value_factory() = 0;
 
    enum Unary_operator {
        OK_BITWISE_COMPLEMENT   = IExpression::OK_BITWISE_COMPLEMENT,
        OK_LOGICAL_NOT          = IExpression::OK_LOGICAL_NOT,
        OK_POSITIVE             = IExpression::OK_POSITIVE,
        OK_NEGATIVE             = IExpression::OK_NEGATIVE,
        OK_PRE_INCREMENT        = IExpression::OK_PRE_INCREMENT,
        OK_PRE_DECREMENT        = IExpression::OK_PRE_DECREMENT,
        OK_POST_INCREMENT       = IExpression::OK_POST_INCREMENT,
        OK_POST_DECREMENT       = IExpression::OK_POST_DECREMENT
    };
 
    enum Binary_operator {
        OK_SELECT               = IExpression_binary::OK_SELECT,                
        OK_ARRAY_INDEX          = IExpression_binary::OK_ARRAY_INDEX,           
        OK_MULTIPLY             = IExpression_binary::OK_MULTIPLY,              
        OK_DIVIDE               = IExpression_binary::OK_DIVIDE,                
        OK_MODULO               = IExpression_binary::OK_MODULO,                
        OK_PLUS                 = IExpression_binary::OK_PLUS,                  
        OK_MINUS                = IExpression_binary::OK_MINUS,                 
        OK_SHIFT_LEFT           = IExpression_binary::OK_SHIFT_LEFT,            
        OK_SHIFT_RIGHT          = IExpression_binary::OK_SHIFT_RIGHT,           
        OK_UNSIGNED_SHIFT_RIGHT = IExpression_binary::OK_UNSIGNED_SHIFT_RIGHT,  
        OK_LESS                 = IExpression_binary::OK_LESS,                  
        OK_LESS_OR_EQUAL        = IExpression_binary::OK_LESS_OR_EQUAL,         
        OK_GREATER_OR_EQUAL     = IExpression_binary::OK_GREATER_OR_EQUAL,      
        OK_GREATER              = IExpression_binary::OK_GREATER,               
        OK_EQUAL                = IExpression_binary::OK_EQUAL,                 
        OK_NOT_EQUAL            = IExpression_binary::OK_NOT_EQUAL,             
        OK_BITWISE_AND          = IExpression_binary::OK_BITWISE_AND,           
        OK_BITWISE_XOR          = IExpression_binary::OK_BITWISE_XOR,           
        OK_BITWISE_OR           = IExpression_binary::OK_BITWISE_OR,            
        OK_LOGICAL_AND          = IExpression_binary::OK_LOGICAL_AND,           
        OK_LOGICAL_OR           = IExpression_binary::OK_LOGICAL_OR,            
    };
 
    virtual IType const *get_bsdf_component_type() = 0;
 
    virtual IType const *get_edf_component_type() = 0;
 
    virtual IType const *get_vdf_component_type() = 0;
 
    virtual IType const *get_bsdf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_edf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_vdf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_color_bsdf_component_type() = 0;
 
    virtual IType const *get_color_edf_component_type() = 0;
 
    virtual IType const *get_color_vdf_component_type() = 0;
 
    virtual IType const *get_color_bsdf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_color_edf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_color_vdf_component_array_type(
        int n_values) = 0;
 
    virtual IType const *get_bool_type() = 0;
 
    virtual DAG_node const *create_unary(
        Unary_operator op,
        DAG_node const *o) = 0;
 
    virtual DAG_node const *create_binary(
        Binary_operator op,
        DAG_node const  *l,
        DAG_node const  *r) = 0;
 
    virtual DAG_node const *create_ternary(
        DAG_node const *cond,
        DAG_node const *t_expr,
        DAG_node const *f_expr) = 0;
 
    virtual DAG_node const *create_select(
        DAG_node const *s,
        char const     *member) = 0;
 
    virtual DAG_node const *create_array(
        IType const            *elem_type,
        DAG_node const * const values[],
        size_t                 n_values) = 0;
 
    virtual DAG_constant const *create_bool_constant(
        bool f) = 0;
 
    virtual DAG_constant const *create_int_constant(
        int i) = 0;
 
    virtual DAG_constant const *create_emission_enum_constant(
        int i) = 0;
 
    virtual DAG_constant const *create_scatter_enum_constant(
        int i) = 0;
 
    virtual DAG_constant const *create_wrap_mode_enum_constant(
        int i) = 0;
 
    virtual DAG_constant const *create_float_constant(
        float f) = 0;
 
    virtual DAG_constant const *create_float3_constant(
        float x, float y, float z) = 0;
 
    virtual DAG_constant const *create_color_constant(
        float r, float g, float b) = 0;
 
    virtual DAG_constant const *create_global_ior() = 0;
 
    virtual DAG_constant const *create_global_float_ior() = 0;
 
    virtual DAG_constant const *create_string_constant(
        char const *s) = 0;
 
    virtual DAG_constant const *create_bsdf_constant() = 0;
 
    virtual DAG_constant const *create_edf_constant() = 0;
 
    virtual DAG_constant const *create_vdf_constant() = 0;
 
    virtual DAG_constant const *create_hair_bsdf_constant() = 0;
 
    virtual DAG_node const *create_bsdf_component(
        DAG_node const *weight_arg,
        DAG_node const *bsdf_arg) = 0;
 
    virtual DAG_node const *create_edf_component(
        DAG_node const *weight_arg,
        DAG_node const *edf_arg) = 0;
 
    virtual DAG_node const *create_vdf_component(
        DAG_node const *weight_arg,
        DAG_node const *vdf_arg) = 0;
 
    virtual DAG_node const *create_color_bsdf_component(
        DAG_node const *weight_arg,
        DAG_node const *bsdf_arg) = 0;
 
    virtual DAG_node const *create_color_edf_component(
        DAG_node const *weight_arg,
        DAG_node const *edf_arg) = 0;
 
    virtual DAG_node const *create_color_vdf_component(
        DAG_node const *weight_arg,
        DAG_node const *edf_arg) = 0;
 
    virtual DAG_constant const *mk_constant(
        const char *const_type,
        const char *value) = 0;
 
    virtual DAG_node const *mk_default(
        char const *param_type,
        char const *param_default) = 0;
 
    virtual size_t get_compound_argument_size(
        DAG_node const *node) = 0;
 
    virtual DAG_node const *get_compound_argument(
        DAG_node const *node,
        size_t         i) = 0;
 
    virtual DAG_node const *get_remapped_argument(
        DAG_node const *node,
        size_t         i) = 0;
 
    virtual char const *get_compound_parameter_name(
        DAG_node const *node,
        size_t         i) const = 0;
 
    virtual bool eval_if(
        DAG_node const *node) = 0;
 
    virtual bool eval_maybe_if(
        DAG_node const *node) = 0;
 
    virtual int get_selector(
        DAG_node const *node) const = 0;
 
    virtual bool all_nodes(
        IRule_matcher::Checker_function test_fct,
        DAG_node const                  *node) = 0;
 
    virtual bool set_normalize_mixers(
        bool new_value) = 0;
 
    virtual IMaterial_instance *normalize_mixers(
        IMaterial_instance const         *inst,
        IRule_matcher_event              *event_handler,
        const mi::mdl::Distiller_options *options,
        mi::Sint32                       &error) = 0;
 
    virtual void release() const  = 0;
 
    virtual void debug_node(
        IOutput_stream *outs,
        DAG_node const *node) = 0;
 
    // This structs collects the node properties that are required for matching on a node in 
    // the Distiller. The following properties are relevant.
    // 1. Semantics
    // 2. Type kind (if the semantics is not enough, e.g. DS_UNKOWN or DS_ELEM_CONSTRUCTOR or 
    //    ternaries)
    // 3. Predefined struct Id (if the Type kind is also not enough, e.g. for materials)
    // 4. Arity (number of arguments for mixers and tint())
    // The properties are stored in the output parameters. Parameters that are not relevant
    // (or not even meaningful) for a node are set to default values as follows:
    // - sema: DS_UNKNOWN
    // - type_kind: TK_ERROR
    // - struct_id: SID_USER
    // - arity: 0
    struct Match_properties {
        IDefinition::Semantics      sema;
        IType::Kind                 type_kind;
        IType_struct::Predefined_id struct_id;
        size_t                      arity;
    };
 
    // Compute all properties of a node that are required for matching against a rule pattern.
    virtual void get_match_properties(
        DAG_node const   *node,
        Match_properties &mprops) const = 0;
};
 
} // mdl
} // mi
 
#endif // MDL_DISTILLER_PLUGIN_API_H