neuray API Programmer's Manual

mi::neuraylib::ITarget_code Class Reference

[MDL compiler]

Description

Represents target code of an MDL backend.

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Enumerations

enum Distribution_kind{ DK_NONE, DK_BSDF, DK_HAIR_BSDF, DK_EDF, DK_INVALID, DK_FORCE_32_BIT = 0xFFFFFFFFu}
Possible kinds of distribution functions.
enum Function_kind{ FK_INVALID, FK_LAMBDA, FK_SWITCH_LAMBDA, FK_ENVIRONMENT, FK_CONST, FK_DF_INIT, FK_DF_SAMPLE, FK_DF_EVALUATE, FK_DF_PDF, FK_DF_AUXILIARY, FK_FORCE_32_BIT = 0xFFFFFFFFu}
Possible kinds of callable functions.
enum Gamma_mode{ GM_GAMMA_DEFAULT, GM_GAMMA_LINEAR, GM_GAMMA_SRGB, GM_GAMMA_UNKNOWN, GM_FORCE_32_BIT = 0xFFFFFFFFu}
Possible texture gamma modes.
enum Prototype_language{ SL_CUDA, SL_PTX, SL_HLSL, SL_GLSL, SL_NUM_LANGUAGES, SL_FORCE_32_BIT = 0xFFFFFFFFu}
Language to use for the callable function prototype.
enum State_usage_property{ SU_POSITION = 0x0001u, SU_NORMAL = 0x0002u, SU_GEOMETRY_NORMAL = 0x0004u, SU_MOTION = 0x0008u, SU_TEXTURE_COORDINATE = 0x0010u, SU_TEXTURE_TANGENTS = 0x0020u, SU_TANGENT_SPACE = 0x0040u, SU_GEOMETRY_TANGENTS = 0x0080u, SU_DIRECTION = 0x0100u, SU_ANIMATION_TIME = 0x0200u, SU_ROUNDED_CORNER_NORMAL = 0x0400u, SU_ALL_VARYING_MASK = 0x07FFu, SU_TRANSFORMS = 0x0800u, SU_OBJECT_ID = 0x1000u, SU_ALL_UNIFORM_MASK = 0x1800u, SU_FORCE_32_BIT = 0xFFFFFFFFu}
The potential state usage properties.

Public Member Functions

