Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
MDL compiler

This module contains the MDL API components representing the MDL compiler, its backends and the generated target code. More...

Classes

class  mi::neuraylib::IMdl_backend
 MDL backends allow to transform compiled material instances or function calls into target code. More...
 
class  mi::neuraylib::ITarget_resource_callback
 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  mi::neuraylib::ITarget_argument_block
 Represents an argument block of a class-compiled material compiled for a specific target. More...
 
struct  mi::neuraylib::Target_value_layout_state
 Structure representing the state during traversal of the nested layout. More...
 
class  mi::neuraylib::ITarget_value_layout
 Represents the layout of an mi::neuraylib::ITarget_argument_block with support for nested elements. More...
 
class  mi::neuraylib::ITarget_code
 Represents target code of an MDL backend. More...
 
class  mi::neuraylib::ILink_unit
 Represents a link-unit of an MDL backend. More...
 
class  mi::neuraylib::IMdl_compiler
 The MDL compiler allows to register builtin modules. More...
 
struct  mi::neuraylib::tct_deriv< T >
 A template struct with derivatives. More...
 
struct  mi::neuraylib::tct_traits< with_derivatives >
 Helper traits struct to switch between derivative and non-derivative types. More...
 
struct  mi::neuraylib::Shading_state_environment
 The MDL environment state structure inside the MDL SDK is a representation of the renderer state in the context of an environment lookup as defined in section 19 "Renderer state" in the MDL specification. More...
 
struct  mi::neuraylib::Shading_state_material_impl< with_derivatives >
 The MDL material state structure inside the MDL SDK is a representation of the renderer state as defined in section 19 "Renderer state" in the MDL specification. More...
 
struct  mi::neuraylib::Texture_handler_vtable_impl< with_derivatives >
 The runtime for bitmap texture access for the generated target code can optionally be implemented in form of a vtable as specified by this structure. More...
 
struct  mi::neuraylib::Texture_handler_base
 The texture handler structure that is passed to the texturing functions. A user can derive from this structure and add custom fields as required by the texturing function implementations. More...
 
struct  mi::neuraylib::Texture_handler_deriv_base
 The texture handler structure that is passed to the texturing functions with derivative support. A user can derive from this structure and add custom fields as required by the texturing function implementations. More...
 
struct  mi::neuraylib::Resource_data
 The data structure providing access to resources for generated code. More...
 
struct  mi::neuraylib::Bsdf_sample_data
 Input and output structure for BSDF sampling data. More...
 
struct  mi::neuraylib::Bsdf_evaluate_data_base
 Input and output structure for BSDF evaluation data. More...
 
struct  mi::neuraylib::Bsdf_pdf_data
 Input and output structure for BSDF PDF calculation data. More...
 
struct  mi::neuraylib::Bsdf_auxiliary_data_base
 Input and output structure for BSDF auxiliary calculation data. More...
 
struct  mi::neuraylib::Edf_sample_data
 Input and output structure for EDF sampling data. More...
 
struct  mi::neuraylib::Edf_evaluate_data_base
 Input and output structure for EDF evaluation data. More...
 
struct  mi::neuraylib::Edf_pdf_data
 Input and output structure for EDF PDF calculation data. More...
 
struct  mi::neuraylib::Edf_auxiliary_data_base
 Input and output structure for EDF auxiliary calculation data. More...
 

Macros

#define MI_NEURAYLIB_BSDF_USE_MATERIAL_IOR   (-1.0f)
 The calling code can mark the x component of an IOR field in *_data with MI_NEURAYLIB_BSDF_USE_MATERIAL_IOR, to make the BSDF functions use the MDL material's IOR for this IOR field. More...
 

Typedefs

typedef float mi::neuraylib::tct_float
 A float. More...
 
typedef mi::Float32_2_struct mi::neuraylib::tct_float2
 A float2. More...
 
typedef mi::Float32_3_struct mi::neuraylib::tct_float3
 A float3. More...
 
typedef mi::Float32_4_struct mi::neuraylib::tct_float4
 A float4. More...
 
typedef mi::Sint32 mi::neuraylib::tct_int
 An int. More...
 
typedef mi::Uint32 mi::neuraylib::tct_uint
 An unsigned int. More...
 
typedef bool mi::neuraylib::tct_bool
 A bool. More...
 
typedef tct_traits< true >
::tct_derivable_float 
mi::neuraylib::tct_deriv_float
 A float with derivatives. More...
 
typedef tct_traits< true >
::tct_derivable_float2 
mi::neuraylib::tct_deriv_float2
 A float2 with derivatives. More...
 
typedef tct_traits< true >
::tct_derivable_float3 
mi::neuraylib::tct_deriv_float3
 A float3 with derivatives. More...
 
typedef tct_traits< true >
::tct_derivable_float4 
mi::neuraylib::tct_deriv_float4
 A float4 with derivatives. More...
 
typedef tct_deriv< float[2]> mi::neuraylib::tct_deriv_arr_float_2
 A float[2] with derivatives (needed to avoid problems with wrong alignment). More...
 
typedef tct_deriv< float[3]> mi::neuraylib::tct_deriv_arr_float_3
 A float[3] with derivatives (needed to avoid problems with wrong alignment). More...
 
typedef tct_deriv< float[4]> mi::neuraylib::tct_deriv_arr_float_4
 A float[4] with derivatives (needed to avoid problems with wrong alignment). More...
 
typedef struct
Shading_state_material_impl
< false > 
mi::neuraylib::Shading_state_material
 The MDL material state structure. More...
 
typedef struct
Shading_state_material_impl
< true > 
mi::neuraylib::Shading_state_material_with_derivs
 The MDL material state structure with derivatives for the texture coordinates. More...
 
typedef
Texture_handler_vtable_impl
< false > 
mi::neuraylib::Texture_handler_vtable
 The texture handler vtable struct. More...
 
typedef
Texture_handler_vtable_impl
< true > 
mi::neuraylib::Texture_handler_deriv_vtable
 The texture handler vtable struct with derivatives for the texture coordinates. More...
 
