Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IMdl_backend Class Referenceabstract

MDL backends allow to transform compiled material instances or function calls into target code. More...

Inheritance diagram for mi::neuraylib::IMdl_backend:
mi::base::Interface_declare< 0x9ecdd747, 0x20b8, 0x4a8a, 0xb1, 0xe2, 0x62, 0xb2, 0x62, 0x30, 0xd3, 0x67 > mi::base::IInterface

Public Member Functions

virtual Sint32 set_option (const char *name, const char *value)=0
 Sets a backend option. More...
 
virtual Sint32 set_option_binary (const char *name, const char *data, Size size)=0
 Sets a binary backend option. More...
 
virtual const Uint8get_device_library (Size &size) const =0
 Returns the representation of a device library for this backend if one exists. More...
 
virtual const ITarget_codedeprecated_translate_environment (ITransaction *transaction, const IFunction_call *call, Float32 mdl_meters_per_scene_unit, Float32 mdl_wavelength_min, Float32 mdl_wavelength_max, const char *fname, Sint32 *errors)=0
 Transforms an MDL environment function call into target code. More...
 
virtual const ITarget_codetranslate_environment (ITransaction *transaction, const IFunction_call *call, const char *fname, IMdl_execution_context *context)=0
 Transforms an MDL environment function call into target code. More...
 
virtual const ITarget_codedeprecated_translate_material_expression (ITransaction *transaction, const ICompiled_material *material, const char *path, const char *fname, Sint32 *errors)=0
 Transforms an expression that is part of an MDL material instance to target code. More...
 
virtual const ITarget_codetranslate_material_expression (ITransaction *transaction, const ICompiled_material *material, const char *path, const char *fname, IMdl_execution_context *context)=0
 Transforms an expression that is part of an MDL material instance to target code. More...
 
virtual const ITarget_codedeprecated_translate_material_expression_uniform_state (ITransaction *transaction, const ICompiled_material *material, const char *path, const char *fname, const Float32_4_4_struct &world_to_obj, const Float32_4_4_struct &obj_to_world, Sint32 object_id, Sint32 *errors)=0
 Transforms an expression that is part of an MDL material instance to target code and sets the uniform state. More...
 
virtual const ITarget_codedeprecated_translate_material_expressions (ITransaction *transaction, const ICompiled_material *material, const char *const paths[], Uint32 path_cnt, const char *fname, Sint32 *errors)=0
 Transforms several expressions that are part of one MDL material instance to target code. More...
 
virtual const ITarget_codedeprecated_translate_material_df (ITransaction *transaction, const ICompiled_material *material, const char *path, const char *base_fname, bool include_geometry_normal, Sint32 *errors)=0
 Transforms an MDL distribution function to target code. More...
 
virtual const ITarget_codetranslate_material_df (ITransaction *transaction, const ICompiled_material *material, const char *path, const char *base_fname, IMdl_execution_context *context)=0
 Transforms an MDL distribution function to target code. More...
 
virtual const ITarget_codedeprecated_translate_material (ITransaction *transaction, const ICompiled_material *material, Target_function_description *function_descriptions, Size description_count, bool include_geometry_normal)=0
 Transforms (multiple) distribution functions and expressions of a material to target code. More...
 
virtual const ITarget_codetranslate_material (ITransaction *transaction, const ICompiled_material *material, Target_function_description *function_descriptions, Size description_count, IMdl_execution_context *context)=0
 Transforms (multiple) distribution functions and expressions of a material to target code. More...
 
virtual ILink_unitdeprecated_create_link_unit (ITransaction *transaction, Sint32 *errors)=0
 Creates a new link unit. More...
 
virtual ILink_unitcreate_link_unit (ITransaction *transaction, IMdl_execution_context *context)=0
 Creates a new link unit. More...
 
virtual const ITarget_codedeprecated_translate_link_unit (const ILink_unit *lu, Sint32 *errors)=0
 Transforms a link unit to target code. More...
 
