omni.mdl.neuraylib¶

CHANGELOG

Python API¶

This module contains bindings to the C++ rtx.neuraylib.plugin interface.

The central structure type MdlModule, MldEntity, and MdlEntitySnapshot are ref-counted internally. So creating the first instance of them actually creates a new object, further calls, with the same configuration (or same parameters) will return the same object while internally the reference count is increased. Every object returned from the create functions that is different from None needs to be disposed by calling the corresponding destroy function to decrease the reference counter of the instance. When this counter reaches zero, the object is disposed.

All the function are in the omni.mdl.neuraylib::NeurayLib class, to get it use get_app_interface method, which caches acquire interface call:

>>> import omni.mdl.neuraylib
>>> a = omni.mdl.neuraylib.get_neuraylib()

class omni.mdl.neuraylib.MdlEntity¶

Bases: pybind11_builtins.pybind11_object

Maps between USD shade nodes and the MDL representation of a shade node. Identified by the USD Prim Path, different components can access this entity in a scene.

property dbScopeName¶: Name of the neuray database scope of the ISceneRenderer in which this entity is stored in. This can NOT change during the lifetime of the object.

getMdlModule(self: omni.mdl.neuraylib._neuraylib.MdlEntity) → omni.mdl.neuraylib._neuraylib.MdlModule¶: Handle to the module that contains the entities definition. This can change during the lifetime of the object. Since this is module is not ‘created’ here, don’t call destroy on it.

property simpleNameWithSignature¶: Name of the material or function within its module along with its parameter list attached. This can change during the lifetime of the object.

property uniquePrimPath¶: The USD Prim Path that identifies this entity in the scene. This can NOT change during the lifetime of the object.

valid(self: omni.mdl.neuraylib._neuraylib.MdlEntity) → bool¶: Get the state of entity. It is valid if a module a simple name is assigned.

class omni.mdl.neuraylib.MdlEntitySnapshot¶

Bases: pybind11_builtins.pybind11_object

MDL representation of a shade node along with the currently set parameters. Parameters can be inspected while changes are reflected from USD (in rtx.hydra.plugin). This snapshot is passed to the ISceneRenderer for creating and updating the renderer material.

Created from an MdlEntity at a certain point in time. When the MdlEntity did not change in the meantime, the same MdlEntitySnapshot can be accessed using the create function. When the MdlEntity changed (different module or function name), a new snapshot can be created while to old one still exist but might not be valid anymore (in case of reloads).

property dbName¶: Name of a MDL material instance or functions call in the neuray database.

property dbScopeName¶: Name of the neuray database scope (of the ISceneRenderer) in which this entity is stored in.

getMdlModule(self: omni.mdl.neuraylib._neuraylib.MdlEntitySnapshot) → omni.mdl.neuraylib._neuraylib.MdlModule¶: Handle to the module that contains the entities definition.) Since this is module is not ‘created’ here, don’t call destroy on it.

property simpleNameWithSignature¶: Name of the material or function within its module along with its parameter list attached.

class omni.mdl.neuraylib.MdlModule¶

Bases: pybind11_builtins.pybind11_object

The representation of an MDL module to load or loaded by neuray.

property dbName¶: The name of the MDL module in the neuray database.

property dbScopeName¶: The name of the DB scope to load the definitions to.

property qualifiedName¶: The fully qualified MDL name of the module

valid(self: omni.mdl.neuraylib._neuraylib.MdlModule) → bool¶: Get the state of module, describes if loaded and if valid or not

class omni.mdl.neuraylib.NeurayLib¶

Bases: pybind11_builtins.pybind11_object

createEditingTransaction(self: omni.mdl.neuraylib._neuraylib.NeurayLib, dbScopeName: str = 'rtx_scope') → int¶

Creates a write access transaction for a given database scope with short term usage in mind.

This transaction should be used for write access e.g. for editing a material instance code. Use the transaction on a per task level and from one thread only. When done, call commit in case you made changes or abort in case you only read information. However, keep in mind that the this new transaction can only see DB state that was already committed.

Parameters: dbScopeName (str) – Name of the DB scope to edit.
Return type: ITransactionEdit
Returns: The created transaction or None if the creation failed, e.g. because of an invalid scope.

createMdlEntity(self: omni.mdl.neuraylib._neuraylib.NeurayLib, uniquePrimPath: str, dbScopeName: str = 'rtx_scope') → omni.mdl.neuraylib._neuraylib.MdlEntity¶

Creates an MdlEnity for a selected scope. It maps an MDL representation to a particular USD shade graph node.

If there already is an MdlEntity the same object is returned again with an increased reference count. This allows multiple components to access the same data based on the USD Prim Path.

Parameters

