imdl_backend.h

Go to the documentation of this file.

/***************************************************************************************************
 * Copyright 2026 NVIDIA Corporation. All rights reserved.
 **************************************************************************************************/
 
#ifndef MI_NEURAYLIB_IMDL_BACKEND_H
#define MI_NEURAYLIB_IMDL_BACKEND_H
 
#include <mi/base/interface_declare.h>
#include <mi/neuraylib/imdl_backend_api.h>
#include <mi/neuraylib/ivalue.h>
#include <mi/neuraylib/target_code_types.h>
#include <mi/neuraylib/typedefs.h>
#include <mi/neuraylib/version.h> // for MI_NEURAYLIB_DEPRECATED_ENUM_VALUE
 
namespace mi {
 
namespace neuraylib {
 
class IBuffer;
class ICompiled_material;
class IFunction_definition;
class IFunction_call;
class ILink_unit;
class IMdl_execution_context;
class ITarget_code;
class ITarget_argument_block;
class ITransaction;
 
struct Target_function_description;
 
class IMdl_backend : public
    mi::base::Interface_declare<0x9ecdd747,0x20b8,0x4a8a,0xb1,0xe2,0x62,0xb2,0x62,0x30,0xd3,0x67>
{
public:
#if !defined(MDL_SOURCE_RELEASE) && defined(MDL_ENABLE_INTERPRETER)
#endif
    virtual Sint32 set_option( const char* name, const char* value) = 0;
 
    virtual Sint32 set_option_binary(
        const char* name,
        const char* data,
        Size size) = 0;
 
    virtual const Uint8* get_device_library( Size &size) const = 0;
 
    virtual const ITarget_code* translate_environment(
        ITransaction* transaction,
        const IFunction_call* call,
        const char* fname,
        IMdl_execution_context* context) = 0;
 
    virtual const ITarget_code* translate_material_expression(
        ITransaction* transaction,
        const ICompiled_material* material,
        const char* path,
        const char* fname,
        IMdl_execution_context* context) = 0;
 
    virtual const ITarget_code* translate_material_df(
        ITransaction* transaction,
        const ICompiled_material* material,
        const char* path,
        const char* base_fname,
        IMdl_execution_context* context) = 0;
 
    virtual const ITarget_code* translate_material(
        ITransaction* transaction,
        const ICompiled_material* material,
        Target_function_description* function_descriptions,
        Size description_count,
        IMdl_execution_context* context) = 0;
 
    virtual ILink_unit* create_link_unit(
        ITransaction* transaction,
        IMdl_execution_context* context) = 0;
 
    virtual const ITarget_code* translate_link_unit(
        const ILink_unit* lu, IMdl_execution_context* context) = 0;
 
    virtual const ITarget_code* deserialize_target_code(
        ITransaction* transaction,
        const IBuffer* buffer,
        IMdl_execution_context* context) const = 0;
 
    virtual const ITarget_code* deserialize_target_code(
        ITransaction* transaction,
        const Uint8* buffer_data,
        Size buffer_size,
        IMdl_execution_context* context) const = 0;
};
 
class ITarget_resource_callback : public
    mi::base::Interface_declare<0xe7559a88,0x9a9a,0x41d8,0xa1,0x9c,0x4a,0x52,0x4e,0x4b,0x7b,0x66>
{
public:
#ifndef MDL_SOURCE_RELEASE
#endif // MDL_SOURCE_RELEASE
    virtual Uint32 get_resource_index(IValue_resource const *resource) = 0;
 
    virtual Uint32 get_string_index(IValue_string const *s) = 0;
};
 
class ITarget_argument_block : public
    mi::base::Interface_declare<0xf2a5db20,0x85ab,0x4c41,0x8c,0x5f,0x49,0xc8,0x29,0x4a,0x73,0x65>
{
public:
    virtual const char* get_data() const = 0;
 
    virtual char* get_data() = 0;
 
    virtual Size get_size() const = 0;
 
    virtual ITarget_argument_block *clone() const = 0;
};
 
struct Target_value_layout_state {
    Target_value_layout_state(mi::Uint32 state_offs = 0, mi::Uint32 data_offs = 0)
        : m_state_offs(state_offs)
        , m_data_offs(data_offs)
    {}
 