virtual const ITarget_codetranslate_link_unit (const ILink_unit *lu, IMdl_execution_context *context)=0
 Transforms a link unit to target code. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0x9ecdd747, 0x20b8, 0x4a8a, 0xb1, 0xe2, 0x62, 0xb2, 0x62, 0x30, 0xd3, 0x67 >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
IInterface
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0x9ecdd747, 0x20b8, 0x4a8a, 0xb1, 0xe2, 0x62, 0xb2, 0x62, 0x30, 0xd3, 0x67 >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 

Detailed Description

MDL backends allow to transform compiled material instances or function calls into target code.

Member Function Documentation

virtual ILink_unit* mi::neuraylib::IMdl_backend::create_link_unit ( ITransaction transaction,
IMdl_execution_context context 
)
pure virtual

Creates a new link unit.

Parameters
transactionThe transaction to be used.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. There are currently no options supported by this operation. Can be NULL.
Returns
The generated link unit, or NULL in case of failure.
The generated link unit, or NULL in case of failure.
virtual ILink_unit* mi::neuraylib::IMdl_backend::deprecated_create_link_unit ( ITransaction transaction,
Sint32 errors 
)
pure virtual

Creates a new link unit.

Parameters
transactionThe transaction to be used.
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: The JIT backend is not available.
Returns
The generated link unit, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_environment ( ITransaction transaction,
const IFunction_call call,
Float32  mdl_meters_per_scene_unit,
Float32  mdl_wavelength_min,
Float32  mdl_wavelength_max,
const char *  fname,
Sint32 errors 
)
pure virtual

Transforms an MDL environment function call into target code.

The prototype of the resulting function will roughly look like this:

void FNAME(
void *result,
void const *res_data,
void const *exception_state);

The result buffer must be big enough for the expression result.

Parameters
transactionThe transaction to be used.
callThe MDL function call for the environment.
mdl_meters_per_scene_unitThe conversion ratio between meters and scene units for this environment function.
mdl_wavelength_minThe smallest supported wavelength. Typical value: 380.
mdl_wavelength_maxThe largest supported wavelength. Typical value: 780.
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
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 expression.
  • -3: The backend failed to generate target code for the function.
Returns
The generated target code, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_link_unit ( const ILink_unit lu,
Sint32 errors 
)
pure virtual

Transforms a link unit to target code.

Parameters
luThe link unit to translate.
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 link unit.
  • -2: The JIT backend failed to compile the unit.
Returns
The generated link unit, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_material ( ITransaction transaction,
const ICompiled_material material,
Target_function_description *  function_descriptions,
Size  description_count,
bool  include_geometry_normal 
)
pure virtual

Transforms (multiple) distribution functions and expressions of a material to target code.

For each distribution function this results in four functions, suffixed with "_init", "_sample", "_evaluate", and "_pdf". Functions can be selected by providing a list of Target_function_descriptions. Each of them needs to define the path, the root of the expression that should be translated. After calling this function, each element of the list will contain information for later usage in the application, e.g., the argument_block_index and the function_index.

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
function_descriptionsThe list of descriptions of function to translate.
description_countThe size of the list of descriptions.
include_geometry_normalIf true, the "geometry.normal" field will be applied to the MDL state prior to evaluation of the given DF.
Returns
The generated target code, or NULL in case of failure. In the latter case, check the return codes in descriptions.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_material_df ( ITransaction transaction,
const ICompiled_material material,
const char *  path,
const char *  base_fname,
bool  include_geometry_normal,
Sint32 errors 
)
pure virtual

Transforms an MDL distribution function to target code.

Note that currently this is only supported for BSDFs. For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf".

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathThe path from the material root to the expression that should be translated, e.g., "surface.scattering".
base_fnameThe base name of the generated functions. If NULL is passed, "lambda" will be used.
include_geometry_normalIf true, the "geometry.normal" field will be applied to the MDL state prior to evaluation of the given DF.
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 path (non-existing).
  • -3: The backend failed to generate target code for the material.
  • -4: The requested expression is a constant.
  • -5: Only distribution functions are allowed.
  • -6: The backend does not support compiled MDL materials obtained from class compilation mode.
  • -7: The backend does not implement this function, yet.
  • -8: EDFs are not supported.
  • -9: VDFs are not supported.
  • -10: The requested BSDF is not supported, yet.
