MDL compiler

This module contains the MDL SDK 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...
struct	mi::neuraylib::Target_function_description
	Description of target function. 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. More...
struct	mi::neuraylib::Texture_handler_deriv_base
	The texture handler structure that is passed to the texturing functions with derivative support. 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, char const *arg_block_data)
	Signature of environment functions created via mi::neuraylib::IMdl_backend::translate_environment() and mi::neuraylib::ILink_unit::add_function(). More...
typedef void()	mi::neuraylib::Material_expr_function(void *result, Shading_state_material const *state, Resource_data const *res_data, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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 ,   SU_FORCE_32_BIT = 0xFFFFFFFFu }
	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 ,   Texture_shape_FORCE_32_BIT = 0xFFFFFFFFu }
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::ILink_unit::Function_execution_context {   mi::neuraylib::ILink_unit::FEC_ENVIRONMENT = 0 ,   mi::neuraylib::ILink_unit::FEC_CORE = 1 ,   mi::neuraylib::ILink_unit::FEC_DISPLACEMENT = 2 ,   FEC_FORCE_32_BIT = 0xFFFFFFFFu }
	Execution context for functions. 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. 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_flags { mi::neuraylib::DF_FLAGS_NONE = 0 , DF_FLAGS_ALLOW_REFLECT = 1 , DF_FLAGS_ALLOW_TRANSMIT = 2 , DF_FLAGS_ALLOW_REFLECT_AND_TRANSMIT = DF_FLAGS_ALLOW_REFLECT | DF_FLAGS_ALLOW_TRANSMIT , DF_FLAGS_ALLOWED_SCATTER_MODE_MASK = DF_FLAGS_ALLOW_REFLECT_AND_TRANSMIT , DF_FLAGS_FORCE_32_BIT = 0xffffffffU }
	Flags controlling the calculation of DF results. 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. 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. 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 (ITransaction *transaction, const IBuffer *buffer, IMdl_execution_context *context) const =0
	Restores an instance of ITarget_code from a buffer. More...
virtual const ITarget_code *	mi::neuraylib::IMdl_backend::deserialize_target_code (ITransaction *transaction, const Uint8 *buffer_data, Size buffer_size, IMdl_execution_context *context) const =0
	Restores an instance of ITarget_code from a buffer. 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 writable). 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 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. 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. More...
virtual Sint32	mi::neuraylib::ILink_unit::add_function (const IFunction_call *call, Function_execution_context fexc, const char *fname, IMdl_execution_context *context=0)=0
	Add an MDL function call as a function to this link unit. More...
virtual Sint32	mi::neuraylib::ILink_unit::add_function (const IFunction_definition *function, Function_execution_context fexc, const char *fname, IMdl_execution_context *context)=0
	Add an MDL function definition as a function to this link unit. 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. 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. 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. More...
ITarget_code::Distribution_kind	mi::neuraylib::Target_function_description::distribution_kind
	Return the distribution kind of this function (or NONE in case expressions). More...
Sint32	mi::neuraylib::Target_function_description::return_code
	A return code. More...

Textures
virtual Size	mi::neuraylib::ITarget_code::get_texture_count () const =0
	Returns the number of texture resources used by the target code. 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 file path 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 file path. More...
virtual bool	mi::neuraylib::ITarget_code::get_texture_is_body_resource (Size index) const =0
	Check whether the texture resource is coming from the body of expressions (not solely from material arguments). 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 const char *	mi::neuraylib::ITarget_code::get_texture_selector (Size index) const =0
	Returns the selector 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 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 file path 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 file path. More...
virtual bool	mi::neuraylib::ITarget_code::get_light_profile_is_body_resource (Size index) const =0
	Check whether the light profile resource is coming from the body of expressions (not solely from material arguments). 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 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 file path 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 file path. More...
virtual bool	mi::neuraylib::ITarget_code::get_bsdf_measurement_is_body_resource (Size index) const =0
	Check whether the BSDF measurement resource is coming from the body of expressions (not solely from material arguments). 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. 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. 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::ITarget_code::execute_init (Size index, Shading_state_material &state, Texture_handler_base *tex_handler, const ITarget_argument_block *cap_args) const =0
	Run the init function for this code on the native CPU (single-init mode). More...
virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0()	mi::neuraylib::ITarget_code::get_body_texture_count () const =0
virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0()	mi::neuraylib::ITarget_code::get_body_light_profile_count () const =0
virtual Size MI_NEURAYLIB_DEPRECATED_METHOD_14_0()	mi::neuraylib::ITarget_code::get_body_bsdf_measurement_count () const =0