    mi::Uint32 m_state_offs;
 
    mi::Uint32 m_data_offs;
};
 
class ITarget_value_layout : public
    mi::base::Interface_declare<0x1003351f,0x0c31,0x4a9d,0xb9,0x99,0x90,0xb5,0xe4,0xb4,0x71,0xe3>
{
public:
    virtual Size get_size() const = 0;
 
    virtual Size get_num_elements(
        Target_value_layout_state state = Target_value_layout_state()) const = 0;
 
    virtual Size get_layout(
        IValue::Kind &kind,
        Size &arg_size,
        Target_value_layout_state state = Target_value_layout_state()) const = 0;
 
    virtual Target_value_layout_state get_nested_state(
        Size i,
        Target_value_layout_state state = Target_value_layout_state()) const = 0;
 
    virtual Sint32 set_value(
        char *block,
        IValue const *value,
        ITarget_resource_callback *resource_callback,
        Target_value_layout_state state = Target_value_layout_state()) const = 0;
};
 
class ITarget_code : public
    mi::base::Interface_declare<0xefca46ae,0xd530,0x4b97,0x9d,0xab,0x3a,0xdb,0x0c,0x58,0xc3,0xac>
{
public:
    enum State_usage_property : Uint32 {
        SU_POSITION              = 0x0001u,   
        SU_NORMAL                = 0x0002u,   
        SU_GEOMETRY_NORMAL       = 0x0004u,   
        SU_MOTION                = 0x0008u,   
        SU_TEXTURE_COORDINATE    = 0x0010u,   
        SU_TEXTURE_TANGENTS      = 0x0020u,   
        SU_TANGENT_SPACE         = 0x0040u,   
        SU_GEOMETRY_TANGENTS     = 0x0080u,   
        SU_DIRECTION             = 0x0100u,   
        SU_ANIMATION_TIME        = 0x0200u,   
        SU_ROUNDED_CORNER_NORMAL = 0x0400u,   
 
        SU_ALL_VARYING_MASK      = 0x07FFu,   
 
        SU_TRANSFORMS            = 0x0800u,   
        SU_OBJECT_ID             = 0x1000u,   
 
        SU_ALL_UNIFORM_MASK      = 0x1800u    
 
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(SU_FORCE_32_BIT, 0xFFFFFFFFu)
    }; // can be or'ed
 
    using State_usage = Uint32;
 
    enum Texture_shape : Uint32 {
        Texture_shape_invalid      = 0, 
        Texture_shape_2d           = 1, 
        Texture_shape_3d           = 2, 
        Texture_shape_cube         = 3, 
        Texture_shape_ptex         = 4, 
        Texture_shape_bsdf_data    = 5  
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(Texture_shape_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    enum Prototype_language : Uint32 {
        SL_CUDA,
        SL_PTX,
        SL_HLSL,
        SL_GLSL,
        SL_NUM_LANGUAGES
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(SL_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    enum Distribution_kind : Uint32 {
        DK_NONE,
        DK_BSDF,
        DK_HAIR_BSDF,
        DK_EDF,
        DK_INVALID
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(DK_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    enum Function_kind : Uint32 {
        FK_INVALID,
        FK_LAMBDA,
        FK_SWITCH_LAMBDA,
        FK_ENVIRONMENT,
        FK_CONST,
        FK_DF_INIT,
        FK_DF_SAMPLE,
        FK_DF_EVALUATE,
        FK_DF_PDF,
        FK_DF_AUXILIARY
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(FK_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    enum Gamma_mode : Uint32 {
        GM_GAMMA_DEFAULT,
        GM_GAMMA_LINEAR,
        GM_GAMMA_SRGB,
        GM_GAMMA_UNKNOWN
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(GM_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    virtual IMdl_backend_api::Mdl_backend_kind get_backend_kind() const = 0;
 
    virtual const char* get_code() const = 0;
 
    virtual Size get_code_size() const = 0;
 
    virtual Size get_callable_function_count() const = 0;
 
    virtual const char* get_callable_function( Size index) const = 0;
 
 
 
    virtual Size get_texture_count() const = 0;
 
    virtual const char* get_texture( Size index) const = 0;
 
    virtual const char* get_texture_url( Size index) const = 0;
 
    virtual const char* get_texture_owner_module( Size index) const = 0;
 
    virtual bool get_texture_is_body_resource( Size index) const = 0;
 
    virtual Gamma_mode get_texture_gamma( Size index) const = 0;
 
    virtual const char* get_texture_selector( Size index) const = 0;
 
    virtual Texture_shape get_texture_shape( Size index) const = 0;
 
    virtual Df_data_kind get_texture_df_data_kind( Size index) const = 0;
 
    virtual const Float32* get_texture_df_data(
        Size index,
        Size& rx,
        Size& ry,
        Size& rz,
        const char*& pixel_type) const = 0;
 
 
 
    virtual Size get_light_profile_count() const = 0;
 
    virtual const char* get_light_profile( Size index) const = 0;
 
    virtual const char* get_light_profile_url( Size index) const = 0;
 
    virtual const char* get_light_profile_owner_module( Size index) const = 0;
 
    virtual bool get_light_profile_is_body_resource( Size index) const = 0;
 
 
 
    virtual Size get_bsdf_measurement_count() const = 0;
 
    virtual const char* get_bsdf_measurement(Size index) const = 0;
 
    virtual const char* get_bsdf_measurement_url( Size index) const = 0;
 
    virtual const char* get_bsdf_measurement_owner_module( Size index) const = 0;
 
    virtual bool get_bsdf_measurement_is_body_resource( Size index) const = 0;
 
 
    virtual Size get_ro_data_segment_count() const = 0;
 
    virtual const char* get_ro_data_segment_name( Size index) const = 0;
 
    virtual Size get_ro_data_segment_size( Size index) const = 0;
 
    virtual const char* get_ro_data_segment_data( Size index) const = 0;
 
    virtual Size get_code_segment_count() const = 0;
 
    virtual const char* get_code_segment( Size index) const = 0;
 
    virtual Size get_code_segment_size( Size index) const = 0;
 
    virtual const char* get_code_segment_description( Size index) const = 0;
 
    virtual State_usage get_render_state_usage() const = 0;
 
    virtual Size get_argument_block_count() const = 0;
 
    virtual const ITarget_argument_block *get_argument_block(Size index) const = 0;
 
    virtual ITarget_argument_block *create_argument_block(
        Size index,
        const ICompiled_material *material,
        ITarget_resource_callback *resource_callback) const = 0;
 
    virtual Size get_argument_layout_count() const = 0;
 
    virtual const ITarget_value_layout *get_argument_block_layout(Size index) const = 0;
 
    virtual Size get_string_constant_count() const = 0;
 
    virtual const char* get_string_constant(Size index) const = 0;
 
    virtual Uint32 get_known_resource_index(
        ITransaction* transaction,
        IValue_resource const *resource) const = 0;
 
    virtual const char* get_callable_function_prototype( Size index, Prototype_language lang)
        const = 0;
 
    virtual Distribution_kind get_callable_function_distribution_kind( Size index) const = 0;
 
    virtual Function_kind get_callable_function_kind( Size index) const = 0;
 
    virtual Size get_callable_function_argument_block_index( Size index) const = 0;
 
    virtual Sint32 execute_environment(
        Size index,
        const Shading_state_environment& state,
        Texture_handler_base* tex_handler,
        Spectrum_struct* result) const = 0;
 
    virtual Sint32 execute(
        Size index,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args,
        void* result) const = 0;
 
    virtual Sint32 execute_bsdf_init(
        Size index,
        Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_bsdf_sample(
        Size index,
        Bsdf_sample_data *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_bsdf_evaluate(
        Size index,
        Bsdf_evaluate_data_base *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_bsdf_pdf(
        Size index,
        Bsdf_pdf_data *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
 
    virtual Sint32 execute_bsdf_auxiliary(
        Size index,
        Bsdf_auxiliary_data_base *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
 
    virtual Sint32 execute_edf_init(
        Size index,
        Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_edf_sample(
        Size index,
        Edf_sample_data *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_edf_evaluate(
        Size index,
        Edf_evaluate_data_base *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Sint32 execute_edf_pdf(
        Size index,
        Edf_pdf_data *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
 
    virtual Sint32 execute_edf_auxiliary(
        Size index,
        Edf_auxiliary_data_base *data,
        const Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
 
    virtual Size get_callable_function_df_handle_count( Size func_index) const = 0;
 
    virtual const char* get_callable_function_df_handle( Size func_index, Size handle_index)
        const = 0;
 
    virtual bool supports_serialization() const = 0;
 
    virtual const IBuffer* serialize( IMdl_execution_context* context) const = 0;
 
    virtual State_usage get_callable_function_render_state_usage( Size index) const = 0;
 
    virtual Sint32 execute_init(
        Size index,
        Shading_state_material& state,
        Texture_handler_base* tex_handler,
        const ITarget_argument_block *cap_args) const = 0;
};
 
class ILink_unit : public
    mi::base::Interface_declare<0x1df9bbb0,0x5d96,0x475f,0x9a,0xf4,0x07,0xed,0x8c,0x2d,0xfd,0xdb>
{
public:
    virtual Sint32 add_material_expression(
        const ICompiled_material* inst,
        const char* path,
        const char* fname,
        IMdl_execution_context* context) = 0;
 
    virtual Sint32 add_material_df(
        const ICompiled_material* material,
        const char* path,
        const char* base_fname,
        IMdl_execution_context* context) = 0;
 
    virtual Sint32 add_material(
        const ICompiled_material*       material,
        Target_function_description*    function_descriptions,
        Size                            description_count,
        IMdl_execution_context*         context) = 0;
 
    enum Function_execution_context : Uint32 {
        FEC_ENVIRONMENT  = 0,   
        FEC_CORE         = 1,   
        FEC_DISPLACEMENT = 2    
        MI_NEURAYLIB_DEPRECATED_ENUM_VALUE(FEC_FORCE_32_BIT, 0xFFFFFFFFu)
    };
 
    virtual Sint32 add_function(
        const IFunction_call       *call,
        Function_execution_context fexc,
        const char                 *fname,
        IMdl_execution_context     *context = nullptr) = 0;
 
    virtual Sint32 add_function(
        const IFunction_definition *function,
        Function_execution_context fexc,
        const char                 *fname,
        IMdl_execution_context     *context) = 0;
};
 
struct Target_function_description
{
    Target_function_description(
        const char* expression_path = nullptr,
        const char* base_function_name = nullptr)
        : path(expression_path)
        , base_fname(base_function_name)
        , argument_block_index(~Size(0))
        , function_index(~Size(0))
        ,
         return_code(~Sint32(0)) // not processed
    {
    }
 
    const char* path;
 
    const char* base_fname;
 
    Size argument_block_index;
 
    Size function_index;
 
    ITarget_code::Distribution_kind distribution_kind{ITarget_code::DK_INVALID};
 
    Sint32 return_code;
};
 
} // namespace neuraylib
 
} // namespace mi
 
#endif // MI_NEURAYLIB_IMDL_BACKEND_H