typedef void( mi::neuraylib::Environment_function )(void *result, Shading_state_environment const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of environment functions created via mi::neuraylib::IMdl_backend::translate_environment() and mi::neuraylib::ILink_unit::add_environment(). More...
 
typedef void( mi::neuraylib::Material_expr_function )(void *result, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of material expression functions created via mi::neuraylib::IMdl_backend::translate_material_expression() and mi::neuraylib::ILink_unit::add_material_expression(). More...
 
typedef void( mi::neuraylib::Material_expr_function_with_derivs )(void *result, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of material expression functions created via mi::neuraylib::IMdl_backend::translate_material_expression() and mi::neuraylib::ILink_unit::add_material_expression(). More...
 
typedef void( mi::neuraylib::Bsdf_init_function )(Shading_state_material *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_init_function_with_derivs )(Shading_state_material_with_derivs *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_sample_function )(Bsdf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_sample_function_with_derivs )(Bsdf_sample_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_evaluate_function )(Bsdf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_evaluate_function_with_derivs )(Bsdf_evaluate_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_pdf_function )(Bsdf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_pdf_function_with_derivs )(Bsdf_pdf_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_auxiliary_function )(Bsdf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Bsdf_auxiliary_function_with_derivs )(Bsdf_auxiliary_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_init_function )(Shading_state_material *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_init_function_with_derivs )(Shading_state_material_with_derivs *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_sample_function )(Edf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_sample_function_with_derivs )(Edf_sample_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_evaluate_function )(Edf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_evaluate_function_with_derivs )(Edf_evaluate_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_pdf_function )(Edf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_pdf_function_with_derivs )(Edf_pdf_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_auxiliary_function )(Edf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 
typedef void( mi::neuraylib::Edf_auxiliary_function_with_derivs )(Edf_auxiliary_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)
 Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df(). More...
 

Enumerations

enum  mi::neuraylib::ITarget_code::State_usage_property {
  mi::neuraylib::ITarget_code::SU_POSITION = 0x0001u,
  mi::neuraylib::ITarget_code::SU_NORMAL = 0x0002u,
  mi::neuraylib::ITarget_code::SU_GEOMETRY_NORMAL = 0x0004u,
  mi::neuraylib::ITarget_code::SU_MOTION = 0x0008u,
  mi::neuraylib::ITarget_code::SU_TEXTURE_COORDINATE = 0x0010u,
  mi::neuraylib::ITarget_code::SU_TEXTURE_TANGENTS = 0x0020u,
  mi::neuraylib::ITarget_code::SU_TANGENT_SPACE = 0x0040u,
  mi::neuraylib::ITarget_code::SU_GEOMETRY_TANGENTS = 0x0080u,
  mi::neuraylib::ITarget_code::SU_DIRECTION = 0x0100u,
  mi::neuraylib::ITarget_code::SU_ANIMATION_TIME = 0x0200u,
  mi::neuraylib::ITarget_code::SU_ROUNDED_CORNER_NORMAL = 0x0400u,
  mi::neuraylib::ITarget_code::SU_ALL_VARYING_MASK = 0x07FFu,
  mi::neuraylib::ITarget_code::SU_TRANSFORMS = 0x0800u,
  mi::neuraylib::ITarget_code::SU_OBJECT_ID = 0x1000u,
  mi::neuraylib::ITarget_code::SU_ALL_UNIFORM_MASK = 0x1800u
}
 The potential state usage properties. More...
 
enum  mi::neuraylib::ITarget_code::Texture_shape {
  mi::neuraylib::ITarget_code::Texture_shape_invalid = 0,
  mi::neuraylib::ITarget_code::Texture_shape_2d = 1,
  mi::neuraylib::ITarget_code::Texture_shape_3d = 2,
  mi::neuraylib::ITarget_code::Texture_shape_cube = 3,
  mi::neuraylib::ITarget_code::Texture_shape_ptex = 4,
  mi::neuraylib::ITarget_code::Texture_shape_bsdf_data = 5
}
 
enum  mi::neuraylib::ITarget_code::Prototype_language
 Language to use for the callable function prototype. More...
 
enum  mi::neuraylib::ITarget_code::Distribution_kind
 Possible kinds of distribution functions. More...
 
enum  mi::neuraylib::ITarget_code::Function_kind
 Possible kinds of callable functions. More...
 
enum  mi::neuraylib::ITarget_code::Gamma_mode
 Possible texture gamma modes. More...
 
enum  mi::neuraylib::Tex_wrap_mode {
  mi::neuraylib::TEX_WRAP_CLAMP = 0,
  mi::neuraylib::TEX_WRAP_REPEAT = 1,
  mi::neuraylib::TEX_WRAP_MIRRORED_REPEAT = 2,
  mi::neuraylib::TEX_WRAP_CLIP = 3
}
 The texture wrap modes as defined by tex::wrap_mode in the MDL specification. It determines the texture lookup behavior if a lookup coordinate is exceeding the normalized half-open texture space range of [0, 1). More...
 
enum  mi::neuraylib::Mbsdf_part {
  mi::neuraylib::MBSDF_DATA_REFLECTION = 0,
  mi::neuraylib::MBSDF_DATA_TRANSMISSION = 1
}
 MBSDFs can consist of two parts, which can be selected using this enumeration. More...
 
enum  mi::neuraylib::Bsdf_event_type
 The type of events created by BSDF importance sampling. More...
 
enum  mi::neuraylib::Df_handle_slot_mode {
  mi::neuraylib::DF_HSM_POINTER = -2,
  mi::neuraylib::DF_HSM_NONE = -1,
  mi::neuraylib::DF_HSM_FIXED_1 = 1,
  mi::neuraylib::DF_HSM_FIXED_2 = 2,
  mi::neuraylib::DF_HSM_FIXED_4 = 4,
  mi::neuraylib::DF_HSM_FIXED_8 = 8
}
 Type of Bsdf_evaluate_data variants, depending on the backend and its configuration. More...
 
enum  mi::neuraylib::Edf_event_type
 The type of events created by EDF importance sampling. More...
 

Functions

virtual Sint32 mi::neuraylib::IMdl_backend::set_option (const char *name, const char *value)=0
 Sets a backend option. More...
 
virtual Sint32 mi::neuraylib::IMdl_backend::set_option_binary (const char *name, const char *data, Size size)=0
 Sets a binary backend option. More...
 
virtual const Uint8 * mi::neuraylib::IMdl_backend::get_device_library (Size &size) const =0
 Returns the representation of a device library for this backend if one exists. More...
 
virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_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_code * mi::neuraylib::IMdl_backend::translate_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_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)=0
 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". More...
 
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)=0
 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. More...
 
virtual ILink_unit * mi::neuraylib::IMdl_backend::create_link_unit (ITransaction *transaction, IMdl_execution_context *context)=0
 Creates a new link unit. More...
 
virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_link_unit (const ILink_unit *lu, IMdl_execution_context *context)=0
 Transforms a link unit to target code. More...
 
virtual const ITarget_code * mi::neuraylib::IMdl_backend::deserialize_target_code (const IBuffer *buffer, IMdl_execution_context *context) const =0
 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. More...
 
virtual const ITarget_code * mi::neuraylib::IMdl_backend::deserialize_target_code (const Uint8 *buffer_data, Size buffer_size, IMdl_execution_context *context) const =0
 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. More...
 
virtual Uint32 mi::neuraylib::ITarget_resource_callback::get_resource_index (IValue_resource const *resource)=0
 Returns a resource index for the given resource value usable by the target code resource handler for the corresponding resource type. More...
 
virtual Uint32 mi::neuraylib::ITarget_resource_callback::get_string_index (IValue_string const *s)=0
 Returns a string identifier for the given string value usable by the target code. More...
 
virtual const char * mi::neuraylib::ITarget_argument_block::get_data () const =0
 Returns the target argument block data. More...
 
virtual char * mi::neuraylib::ITarget_argument_block::get_data ()=0
 Returns the target argument block data. More...
 
virtual Size mi::neuraylib::ITarget_argument_block::get_size () const =0
 Returns the size of the target argument block data. More...
 
virtual ITarget_argument_block * mi::neuraylib::ITarget_argument_block::clone () const =0
 Clones the argument block (to make it writeable). More...
 
virtual Size mi::neuraylib::ITarget_value_layout::get_size () const =0
 Returns the size of the target argument block. More...
 
virtual Size mi::neuraylib::ITarget_value_layout::get_num_elements (Target_value_layout_state state=Target_value_layout_state()) const =0
 Get the number of arguments / elements at the given layout state. More...
 
virtual Size mi::neuraylib::ITarget_value_layout::get_layout (IValue::Kind &kind, Size &arg_size, Target_value_layout_state state=Target_value_layout_state()) const =0
 Get the offset, the size and the kind of the argument / element inside the argument block at the given layout state. More...
 
virtual Target_value_layout_state mi::neuraylib::ITarget_value_layout::get_nested_state (Size i, Target_value_layout_state state=Target_value_layout_state()) const =0
 Get the layout state for the i'th argument / element inside the argument value block at the given layout state. More...
 
virtual Sint32 mi::neuraylib::ITarget_value_layout::set_value (char *block, IValue const *value, ITarget_resource_callback *resource_callback, Target_value_layout_state state=Target_value_layout_state()) const =0
 Set the value inside the given block at the given layout state. More...
 
virtual
IMdl_backend_api::Mdl_backend_kind 
mi::neuraylib::ITarget_code::get_backend_kind () const =0
 Returns the kind of backend this information belongs to. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_code () const =0
 Returns the represented target code in ASCII representation. More...
 
virtual Size mi::neuraylib::ITarget_code::get_code_size () const =0
 Returns the length of the represented target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_callable_function_count () const =0
 Returns the number of callable functions in the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_callable_function (Size index) const =0
 Returns the name of a callable function in the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_ro_data_segment_count () const =0
 Returns the number of constant data initializers. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_ro_data_segment_name (Size index) const =0
 Returns the name of the constant data segment at the given index. More...
 
virtual Size mi::neuraylib::ITarget_code::get_ro_data_segment_size (Size index) const =0
 Returns the size of the constant data segment at the given index. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_ro_data_segment_data (Size index) const =0
 Returns the data of the constant data segment at the given index. More...
 
virtual Size mi::neuraylib::ITarget_code::get_code_segment_count () const =0
 Returns the number of code segments of the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_code_segment (Size index) const =0
 Returns the represented target code segment in ASCII representation. More...
 
virtual Size mi::neuraylib::ITarget_code::get_code_segment_size (Size index) const =0
 Returns the length of the represented target code segment. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_code_segment_description (Size index) const =0
 Returns the description of the target code segment. More...
 
virtual State_usage mi::neuraylib::ITarget_code::get_render_state_usage () const =0
 Returns the potential render state usage of the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_argument_block_count () const =0
 Returns the number of target argument blocks. More...
 
virtual const
ITarget_argument_block * 
mi::neuraylib::ITarget_code::get_argument_block (Size index) const =0
 Get a target argument block if available. More...
 
virtual ITarget_argument_block * mi::neuraylib::ITarget_code::create_argument_block (Size index, const ICompiled_material *material, ITarget_resource_callback *resource_callback) const =0
 Create a new target argument block of the class-compiled material for this target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_argument_layout_count () const =0
 Returns the number of target argument block layouts. More...
 
virtual const
ITarget_value_layout * 
mi::neuraylib::ITarget_code::get_argument_block_layout (Size index) const =0
 Get a captured arguments block layout if available. More...
 
virtual Size mi::neuraylib::ITarget_code::get_string_constant_count () const =0
 Returns the number of string constants used by the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_string_constant (Size index) const =0
 Returns the string constant used by the target code. More...
 
virtual Uint32 mi::neuraylib::ITarget_code::get_known_resource_index (ITransaction *transaction, IValue_resource const *resource) const =0
 Returns the resource index for use in an ITarget_argument_block of resources already known when this ITarget_code object was generated. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_callable_function_prototype (Size index, Prototype_language lang) const =0
 Returns the prototype of a callable function in the target code. More...
 
virtual Distribution_kind mi::neuraylib::ITarget_code::get_callable_function_distribution_kind (Size index) const =0
 Returns the distribution kind of a callable function in the target code. More...
 
virtual Function_kind mi::neuraylib::ITarget_code::get_callable_function_kind (Size index) const =0
 Returns the function kind of a callable function in the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_callable_function_argument_block_index (Size index) const =0
 Get the index of the target argument block to use with a callable function. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::execute_environment (Size index, const Shading_state_environment &state, Texture_handler_base *tex_handler, Spectrum_struct *result) const =0
 Run this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::execute (Size index, const Shading_state_material &state, Texture_handler_base *tex_handler, const ITarget_argument_block *cap_args, void *result) const =0
 Run this code on the native CPU with the given captured arguments block. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::execute_bsdf_init (Size index, Shading_state_material &state, Texture_handler_base *tex_handler, const ITarget_argument_block *cap_args) const =0
 Run the BSDF init function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the BSDF sample function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the BSDF evaluation function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the BSDF PDF calculation function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the BSDF auxiliary calculation function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::execute_edf_init (Size index, Shading_state_material &state, Texture_handler_base *tex_handler, const ITarget_argument_block *cap_args) const =0
 Run the EDF init function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the EDF sample function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the EDF evaluation function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the EDF PDF calculation function for this code on the native CPU. More...
 
virtual Sint32 mi::neuraylib::ITarget_code::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
 Run the EDF auxiliary calculation function for this code on the native CPU. More...
 
virtual Size mi::neuraylib::ITarget_code::get_callable_function_df_handle_count (Size func_index) const =0
 Get the number of distribution function handles referenced by a callable function. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_callable_function_df_handle (Size func_index, Size handle_index) const =0
 Get the name of a distribution function handle referenced by a callable function. More...
 
virtual bool mi::neuraylib::ITarget_code::supports_serialization () const =0
 Indicates whether the target code can be serialized. Not all back-ends support serialization. More...
 
virtual const IBuffer * mi::neuraylib::ITarget_code::serialize (IMdl_execution_context *context) const =0
 Stores the data of this object in a buffer that can written to an external cache. The object can be restored by a corresponding back-end. More...
 
virtual State_usage mi::neuraylib::ITarget_code::get_callable_function_render_state_usage (Size index) const =0
 Returns the potential render state usage of callable function in the target code. More...
 
virtual Sint32 mi::neuraylib::ILink_unit::add_environment (const IFunction_call *call, const char *fname, IMdl_execution_context *context=0)=0
 Add an MDL environment function call as a function to this link unit. More...
 
virtual Sint32 mi::neuraylib::ILink_unit::add_material_expression (const ICompiled_material *inst, const char *path, const char *fname, IMdl_execution_context *context)=0
 Add an expression that is part of an MDL material instance as a function to this link unit. More...
 
virtual Sint32 mi::neuraylib::ILink_unit::add_material_df (const ICompiled_material *material, const char *path, const char *base_fname, IMdl_execution_context *context)=0
 Add an MDL distribution function to this link unit. Note that currently this is only supported for BSDFs. For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf". More...
 
virtual Sint32 mi::neuraylib::ILink_unit::add_material (const ICompiled_material *material, Target_function_description *function_descriptions, Size description_count, IMdl_execution_context *context)=0
 Add (multiple) MDL distribution functions and expressions of a material to this link unit. 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. More...
 

Variables

mi::Uint32 mi::neuraylib::Target_value_layout_state::m_state_offs
 The offset inside the layout state structure. More...
 
mi::Uint32 mi::neuraylib::Target_value_layout_state::m_data_offs
 The offset which needs to be added to the element data offset. More...
 
const char * mi::neuraylib::Target_function_description::path
 The path from the material root to the expression that should be translated, e.g., "surface.scattering". More...
 
const char * mi::neuraylib::Target_function_description::base_fname
 The base name of the generated functions. If NULL is passed, the function name will be 'lambda' followed by an increasing counter. Note, that this counter is tracked per link unit. That means, you need to provide functions names when using multiple link units in order to avoid collisions. More...
 
Size mi::neuraylib::Target_function_description::argument_block_index
 The index of argument block that belongs to the compiled material the function is generated from or ~0 if none of the added function required arguments. It allows to get the layout and a writable pointer to argument data. This is an output parameter which is available after adding the function to the link unit. More...
 
Size mi::neuraylib::Target_function_description::function_index
 The index of the generated function for accessing the callable function information of the link unit or ~0 if the selected function is an invalid distribution function. ~0 is not an error case, it just means, that evaluating the function will result in 0. In case the function is a distribution function, the returned index will be the index of the init function, while sample, evaluate, and pdf will be accessible by the consecutive indices, i.e., function_index + 1, function_index + 2, function_index + 3. This is an output parameter which is available after adding the function to the link unit. More...
 
ITarget_code::Distribution_kind mi::neuraylib::Target_function_description::distribution_kind
 Return the distribution kind of this function (or NONE in case expressions). This is an output parameter which is available after adding the function to the link unit. More...
 
Sint32 mi::neuraylib::Target_function_description::return_code
 A return code. For the meaning of the error codes correspond to the codes add_material_expression (code * 10) and add_material_df (code * 100). 0: Success. ~0: The function has not yet been processed -1: Invalid parameters (NULL pointer). -2: Invalid path (non-existing). -7: The backend does not implement this function, yet. More...
 

Texures

virtual Size mi::neuraylib::ITarget_code::get_texture_count () const =0
 Returns the number of texture resources used by the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_body_texture_count () const =0
 Returns the number of texture resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid texture). More...
 
virtual const char * mi::neuraylib::ITarget_code::get_texture (Size index) const =0
 Returns the name of a texture resource used by the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_texture_url (Size index) const =0
 Returns the MDL URL of a texture resource used by the target code if no database element is associated to the resource. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_texture_owner_module (Size index) const =0
 Returns the owner module name of a relative texture url. More...
 
virtual Gamma_mode mi::neuraylib::ITarget_code::get_texture_gamma (Size index) const =0
 Returns the gamma mode of a texture resource used by the target code. More...
 
virtual Texture_shape mi::neuraylib::ITarget_code::get_texture_shape (Size index) const =0
 Returns the texture shape of a given texture resource used by the target code. More...
 
virtual Df_data_kind mi::neuraylib::ITarget_code::get_texture_df_data_kind (Size index) const =0
 Returns the distribution function data kind of a given texture resource used by the target code. More...
 
virtual const Float32 * mi::neuraylib::ITarget_code::get_texture_df_data (Size index, Size &rx, Size &ry, Size &rz) const =0
 Returns the distribution function data this texture refers to. More...
 

Light profiles

virtual Size mi::neuraylib::ITarget_code::get_light_profile_count () const =0
 Returns the number of light profile resources used by the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_body_light_profile_count () const =0
 Returns the number of light profile resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid light profile). More...
 