Returns
The generated target code, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_material_expression ( ITransaction transaction,
const ICompiled_material material,
const char *  path,
const char *  fname,
Sint32 errors 
)
pure virtual

Transforms an expression that is part of an MDL material instance to target code.

The prototype of the resulting function will roughly look like this:

void FNAME(
void *result,
void const *res_data,
void const *exception_state,
char const *arg_block_data);

The result buffer must be big enough for the expression result.

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathThe path from the material root to the expression that should be translated, e.g., "geometry.displacement".
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
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 path (non-existing).
  • -3: The backend failed to generate target code for the expression.
  • -4: The requested expression is a constant.
  • -5: Neither BSDFs, EDFs, VDFs, nor resource type expressions can be handled.
  • -6: The backend does not support compiled MDL materials obtained from class compilation mode.
Returns
The generated target code, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_material_expression_uniform_state ( ITransaction transaction,
const ICompiled_material material,
const char *  path,
const char *  fname,
const Float32_4_4_struct world_to_obj,
const Float32_4_4_struct obj_to_world,
Sint32  object_id,
Sint32 errors 
)
pure virtual

Transforms an expression that is part of an MDL material instance to target code and sets the uniform state.

The prototype of the resulting function will roughly look like this:

void FNAME(
void *result,
void const *res_data,
void const *exception_state,
char const *arg_block_data);

The result buffer must be big enough for the expression result.

See Also
translate_material_expression()
Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathThe path from the material root to the expression that should be translated, e.g., "geometry.displacement".
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
world_to_objThe 4x4 world-to-object space transformation matrix.
obj_to_worldThe 4x4 object-to-world space transformation matrix.
object_idThe result of the state::object_id() function.
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 path (non-existing).
  • -3: The backend failed to generate target code for the expression.
  • -4: The requested expression is a constant.
  • -5: Neither BSDFs, EDFs, VDFs, nor resource type expressions can be handled.
  • -6: The backend does not support compiled MDL materials obtained from class compilation mode.
Returns
The generated target code, or NULL in case of failure.
Note
Currently the uniform state will be compiled into the target code.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deprecated_translate_material_expressions ( ITransaction transaction,
const ICompiled_material material,
const char *const  paths[],
Uint32  path_cnt,
const char *  fname,
Sint32 errors 
)
pure virtual

Transforms several expressions that are part of one MDL material instance to target code.

The prototype of the resulting function will roughly look like this:

bool FNAME(
void const *res_data_pair,
void const *exception_state,
char const *arg_block_data,
void *result,
Uint32 expression_index);

The expression to be evaluated will be chosen via expression_index. The result buffer must be big enough for the according expression result. The generated function will return true, iff expression_index was valid.

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathsThe paths from the material root to the expression that should be translated, e.g., "geometry.displacement".
path_cntThe number of material paths.
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
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 path (non-existing).
  • -3: The backend failed to generate target code for the expression.
  • -4: The requested expression is a constant.
  • -5: Neither BSDFs, EDFs, VDFs, nor resource type expressions can be handled.
  • -6: The backend does not support compiled MDL materials obtained from class compilation mode.
  • -7: Mixing displacement and non-displacement expression not possible.
Returns
The generated target code, or NULL in case of failure.
virtual const Uint8* mi::neuraylib::IMdl_backend::get_device_library ( Size size) const
pure virtual

Returns the representation of a device library for this backend if one exists.

Parameters
[out]sizeThe size of the library.
Returns
The device library or NULL if no library exists for this backend.
virtual Sint32 mi::neuraylib::IMdl_backend::set_option ( const char *  name,
const char *  value 
)
pure virtual

Sets a backend option.