uniquePrimPath (str) – USD path of the shade node this entity will belong to. Allows to identify the node from different kit components.
scopeName (str) – Name of the DB scope to later store snapshots in (default: ‘usdIdentifier’).

Return type

MdlEntity

Returns

The handle that represents the shade USD graph node. Needs the released using destroyMdlEntity when not required anymore.

createMdlEntitySnapshot(self: omni.mdl.neuraylib._neuraylib.NeurayLib, arg0: omni.mdl.neuraylib._neuraylib.MdlEntity) → omni.mdl.neuraylib._neuraylib.MdlEntitySnapshot¶

Creates an MDL material instance or function call in the neuray DB scope provided. This snapshot is used for editing and creating material representations specific to the renderer. If there already is a valid snapshot for this MdlEntity and if the selected function name did not change, the same snapshot is returned again with an increased reference count.

Parameters: mdlEntity (MdlEntity) – An MdlEntityId with a valid function name set (currently only from C++).
Return type: MdlEntitySnapshot
Returns: A snapshot that represents a MDL material instance or function call present in the neuray database. Needs the released using destroyMdlEntity when not required anymore.

createMdlModule(self: omni.mdl.neuraylib._neuraylib.NeurayLib, usdIdentifier: str, dbScopeName: str = 'rtx_scope') → omni.mdl.neuraylib._neuraylib.MdlModule¶

Loads an MDL module and stores the loaded definitions in the neuray DB scope provided.

Parameters

usdIdentifier (str) – The USD asset identifier of the module to load.
scopeName (str) – Name of the DB scope to load the definitions to (default: ‘usdIdentifier’).

Return type

MdlModule

Returns

The handle that contains the database name of the created module. Needs the released using destroyMdlModule when not required anymore.

createReadingTransaction(self: omni.mdl.neuraylib._neuraylib.NeurayLib, dbScopeName: str = 'rtx_scope') → int¶

Creates a read-only transaction for a given database scope with short term usage in mind.

This transaction can only be used for read access e.g. for generating shader code. Use the transaction on a per task level and from one thread only. This transaction can not be committed as it is not allowed to make changes to the database. However, keep in mind that the this new transaction can only see DB state that was already committed.

Parameters: dbScopeName (str) – Name of the DB scope to read from.
Return type: ITransactionRead
Returns: The created transaction or None if the creation failed, e.g. because of an invalid scope.

destroyMdlEntity(self: omni.mdl.neuraylib._neuraylib.NeurayLib, arg0: omni.mdl.neuraylib._neuraylib.MdlEntity) → None¶

Releases a previously created entity.

Parameters: mdlEntity (MdlEntity) – An enitity that was created using`createMdlEntity`.

destroyMdlEntitySnapshot(self: omni.mdl.neuraylib._neuraylib.NeurayLib, arg0: omni.mdl.neuraylib._neuraylib.MdlEntitySnapshot) → None¶

Releases a previously created entity snapshot.

Parameters: mdlEntity (MdlEntitySnapshot) – An enitity that was created using`createMdlEntitySnapshot`.

destroyMdlModule(self: omni.mdl.neuraylib._neuraylib.NeurayLib, arg0: omni.mdl.neuraylib._neuraylib.MdlModule) → None¶

Releases a previously loaded module.

Parameters: mdlModule (MdlModule) – A module that was created using`createMdlModule`.

getNeurayAPI(self: omni.mdl.neuraylib._neuraylib.NeurayLib) → int¶: Returns a handle to the neuray API. This handle has to be attached to the MDL SDK Python binding using omni.mdl.pymdlsdk.attach_ineuray.

omni.mdl.neuraylib.PrepareModule(module, result)¶: Prepare an extension module at import time. Generally, this should only be called by the __init__.py script for a module upon loading a pybind11 module (generally ‘_LibName.so’).

omni.mdl.neuraylib.acquire_interface(plugin_name: str = None, library_path: str = None) → omni.mdl.neuraylib._neuraylib.NeurayLib¶

omni.mdl.neuraylib.get_neuraylib() → omni.mdl.neuraylib.NeurayLib ¶: Returns cached omni.mdl.neuraylib.NeurayLib interface

omni.mdl.neuraylib.lru_cache(maxsize=128, typed=False)¶

Least-recently-used cache decorator.

If maxsize is set to None, the LRU features are disabled and the cache can grow without bound.

If typed is True, arguments of different types will be cached separately. For example, f(3.0) and f(3) will be treated as distinct calls with distinct results.

Arguments to the cached function must be hashable.

View the cache statistics named tuple (hits, misses, maxsize, currsize) with f.cache_info(). Clear the cache and statistics with f.cache_clear(). Access the underlying function with f.__wrapped__.

See: http://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)

omni.mdl.neuraylib.release_interface(arg0: omni.mdl.neuraylib._neuraylib.NeurayLib) → None¶