Member Functions

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

Creates a new link unit.

• The JIT backend is not available.

Parameters

transaction

The transaction to be used.

context

virtual const ITarget_code* mi::​neuraylib::​IMdl_backend::deserialize_target_code( ITransaction* transaction, const IBuffer* buffer, IMdl_execution_context* context) const [pure virtual]

Restores an instance of ITarget_code from a buffer. Deserialization can fail for outdated input date, which is not an error. Check the context messages for details.

Parameters

transaction

The transaction to be used.

buffer

The buffer containing the serialized target code to restore.

context

Returns

The restored object in case of success or NULL otherwise.

virtual const ITarget_code* mi::​neuraylib::​IMdl_backend::deserialize_target_code( ITransaction* transaction, const Uint8* buffer_data, Size buffer_size, IMdl_execution_context* context) const [pure virtual]

Restores an instance of ITarget_code from a buffer. Deserialization can fail for outdated input date, which is not an error. Check the context messages for details.

Parameters

transaction

The transaction to be used.

buffer_data

The buffer containing the serialized target code to restore.

buffer_size

The size of buffer_data.

context

Returns

The restored object in case of success or NULL otherwise.

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

size

The 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".

• "enable_auxiliary": Enable code generation for auxiliary methods on distribution functions. For BSDFs, these compute albedo approximations and normals. For EDFs, the functions exist only as placeholder for future use. Possible values: "on", "off". Default: "off".

• "enable_pdf": Enable code generation of PDF method on distribution functions. Possible values: "on", "off". Default: "on".

• "df_handle_slot_mode": When using light path expressions, individual parts of the distribution functions can be selected using "handles". The contribution of each of those parts has to be evaluated during rendering. This option controls how many parts are evaluated with each call into the generated "evaluate" and "auxiliary" functions and how the data is passed. Possible values: "none", "fixed_1", "fixed_2", "fixed_4", "fixed_8", and "pointer", while "pointer" is not available for all backends. Default: "none".

• "libbsdf_flags_in_bsdf_data": If enabled, the generated code will use the optional "flags" field in the BSDF data structures. Possible values: "on", "off". Default: "off".

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, native, GLSL and HLSL backend:

• "inline_aggressively": Enables/disables aggressive inlining. Possible values: "on", "off". Default: "off".

• "eval_dag_ternary_strictly": Enables/disables strict evaluation of ternary operators on the DAG. Possible values: "on", "off". Default: "on".

• "enable_exceptions": Enables/disables support for exceptions through runtime function calls on CPU. For GPU, this options is always treated as disabled. Possible values: "on", "off". Default: "off".

• "enable_ro_segment": Enables/disables the creation of the read-only data segment calls. Possible values: "on", "off". Default: "off".

• "max_const_data": Specifies the maximum size of a constant in bytes to be put into the generated code, if the "enable_ro_segment" option is enabled. Bigger constants will be moved into the read-only data segment. If the "glsl_max_const_data" option is also used, the read-only data segment has priority.

• "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".

• "visible_functions": Comma-separated list of function names which will be visible in the generated code (empty string means no special restriction). Can especially be used in combination with "llvm_renderer_module" binary option to limit the number of functions for which target code will be generated. Default: ""

• "use_renderer_adapt_normal": If enabled, the generated code expects the renderer to provide a function with the prototype "void adapt_normal(float result[3], Textue_handler_base const *self, Shading_state_material *state, float const normal[3])" which can adapt the normal of BSDFs. For native: The function must be set in the vtable of the Texture_handler_base object provided to the execute functions. If the built-in texture runtime is used, only the adapt_normal entry of the vtable needs to be set. For HLSL: The expected function is "float3 mdl_adapt_normal(Shading_state_material state, float3 normal)". Possible values: "on", "off". Default: "off".

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

• "lambda_return_mode": Selects how generated lambda functions return their results. Possible value: "default": Use the default mode for the backend, currently always sret mode "sret": Write the result into a buffer provided as first argument "value": Return the value directly. If the type is not supported as return type by the backend, fallback to sret mode. Currently only supports base types and vector types as return types.

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". "70", "75", "80", and "86". Default: "20".

• "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 mi_neuray_ptx_texture_lookup_call_modes 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 defined resource data struct is passed to all resource callbacks. This option is currently not supported. Possible values: "on", "off". Default: "off".

• "hlsl_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: "".

• "df_handle_slot_mode": The option "pointer" is not available (see above).

• "use_renderer_adapt_microfacet_roughness": If enabled, the generated code expects the renderer to provide a function with the prototype

  ‎   float2 mdl_adapt_microfacet_roughness(Shading_state_material state, float2 roughness_uv)

  which can adapt the roughness of microfacet BSDFs. For sheen_bsdf, the same roughness will be provided in both dimensions and only the x component of the result will be used. 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 for "core" and "compatibility" profiles: "150", "330", "400", "410", "420", "430", "440", "450", "460". Values for the "es" profile: "100", "300", "310". Default: "450".

• "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 size of a constant in bytes to be put into the generated GLSL code, if the "glsl_place_uniforms_into_ssbo" option is enabled. Bigger constants will be moved into the SSBO. If the "max_const_data" option is also used, the read-only data segment has priority. 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_uniform_ssbo_binding": A GLSL binding attribute expression for the SSBO buffer. Possible values: Currently limited to unsigned literals. Default: "" (Means no "binding" attribute)

  • "glsl_uniform_ssbo_set": A GLSL set attribute expression for the SSBO buffer. Possible values: Currently limited to unsigned literals. Default: "" (Means no "set" attribute)

• "glsl_use_resource_data": If enabled, an extra user defined resource data struct is passed to all resource callbacks. This option is currently not supported. Possible values: "on", "off". Default: "off".

• "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_OES_EGL_image_external"

• "GL_EXT_frag_depth"

• "GL_EXT_shader_texture_lod"

• "GL_EXT_shader_implicit_conversions"

• "GL_ARB_texture_rectangle"

• "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_3DL_array_objects"

• "GL_KHR_vulkan_glsl"

• "GL_NV_shader_buffer_load"

• "GL_NV_half_float"

• "GL_NV_gpu_shader5"

• "GL_AMD_gpu_shader_half_float"

• "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

Note:

In this version, state modes cannot be configured and are always fixed to "field"!

Parameters

name

The name of the option.

value

The 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.

• "llvm_renderer_module": Sets a user-defined LLVM renderer module which will be linked and optimized together with the generated code.

Parameters

name

The name of the option.

data

The data for the option. If NULL is passed, the option is cleared.

size

The 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,
         mi::neuraylib::Shading_state_environment const  *state,
         void const                                      *res_data,
         void const                                      *exception_state);

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

Parameters

transaction

The transaction to be used.

call

The MDL function call for the environment.

fname

The name of the generated function. If NULL is passed, "lambda" will be used.

context

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

lu

The link unit to translate.

context

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

transaction

The transaction to be used.

material

The compiled MDL material.

function_descriptions

The list of descriptions of function to translate.

description_count

The size of the list of descriptions.

context

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. For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf".

Parameters

transaction

The transaction to be used.

material

The compiled MDL material.

path

The path from the material root to the expression that should be translated, e.g., "surface.scattering".

base_fname

The base name of the generated functions. If NULL is passed, "lambda" will be used.

context

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,
         mi::neuraylib::Shading_state_material const  *state,
         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

transaction

The transaction to be used.

material

The compiled MDL material.

path

The path from the material root to the expression that should be translated, e.g., "geometry.displacement".

fname

The name of the generated function. If NULL is passed, "lambda" will be used.

context

Returns

The generated target code, or NULL in case of failure.