neuray API Programmer's Manual

imdl_backend.h File Reference

Description

Interfaces related to MDL compiler backends.

Code Example

imdl_backend.h

‎/***************************************************************************************************
 * Copyright 2023 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/version.h>

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 {
        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,        

        SU_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    }; // can be or'ed

    typedef Uint32 State_usage;

    enum Texture_shape {
        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, 

        Texture_shape_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    enum Prototype_language {
        SL_CUDA,
        SL_PTX,
        SL_HLSL,
        SL_GLSL,
        SL_OLD_GLSL, // \if MDL_SOURCE_RELEASE Reserved\else old GLSL\endif.
        SL_NUM_LANGUAGES,
        SL_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    enum Distribution_kind
    {
        DK_NONE,
        DK_BSDF,
        DK_HAIR_BSDF,
        DK_EDF,
        DK_INVALID,
        DK_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    enum Function_kind {
        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,
        FK_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    enum Gamma_mode {
        GM_GAMMA_DEFAULT,
        GM_GAMMA_LINEAR,
        GM_GAMMA_SRGB,
        GM_GAMMA_UNKNOWN,
        GM_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    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 = 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;

    virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0(get_body_texture_count)() const = 0;

    virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0(get_body_light_profile_count)() const = 0;

    virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0(get_body_bsdf_measurement_count)() 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 {
        FEC_ENVIRONMENT  = 0,   
        FEC_CORE         = 1,   
        FEC_DISPLACEMENT = 2,   
        FEC_FORCE_32_BIT = 0xFFFFFFFFu //   Undocumented, for alignment only
    };

    virtual Sint32 
               add_function(
        const IFunction_call       *call,
        Function_execution_context fexc,
        const char                 *fname,
        IMdl_execution_context     *context = 0) = 0;

    virtual Sint32 
               add_function(
        const IFunction_definition *function,
        Function_execution_context fexc,
        const char                 *fname,
        IMdl_execution_context     *context) = 0;

    virtual Sint32 MI_NEURAYLIB_DEPRECATED_METHOD_14_0(add_environment)(
        const IFunction_call    *call,
        const char              *fname,
        IMdl_execution_context  *context = 0) = 0;
};

struct Target_function_description
{
    Target_function_description(
        const char* expression_path = 0,
        const char* base_function_name = 0)
        : path(expression_path)
        , base_fname(base_function_name)
        , argument_block_index(~Size(0))
        , function_index(~Size(0))
        , distribution_kind(ITarget_code::DK_INVALID)
        , 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;

    Sint32 
               return_code;
};

mi_static_assert( sizeof( ITarget_code::State_usage_property) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ITarget_code::Texture_shape) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ITarget_code::Prototype_language) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ITarget_code::Distribution_kind) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ITarget_code::Function_kind) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ITarget_code::Gamma_mode) == sizeof( mi::Uint32));
mi_static_assert( sizeof( ILink_unit::Function_execution_context) == sizeof( mi::Uint32));

} // namespace neuraylib

} // namespace mi

#endif // MI_NEURAYLIB_IMDL_BACKEND_H

Namespaces

namespace 
Common namespace for APIs of NVIDIA Advanced Rendering Center GmbH. More...
namespace 
Namespace for the neuray API. More...

Classes

class 
Represents a link-unit of an MDL backend. More...
class 
MDL backends allow to transform compiled material instances or function calls into target code. More...
class 
Represents an argument block of a class-compiled material compiled for a specific target. More...
class 
Represents target code of an MDL backend. More...
class 
A callback interface to allow the user to handle resources when creating new mi::neuraylib::ITarget_argument_block objects for class-compiled materials when the arguments contain textures not known during compilation. More...
class 
Represents the layout of an mi::neuraylib::ITarget_argument_block with support for nested elements. More...
struct 
Description of target function. More...
struct 
Structure representing the state during traversal of the nested layout. More...