neuray API Programmer's Manual

mi::neuraylib::IMdl_module_transformer Class Reference

[Miscellaneous MDL-related Interfaces]

Description

The module transformer allows to apply certain transformations on an MDL module.

Note:
Beware of the following implicit changes to MDL modules when using the module transformer, in particular from the point of view of MDL source code:

  • All comments are removed.

  • Defaults are inserted for parameters without arguments.

  • Conversion between named and positional arguments.

  • Reformatting of the MDL source code.

  • Possibly restructuring of alias declarations (including introduction of new ones).

/

See also:

mi::neuraylib::IMdl_factory::create_module_transformer()

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

Public Member Functions

virtual Sint32 export_module( const char* filename, IMdl_execution_context* context) =0
Exports the transformed MDL module to disk. More...
virtual Sint32 export_module_to_string( IString* exported_module, IMdl_execution_context* context) =0
Exports the transformed MDL module to string. More...
virtual Sint32 inline_imported_modules( const char* include_filter, const char* exclude_filter, bool omit_anno_origin, IMdl_execution_context* context) =0
Inline imported modules. More...
virtual Sint32 upgrade_mdl_version( Mdl_version version, IMdl_execution_context* context) =0
Upgrades the MDL version. More...
virtual Sint32 use_absolute_import_declarations( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) =0
Changes import declarations to absolute style. More...
virtual Sint32 use_absolute_resource_file_paths( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) =0
Changes resource file paths to absolute style. More...
virtual Sint32 use_relative_import_declarations( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) =0
Changes import declarations to strict relative style. More...
virtual Sint32 use_relative_resource_file_paths( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) =0
Changes resource file paths to relative style. More...

Member Functions

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::export_module( const char* filename, IMdl_execution_context* context) [pure virtual]

Exports the transformed MDL module to disk. The following options are supported:

  • "bundle_resources" of type bool: If true, referenced resources are exported into the same directory as the module, even if they can be found via the module search path. Default: false.

  • bool "export_resources_with_module_prefix": If true, the name of the exported resources start with the module name as prefix. Default: true.

Parameters

filename
The name of the file to be used for the export.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Failed to open filename for write operations.
  • -6002: There is no MDL module in the database of the given name.
  • -6003: The export failed for unknown reasons.
  • -6004: The MDL module can not be exported since it is a builtin module.
  • -6005: The MDL module can not be exported since filename does not result in a valid MDL identifier.
  • -6010: Incorrect type for a referenced resource.
  • -6013: The export of a file-based resource failed.
  • -6014: The export of a memory-based resource failed.
  • -6016: The export of an archive-based resource failed.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::export_module_to_string( IString* exported_module, IMdl_execution_context* context) [pure virtual]

Exports the transformed MDL module to string.

Parameters

exported_module
The exported module source code is written to this string.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -6002: There is no MDL module in the database of the given name.
  • -6003: The export failed for unknown reasons.
  • -6004: The MDL module can not be exported since it is a builtin module.
  • -6006: The option bundle_resources is not supported for string-based exports.
  • -6010: Incorrect type for a referenced resource.
  • -6011: The export of file-based resources is not supported for string-based exports.
  • -6012: The export of memory-based resources is not supported for string-based exports.
  • -6013: The export of a file-based resource failed.
  • -6014: The export of a memory-based resource failed.
  • -6015: The export of archive-based resources is not supported for string-based exports.
  • -6016: The export of an archive-based resource failed.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::inline_imported_modules( const char* include_filter, const char* exclude_filter, bool omit_anno_origin, IMdl_execution_context* context) [pure virtual]

Inline imported modules. Only modules that match the include filter, but not the exclude filter, are inlined. Builtin modules are never inlined. Inlining of modules with relative resource file paths does not work.

Parameters

include_filter
An extended regular expression [OGBS7] of absolute MDL module names to include, or NULL which matches any module.
exclude_filter
An extended regular expression [OGBS7] of absolute MDL module names to exclude, or NULL which matches no module.
omit_anno_origin
The anno::origin annotation causes an MDL version of at least 1.5 for the new module. Omitting the annotation allows to create MDL modules of older versions (depending on the other features used).
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

A return code. The return codes have the following meaning:

  • 0: Success.
  • -1: An error occurred. Details are provided in the execution context.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::upgrade_mdl_version( Mdl_version version, IMdl_execution_context* context) [pure virtual]

Upgrades the MDL version. The MDL version can only be increased, not decreased. The new MDL needs to be at least MDL version 1.3.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::use_absolute_import_declarations( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) [pure virtual]

Changes import declarations to absolute style. Only import declaration that match the include filter, but not the exclude filter, are changed.

Parameters

include_filter
An extended regular expression [OGBS7] of absolute MDL module names to include, or NULL which matches any module.
exclude_filter
An extended regular expression [OGBS7] of absolute MDL module names to exclude, or NULL which matches no module.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

A return code. The return codes have the following meaning:

  • 0: Success.
  • -1: An error occurred. Details are provided in the execution context.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::use_absolute_resource_file_paths( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) [pure virtual]

Changes resource file paths to absolute style. Only resource file paths that match the include filter, but not the exclude filter, are changed. Memory-based resources do not have any file paths. They are not affected by this transformation. Later, they are exported next to the module with relative paths.

Parameters

include_filter
An extended regular expression [OGBS7] of absolute file paths to include, or NULL which matches any resource.
exclude_filter
An extended regular expression [OGBS7] of absolute file paths to exclude, or NULL which matches no resource.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

A return code. The return codes have the following meaning:

  • 0: Success.
  • -1: An error occurred. Details are provided in the execution context.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::use_relative_import_declarations( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) [pure virtual]

Changes import declarations to strict relative style. Only import declaration that match the include filter, but not the exclude filter, are changed. Import declarations for builtin modules or modules in different search paths are never changed.

This transformation requires MDL version >= 1.3.

Parameters

include_filter
An extended regular expression [OGBS7] of absolute MDL module names to include, or NULL which matches any module.
exclude_filter
An extended regular expression [OGBS7] of absolute MDL module names to exclude, or NULL which matches no module.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

A return code. The return codes have the following meaning:

  • 0: Success.
  • -1: An error occurred. Details are provided in the execution context.

virtual Sint32 mi::​neuraylib::​IMdl_module_transformer::use_relative_resource_file_paths( const char* include_filter, const char* exclude_filter, IMdl_execution_context* context) [pure virtual]

Changes resource file paths to relative style. Only resource file paths that match the include filter, but not the exclude filter, are changed. Resource file paths for resources in different search paths are never changed.

Memory-based resources do not have any file paths. They are not affected by this transformation. Later, they are exported next to the module with relative paths.

This transformation requires MDL version >= 1.3.

Parameters

include_filter
An extended regular expression [OGBS7] of absolute file paths to include, or NULL which matches any resource.
exclude_filter
An extended regular expression [OGBS7] of absolute file paths to exclude, or NULL which matches no resource.
context
The execution context can be used to obtain messages like errors or warnings are stored in the context. Can be NULL.

Returns

A return code. The return codes have the following meaning:

  • 0: Success.
  • -1: An error occurred. Details are provided in the execution context.