virtual const char * mi::neuraylib::ITarget_code::get_light_profile (Size index) const =0
 Returns the name of a light profile resource used by the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_light_profile_url (Size index) const =0
 Returns the MDL URL of a light profile resource used by the target code if no database element is associated to the resource. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_light_profile_owner_module (Size index) const =0
 Returns the owner module name of a relative light profile URL. More...
 

BSDF measurements

virtual Size mi::neuraylib::ITarget_code::get_bsdf_measurement_count () const =0
 Returns the number of bsdf measurement resources used by the target code. More...
 
virtual Size mi::neuraylib::ITarget_code::get_body_bsdf_measurement_count () const =0
 Returns the number of BSDF measurement resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid BSDF measurement). More...
 
virtual const char * mi::neuraylib::ITarget_code::get_bsdf_measurement (Size index) const =0
 Returns the name of a bsdf measurement resource used by the target code. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_bsdf_measurement_url (Size index) const =0
 Returns the MDL URL of a BSDF measurement resource used by the target code if no database element is associated to the resource. More...
 
virtual const char * mi::neuraylib::ITarget_code::get_bsdf_measurement_owner_module (Size index) const =0
 Returns the owner module name of a relative BSDF measurement URL. More...
 

Detailed Description

This module contains the MDL API components representing the MDL compiler, its backends and the generated target code.