The following options are supported by all backends:

  • "compile_constants": If true, compile simple constants into functions returning constants. If false, do not compile simple constants but return error -4. Possible values: "on", "off". Default: "on".
  • "fast_math": Enables/disables unsafe floating point optimization. Possible values: "on", "off". Default: "on".
  • "opt_level": Set the optimization level. Possible values:
    • "0": no optimization
    • "1": no inlining, no expensive optimizations
    • "2": full optimizations, including inlining (default)
  • "num_texture_spaces": Set the number of supported texture spaces. Default: "32".

The following options are supported by the NATIVE backend only:

  • "use_builtin_resource_handler": Enables/disables the built-in texture runtime. Possible values: "on", "off". Default: "on".

The following options are supported by the PTX, LLVM-IR and native backend:

  • "enable_exceptions": Enables/disables support for exceptions through runtime function calls. For PTX, this options is always treated as disabled. Possible values: "on", "off". Default: "on".
  • "enable_ro_segment": Enables/disables the creation of the read-only data segment calls. Possible values: "on", "off". Default: "off".
  • "num_texture_results": Set the size of the text_results array in the MDL SDK state in number of float4 elements. The array has to be provided by the renderer and must be provided per thread (for example as an array on the stack) and will be filled in the init function created for a material and used by the sample, evaluate and pdf functions, if the size is non-zero. Default: "0".
  • "texture_runtime_with_derivs": Enables/disables derivative support for texture lookup functions. If enabled, the user-provided texture runtime has to provide functions with derivative parameters for the texture coordinates. Possible values: "on", "off". Default: "off".

The following options are supported by the LLVM-IR backend only:

  • "enable_simd": Enables/disables the use of SIMD instructions. Possible values: "on", "off". Default: "on".
  • "write_bitcode": Enables/disables the creation of the LLVM bitcode instead of LLVM IR. Possible values: "on", "off". Default: "off".

The following options are supported by the PTX backend only:

  • "sm_version": Specifies the SM target version. Possible values: "20", "30", "35", "37", "50", "52", "60", "61", "62" and "70". Default: "20". Note that currently the PTX backend will create code for target version "35" for all values higher than that.
  • "enable_ro_segment": Enables/disables the creation of the read-only data segment calls. Possible values: "on", "off". Default: "off".
  • "link_libdevice": Enables/disables linking of libdevice before PTX is generated. Possible values: "on", "off". Default: "on".
  • "output_format": Selects the output format of the backend. Possible values: "PTX", "LLVM-IR", "LLVM-BC". Default: "PTX".
  • "tex_lookup_call_mode": Selects how tex_lookup calls will be generated. See Texture lookup call modes of the PTX backend for more details. Possible values:
    • "vtable": generate calls through a vtable call (default)
    • "direct_call": generate direct function calls
    • "optix_cp": generate calls through OptiX bindless callable programs

The following options are supported by the HLSL backend only:

  • "hlsl_use_resource_data": If enabled, an extra user define resource data struct is passed to all resource callbacks. Possible values: "on", "off". Default: "off".

