vray.Util¶
- class vray.Util¶
Bases:
objectStatic class for utility helper methods.
Attributes
Methods
__init__()Copies some of the specified plugins in the includeListOfPlugins list of the srcRenderer and some of their successors, depending on an exludeListOfPlugins, a user-defined pre-create callback to the dstRenderer and at the end, invoking a user-defined post-create callback on the created plugins after all have been processed. REMARK: if a plugin scheduled to be visited by the preCreateCallback is deleted, it will not be counted as an error and it will be skipped as well as the successors that were attached to it as we have no reference to them. WARNING: One should decide how to handle singleton plugins (plugins which have at most one instance in a scene)! WARNING: We highly recommend that you don’t modify plugins (including deletion, clearing the scene etc.) of srcRenderer and dstRenderer for the whole duration of this call! Doing so could lead to unexpected results including crashes. If the includeListOfPlugins is empty, we will invoke the preCreateCallback on all the plugins of the srcRenderer (a part from the rtEngine). If the includeListOfPlugins is non-empty, we will surely invoke the preCreateCallback on all plugins in the list and all successors which have been approved by the preCreateCallback invocations. If the excludeListOfPlugins is empty, it does not affect anything. If the excludeListOfPlugins is non-empty, then the mentioned plugins in it will not be scheduled to be visited by the preCreateCallback (even if they are mentioned explicitly in the includeListOfPlugins or implicitly via relatedness to a plugin mentioned in the includeListOfPlugins) and will surely not be copied. Their successors will also not be scheduled, but are not banned to be scheduled by being in another plugin’s successor list. What can you do with the preCreateCallback? You get as arguments the dstRenderer and the srcPlugin. You will return an object which can contain the following properties: - name - A string with which we will try to rename the plugin in the dstRenderer. If it is an empty string, then this plugin creation will be skipped and successors will not be processed. Default is empty string. REMARK: If the ‘name’ field of the object is missing, then the plugin being reviewed will be skipped. - skipOnlyCurrentPlugin - A boolean variable which, if true and combined with the field “name” being an empty string, then the plugin is skipped, but successors will be processed. Default is false. Can be skipped. - skipAllSuccessorsOfCurrentPlugin - A boolean variable which, if true will ensure that no successors of the currently processed plugin will be processed. Default is false. Can be skipped. - overwriteExistingPlugin - A boolean variable which, if set to true, if there is a plugin in the dstRenderer with the same name as the one specified in the field ‘name’, it will try to overwrite it (reusing the existing instance and not recreating it from scratch). Keep in mind that they may not be of the same type, and if it occurs, then the created plugin will have an auto-generated name and the postCreateCallback integer enumerable argument autoRenamedResult will be set to the corresponding value. Default is false. Can be skipped. What can you do with the postCreateCallback? You get as arguments the dstPlugin, srcPluginName, autoRenamedResult and preCreateCallbackReturnedName. Some more information about some of the arguments: - srcPluginName - A string that is the same as srcPlugin name. - autoRenamedResult - An integer constant which is used to indicate how the renaming process has finished. Can be:
vray.Util.NO_AUTO_RENAME- No automatic renaming has occured.vray.Util.NO_OVERWRITE_NO_EXISTING_PLUGIN_BUT_INVALID_PLUGIN_NAME- We have not set the plugin to be overwritten, and there isn’t a plugin with the same name in the dstRenderer, but the chosen plugin name is invalid. Hence, the plugin is created, but automatically renamed.vray.Util.NO_OVERWRITE_BUT_EXISTING_PLUGIN_WITH_NAME- We have not set the plugin to be overwritten, but there is an existing plugin in the dstRenderer with the same name, so we fallback to automatic renaming.vray.Util.OVERWRITE_EXISTING_PLUGIN_WITH_NAME_BUT_DIFFERENT_TYPE- We have set the plugin to be overwritten if there exists a plugin with the same name in the dstRenderer, but the plugins don’t have the same plugin type. Hence, fallback to automatic renaming. - preCreateCallbackReturnedName - A string that is the same as ‘name’ field in the returned object of the preCreateCallback.Copies some of the specified plugins of type (class) pluginType of the srcRenderer and some of their successors, depending on a user-defined pre-create callback to the dstRenderer and at the end, invoking a user-defined post-create callback on the created plugins after all have been processed. REMARK: if a plugin scheduled to be visited by the preCreateCallback is deleted, it will not be counted as an error and it will be skipped as well as the successors that were attached to it as we have no reference to them. WARNING: One should decide how to handle singleton plugins (plugins which have at most one instance in a scene)! WARNING: We highly recommend that you don’t modify plugins (including deletion, clearing the scene etc.) of srcRenderer and dstRenderer for the whole duration of this call! Doing so could lead to unexpected results including crashes. What can you do with the preCreateCallback? You get as arguments the dstRenderer and the srcPlugin. You will return an object which can contain the following properties: - name - A string with which we will try to rename the plugin in the dstRenderer. If it is an empty string, then this plugin creation will be skipped and successors will not be processed. Default is empty string. REMARK: If the ‘name’ field of the object is missing, then the plugin being reviewed will be skipped. - skipOnlyCurrentPlugin - A boolean variable which, if true and combined with the field “name” being an empty string, then the plugin is skipped, but successors will be processed. Default is false. Can be skipped. - skipAllSuccessorsOfCurrentPlugin - A boolean variable which, if true will ensure that no successors of the currently processed plugin will be processed. Default is false. Can be skipped. - overwriteExistingPlugin - A boolean variable which, if set to true, if there is a plugin in the dstRenderer with the same name as the one specified in the field ‘name’, it will try to overwrite it (reusing the existing instance and not recreating it from scratch). Keep in mind that they may not be of the same type, and if it occurs, then the created plugin will have an auto-generated name and the postCreateCallback integer enumerable argument autoRenamedResult will be set to the corresponding value. Default is false. Can be skipped. What can you do with the postCreateCallback? You get as arguments the dstPlugin, srcPluginName, autoRenamedResult and preCreateCallbackReturnedName. Some more information about some of the arguments: - srcPluginName - A string that is the same as srcPlugin name. - autoRenamedResult - An integer constant which is used to indicate how the renaming process has finished. Can be:
vray.Util.NO_AUTO_RENAME- No automatic renaming has occured.vray.Util.NO_OVERWRITE_NO_EXISTING_PLUGIN_BUT_INVALID_PLUGIN_NAME- We have not set the plugin to be overwritten, and there isn’t a plugin with the same name in the dstRenderer, but the chosen plugin name is invalid. Hence, the plugin is created, but automatically renamed.vray.Util.NO_OVERWRITE_BUT_EXISTING_PLUGIN_WITH_NAME- We have not set the plugin to be overwritten, but there is an existing plugin in the dstRenderer with the same name, so we fallback to automatic renaming.vray.Util.OVERWRITE_EXISTING_PLUGIN_WITH_NAME_BUT_DIFFERENT_TYPE- We have set the plugin to be overwritten if there exists a plugin with the same name in the dstRenderer, but the plugins don’t have the same plugin type. Hence, fallback to automatic renaming. - preCreateCallbackReturnedName - A string that is the same as ‘name’ field in the returned object of the preCreateCallback.Returns a list of plugin dependency links.
Returns the prescribed intensity of the light specified in an .ies file.
Returns a list of plugins that directly reference the given child plugin.
- static copyPlugins()¶
Copies some of the specified plugins in the includeListOfPlugins list of the srcRenderer and some of their successors, depending on an exludeListOfPlugins, a user-defined pre-create callback to the dstRenderer and at the end, invoking a user-defined post-create callback on the created plugins after all have been processed. REMARK: if a plugin scheduled to be visited by the preCreateCallback is deleted, it will not be counted as an error and it will be skipped as well as the successors that were attached to it as we have no reference to them. WARNING: One should decide how to handle singleton plugins (plugins which have at most one instance in a scene)! WARNING: We highly recommend that you don’t modify plugins (including deletion, clearing the scene etc.) of srcRenderer and dstRenderer for the whole duration of this call! Doing so could lead to unexpected results including crashes. If the includeListOfPlugins is empty, we will invoke the preCreateCallback on all the plugins of the srcRenderer (a part from the rtEngine). If the includeListOfPlugins is non-empty, we will surely invoke the preCreateCallback on all plugins in the list and all successors which have been approved by the preCreateCallback invocations. If the excludeListOfPlugins is empty, it does not affect anything. If the excludeListOfPlugins is non-empty, then the mentioned plugins in it will not be scheduled to be visited by the preCreateCallback (even if they are mentioned explicitly in the includeListOfPlugins or implicitly via relatedness to a plugin mentioned in the includeListOfPlugins) and will surely not be copied. Their successors will also not be scheduled, but are not banned to be scheduled by being in another plugin’s successor list. What can you do with the preCreateCallback? You get as arguments the dstRenderer and the srcPlugin. You will return an object which can contain the following properties:
name - A string with which we will try to rename the plugin in the dstRenderer.
If it is an empty string, then this plugin creation will be skipped and successors will not be processed. Default is empty string. REMARK: If the ‘name’ field of the object is missing, then the plugin being reviewed will be skipped. - skipOnlyCurrentPlugin - A boolean variable which, if true and combined with the field “name” being an empty string, then the plugin is skipped, but successors will be processed. Default is false. Can be skipped. - skipAllSuccessorsOfCurrentPlugin - A boolean variable which, if true will ensure that no successors of the currently processed plugin will be processed. Default is false. Can be skipped. - overwriteExistingPlugin - A boolean variable which, if set to true, if there is a plugin in the dstRenderer with the same name as the one specified in the field ‘name’, it will try to overwrite it (reusing the existing instance and not recreating it from scratch). Keep in mind that they may not be of the same type, and if it occurs, then the created plugin will have an auto-generated name and the postCreateCallback integer enumerable argument autoRenamedResult will be set to the corresponding value. Default is false. Can be skipped.
What can you do with the postCreateCallback? You get as arguments the dstPlugin, srcPluginName, autoRenamedResult and preCreateCallbackReturnedName. Some more information about some of the arguments:
srcPluginName - A string that is the same as srcPlugin name.
autoRenamedResult - An integer constant which is used to indicate how the renaming process has finished.
- Can be:
vray.Util.NO_AUTO_RENAME- No automatic renaming has occured.vray.Util.NO_OVERWRITE_NO_EXISTING_PLUGIN_BUT_INVALID_PLUGIN_NAME- We have not set the plugin to be overwritten, and there isn’t a plugin with the same name in the dstRenderer, but the chosen plugin name is invalid. Hence, the plugin is created, but automatically renamed.vray.Util.NO_OVERWRITE_BUT_EXISTING_PLUGIN_WITH_NAME- We have not set the plugin to be overwritten, but there is an existing plugin in the dstRenderer with the same name, so we fallback to automatic renaming.vray.Util.OVERWRITE_EXISTING_PLUGIN_WITH_NAME_BUT_DIFFERENT_TYPE- We have set the plugin to be overwritten if there exists a plugin with the same name in the dstRenderer, but the plugins don’t have the same plugin type. Hence, fallback to automatic renaming.
preCreateCallbackReturnedName - A string that is the same as ‘name’ field in the returned object of the preCreateCallback.
Positional (in this order) or keyword arguments:
srcRenderer, VRayRenderer - the source renderer (a valid VRayRenderer object). All plugins in the following lists must be of this renderer.
dstRenderer, VRayRenderer - the destination renderer (a valid VRayRenderer object).
includeListOfPlugins, a list of Plugins - a list of plugin names and/or plugin instances that will be processed. It is an optional argument.
excludeListOfPlugins, a list of Plugins - a list of plugin names and/or plugin instances that will be excluded from being processed. It is an optional argument.
preCreateCallback, function(VRayRenderer, Plugin)->PyObject. It is an optional argument.
Pre-creation callback:
dstRenderer - the destination renderer
srcPlugin - the plugin to be copied
A user-defined callback called on each plugin in the includeListOfPlugins and some of their successors. The user should return an object with some of the properties ‘name’, ‘skipOnlyCurrentPlugin’, ‘overwriteExistingPlugin’ set.
postCreateCallback, function(Plugin, string, integer constant, string)->void. It is an optional argument.
Post-creation callback:
dstPlugin - the copied plugin
srcPluginName - the name of the copied plugin in the srcRenderer
autoRenamedResult - an integer constant which is used to indicate how the renaming process has finished
preCreateCallbackReturnedName - the name given by the user via the preCreateCallback return object
A user callback which is called for each plugin instance after copying it to the dstRenderer. The user can see whether it is named as desired by checking autoRenamedResult and can set the name to the desired preCreateCallbackReturnedName. The user also can use the name of the corresponding plugin in the srcRenderer. The user can also mutate the plugin (change the plugin’s parents and children plugins, values of parameters, etc.) Will return the number of successfully copied (plus the overwritten) plugins on success.
- static copyPluginsOfType()¶
Copies some of the specified plugins of type (class) pluginType of the srcRenderer and some of their successors, depending on a user-defined pre-create callback to the dstRenderer and at the end, invoking a user-defined post-create callback on the created plugins after all have been processed. REMARK: if a plugin scheduled to be visited by the preCreateCallback is deleted, it will not be counted as an error and it will be skipped as well as the successors that were attached to it as we have no reference to them. WARNING: One should decide how to handle singleton plugins (plugins which have at most one instance in a scene)! WARNING: We highly recommend that you don’t modify plugins (including deletion, clearing the scene etc.) of srcRenderer and dstRenderer for the whole duration of this call! Doing so could lead to unexpected results including crashes. What can you do with the preCreateCallback? You get as arguments the dstRenderer and the srcPlugin. You will return an object which can contain the following properties:
name - A string with which we will try to rename the plugin in the dstRenderer.
If it is an empty string, then this plugin creation will be skipped and successors will not be processed. Default is empty string. REMARK: If the ‘name’ field of the object is missing, then the plugin being reviewed will be skipped. - skipOnlyCurrentPlugin - A boolean variable which, if true and combined with the field “name” being an empty string, then the plugin is skipped, but successors will be processed. Default is false. Can be skipped. - skipAllSuccessorsOfCurrentPlugin - A boolean variable which, if true will ensure that no successors of the currently processed plugin will be processed. Default is false. Can be skipped. - overwriteExistingPlugin - A boolean variable which, if set to true, if there is a plugin in the dstRenderer with the same name as the one specified in the field ‘name’, it will try to overwrite it (reusing the existing instance and not recreating it from scratch). Keep in mind that they may not be of the same type, and if it occurs, then the created plugin will have an auto-generated name and the postCreateCallback integer enumerable argument autoRenamedResult will be set to the corresponding value. Default is false. Can be skipped.
What can you do with the postCreateCallback? You get as arguments the dstPlugin, srcPluginName, autoRenamedResult and preCreateCallbackReturnedName. Some more information about some of the arguments:
srcPluginName - A string that is the same as srcPlugin name.
autoRenamedResult - An integer constant which is used to indicate how the renaming process has finished.
- Can be:
vray.Util.NO_AUTO_RENAME- No automatic renaming has occured.vray.Util.NO_OVERWRITE_NO_EXISTING_PLUGIN_BUT_INVALID_PLUGIN_NAME- We have not set the plugin to be overwritten, and there isn’t a plugin with the same name in the dstRenderer, but the chosen plugin name is invalid. Hence, the plugin is created, but automatically renamed.vray.Util.NO_OVERWRITE_BUT_EXISTING_PLUGIN_WITH_NAME- We have not set the plugin to be overwritten, but there is an existing plugin in the dstRenderer with the same name, so we fallback to automatic renaming.vray.Util.OVERWRITE_EXISTING_PLUGIN_WITH_NAME_BUT_DIFFERENT_TYPE- We have set the plugin to be overwritten if there exists a plugin with the same name in the dstRenderer, but the plugins don’t have the same plugin type. Hence, fallback to automatic renaming.
preCreateCallbackReturnedName - A string that is the same as ‘name’ field in the returned object of the preCreateCallback.
Positional (in this order) or keyword arguments:
srcRenderer, VRayRenderer - the source renderer (a valid VRayRenderer object). All plugins in the following lists must be of this renderer.
dstRenderer, VRayRenderer - the destination renderer (a valid VRayRenderer object).
pluginType, string or vray.Class - the type (class) of the plugins to be processed. Cannot be None.
preCreateCallback, function(VRayRenderer, Plugin)->Dictionary. It is an optional argument.
Pre-creation callback:
dstRenderer - the destination renderer
srcPlugin - the plugin to be copied
A user-defined callback called on each plugin in the includeListOfPlugins and some of their successors. The user should return an object with some of the properties ‘name’, ‘skipOnlyCurrentPlugin’, ‘overwriteExistingPlugin’ set.
postCreateCallback, function(Plugin, string, integer constant, string)->void. It is an optional argument.
Post-creation callback:
dstPlugin - the copied plugin
srcPluginName - the name of the copied plugin in the srcRenderer
autoRenamedResult - an integer constant which is used to indicate how the renaming process has finished
preCreateCallbackReturnedName - the name given by the user via the preCreateCallback return object
A user callback which is called for each plugin instance after copying it to the dstRenderer. The user can see whether it is named as desired by checking autoRenamedResult and can set the name to the desired preCreateCallbackReturnedName. The user also can use the name of the corresponding plugin in the srcRenderer. The user can also mutate the plugin (change the plugin’s parents and children plugins, values of parameters, etc.) Will return the number of successfully copied (plus the overwritten) plugins on success.
- static getChildPlugins()¶
Returns a list of plugin dependency links.
Any reference to another plugin from a property (including list property) will append a PluginLink tuple to the list Properties are checked in the order of their definition in the plugin descriptor.
- PluginLink tuples in the list contain:
[0] - Plugin which makes the reference
[1] - string name of the property containing the reference
[2] - PluginRef which is being referenced (may have an output property)
- Arguments:
root, Plugin - The plugin to start from
recursive, boolean - If True, after processing all the properties of one plugin, recursively check the dependency plugins
- static getIESPrescribedIntensity()¶
Returns the prescribed intensity of the light specified in an .ies file.
- Arguments:
iesFile, string - The .ies file name full path
- static getParentPlugins()¶
Returns a list of plugins that directly reference the given child plugin.
- PluginLink tuples in the list contain:
[0] - Plugin which makes the reference
[1] - string name of the property containing the reference
[2] - PluginRef which is being referenced (may have an output property)
- Arguments:
child, Plugin - The plugin which we is used by “parents”
- NO_AUTO_RENAME = 0¶
- NO_OVERWRITE_BUT_EXISTING_PLUGIN_WITH_NAME = 2¶
- NO_OVERWRITE_NO_EXISTING_PLUGIN_BUT_INVALID_PLUGIN_NAME = 1¶
- OVERWRITE_EXISTING_PLUGIN_WITH_NAME_BUT_DIFFERENT_TYPE = 3¶