virtual ITarget_argument_block* 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 Sint32 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 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 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 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 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 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 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 Sint32 execute_edf_evaluate( Size index, Edf_evaluate_data_base* data, const Shading_state_material& state, Texture_handler_base* tex_handler, const ITarget_argument_block* cap_args) const =0
Run the EDF evaluation function for this code on the native CPU. More...
virtual Sint32 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 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 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 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 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 const ITarget_argument_block* get_argument_block( Size index) const =0
Get a target argument block if available. More...
virtual Size get_argument_block_count() const =0
Returns the number of target argument blocks.
virtual const ITarget_value_layout* get_argument_block_layout( Size index) const =0
Get a captured arguments block layout if available. More...
virtual Size get_argument_layout_count() const =0
Returns the number of target argument block layouts.
virtual IMdl_backend_api::​Mdl_backend_kind get_backend_kind() const =0
Returns the kind of backend this information belongs to.
virtual const char* get_callable_function( Size index) const =0
Returns the name of a callable function in the target code. More...
virtual Size 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 Size get_callable_function_count() const =0
Returns the number of callable functions in the target code.
virtual const char* 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 Size 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 Distribution_kind 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 get_callable_function_kind( Size index) const =0
Returns the function kind of a callable function in the target code. More...
virtual const char* get_callable_function_prototype( Size index, Prototype_language lang) const =0
Returns the prototype of a callable function in the target code. More...
virtual State_usage 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 const char* get_code() const =0
Returns the represented target code in ASCII representation.
virtual const char* get_code_segment( Size index) const =0
Returns the represented target code segment in ASCII representation. More...
virtual Size get_code_segment_count() const =0
Returns the number of code segments of the target code.
virtual const char* get_code_segment_description( Size index) const =0
Returns the description of the target code segment. More...
virtual Size get_code_segment_size( Size index) const =0
Returns the length of the represented target code segment. More...
virtual Size get_code_size() const =0
Returns the length of the represented target code.
virtual Uint32 get_known_resource_index( ITransaction* transaction, const IValue_resource* 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 State_usage get_render_state_usage() const =0
Returns the potential render state usage of the target code. More...
virtual Size get_ro_data_segment_count() const =0
Returns the number of constant data initializers.
virtual const char* get_ro_data_segment_data( Size index) const =0
Returns the data of the constant data segment at the given index. More...
virtual const char* get_ro_data_segment_name( Size index) const =0
Returns the name of the constant data segment at the given index. More...
virtual Size 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* get_string_constant( Size index) const =0
Returns the string constant used by the target code. More...
virtual Size get_string_constant_count() const =0
Returns the number of string constants used by the target code.
virtual const IBuffer* 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 bool  supports_serialization() const =0
Indicates whether the target code can be serialized. More...

Textures

virtual const char* get_texture( Size index) const =0
Returns the name of a texture resource used by the target code. More...
virtual Size get_texture_count() const =0
Returns the number of texture resources used by the target code.
virtual const Float32* get_texture_df_data( Size index, Size& rx, Size& ry, Size& rz) const =0
Returns the distribution function data this texture refers to. More...
virtual Df_data_kind 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 Gamma_mode get_texture_gamma( Size index) const =0
Returns the gamma mode of a texture resource used by the target code. More...
virtual bool  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 const char* get_texture_owner_module( Size index) const =0
Returns the owner module name of a relative texture file path. More...
virtual const char* get_texture_selector( Size index) const =0
Returns the selector mode of a texture resource used by the target code. More...
virtual Texture_shape get_texture_shape( Size index) const =0
Returns the texture shape of a given texture resource used by the target code. More...
virtual const char* 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...

Light profiles

virtual const char* get_light_profile( Size index) const =0
Returns the name of a light profile resource used by the target code. More...
virtual Size get_light_profile_count() const =0
Returns the number of light profile resources used by the target code.
virtual bool  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...
virtual const char* get_light_profile_owner_module( Size index) const =0
Returns the owner module name of a relative light profile file path. More...
virtual const char* 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...

BSDF measurements

virtual const char* get_bsdf_measurement( Size index) const =0
Returns the name of a bsdf measurement resource used by the target code. More...
virtual Size get_bsdf_measurement_count() const =0
Returns the number of bsdf measurement resources used by the target code.
virtual bool  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 const char* get_bsdf_measurement_owner_module( Size index) const =0
Returns the owner module name of a relative BSDF measurement file path. More...
virtual const char* 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...

Enums

enum mi::​neuraylib::​ITarget_code::Distribution_kind

Possible kinds of distribution functions.

Enumerator:

DK_NONE
DK_BSDF
DK_HAIR_BSDF
DK_EDF
DK_INVALID
DK_FORCE_32_BIT = 0xFFFFFFFFu
enum mi::​neuraylib::​ITarget_code::Function_kind

Possible kinds of callable functions.

Enumerator:

FK_INVALID
FK_LAMBDA
FK_SWITCH_LAMBDA
FK_ENVIRONMENT
FK_CONST
FK_DF_INIT
FK_DF_SAMPLE
FK_DF_EVALUATE
FK_DF_PDF
FK_DF_AUXILIARY
FK_FORCE_32_BIT = 0xFFFFFFFFu
enum mi::​neuraylib::​ITarget_code::Gamma_mode

Possible texture gamma modes.

Enumerator:

GM_GAMMA_DEFAULT
GM_GAMMA_LINEAR
GM_GAMMA_SRGB
GM_GAMMA_UNKNOWN
GM_FORCE_32_BIT = 0xFFFFFFFFu
enum mi::​neuraylib::​ITarget_code::Prototype_language

Language to use for the callable function prototype.

Enumerator:

SL_CUDA
SL_PTX
SL_HLSL
SL_GLSL
SL_NUM_LANGUAGES
SL_FORCE_32_BIT = 0xFFFFFFFFu
enum mi::​neuraylib::​ITarget_code::State_usage_property

The potential state usage properties.

Enumerator:

SU_POSITION = 0x0001u
uses state::position()
SU_NORMAL = 0x0002u
uses state::normal()
SU_GEOMETRY_NORMAL = 0x0004u
uses state::geometry_normal()
SU_MOTION = 0x0008u
uses state::motion()
SU_TEXTURE_COORDINATE = 0x0010u
uses state::texture_coordinate()
SU_TEXTURE_TANGENTS = 0x0020u
uses state::texture_tangent_*()
SU_TANGENT_SPACE = 0x0040u
uses state::tangent_space()
SU_GEOMETRY_TANGENTS = 0x0080u
uses state::geometry_tangent_*()
SU_DIRECTION = 0x0100u
uses state::direction()
SU_ANIMATION_TIME = 0x0200u
uses state::animation_time()
SU_ROUNDED_CORNER_NORMAL = 0x0400u
uses state::rounded_corner_normal()
SU_ALL_VARYING_MASK = 0x07FFu
set of varying states
SU_TRANSFORMS = 0x0800u
uses uniform state::transform*()
SU_OBJECT_ID = 0x1000u
uses uniform state::object_id()
SU_ALL_UNIFORM_MASK = 0x1800u
set of uniform states
SU_FORCE_32_BIT = 0xFFFFFFFFu

Member Functions

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.

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.

Note:

This allows to execute any compiled function on the CPU. The result must be big enough to take the functions result.

Parameters

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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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

index
The index of the callable function.
data
state
The core state.
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.
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

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.

Note:

This allows to execute any compiled function on the CPU.

Parameters

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

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

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

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.

virtual Size mi::​neuraylib::​ITarget_code::get_argument_block_count() const [pure virtual]

Returns the number of target argument blocks.

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

Get a captured arguments block layout if available.

Parameters

index
The index of the target argument block.

Returns

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

virtual Size mi::​neuraylib::​ITarget_code::get_argument_layout_count() const [pure virtual]

Returns the number of target argument block layouts.

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

Returns the kind of backend this information belongs to.

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

virtual Size mi::​neuraylib::​ITarget_code::get_bsdf_measurement_count() const [pure virtual]

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

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

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.

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.

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.

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.

virtual Size mi::​neuraylib::​ITarget_code::get_callable_function_count() const [pure virtual]

Returns the number of callable functions in the target code.

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

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

Parameters

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

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.

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.

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.

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.

virtual State_usage mi::​neuraylib::​ITarget_code::get_callable_function_render_state_usage( Size index) const [pure virtual]

Returns the potential render state usage of callable function in the target code. If the corresponding property bit is not set, it is guaranteed that the code does not use the associated render state property.

Returns

The potential render state usage of the callable function or 0 if index was invalid.

virtual const char* mi::​neuraylib::​ITarget_code::get_code() const [pure virtual]

Returns the represented target code in ASCII representation.

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

Returns the represented target code segment in ASCII representation.

Parameters

index
The index of the code segment.

Returns

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

virtual Size mi::​neuraylib::​ITarget_code::get_code_segment_count() const [pure virtual]

Returns the number of code segments of the target code.

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

Returns the description of the target code segment.

Parameters

index
The index of the code segment.

Returns

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

virtual Size mi::​neuraylib::​ITarget_code::get_code_segment_size( Size index) const [pure virtual]

Returns the length of the represented target code segment.

Parameters

index
The index of the code segment.

Returns

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

virtual Size mi::​neuraylib::​ITarget_code::get_code_size() const [pure virtual]

Returns the length of the represented target code.

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

virtual Size mi::​neuraylib::​ITarget_code::get_light_profile_count() const [pure virtual]

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

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

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.

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.

virtual State_usage mi::​neuraylib::​ITarget_code::get_render_state_usage() const [pure virtual]

Returns the potential render state usage of the target code. If the corresponding property bit is not set, it is guaranteed that the code does not use the associated render state property.

virtual Size mi::​neuraylib::​ITarget_code::get_ro_data_segment_count() const [pure virtual]

Returns the number of constant data initializers.

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

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

Parameters

index
The index of the data segment.

Returns

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

virtual const char* mi::​neuraylib::​ITarget_code::get_ro_data_segment_name( Size index) const [pure virtual]

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

Parameters

index
The index of the data segment.

Returns

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

virtual Size mi::​neuraylib::​ITarget_code::get_ro_data_segment_size( Size index) const [pure virtual]

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

Parameters

index
The index of the data segment.

Returns

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

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.

virtual Size mi::​neuraylib::​ITarget_code::get_string_constant_count() const [pure virtual]

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

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

virtual Size mi::​neuraylib::​ITarget_code::get_texture_count() const [pure virtual]

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

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

Returns the distribution function data this texture refers to.

Note:

Calling this function is only meaningful in case get_texture_shape() returns mi::neuraylib::ITarget_code::Texture_shape_bsdf_data.

Parameters

index
The index of the texture resource.
rx
The resolution of the texture in x.
ry
The resolution of the texture in y.
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.

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.

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.

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.

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.

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.

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.

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.

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.

Returns

The buffer in case of success and NULL otherwise.

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.