The following options are supported by the GLSL backend only:

  • "glsl_version": Specifies the GLSL target version. Possible values: "150", "330", "400", "410", "420", "430", "440", "450". Default: "330".
  • "glsl_profile": Specifies the GLSL target profile. Possible values: "core", "es", "compatibility". Default: "core".
  • "glsl_include_uniform_state": If true, object_id will be included in the state according to the "glsl_state_object_id_mode" option. Possible values: "on", "off". Default: "off"
  • "glsl_max_const_data": Specifies the maximum allowed amount in bytes of constant data for a generated shader by the GLSL backend. If bigger data are necessary, the backend will move it to uniform inputs. Default: "1024".
  • "glsl_place_uniforms_into_ssbo": If true, all generated uniform inputs will be placed into a shader storage buffer object. This option can only be enabled, if the "GL_ARB_shader_storage_buffer_object" extension is enabled. Possible values: "on", "off". Default: "off"
  • "glsl_uniform_ssbo_name": If non-empty, specifies a name for the SSBO buffer containing the uniform initializer if option "glsl_place_uniforms_into_ssbo" is enabled. Possible values: Any valid GLSL identifier. Default: "".
  • "glsl_remap_functions": Specifies a comma separated remap list of MDL functions. The entries must be specified as <old_name>=<new_name>. Both names have to be in mangled form. Default: "".
  • "glsl_state_animation_time_mode": Specify the implementation mode of state::animation_time(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_geometry_normal_mode": Specify the implementation mode of state::geometry_normal(). Possible values: "field", "arg", "func", "zero". Default: "field".
  • "glsl_state_motion_mode": Specify the implementation mode of state::motion(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_normal_mode": Specify the implementation mode of state::normal(). Possible values: "field", "arg", "func", "zero". Default: "field".
  • "glsl_state_object_id_mode": Specify the implementation mode of state::object_id(). You have to enable "glsl_include_uniform_state" for this mode to have any effect. Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_position_mode": Specify the implementation mode of state::position(). Possible values: "field", "arg", "func", "zero". Default: "field".
  • "glsl_state_texture_coordinate_mode": Specify the implementation mode of state::texture_coordinate(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_texture_space_max_mode": Specify the implementation mode of state::texture_space_max(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_texture_tangent_u_mode": Specify the implementation mode of state::texture_tangent_u(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_texture_tangent_v_mode": Specify the implementation mode of state::texture_tangent_v(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_geometry_tangent_u_mode": Specify the implementation mode of state::geometry_tangent_u(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_state_geometry_tangent_v_mode": Specify the implementation mode of state::geometry_tangent_v(). Possible values: "field", "arg", "func", "zero". Default: "zero".
  • "glsl_enabled_extensions": Specifies the enabled GLSL extensions as a comma separated list. Default: "".
  • "glsl_required_extensions": Specifies the required GLSL extensions as a comma separated list. Default: "".

The following extensions are fully supported by the GLSL backend:

  • "GL_ARB_gpu_shader_fp64"
  • "GL_ARB_shader_atomic_counters"
  • "GL_ARB_shading_language_420pack"
  • "GL_ARB_arrays_of_arrays"

The following extensions are partially supported by the GLSL backend:

  • "GL_OES_texture_3D"
  • "GL_OES_standard_derivatives"
  • "GL_EXT_frag_depth"
  • "GL_OES_EGL_image_external"
  • "GL_EXT_shader_texture_lod"
  • "GL_ARB_texture_rectangle"
  • "GL_3DL_array_objects"
  • "GL_ARB_texture_gather"
  • "GL_ARB_gpu_shader5"
  • "GL_ARB_separate_shader_objects"
  • "GL_ARB_tessellation_shader"
  • "GL_ARB_enhanced_layouts"
  • "GL_ARB_texture_cube_map_array"
  • "GL_ARB_shader_texture_lod"
  • "GL_ARB_explicit_attrib_location"
  • "GL_ARB_shader_image_load_store"
  • "GL_ARB_derivative_control"
  • "GL_ARB_shader_texture_image_samples"
  • "GL_ARB_viewport_array"
  • "GL_ARB_cull_distance"
  • "GL_ARB_shader_subroutine"
  • "GL_ARB_shader_storage_buffer_object"
  • "GL_ARB_bindless_texture"
  • "GL_ARB_gpu_shader_int64"
  • "GL_NV_shader_buffer_load"
  • "GL_NV_half_float"
  • "GL_NV_gpu_shader5"
  • "GL_GOOGLE_cpp_style_line_directive"
  • "GL_GOOGLE_include_directive"

Meaning of the state modes:

  • "field": access a field of a passed state struct
  • "arg": access an argument of the generated shader
  • "func": call a wrapper function
  • "zero": always zero
    Parameters
    nameThe name of the option.
    valueThe value of the option.
    Returns
    • 0: Success.
    • -1: Unknown option.
    • -2: Unsupported value.
virtual Sint32 mi::neuraylib::IMdl_backend::set_option_binary ( const char *  name,
const char *  data,
Size  size 
)
pure virtual

Sets a binary backend option.

The following options are supported by the LLVM backends:

  • "llvm_state_module": Sets a user-defined implementation of the state module. Please refer to Example for User-Defined State Modules" in the MDL SDK API documentation for details.
Parameters
nameThe name of the option.
dataThe data for the option.
sizeThe size of the data.
Returns
  • 0: Success.
  • -1: Unknown option.
  • -2: Unsupported value.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::translate_environment ( ITransaction transaction,
const IFunction_call call,
const char *  fname,
IMdl_execution_context context 
)
pure virtual

Transforms an MDL environment function call into target code.

The prototype of the resulting function will roughly look like this:

void FNAME(
void *result,
void const *res_data,
void const *exception_state);

The result buffer must be big enough for the expression result.

Parameters
transactionThe transaction to be used.
callThe MDL function call for the environment.
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. The following options are supported by this operation:
  • Float32 "meters_per_scene_unit": The conversion ratio between meters and scene units for this material. Default: 1.0f.
  • Float32 "wavelength_min": The smallest supported wavelength. Default: 380.0f.
  • Float32 "wavelength_max": The largest supported wavelength. Default: 780.0f. During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL.
Returns
The generated target code, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::translate_link_unit ( const ILink_unit lu,
IMdl_execution_context context 
)
pure virtual

Transforms a link unit to target code.

Parameters
luThe link unit to translate.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. There are currently no options supported by this operation. Can be NULL.
Returns
The generated link unit, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::translate_material ( ITransaction transaction,
const ICompiled_material material,
Target_function_description *  function_descriptions,
Size  description_count,
IMdl_execution_context context 
)
pure virtual

Transforms (multiple) distribution functions and expressions of a material to target code.

For each distribution function this results in four functions, suffixed with "_init", "_sample", "_evaluate", and "_pdf". Functions can be selected by providing a list of Target_function_descriptions. Each of them needs to define the path, the root of the expression that should be translated. After calling this function, each element of the list will contain information for later usage in the application, e.g., the argument_block_index and the function_index.

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
function_descriptionsThe list of descriptions of function to translate.
description_countThe size of the list of descriptions.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. The following options are supported for this operation:
  • bool "include_geometry_normal". If true, the "geometry.normal" field will be applied to the MDL state prior to evaluation of the given DF (default true). During material compilation messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL.
Returns
The generated target code, or NULL in case of failure. In the latter case, the return code in the failing description is set to -1 and the context, if provided, contains an error message.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::translate_material_df ( ITransaction transaction,
const ICompiled_material material,
const char *  path,
const char *  base_fname,
IMdl_execution_context context 
)
pure virtual

Transforms an MDL distribution function to target code.

Note that currently this is only supported for BSDFs. For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf".

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathThe path from the material root to the expression that should be translated, e.g., "surface.scattering".
base_fnameThe base name of the generated functions. If NULL is passed, "lambda" will be used.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. The following options are supported by this operation:
  • bool "include_geometry_normal". If true, the "geometry.normal" field will be applied to the MDL state prior to evaluation of the given DF (default: true). During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL.
Returns
The generated target code, or NULL in case of failure.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::translate_material_expression ( ITransaction transaction,
const ICompiled_material material,
const char *  path,
const char *  fname,
IMdl_execution_context context 
)
pure virtual

Transforms an expression that is part of an MDL material instance to target code.

The prototype of the resulting function will roughly look like this:

void FNAME(
void *result,
void const *res_data,
void const *exception_state,
char const *arg_block_data);

The result buffer must be big enough for the expression result.

Parameters
transactionThe transaction to be used.
materialThe compiled MDL material.
pathThe path from the material root to the expression that should be translated, e.g., "geometry.displacement".
fnameThe name of the generated function. If NULL is passed, "lambda" will be used.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass compilation options to the MDL compiler. Currently, no options are supported by this operation. During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL.
Returns
The generated target code, or NULL in case of failure.