Detailed Description

This module contains the MDL SDK 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

MI_NEURAYLIB_BSDF_USE_MATERIAL_IOR

#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

Bsdf_auxiliary_function

typedef void() mi::neuraylib::Bsdf_auxiliary_function(Bsdf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_auxiliary_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_evaluate_function

typedef void() mi::neuraylib::Bsdf_evaluate_function(Bsdf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_evaluate_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_init_function

typedef void() mi::neuraylib::Bsdf_init_function(Shading_state_material *state, Resource_data const *res_data, 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

state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_init_function_with_derivs

typedef void() mi::neuraylib::Bsdf_init_function_with_derivs(Shading_state_material_with_derivs *state, Resource_data const *res_data, 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

state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_pdf_function

typedef void() mi::neuraylib::Bsdf_pdf_function(Bsdf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_pdf_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_sample_function

typedef void() mi::neuraylib::Bsdf_sample_function(Bsdf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Bsdf_sample_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_auxiliary_function

typedef void() mi::neuraylib::Edf_auxiliary_function(Edf_auxiliary_data_base *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_auxiliary_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_evaluate_function

typedef void() mi::neuraylib::Edf_evaluate_function(Edf_evaluate_data_base *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_evaluate_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_init_function

typedef void() mi::neuraylib::Edf_init_function(Shading_state_material *state, Resource_data const *res_data, 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

state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_init_function_with_derivs

typedef void() mi::neuraylib::Edf_init_function_with_derivs(Shading_state_material_with_derivs *state, Resource_data const *res_data, 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

state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_pdf_function

typedef void() mi::neuraylib::Edf_pdf_function(Edf_pdf_data *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_pdf_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_sample_function

typedef void() mi::neuraylib::Edf_sample_function(Edf_sample_data *data, Shading_state_material const *state, Resource_data const *res_data, 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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Edf_sample_function_with_derivs

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

data	the input and output structure
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Environment_function

typedef void() mi::neuraylib::Environment_function(void *result, Shading_state_environment const *state, Resource_data const *res_data, char const *arg_block_data)

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

Parameters

result	pointer to the result buffer which must be large enough for the result
state	the shading state
res_data	the resources
arg_block_data	unused, should be NULL

Material_expr_function

typedef void() mi::neuraylib::Material_expr_function(void *result, Shading_state_material const *state, Resource_data const *res_data, 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

result	pointer to the result buffer which must be large enough for the result
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Material_expr_function_with_derivs

typedef void() mi::neuraylib::Material_expr_function_with_derivs(void *result, Shading_state_material_with_derivs const *state, Resource_data const *res_data, 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

result	pointer to the result buffer which must be large enough for the result
state	the shading state
res_data	the resources
arg_block_data	the target argument block data, if class compilation was used

Shading_state_material

typedef struct Shading_state_material_impl<false> mi::neuraylib::Shading_state_material

The MDL material state structure.

Shading_state_material_with_derivs

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.

tct_bool

typedef bool mi::neuraylib::tct_bool

A bool.

tct_deriv_arr_float_2

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

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

tct_deriv_arr_float_3

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

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

tct_deriv_arr_float_4

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

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

tct_deriv_float

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

A float with derivatives.

tct_deriv_float2

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

A float2 with derivatives.

tct_deriv_float3

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

A float3 with derivatives.

tct_deriv_float4

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

A float4 with derivatives.

tct_float

typedef float mi::neuraylib::tct_float

A float.

tct_float2

typedef mi::Float32_2_struct mi::neuraylib::tct_float2

A float2.

tct_float3

typedef mi::Float32_3_struct mi::neuraylib::tct_float3

A float3.

tct_float4

typedef mi::Float32_4_struct mi::neuraylib::tct_float4

A float4.

tct_int

typedef mi::Sint32 mi::neuraylib::tct_int

An int.

tct_uint

typedef mi::Uint32 mi::neuraylib::tct_uint

An unsigned int.

Texture_handler_deriv_vtable

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

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

Texture_handler_vtable

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

The texture handler vtable struct.

Enumeration Type Documentation

Bsdf_event_type

enum mi::neuraylib::Bsdf_event_type

The type of events created by BSDF importance sampling.

Df_flags

enum mi::neuraylib::Df_flags

Flags controlling the calculation of DF results.

Enumerator
DF_FLAGS_NONE	allows nothing -> black

Df_handle_slot_mode

enum mi::neuraylib::Df_handle_slot_mode

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

Distribution_kind

enum mi::neuraylib::ITarget_code::Distribution_kind

Possible kinds of distribution functions.

Edf_event_type

enum mi::neuraylib::Edf_event_type

The type of events created by EDF importance sampling.

Function_execution_context

enum mi::neuraylib::ILink_unit::Function_execution_context

Execution context for functions.

Enumerator
FEC_ENVIRONMENT	This function will be executed inside the environment.
FEC_CORE	This function will be executed in the renderer core.
FEC_DISPLACEMENT	This function will be executed inside displacement.

Function_kind

enum mi::neuraylib::ITarget_code::Function_kind

Possible kinds of callable functions.

Gamma_mode

enum mi::neuraylib::ITarget_code::Gamma_mode

Possible texture gamma modes.

Mbsdf_part

enum mi::neuraylib::Mbsdf_part

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)

Prototype_language

enum mi::neuraylib::ITarget_code::Prototype_language

Language to use for the callable function prototype.

State_usage_property

enum mi::neuraylib::ITarget_code::State_usage_property

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

Tex_wrap_mode

enum mi::neuraylib::Tex_wrap_mode

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

Texture_shape

enum mi::neuraylib::ITarget_code::Texture_shape

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

add_function() [1/2]

virtual Sint32 mi::neuraylib::ILink_unit::add_function ( const IFunction_call *  call, Function_execution_context  fexc, const char *  fname, IMdl_execution_context *  context = 0  )

pure virtual

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

Parameters

	call	The MDL function call.
	fexc	The context from which this function will be called.
	fname	The name of the function that is created.
[in,out]	context	An 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:

• 0: Success.
• -1: An error occurred. Please check the execution context for details if it has been provided.

add_function() [2/2]

virtual Sint32 mi::neuraylib::ILink_unit::add_function ( const IFunction_definition *  function, Function_execution_context  fexc, const char *  fname, IMdl_execution_context *  context  )

pure virtual

Add an MDL function definition as a function to this link unit.

Parameters

	function	The MDL function definition.
	fexc	The context from which this function will be called.
	fname	The name of the function that is created.
[in,out]	context	An 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:

• 0: Success.
• -1: An error occurred. Please check the execution context for details if it has been provided.

add_material()

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.

Functions can be selected by providing a list of Target_function_descriptions. If the first function in the list uses the path "init", one init function will be generated, precalculating values which will be used by the other requested functions. Each other entry in the list needs to define the path, the root of the expression that should be translated. For each distribution function it results in three or four functions, suffixed with "_init" (if first requested path was not "init"), "_sample", "_evaluate", and "_pdf". 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

	material	The compiled MDL material.
[in,out]	function_descriptions	The list of descriptions of function to translate.
	description_count	The size of the list of descriptions.
[in,out]	context	An 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:

• 0: Success.
• -1: An error occurred while processing the entries in the list. Please check the execution context for details if it has been provided.

Note

Upon unsuccessful return, function_descriptions.return_code might contain further info.

add_material_df()

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.

For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf".

Parameters

	material	The compiled MDL material.
	path	The path from the material root to the expression that should be translated, e.g., "surface.scattering".
	base_fname	The base name of the generated functions. If NULL is passed, "lambda" will be used.
[in,out]	context	An 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:

• 0: Success.
• -1: An error occurred. Please check the execution context for details if it has been provided.

add_material_expression()

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

	inst	The compiled MDL material instance.
	path	The path from the material root to the expression that should be translated, e.g., "geometry.displacement".
	fname	The name of the function that is created.
[in,out]	context	An 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:

• 0: Success.
• -1: An error occurred. Please check the execution context for details if it has been provided.

clone()

virtual ITarget_argument_block * mi::neuraylib::ITarget_argument_block::clone ( ) const

pure virtual

Clones the argument block (to make it writable).

create_argument_block()

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

index	The index of the base target argument block of this target code.
material	The 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_callback	Callback 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.

create_link_unit()

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

pure virtual

Creates a new link unit.

Parameters

	transaction	The transaction to be used.
[in,out]	context	An 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.

deserialize_target_code() [1/2]

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

pure virtual

Restores an instance of ITarget_code from a buffer.

Deserialization can fail for outdated input date, which is not an error. Check the context messages for details.

Parameters

	transaction	The transaction to be used.
	buffer	The buffer containing the serialized target code to restore.
[in,out]	context	An 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.

deserialize_target_code() [2/2]

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

pure virtual

Restores an instance of ITarget_code from a buffer.

Deserialization can fail for outdated input date, which is not an error. Check the context messages for details.

Parameters

	transaction	The transaction to be used.
	buffer_data	The buffer containing the serialized target code to restore.
	buffer_size	The size of buffer_data.
[in,out]	context	An 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.

execute()

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]	index	The index of the callable function.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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]	result	The 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.

execute_bsdf_auxiliary()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the BSDF auxiliary calculation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_bsdf_evaluate()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the BSDF evaluation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_bsdf_init()

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]	index	The index of the callable function.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_bsdf_pdf()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the BSDF PDF calculation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_bsdf_sample()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the BSDF sampling.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_edf_auxiliary()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the EDF auxiliary calculation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_edf_evaluate()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the EDF evaluation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_edf_init()

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]	index	The index of the callable function.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_edf_pdf()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the EDF PDF calculation.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_edf_sample()

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]	index	The index of the callable function.
[in,out]	data	The input and output fields for the EDF sampling.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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

execute_environment()

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]	index	The index of the callable function.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[out]	result	The 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.

execute_init()

virtual Sint32 mi::neuraylib::ITarget_code::execute_init ( Size  index, Shading_state_material &  state, Texture_handler_base *  tex_handler, const ITarget_argument_block *  cap_args  ) const

pure virtual

Run the init function for this code on the native CPU (single-init mode).

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]	index	The index of the callable function.
[in]	state	The core state.
[in]	tex_handler	Texture handler containing the vtable for the user-defined texture lookup functions. Can be NULL if the built-in resource handler is used.
[in]	cap_args	The 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 an init function for single-init mode

get_argument_block()

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

index

The index of the target argument block.

Returns

the captured argument block or NULL if no arguments were captured or the index was invalid.

get_argument_block_count()

virtual Size mi::neuraylib::ITarget_code::get_argument_block_count ( ) const

pure virtual

Returns the number of target argument blocks.

get_argument_block_layout()

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

index

The index of the target argument block.

Returns

the layout or NULL if no arguments were captured or the index was invalid.

get_argument_layout_count()

virtual Size mi::neuraylib::ITarget_code::get_argument_layout_count ( ) const

pure virtual

Returns the number of target argument block layouts.

get_backend_kind()

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.

get_bsdf_measurement()

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

index

The index of the BSDF measurement 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.

get_bsdf_measurement_count()

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.

get_bsdf_measurement_is_body_resource()

virtual bool mi::neuraylib::ITarget_code::get_bsdf_measurement_is_body_resource ( Size  index ) const

pure virtual

Check whether the BSDF measurement resource is coming from the body of expressions (not solely from material arguments).

It will be necessary regardless of the chosen material arguments.

Parameters

index

The index of the BSDF measurement resource.

Returns

true if the BSDF measurement is referenced from inside the material body.

get_bsdf_measurement_owner_module()

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 file path.

Parameters

index

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

get_bsdf_measurement_url()

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

pure virtual

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

Parameters

index

The index of the BSDF measurement resource.

Returns

The MDL file path 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.

get_callable_function()

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

index

The index of the callable function.

Returns

The name of the index -th callable function, or NULL if index is out of bounds.

get_callable_function_argument_block_index()

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

index

The index of the callable function.

Returns

The index of the target argument block for this function or ~0 if not used.

get_callable_function_count()

virtual Size mi::neuraylib::ITarget_code::get_callable_function_count ( ) const

pure virtual

Returns the number of callable functions in the target code.

get_callable_function_df_handle()

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_index	The index of the callable function.
handle_index	The 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.

get_callable_function_df_handle_count()

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_index

The index of the callable function.

Returns

The number of distribution function handles referenced or 0, if the callable function is not a distribution function.

get_callable_function_distribution_kind()

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

index

The index of the callable function.

Returns

The distribution kind of the callable function or DK_INVALID if index was invalid.

get_callable_function_kind()

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

index

The index of the callable function.

Returns

The kind of the callable function or FK_INVALID if index was invalid.

get_callable_function_prototype()

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

index	The index of the callable function.
lang	The 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.

get_callable_function_render_state_usage()

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.

get_code()

virtual const char * mi::neuraylib::ITarget_code::get_code ( ) const

pure virtual

Returns the represented target code in ASCII representation.

get_code_segment()

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

index

The index of the code segment.

Returns

The code segment or NULL if the index is out of bounds.

get_code_segment_count()

virtual Size mi::neuraylib::ITarget_code::get_code_segment_count ( ) const

pure virtual

Returns the number of code segments of the target code.

get_code_segment_description()

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

index

The index of the code segment.

Returns

The code segment description or NULL if the index is out of bounds.

get_code_segment_size()

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

index

The index of the code segment.

Returns

The size of the code segment or 0 if the index is out of bounds.

get_code_size()

virtual Size mi::neuraylib::ITarget_code::get_code_size ( ) const

pure virtual

Returns the length of the represented target code.

get_data() [1/2]

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

pure virtual

Returns the target argument block data.

get_data() [2/2]

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

pure virtual

Returns the target argument block data.

get_device_library()

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]

size

The size of the library.

Returns

The device library or NULL if no library exists for this backend.

get_known_resource_index()

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

transaction	Transaction to retrieve resource names from tags.
resource	The resource value.

get_layout()

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]	kind	Receives the kind of the argument.
[out]	arg_size	Receives the size of the argument.
	state	The 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.

get_light_profile()

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

index

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

get_light_profile_count()

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.

get_light_profile_is_body_resource()

virtual bool mi::neuraylib::ITarget_code::get_light_profile_is_body_resource ( Size  index ) const

pure virtual

Check whether the light profile resource is coming from the body of expressions (not solely from material arguments).

It will be necessary regardless of the chosen material arguments.

Parameters

index

The index of the light profile resource.

Returns

true if the light profile is referenced from inside the material body.

get_light_profile_owner_module()

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 file path.

Parameters

index

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

get_light_profile_url()

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

pure virtual

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

Parameters

index

The index of the light profile resource.

Returns

The MDL file path 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.

get_nested_state()

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

i	The index of the argument / element.
state	The 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.

get_num_elements()

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

state

The layout state representing the current nesting within the argument value block. The default value is used for the top-level.

get_render_state_usage()

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.

get_resource_index()

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

resource

the resource value

Returns

a resource index or 0 if no resource index can be returned

get_ro_data_segment_count()

virtual Size mi::neuraylib::ITarget_code::get_ro_data_segment_count ( ) const

pure virtual

Returns the number of constant data initializers.

get_ro_data_segment_data()

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

index

The index of the data segment.

Returns

The data of the constant data segment or NULL if the index is out of bounds.

get_ro_data_segment_name()

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

index

The index of the data segment.

Returns

The name of the constant data segment or NULL if the index is out of bounds.

get_ro_data_segment_size()

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

index

The index of the data segment.

Returns

The size of the constant data segment or 0 if the index is out of bounds.

get_size() [1/2]

virtual Size mi::neuraylib::ITarget_argument_block::get_size ( ) const

pure virtual

Returns the size of the target argument block data.

get_size() [2/2]

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

pure virtual

Returns the size of the target argument block.

get_string_constant()

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

index

The index of the string constant.

Returns

The string constant that is represented by the given index, or NULL if index is out of range.

get_string_constant_count()

virtual Size mi::neuraylib::ITarget_code::get_string_constant_count ( ) const

pure virtual

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

get_string_index()

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

s	the string value

get_texture()

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

index

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

get_texture_count()

virtual Size mi::neuraylib::ITarget_code::get_texture_count ( ) const

pure virtual

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

get_texture_df_data()

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

	index	The index of the texture resource.
[out]	rx	The resolution of the texture in x.
[out]	ry	The resolution of the texture in y.
[out]	rz	The resolution of the texture in z.

Returns

A pointer to the texture data, if the texture is a distribution function data texture, NULL otherwise.

get_texture_df_data_kind()

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

index

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

get_texture_gamma()

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

index

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

get_texture_is_body_resource()

virtual bool mi::neuraylib::ITarget_code::get_texture_is_body_resource ( Size  index ) const

pure virtual

Check whether the texture resource is coming from the body of expressions (not solely from material arguments).

It will be necessary regardless of the chosen material arguments.

Parameters

index

The index of the texture resource.

Returns

true if the texture is referenced from inside the material body.

get_texture_owner_module()

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 file path.

Parameters

index

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

get_texture_selector()

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

pure virtual

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

Parameters

index

The index of the texture resource.

Returns

The selector of the texture resource of the given index, or NULL if index is out of range or there is no selector for that texture resource.

get_texture_shape()

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

index

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

get_texture_url()

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

pure virtual

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

Parameters

index

The index of the texture resource.

Returns

The MDL file path of the texture resource of the given index, or NULL if index is out of range or the texture exists in the database.

serialize()

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]

context

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

set_option()

virtual Sint32 mi::neuraylib::IMdl_backend::set_option ( const char *  name, const char *  value  )

pure virtual

Sets a backend option.

The following options are supported by all backends:

• "compile_constants": If true, compile simple constants into functions returning constants. If false, do not compile simple constants but return error -4. Possible values: "on", "off". Default: "on".
• "fast_math": Enables/disables unsafe floating point optimization. Possible values: "on", "off". Default: "on".
• "opt_level": Set the optimization level. Possible values:
  • "0": no optimization
  • "1": no inlining, no expensive optimizations
  • "2": full optimizations, including inlining (default)
• "num_texture_spaces": Set the number of supported texture spaces. Default: "32".
• "enable_auxiliary": Enable code generation for auxiliary methods on distribution functions. For BSDFs, these compute albedo approximations and normals. For EDFs, the functions exist only as placeholder for future use. Possible values: "on", "off". Default: "off".
• "enable_pdf": Enable code generation of PDF method on distribution functions. Possible values: "on", "off". Default: "on".
• "df_handle_slot_mode": When using light path expressions, individual parts of the distribution functions can be selected using "handles". The contribution of each of those parts has to be evaluated during rendering. This option controls how many parts are evaluated with each call into the generated "evaluate" and "auxiliary" functions and how the data is passed. Possible values: "none", "fixed_1", "fixed_2", "fixed_4", "fixed_8", and "pointer", while "pointer" is not available for all backends. Default: "none".
• "libbsdf_flags_in_bsdf_data": If enabled, the generated code will use the optional "flags" field in the BSDF data structures. Possible values: "on", "off". Default: "off".

The following options are supported by the NATIVE backend only:

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

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

• "inline_aggressively": Enables/disables aggressive inlining. Possible values: "on", "off". Default: "off".
• "eval_dag_ternary_strictly": Enables/disables strict evaluation of ternary operators on the DAG. Possible values: "on", "off". Default: "on".
• "enable_exceptions": Enables/disables support for exceptions through runtime function calls on CPU. For GPU, this options is always treated as disabled. Possible values: "on", "off". Default: "off".
• "enable_ro_segment": Enables/disables the creation of the read-only data segment calls. Possible values: "on", "off". Default: "off".
• "max_const_data": Specifies the maximum size of a constant in bytes to be put into the generated code, if the "enable_ro_segment" option is enabled. Bigger constants will be moved into the read-only data segment. If the "glsl_max_const_data" option is also used, the read-only data segment has priority.
• "num_texture_results": Set the size of the text_results array in the MDL SDK state in number of float4 elements. The array has to be provided by the renderer and must be provided per thread (for example as an array on the stack) and will be filled in the init function created for a material and used by the sample, evaluate and pdf functions, if the size is non-zero. Default: "0".
• "texture_runtime_with_derivs": Enables/disables derivative support for texture lookup functions. If enabled, the user-provided texture runtime has to provide functions with derivative parameters for the texture coordinates. Possible values: "on", "off". Default: "off".
• "visible_functions": Comma-separated list of function names which will be visible in the generated code (empty string means no special restriction). Can especially be used in combination with "llvm_renderer_module" binary option to limit the number of functions for which target code will be generated. Default: ""
• "use_renderer_adapt_normal": If enabled, the generated code expects the renderer to provide a function with the prototype "void adapt_normal(float result[3], Textue_handler_base const *self, Shading_state_material *state, float const normal[3])" which can adapt the normal of BSDFs. For native: The function must be set in the vtable of the Texture_handler_base object provided to the execute functions. If the built-in texture runtime is used, only the adapt_normal entry of the vtable needs to be set. For HLSL: The expected function is "float3 mdl_adapt_normal(Shading_state_material state, float3 normal)". Possible values: "on", "off". Default: "off".

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

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

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

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

The following options are supported by the PTX backend only:

• "sm_version": Specifies the SM target version. Possible values: "20", "30", "35", "37", "50", "52", "60", "61", "62". "70", "75", "80", and "86". Default: "20".
• "enable_ro_segment": Enables/disables the creation of the read-only data segment calls. Possible values: "on", "off". Default: "off".
• "link_libdevice": Enables/disables linking of libdevice before PTX is generated. Possible values: "on", "off". Default: "on".
• "output_format": Selects the output format of the backend. Possible values: "PTX", "LLVM-IR", "LLVM-BC". Default: "PTX".
• "tex_lookup_call_mode": Selects how tex_lookup calls will be generated. See 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 defined resource data struct is passed to all resource callbacks. This option is currently not supported. Possible values: "on", "off". Default: "off".
• "hlsl_remap_functions": Specifies a comma separated remap list of MDL functions. The entries must be specified as <old_name>=<new_name>. Both names have to be in mangled form. Default: "".
• "df_handle_slot_mode": The option "pointer" is not available (see above).
• "use_renderer_adapt_microfacet_roughness": If enabled, the generated code expects the renderer to provide a function with the prototype

  float2 mdl_adapt_microfacet_roughness(Shading_state_material state, float2 roughness_uv)

  which can adapt the roughness of microfacet BSDFs. For sheen_bsdf, the same roughness will be provided in both dimensions and only the x component of the result will be used. Possible values: "on", "off". Default: "off".

The following options are supported by the GLSL backend only:

• "glsl_version": Specifies the GLSL target version. Possible values for "core" and "compatibility" profiles: "150", "330", "400", "410", "420", "430", "440", "450", "460". Values for the "es" profile: "100", "300", "310". Default: "450".
• "glsl_profile": Specifies the GLSL target profile. Possible values: "core", "es", "compatibility". Default: "core".
• "glsl_include_uniform_state": If true, object_id will be included in the state according to the "glsl_state_object_id_mode" option. Possible values: "on", "off". Default: "off"
• "glsl_max_const_data": Specifies the maximum size of a constant in bytes to be put into the generated GLSL code, if the "glsl_place_uniforms_into_ssbo" option is enabled. Bigger constants will be moved into the SSBO. If the "max_const_data" option is also used, the read-only data segment has priority. Default: "1024".
• "glsl_place_uniforms_into_ssbo": If true, all generated uniform inputs will be placed into a shader storage buffer object. This option can only be enabled, if the "GL_ARB_shader_storage_buffer_object" extension is enabled. Possible values: "on", "off". Default: "off"
• "glsl_uniform_ssbo_name": If non-empty, specifies a name for the SSBO buffer containing the uniform initializer if option "glsl_place_uniforms_into_ssbo" is enabled. Possible values: Any valid GLSL identifier. Default: "".
  • "glsl_uniform_ssbo_binding": A GLSL binding attribute expression for the SSBO buffer. Possible values: Currently limited to unsigned literals. Default: "" (Means no "binding" attribute)
  • "glsl_uniform_ssbo_set": A GLSL set attribute expression for the SSBO buffer. Possible values: Currently limited to unsigned literals. Default: "" (Means no "set" attribute)
• "glsl_use_resource_data": If enabled, an extra user defined resource data struct is passed to all resource callbacks. This option is currently not supported. Possible values: "on", "off". Default: "off".
• "glsl_remap_functions": Specifies a comma separated remap list of MDL functions. The entries must be specified as <old_name>=<new_name>. Both names have to be in mangled form. Default: "".
• "glsl_state_animation_time_mode": Specify the implementation mode of state::animation_time(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_geometry_normal_mode": Specify the implementation mode of state::geometry_normal(). Possible values: "field", "arg", "func", "zero". Default: "field".
• "glsl_state_motion_mode": Specify the implementation mode of state::motion(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_normal_mode": Specify the implementation mode of state::normal(). Possible values: "field", "arg", "func", "zero". Default: "field".
• "glsl_state_object_id_mode": Specify the implementation mode of state::object_id(). You have to enable "glsl_include_uniform_state" for this mode to have any effect. Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_position_mode": Specify the implementation mode of state::position(). Possible values: "field", "arg", "func", "zero". Default: "field".
• "glsl_state_texture_coordinate_mode": Specify the implementation mode of state::texture_coordinate(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_texture_space_max_mode": Specify the implementation mode of state::texture_space_max(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_texture_tangent_u_mode": Specify the implementation mode of state::texture_tangent_u(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_texture_tangent_v_mode": Specify the implementation mode of state::texture_tangent_v(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_geometry_tangent_u_mode": Specify the implementation mode of state::geometry_tangent_u(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_state_geometry_tangent_v_mode": Specify the implementation mode of state::geometry_tangent_v(). Possible values: "field", "arg", "func", "zero". Default: "zero".
• "glsl_enabled_extensions": Specifies the enabled GLSL extensions as a comma separated list. Default: "".
• "glsl_required_extensions": Specifies the required GLSL extensions as a comma separated list. Default: "".

The following extensions are fully supported by the GLSL backend:

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

The following extensions are partially supported by the GLSL backend:

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

Meaning of the state modes:

• "field": access a field of a passed state struct
• "arg": access an argument of the generated shader
• "func": call a wrapper function
• "zero": always zero

Note

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

Parameters

name	The name of the option.
value	The value of the option.

Returns

• 0: Success.
• -1: Unknown option.
• -2: Unsupported value.

set_option_binary()

virtual Sint32 mi::neuraylib::IMdl_backend::set_option_binary ( const char *  name, const char *  data, Size  size  )

pure virtual

Sets a binary backend option.

The following options are supported by the LLVM backends:

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

Parameters

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

Returns

• 0: Success.
• -1: Unknown option.
• -2: Unsupported value.

set_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]	block	The argument value block buffer to be modified.
[in]	value	The value to be set. It has to match the expected kind.
[in]	resource_callback	Callback for retrieving resource indices for resource values.
[in]	state	The 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.

supports_serialization()

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.

translate_environment()

virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_environment ( ITransaction *  transaction, const IFunction_call *  call, const char *  fname, IMdl_execution_context *  context  )

pure virtual

Transforms an MDL environment function call into target code.

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

void FNAME(
    void                                            *result,
    mi::neuraylib::Shading_state_environment const  *state,
    void const                                      *res_data,
    void const                                      *exception_state);

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

Parameters

	transaction	The transaction to be used.
	call	The MDL function call for the environment.
	fname	The name of the generated function. If NULL is passed, "lambda" will be used.
[in,out]	context	An 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.

translate_link_unit()

virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_link_unit ( const ILink_unit *  lu, IMdl_execution_context *  context  )

pure virtual

Transforms a link unit to target code.

Parameters

	lu	The link unit to translate.
[in,out]	context	An 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.

translate_material()

virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_material ( ITransaction *  transaction, const ICompiled_material *  material, Target_function_description *  function_descriptions, Size  description_count, IMdl_execution_context *  context  )

pure virtual

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

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

Parameters

	transaction	The transaction to be used.
	material	The compiled MDL material.
	function_descriptions	The list of descriptions of function to translate.
	description_count	The size of the list of descriptions.
[in,out]	context	An 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.

translate_material_df()

virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_material_df ( ITransaction *  transaction, const ICompiled_material *  material, const char *  path, const char *  base_fname, IMdl_execution_context *  context  )

pure virtual

Transforms an MDL distribution function to target code.

For a BSDF it results in four functions, suffixed with "_init", "_sample", "_evaluate" and "_pdf".

Parameters

	transaction	The transaction to be used.
	material	The compiled MDL material.
	path	The path from the material root to the expression that should be translated, e.g., "surface.scattering".
	base_fname	The base name of the generated functions. If NULL is passed, "lambda" will be used.
[in,out]	context	An 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. VDFs are not supported. The requested BSDF is not supported, yet.

Returns

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

translate_material_expression()

virtual const ITarget_code * mi::neuraylib::IMdl_backend::translate_material_expression ( ITransaction *  transaction, const ICompiled_material *  material, const char *  path, const char *  fname, IMdl_execution_context *  context  )

pure virtual

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

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

void FNAME(
    void                                         *result,
    mi::neuraylib::Shading_state_material const  *state,
    void const                                   *res_data,
    void const                                   *exception_state,
    char const                                   *arg_block_data);

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

Parameters

	transaction	The transaction to be used.
	material	The compiled MDL material.
	path	The path from the material root to the expression that should be translated, e.g., "geometry.displacement".
	fname	The name of the generated function. If NULL is passed, "lambda" will be used.
[in,out]	context	An 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

argument_block_index

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.

base_fname

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.

distribution_kind

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.

function_index

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.

m_data_offs

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

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

m_state_offs

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

The offset inside the layout state structure.

path

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

return_code

Sint32 mi::neuraylib::Target_function_description::return_code

A return code.

The error codes correspond to the codes returned by mi::neuraylib::ILink_unit::add_material_expression() (multiplied by 10) and mi::neuraylib::ILink_unit::add_material_df (multiplied by 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.