The MDL compiler can be obtained from mi::neuraylib::INeuray::get_api_component(). The backends can be obtained via the MDL backend API from mi::neuraylib::IMdl_backend_api::get_backend().

Macro Definition Documentation

#define MI_NEURAYLIB_BSDF_USE_MATERIAL_IOR   (-1.0f)

The calling code can mark the x component of an IOR field in *_data with MI_NEURAYLIB_BSDF_USE_MATERIAL_IOR, to make the BSDF functions use the MDL material's IOR for this IOR field.

Typedef Documentation

typedef void( mi::neuraylib::Bsdf_auxiliary_function)(Bsdf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_auxiliary_function_with_derivs)(Bsdf_auxiliary_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_evaluate_function)(Bsdf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_evaluate_function_with_derivs)(Bsdf_evaluate_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_init_function)(Shading_state_material *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_init_function_with_derivs)(Shading_state_material_with_derivs *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_pdf_function)(Bsdf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_pdf_function_with_derivs)(Bsdf_pdf_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_sample_function)(Bsdf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Bsdf_sample_function_with_derivs)(Bsdf_sample_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_auxiliary_function)(Edf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_auxiliary_function_with_derivs)(Edf_auxiliary_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the auxiliary function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_evaluate_function)(Edf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_evaluate_function_with_derivs)(Edf_evaluate_data_base *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the evaluation function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_init_function)(Shading_state_material *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_init_function_with_derivs)(Shading_state_material_with_derivs *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the initialization function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_pdf_function)(Edf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_pdf_function_with_derivs)(Edf_pdf_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the probability density function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_sample_function)(Edf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Edf_sample_function_with_derivs)(Edf_sample_data *data, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of the importance sampling function for material distribution functions created via mi::neuraylib::IMdl_backend::translate_material_df() and mi::neuraylib::ILink_unit::add_material_df().

Parameters
datathe input and output structure
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Environment_function)(void *result, Shading_state_environment const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of environment functions created via mi::neuraylib::IMdl_backend::translate_environment() and mi::neuraylib::ILink_unit::add_environment().

Parameters
resultpointer to the result buffer which must be large enough for the result
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_dataunused, should be NULL
typedef void( mi::neuraylib::Material_expr_function)(void *result, Shading_state_material const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of material expression functions created via mi::neuraylib::IMdl_backend::translate_material_expression() and mi::neuraylib::ILink_unit::add_material_expression().

Parameters
resultpointer to the result buffer which must be large enough for the result
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef void( mi::neuraylib::Material_expr_function_with_derivs)(void *result, Shading_state_material_with_derivs const *state, Resource_data const *res_data, void const *exception_state, char const *arg_block_data)

Signature of material expression functions created via mi::neuraylib::IMdl_backend::translate_material_expression() and mi::neuraylib::ILink_unit::add_material_expression().

Parameters
resultpointer to the result buffer which must be large enough for the result
statethe shading state
res_datathe resources
exception_stateunused, should be NULL
arg_block_datathe target argument block data, if class compilation was used
typedef struct Shading_state_material_impl< false > mi::neuraylib::Shading_state_material

The MDL material state structure.

typedef struct Shading_state_material_impl< true > mi::neuraylib::Shading_state_material_with_derivs

The MDL material state structure with derivatives for the texture coordinates.

A bool.

typedef tct_deriv<float[2]> mi::neuraylib::tct_deriv_arr_float_2

A float[2] with derivatives (needed to avoid problems with wrong alignment).

typedef tct_deriv<float[3]> mi::neuraylib::tct_deriv_arr_float_3

A float[3] with derivatives (needed to avoid problems with wrong alignment).

typedef tct_deriv<float[4]> mi::neuraylib::tct_deriv_arr_float_4

A float[4] with derivatives (needed to avoid problems with wrong alignment).

typedef tct_traits<true>::tct_derivable_float mi::neuraylib::tct_deriv_float

A float with derivatives.

typedef tct_traits<true>::tct_derivable_float2 mi::neuraylib::tct_deriv_float2

A float2 with derivatives.

typedef tct_traits<true>::tct_derivable_float3 mi::neuraylib::tct_deriv_float3

A float3 with derivatives.

typedef tct_traits<true>::tct_derivable_float4 mi::neuraylib::tct_deriv_float4

A float4 with derivatives.

typedef float mi::neuraylib::tct_float

A float.

An unsigned int.

typedef Texture_handler_vtable_impl<true> mi::neuraylib::Texture_handler_deriv_vtable

The texture handler vtable struct with derivatives for the texture coordinates.

typedef Texture_handler_vtable_impl<false> mi::neuraylib::Texture_handler_vtable

The texture handler vtable struct.

Enumeration Type Documentation

The type of events created by BSDF importance sampling.

Type of Bsdf_evaluate_data variants, depending on the backend and its configuration.

Enumerator
DF_HSM_POINTER 

Uses renderer defined buffers; not supported by all backends.

DF_HSM_NONE 

No slots, handles are ignored completely.

DF_HSM_FIXED_1 

fixed size array for processing 1 handle at a time

DF_HSM_FIXED_2 

fixed size array for processing 2 handle at a time

DF_HSM_FIXED_4 

fixed size array for processing 4 handle at a time

DF_HSM_FIXED_8 

fixed size array for processing 8 handle at a time

Possible kinds of distribution functions.

The type of events created by EDF importance sampling.

Possible kinds of callable functions.

Possible texture gamma modes.

MBSDFs can consist of two parts, which can be selected using this enumeration.

Enumerator
MBSDF_DATA_REFLECTION 

the bidirectional reflection distribution function (BRDF)

MBSDF_DATA_TRANSMISSION 

the bidirectional transmission distribution function (BTDF)

Language to use for the callable function prototype.

The potential state usage properties.

Enumerator
SU_POSITION 

uses state::position()

SU_NORMAL 

uses state::normal()

SU_GEOMETRY_NORMAL 

uses state::geometry_normal()

SU_MOTION 

uses state::motion()

SU_TEXTURE_COORDINATE 

uses state::texture_coordinate()

SU_TEXTURE_TANGENTS 

uses state::texture_tangent_*()

SU_TANGENT_SPACE 

uses state::tangent_space()

SU_GEOMETRY_TANGENTS 

uses state::geometry_tangent_*()

SU_DIRECTION 

uses state::direction()

SU_ANIMATION_TIME 

uses state::animation_time()

SU_ROUNDED_CORNER_NORMAL 

uses state::rounded_corner_normal()

SU_ALL_VARYING_MASK 

set of varying states

SU_TRANSFORMS 

uses uniform state::transform*()

SU_OBJECT_ID 

uses uniform state::object_id()

SU_ALL_UNIFORM_MASK 

set of uniform states

The texture wrap modes as defined by tex::wrap_mode in the MDL specification. It determines the texture lookup behavior if a lookup coordinate is exceeding the normalized half-open texture space range of [0, 1).

Enumerator
TEX_WRAP_CLAMP 

tex::wrap_clamp: clamps the lookup coordinate to the range

TEX_WRAP_REPEAT 

tex::wrap_repeat: takes the fractional part of the lookup coordinate effectively repeating the texture along this axis

TEX_WRAP_MIRRORED_REPEAT 

tex::wrap_mirrored_repeat: like wrap_repeat but takes one minus the fractional part every other interval to mirror every second instance of the texture

TEX_WRAP_CLIP 

tex::wrap_clip: makes the texture lookup return zero for texture coordinates outside of the range

Enumerator
Texture_shape_invalid 

Invalid texture.

Texture_shape_2d 

Two-dimensional texture.

Texture_shape_3d 

Three-dimensional texture.

Texture_shape_cube 

Cube map texture.

Texture_shape_ptex 

PTEX texture.

Texture_shape_bsdf_data 

Three-dimensional texture representing a BSDF data table.

Function Documentation

virtual Sint32 mi::neuraylib::ILink_unit::add_environment ( const IFunction_call call,
const char *  fname,
IMdl_execution_context context = 0 
)
pure virtual

Add an MDL environment function call as a function to this link unit.

Parameters
callThe MDL function call for the environment.
fnameThe name of the function that is created.
[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 compilation messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
  • Invalid parameters (NULL pointer).
  • Invalid expression.
  • The backend failed to compile the function.
Returns
A return code. The return codes have the following meaning:
virtual Sint32 mi::neuraylib::ILink_unit::add_material ( const ICompiled_material material,
Target_function_description *  function_descriptions,
Size  description_count,
IMdl_execution_context context 
)
pure virtual

Add (multiple) MDL distribution functions and expressions of a material to this link unit. 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
materialThe compiled MDL material.
[in,out]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
A return code. The error codes have the following meaning:
Note
Upon unsuccessful return, function_descriptions.return_code might contain further info.
virtual Sint32 mi::neuraylib::ILink_unit::add_material_df ( const ICompiled_material material,
const char *  path,
const char *  base_fname,
IMdl_execution_context context 
)
pure virtual

Add an MDL distribution function to this link unit. 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
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 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. Possible error conditions:
  • Invalid parameters (NULL pointer).
  • Invalid path (non-existing).
  • The backend failed to generate target code for the material.
  • The requested expression is a constant.
  • Only distribution functions are allowed.
  • The backend does not support compiled MDL materials obtained from class compilation mode.
  • The backend does not implement this function, yet.
  • VDFs are not supported.
  • The requested DF is not supported, yet.
Returns
A return code. The return codes have the following meaning:
virtual Sint32 mi::neuraylib::ILink_unit::add_material_expression ( const ICompiled_material inst,
const char *  path,
const char *  fname,
IMdl_execution_context context 
)
pure virtual

Add an expression that is part of an MDL material instance as a function to this link unit.

Parameters
instThe compiled MDL material instance.
pathThe path from the material root to the expression that should be translated, e.g., "geometry.displacement".
fnameThe name of the function that is created.
[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 compilation messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
  • The JIT backend is not available.
  • Invalid field name (non-existing).
  • invalid function name.
  • The JIT backend failed to compile the function.
  • The requested expression is a constant.
  • Neither BSDFs, EDFs, VDFs, nor resource type expressions can be compiled.
Returns
A return code. The return codes have the following meaning:
virtual ITarget_argument_block* mi::neuraylib::ITarget_argument_block::clone ( ) const
pure virtual

Clones the argument block (to make it writeable).

virtual ITarget_argument_block* mi::neuraylib::ITarget_code::create_argument_block ( Size  index,
const ICompiled_material material,
ITarget_resource_callback resource_callback 
) const
pure virtual

Create a new target argument block of the class-compiled material for this target code.

Parameters
indexThe index of the base target argument block of this target code.
materialThe class-compiled MDL material which has to fit to this ITarget_code, i.e. the hash of the compiled material must be identical to the one used to generate this ITarget_code.
resource_callbackCallback for retrieving resource indices for resource values.
Returns
the generated target argument block or NULL if no arguments were captured or the index was invalid.
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. The following options are supported for this operation:
  • "internal_space"
  • "fold_meters_per_scene_unit"
  • "meters_per_scene_unit"
  • "wavelength_min"
  • "wavelength_max" During material translation, messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
  • 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::deserialize_target_code ( 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
bufferThe buffer containing the serialized target code to restore.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass serialization options. Currently there are no options supported for this operation. During the serialization messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
  • Serialization is not supported for this kind of back-end.
  • Corrupt input data, invalid header. Expected failure conditions that raise an info message:
  • Protocol version mismatch, deserialization invalid.
  • MDL SDK version mismatch, deserialization invalid.
Returns
The restored object in case of success or NULL otherwise.
virtual const ITarget_code* mi::neuraylib::IMdl_backend::deserialize_target_code ( 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
buffer_dataThe buffer containing the serialized target code to restore.
buffer_sizeThe size of buffer_data.
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass serialization options. Currently there are no options supported for this operation. During the serialization messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
  • Serialization is not supported for this kind of back-end.
  • Corrupt input data, invalid header. Expected failure conditions that raise an info message:
  • Protocol version mismatch, deserialization invalid.
  • MDL SDK version mismatch, deserialization invalid.
Returns
The restored object in case of success or NULL otherwise.
virtual Sint32 mi::neuraylib::ITarget_code::execute ( Size  index,
const Shading_state_material state,
Texture_handler_base tex_handler,
const ITarget_argument_block cap_args,
void *  result 
) const
pure virtual

Run this code on the native CPU with the given captured arguments block.

Parameters
[in]indexThe index of the callable function.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object will be used, if any.
[out]resultThe result will be written to.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given index does not refer to a material expression
Note
This allows to execute any compiled function on the CPU. The result must be big enough to take the functions result.
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the BSDF auxiliary calculation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the BSDF auxiliary calculation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a BSDF PDF calculation function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the BSDF evaluation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the BSDF evaluation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a BSDF evaluation function
virtual Sint32 mi::neuraylib::ITarget_code::execute_bsdf_init ( Size  index,
Shading_state_material state,
Texture_handler_base tex_handler,
const ITarget_argument_block cap_args 
) const
pure virtual

Run the BSDF init function for this code on the native CPU.

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
[in]indexThe index of the callable function.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a BSDF init function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the BSDF PDF calculation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the BSDF PDF calculation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a BSDF PDF calculation function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the BSDF sample function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the BSDF sampling.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a BSDF sample function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the EDF auxiliary calculation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the EDF auxiliary calculation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a EDF PDF calculation function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the EDF evaluation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the EDF evaluation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a EDF evaluation function
virtual Sint32 mi::neuraylib::ITarget_code::execute_edf_init ( Size  index,
Shading_state_material state,
Texture_handler_base tex_handler,
const ITarget_argument_block cap_args 
) const
pure virtual

Run the EDF init function for this code on the native CPU.

This function updates the normal field of the shading state with the result of "geometry.normal" and, if the "num_texture_results" backend option has been set to non-zero, fills the text_results fields of the state.

Parameters
[in]indexThe index of the callable function.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a EDF init function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the EDF PDF calculation function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the EDF PDF calculation.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a EDF PDF calculation function
virtual Sint32 mi::neuraylib::ITarget_code::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
pure virtual

Run the EDF sample function for this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in,out]dataThe input and output fields for the EDF sampling.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]cap_argsThe captured arguments to use for the execution. If cap_args is NULL, the captured arguments of this ITarget_code object for the given callable function will be used, if any.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given function is not a EDF sample function
virtual Sint32 mi::neuraylib::ITarget_code::execute_environment ( Size  index,
const Shading_state_environment state,
Texture_handler_base tex_handler,
Spectrum_struct result 
) const
pure virtual

Run this code on the native CPU.

Parameters
[in]indexThe index of the callable function.
[in]stateThe core state.
[in]tex_handlerTexture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[out]resultThe result will be written to.
Returns
  • 0: on success
  • -1: if execution was aborted by runtime error
  • -2: cannot execute: not native code or the given index does not refer to an environment function.
Note
This allows to execute any compiled function on the CPU.
virtual const ITarget_argument_block* mi::neuraylib::ITarget_code::get_argument_block ( Size  index) const
pure virtual

Get a target argument block if available.

Parameters
indexThe index of the target argument block.
Returns
the captured argument block or NULL if no arguments were captured or the index was invalid.
virtual Size mi::neuraylib::ITarget_code::get_argument_block_count ( ) const
pure virtual

Returns the number of target argument blocks.

virtual const ITarget_value_layout* mi::neuraylib::ITarget_code::get_argument_block_layout ( Size  index) const
pure virtual

Get a captured arguments block layout if available.

Parameters
indexThe index of the target argument block.
Returns
the layout or NULL if no arguments were captured or the index was invalid.
virtual Size mi::neuraylib::ITarget_code::get_argument_layout_count ( ) const
pure virtual

Returns the number of target argument block layouts.

virtual IMdl_backend_api::Mdl_backend_kind mi::neuraylib::ITarget_code::get_backend_kind ( ) const
pure virtual

Returns the kind of backend this information belongs to.

virtual Size mi::neuraylib::ITarget_code::get_body_bsdf_measurement_count ( ) const
pure virtual

Returns the number of BSDF measurement resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid BSDF measurement).

Returns
The body BSDF measurement count or ~0ull, if the value is invalid due to more than one call to a link unit add function.
virtual Size mi::neuraylib::ITarget_code::get_body_light_profile_count ( ) const
pure virtual

Returns the number of light profile resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid light profile).

Returns
The body light profile count or ~0ull, if the value is invalid due to more than one call to a link unit add function.
virtual Size mi::neuraylib::ITarget_code::get_body_texture_count ( ) const
pure virtual

Returns the number of texture resources coming from the body of expressions (not solely from material arguments). These will be necessary regardless of the chosen material arguments and start at index 0 (including the invalid texture).

Returns
The body texture count or ~0ull, if the value is invalid due to more than one call to a link unit add function.
virtual const char* mi::neuraylib::ITarget_code::get_bsdf_measurement ( Size  index) const
pure virtual

Returns the name of a bsdf measurement resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The name of the DB element associated the bsdf measurement resource of the given index, or NULL if index is out of range.
virtual Size mi::neuraylib::ITarget_code::get_bsdf_measurement_count ( ) const
pure virtual

Returns the number of bsdf measurement resources used by the target code.

virtual const char* mi::neuraylib::ITarget_code::get_bsdf_measurement_owner_module ( Size  index) const
pure virtual

Returns the owner module name of a relative BSDF measurement URL.

Parameters
indexThe index of the BSDF measurement resource.
Returns
The owner module name of the BSDF measurement resource of the given index, or NULL if index is out of range or the owner module is not provided.
virtual const char* mi::neuraylib::ITarget_code::get_bsdf_measurement_url ( Size  index) const
pure virtual

Returns the MDL URL of a BSDF measurement resource used by the target code if no database element is associated to the resource.

Parameters
indexThe index of the BSDF measurement resource.
Returns
The MDL URL of the BSDF measurement resource of the given index, or NULL if index is out of range or the BSDF measurement exists in the database.
virtual const char* mi::neuraylib::ITarget_code::get_callable_function ( Size  index) const
pure virtual

Returns the name of a callable function in the target code.

The name of a callable function is specified via the fname parameter of mi::neuraylib::IMdl_backend::translate_environment() and mi::neuraylib::IMdl_backend::translate_material_expression().

Parameters
indexThe index of the callable function.
Returns
The name of the index -th callable function, or NULL if index is out of bounds.
virtual Size mi::neuraylib::ITarget_code::get_callable_function_argument_block_index ( Size  index) const
pure virtual

Get the index of the target argument block to use with a callable function.

Note
All DF_* functions of one material DF use the same target argument block.
Parameters
indexThe index of the callable function.
Returns
The index of the target argument block for this function or ~0 if not used.
virtual Size mi::neuraylib::ITarget_code::get_callable_function_count ( ) const
pure virtual

Returns the number of callable functions in the target code.

virtual const char* mi::neuraylib::ITarget_code::get_callable_function_df_handle ( Size  func_index,
Size  handle_index 
) const
pure virtual

Get the name of a distribution function handle referenced by a callable function.

Parameters
func_indexThe index of the callable function.
handle_indexThe index of the handle.
Returns
The name of the distribution function handle or NULL, if the callable function is not a distribution function or index is invalid.
virtual Size mi::neuraylib::ITarget_code::get_callable_function_df_handle_count ( Size  func_index) const
pure virtual

Get the number of distribution function handles referenced by a callable function.

Parameters
func_indexThe index of the callable function.
Returns
The number of distribution function handles referenced or 0, if the callable function is not a distribution function.
virtual Distribution_kind mi::neuraylib::ITarget_code::get_callable_function_distribution_kind ( Size  index) const
pure virtual

Returns the distribution kind of a callable function in the target code.

Parameters
indexThe index of the callable function.
Returns
The distribution kind of the callable function or DK_INVALID if index was invalid.
virtual Function_kind mi::neuraylib::ITarget_code::get_callable_function_kind ( Size  index) const
pure virtual

Returns the function kind of a callable function in the target code.

Parameters
indexThe index of the callable function.
Returns
The kind of the callable function or FK_INVALID if index was invalid.
virtual const char* mi::neuraylib::ITarget_code::get_callable_function_prototype ( Size  index,
Prototype_language  lang 
) const
pure virtual

Returns the prototype of a callable function in the target code.

Parameters
indexThe index of the callable function.
langThe language to use for the prototype.
Returns
The prototype or NULL if index is out of bounds or lang cannot be used for this target code.
virtual State_usage mi::neuraylib::ITarget_code::get_callable_function_render_state_usage ( Size  index) const
pure virtual

Returns the potential render state usage of callable function in the target code.

If the corresponding property bit is not set, it is guaranteed that the code does not use the associated render state property.

Returns
The potential render state usage of the callable function or 0 if index was invalid.
virtual const char* mi::neuraylib::ITarget_code::get_code ( ) const
pure virtual

Returns the represented target code in ASCII representation.

virtual const char* mi::neuraylib::ITarget_code::get_code_segment ( Size  index) const
pure virtual

Returns the represented target code segment in ASCII representation.

Parameters
indexThe index of the code segment.
Returns
The code segment or NULL if the index is out of bounds.
virtual Size mi::neuraylib::ITarget_code::get_code_segment_count ( ) const
pure virtual

Returns the number of code segments of the target code.

virtual const char* mi::neuraylib::ITarget_code::get_code_segment_description ( Size  index) const
pure virtual

Returns the description of the target code segment.

Parameters
indexThe index of the code segment.
Returns
The code segment description or NULL if the index is out of bounds.
virtual Size mi::neuraylib::ITarget_code::get_code_segment_size ( Size  index) const
pure virtual

Returns the length of the represented target code segment.

Parameters
indexThe index of the code segment.
Returns
The size of the code segment or 0 if the index is out of bounds.
virtual Size mi::neuraylib::ITarget_code::get_code_size ( ) const
pure virtual

Returns the length of the represented target code.

virtual const char* mi::neuraylib::ITarget_argument_block::get_data ( ) const
pure virtual

Returns the target argument block data.

virtual char* mi::neuraylib::ITarget_argument_block::get_data ( )
pure virtual

Returns the target argument block data.

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 Uint32 mi::neuraylib::ITarget_code::get_known_resource_index ( ITransaction transaction,
IValue_resource const *  resource 
) const
pure virtual

Returns the resource index for use in an ITarget_argument_block of resources already known when this ITarget_code object was generated.

Parameters
transactionTransaction to retrieve resource names from tags.
resourceThe resource value.
virtual Size mi::neuraylib::ITarget_value_layout::get_layout ( IValue::Kind kind,
Size arg_size,
Target_value_layout_state  state = Target_value_layout_state() 
) const
pure virtual

Get the offset, the size and the kind of the argument / element inside the argument block at the given layout state.

Parameters
[out]kindReceives the kind of the argument.
[out]arg_sizeReceives the size of the argument.
stateThe layout state representing the current nesting within the argument value block. The default value is used for the top-level.
Returns
the offset of the requested argument / element or "~mi::Size(0)" if the state is invalid.
virtual const char* mi::neuraylib::ITarget_code::get_light_profile ( Size  index) const
pure virtual

Returns the name of a light profile resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The name of the DB element associated the light profile resource of the given index, or NULL if index is out of range.
virtual Size mi::neuraylib::ITarget_code::get_light_profile_count ( ) const
pure virtual

Returns the number of light profile resources used by the target code.

virtual const char* mi::neuraylib::ITarget_code::get_light_profile_owner_module ( Size  index) const
pure virtual

Returns the owner module name of a relative light profile URL.

Parameters
indexThe index of the light profile resource.
Returns
The owner module name of the light profile resource of the given index, or NULL if index is out of range or the owner module is not provided.
virtual const char* mi::neuraylib::ITarget_code::get_light_profile_url ( Size  index) const
pure virtual

Returns the MDL URL of a light profile resource used by the target code if no database element is associated to the resource.

Parameters
indexThe index of the light profile resource.
Returns
The MDL URL of the light profile resource of the given index, or NULL if index is out of range or the light profile exists in the database.
virtual Target_value_layout_state mi::neuraylib::ITarget_value_layout::get_nested_state ( Size  i,
Target_value_layout_state  state = Target_value_layout_state() 
) const
pure virtual

Get the layout state for the i'th argument / element inside the argument value block at the given layout state.

Parameters
iThe index of the argument / element.
stateThe layout state representing the current nesting within the argument value block. The default value is used for the top-level.
Returns
the layout state for the nested element or a state with "~mi::Uint32(0)" as m_state_offs if the element is atomic.
virtual Size mi::neuraylib::ITarget_value_layout::get_num_elements ( Target_value_layout_state  state = Target_value_layout_state()) const
pure virtual

Get the number of arguments / elements at the given layout state.

Parameters
stateThe layout state representing the current nesting within the argument value block. The default value is used for the top-level.
virtual State_usage mi::neuraylib::ITarget_code::get_render_state_usage ( ) const
pure virtual

Returns the potential render state usage of the target code.

If the corresponding property bit is not set, it is guaranteed that the code does not use the associated render state property.

virtual Uint32 mi::neuraylib::ITarget_resource_callback::get_resource_index ( IValue_resource const *  resource)
pure virtual

Returns a resource index for the given resource value usable by the target code resource handler for the corresponding resource type.

The index 0 is always an invalid resource reference. For mi::neuraylib::IValue_texture values, the first indices correspond to the indices used with mi::neuraylib::ITarget_code::get_texture(). For mi::mdl::IValue_light_profile values, the first indices correspond to the indices used with mi::neuraylib::ITarget_code::get_light_profile(). For mi::mdl::IValue_bsdf_measurement values, the first indices correspond to the indices used with mi::neuraylib::ITarget_code::get_bsdf_measurement().

You can use mi::neuraylib::ITarget_code::get_known_resource_index() to handle resources which were known during compilation of the target code object.

See Texture lookup call modes of the PTX backend for more details about texture handlers for the PTX backend. See Example for Execution of Compiled MDL Materials (GLSL) for more details about texture handlers for the GLSL backend.

Parameters
resourcethe resource value
Returns
a resource index or 0 if no resource index can be returned
virtual Size mi::neuraylib::ITarget_code::get_ro_data_segment_count ( ) const
pure virtual

Returns the number of constant data initializers.

virtual const char* mi::neuraylib::ITarget_code::get_ro_data_segment_data ( Size  index) const
pure virtual

Returns the data of the constant data segment at the given index.

Parameters
indexThe index of the data segment.
Returns
The data of the constant data segment or NULL if the index is out of bounds.
virtual const char* mi::neuraylib::ITarget_code::get_ro_data_segment_name ( Size  index) const
pure virtual

Returns the name of the constant data segment at the given index.

Parameters
indexThe index of the data segment.
Returns
The name of the constant data segment or NULL if the index is out of bounds.
virtual Size mi::neuraylib::ITarget_code::get_ro_data_segment_size ( Size  index) const
pure virtual

Returns the size of the constant data segment at the given index.

Parameters
indexThe index of the data segment.
Returns
The size of the constant data segment or 0 if the index is out of bounds.
virtual Size mi::neuraylib::ITarget_argument_block::get_size ( ) const
pure virtual

Returns the size of the target argument block data.

virtual Size mi::neuraylib::ITarget_value_layout::get_size ( ) const
pure virtual

Returns the size of the target argument block.

virtual const char* mi::neuraylib::ITarget_code::get_string_constant ( Size  index) const
pure virtual

Returns the string constant used by the target code.

Parameters
indexThe index of the string constant.
Returns
The string constant that is represented by the given index, or NULL if index is out of range.
virtual Size mi::neuraylib::ITarget_code::get_string_constant_count ( ) const
pure virtual

Returns the number of string constants used by the target code.

virtual Uint32 mi::neuraylib::ITarget_resource_callback::get_string_index ( IValue_string const *  s)
pure virtual

Returns a string identifier for the given string value usable by the target code.

The value 0 is always the "not known string".

Parameters
sthe string value
virtual const char* mi::neuraylib::ITarget_code::get_texture ( Size  index) const
pure virtual

Returns the name of a texture resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The name of the DB element associated the texture resource of the given index, or NULL if index is out of range or the texture does not exist in the database.
virtual Size mi::neuraylib::ITarget_code::get_texture_count ( ) const
pure virtual

Returns the number of texture resources used by the target code.

virtual const Float32* mi::neuraylib::ITarget_code::get_texture_df_data ( Size  index,
Size rx,
Size ry,
Size rz 
) const
pure virtual

Returns the distribution function data this texture refers to.

Note
Calling this function is only meaningful in case get_texture_shape() returns mi::neuraylib::ITarget_code::Texture_shape_bsdf_data.
Parameters
indexThe index of the texture resource.
[out]rxThe resolution of the texture in x.
[out]ryThe resolution of the texture in y.
[out]rzThe resolution of the texture in z.
Returns
A pointer to the texture data, if the texture is a distribution function data texture, NULL otherwise.
virtual Df_data_kind mi::neuraylib::ITarget_code::get_texture_df_data_kind ( Size  index) const
pure virtual

Returns the distribution function data kind of a given texture resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The distribution function data kind of the texture resource of the given index, or DFK_INVALID if index is out of range.
virtual Gamma_mode mi::neuraylib::ITarget_code::get_texture_gamma ( Size  index) const
pure virtual

Returns the gamma mode of a texture resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The gamma of the texture resource of the given index, or GM_GAMMA_UNKNOWN if index is out of range.
virtual const char* mi::neuraylib::ITarget_code::get_texture_owner_module ( Size  index) const
pure virtual

Returns the owner module name of a relative texture url.

Parameters
indexThe index of the texture resource.
Returns
The owner module name of the texture resource of the given index, or NULL if index is out of range or the owner module is not provided.
virtual Texture_shape mi::neuraylib::ITarget_code::get_texture_shape ( Size  index) const
pure virtual

Returns the texture shape of a given texture resource used by the target code.

Parameters
indexThe index of the texture resource.
Returns
The shape of the texture resource of the given index, or Texture_shape_invalid if index is out of range.
virtual const char* mi::neuraylib::ITarget_code::get_texture_url ( Size  index) const
pure virtual

Returns the MDL URL of a texture resource used by the target code if no database element is associated to the resource.

Parameters
indexThe index of the texture resource.
Returns
The MDL URL of the texture resource of the given index, or NULL if index is out of range or the texture exists in the database.
virtual const IBuffer* mi::neuraylib::ITarget_code::serialize ( IMdl_execution_context context) const
pure virtual

Stores the data of this object in a buffer that can written to an external cache. The object can be restored by a corresponding back-end.

Parameters
[in,out]contextA pointer to an mi::neuraylib::IMdl_execution_context which can be used to pass serialization options. The following options are supported for this operation:
  • bool "serialize_class_instance_data": If true, the argument block, resources, and strings in class instance parameters are serialized as well. Otherwise only body information are stored, which is sufficient to create new argument blocks for a material class. Default: true. During the serialization messages like errors and warnings will be passed to the context for later evaluation by the caller. Can be NULL. Possible error conditions:
    • Serialization is not supported for this kind of back-end.
Returns
The buffer in case of success and NULL otherwise.
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".
  • "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". 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 and HLSL backend:

  • "inline_aggressively": Enables/disables aggressive inlining. Possible values: "on", "off". Default: "off".
  • "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".
  • "scene_data_names": Comma-separated list of names for which scene data may be available in the renderer. For names not in the list, scene::data_isvalid will always return false and the scene::data_lookup_* functions will always return the provided default value. Use "*" to specify that scene data for any name may be available. Default: ""
  • "visible_names": Comma-separated list of names functions 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: ""

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 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".
  • "df_handle_slot_mode": The option "pointer" is not available (see above).

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: "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.
  • "llvm_renderer_module": Sets a user-defined LLVM renderer module which will be linked and optimized together with the generated code.
Parameters
nameThe name of the option.
dataThe data for the option. If NULL is passed, the option is cleared.
sizeThe size of the data.
Returns
  • 0: Success.
  • -1: Unknown option.
  • -2: Unsupported value.
virtual Sint32 mi::neuraylib::ITarget_value_layout::set_value ( char *  block,
IValue const *  value,
ITarget_resource_callback resource_callback,
Target_value_layout_state  state = Target_value_layout_state() 
) const
pure virtual

Set the value inside the given block at the given layout state.

Parameters
[in,out]blockThe argument value block buffer to be modified.
[in]valueThe value to be set. It has to match the expected kind.
[in]resource_callbackCallback for retrieving resource indices for resource values.
[in]stateThe layout state representing the current nesting within the argument value block. The default value is used for the top-level.
Returns
  • 0: Success.
  • -1: Invalid parameters, block or value is a NULL pointer.
  • -2: Invalid state provided.
  • -3: Value kind does not match expected kind.
  • -4: Size of compound value does not match expected size.
  • -5: Unsupported value type.
virtual bool mi::neuraylib::ITarget_code::supports_serialization ( ) const
pure virtual

Indicates whether the target code can be serialized. Not all back-ends support serialization.

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. Possible error conditions:
  • Invalid parameters (NULL pointer).
  • Invalid expression.
  • 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::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. Possible error conditions:
  • Invalid link unit.
  • 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::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. Possible error conditions:
  • Invalid parameters (NULL pointer).
  • Invalid path (non-existing).
  • The backend failed to generate target code for the material.
  • The requested expression is a constant.
  • Only distribution functions are allowed.
  • The backend does not support compiled MDL materials obtained from class compilation mode.
  • The backend does not implement this function, yet.
  • EDFs are not supported.
  • VDFs are not supported.
  • 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::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. Possible error conditions:
  • Invalid parameters (NULL pointer).
  • Invalid path (non-existing).
  • The backend failed to generate target code for the expression.
  • The requested expression is a constant.
  • Neither BSDFs, EDFs, VDFs, nor resource type expressions can be handled.
  • The backend does not support compiled MDL materials obtained from class compilation mode.
Returns
The generated target code, or NULL in case of failure.

Variable Documentation

Size mi::neuraylib::Target_function_description::argument_block_index

The index of argument block that belongs to the compiled material the function is generated from or ~0 if none of the added function required arguments. It allows to get the layout and a writable pointer to argument data. This is an output parameter which is available after adding the function to the link unit.

const char* mi::neuraylib::Target_function_description::base_fname

The base name of the generated functions. If NULL is passed, the function name will be 'lambda' followed by an increasing counter. Note, that this counter is tracked per link unit. That means, you need to provide functions names when using multiple link units in order to avoid collisions.

ITarget_code::Distribution_kind mi::neuraylib::Target_function_description::distribution_kind

Return the distribution kind of this function (or NONE in case expressions). This is an output parameter which is available after adding the function to the link unit.

Size mi::neuraylib::Target_function_description::function_index

The index of the generated function for accessing the callable function information of the link unit or ~0 if the selected function is an invalid distribution function. ~0 is not an error case, it just means, that evaluating the function will result in 0. In case the function is a distribution function, the returned index will be the index of the init function, while sample, evaluate, and pdf will be accessible by the consecutive indices, i.e., function_index + 1, function_index + 2, function_index + 3. This is an output parameter which is available after adding the function to the link unit.

mi::Uint32 mi::neuraylib::Target_value_layout_state::m_data_offs

The offset which needs to be added to the element data offset.

mi::Uint32 mi::neuraylib::Target_value_layout_state::m_state_offs

The offset inside the layout state structure.

const char* mi::neuraylib::Target_function_description::path

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

Sint32 mi::neuraylib::Target_function_description::return_code

A return code. For the meaning of the error codes correspond to the codes add_material_expression (code * 10) and add_material_df (code * 100). 0: Success. ~0: The function has not yet been processed -1: Invalid parameters (NULL pointer). -2: Invalid path (non-existing). -7: The backend does not implement this function, yet.

codes for expressions, i.e., distribution_kind == DK_NONE -10: The JIT backend is not available. -20: Invalid field name (non-existing). -30: invalid function name. -40: The JIT backend failed to compile the function. -50: The requested expression is a constant. -60: Neither BSDFs, EDFs, VDFs, nor resource type expressions can be compiled.

codes for distribution functions, i.e., distribution_kind == DK_BSDF, DK_EDF, ... -100: Invalid parameters (NULL pointer). -200: Invalid path (non-existing). -300: The backend failed to generate target code for the material. -400: The requested expression is a constant. -500: Only distribution functions are allowed. -600: The backend does not support compiled MDL materials obtained from class compilation mode. -700: The backend does not implement this function, yet. -800: EDFs are not supported. (deprecated, will not occur anymore) -900: VDFs are not supported. -1000: The requested DF is not supported, yet.