cacheEvaluator

Go to: Synopsis. Return value. Keywords. Flags. MEL examples.

Synopsis

cacheEvaluator [-cacheFillMode string] [-cacheFillOrder string] [-cacheInvalidate timerange] [-cacheName string] [-cachingPoints] [-creationParameters] [-flushCache string] [-flushCacheRange timerange boolean] [-flushCacheSync boolean] [-flushCacheWait] [-listCacheNames] [-listCachedNodes] [-listValueNames] [-newAction string] [-newActionParam string] [-newFilter string] [-newFilterParam string] [-newRule string] [-newRuleParam string] [-pauseInvalidation] [-preventFrameSkip boolean] [-resetRules] [-resourceUsage] [-resumeInvalidation] [-safeMode boolean] [-safeModeMessages] [-safeModeTriggered] [-valueName string] [-waitForCache float]

cacheEvaluator is NOT undoable, queryable, and editable.

This command controls caching configuration. It allows interaction with the caching system.

Caching configuration is done through a set of rules. Most rules are composed of a "filter", which is the test to be perform in order to determine if the rule should be applied, and an "action", which is the effect that the rule application should have on nodes that satisfy the criteria.

A caching mode is therefore a set of rules that determines which nodes are being cached. This mode can be serialized to a JSON string using the "creationParameters" flag in query mode.

Built-in Cache Configuration Modes

Built-in Filters

• evaluationCacheNodes
  This filter matches all nodes for which the node type is in the default supported list for evaluation cache. See the code example below for the current list of supported types.
• nodeTypes
  This filter matches all nodes for which the node type is in the list provided with the newFilterParam flag. The parameter string is a list of comma-separated node types, prefixed with either '-' or '+'. The filter will go through the list in order and will stop if the node is of the given node type (or any derived node type). If the prefix is '-', the filter will return that the node did not match and stop processing. If the prefix is '+', the filter will return a match and stop processing.
• downstreamNodeTypes
  This filter matches all nodes for which the node type is in the list provided with the newFilterParam flag if they also have immediate downstream nodes of the right node type(s). The parameter string is in the form "type=+type1,+type2 downstreamTypes=+type3,+type3", where the list of node types uses the same semantic as the nodeTypes filter.
• vp2CacheNodes
  This filter matches all nodes for which the node type is in the list of node types supported by VP2 caching. Enabling VP2 caching for other node types will have no effect. See the comments in the code example below for the current list of supported types.
• vp2FallbackNodes
  This filter matches all nodes for which VP2 caching should revert to evaluation caching because of unsupported features. Namely, it matches nodes for which VP2 caching is enabled but which have animated visibility or animated topology (potentially changing number of vertices, edges, faces, etc.). It also matches nodes with static geometry, i.e. for which nothing needs to be cached in VP2 format for each frame.

Built-in Actions

• enableEvaluationCache
  This action enables evaluation cache on the matched node. If the evaluation cache is already enabled, it has no effect.
• disableEvaluationCache
  This action disables evaluation cache on the matched node. If the evaluation cache is already disabled, it has no effect.
• disableAllCache
  This action disables all types of caching on the matched node.
• enableVP2Cache
  This action enables VP2 cache on the matched node. "useHardware=1" can be passed to the newActionParam in order to enable the VP2 hardware cache, while "useHardware=0" will use the VP2 software cache. This action disables the evaluation cache (to only keep VP2 cache) on the matched node to save memory. Specifying "useEvaluation=1" to turn on evaluation cache (along with VP2 cache). For example, NURBS surfaces keep the evaluation cache to make the selection highlighting more efficient. This action also automatically applies the fallback to evaluation cache rule for safety if required. This fallback will be applied if the node matches the criteria from the "vp2FallbackNodes" filter and will then apply the action from the "fallbackFromVP2CacheToEvaluationCache" action. "fallback=0" can be used to disable this fallback, but doing so can cause correctness issues,instabilities and even crashes. "useEvaluation=0" does not affect the fallback behavior. To use multiple parameters, separate them with ' ' like "useHardware=1 fallback=0 useEvaluation=1".
• disableVP2Cache
  This action disables the VP2 cache on the matched node. If the VP2 cache is already disabled, it has no effect.
• fallbackFromVP2CacheToEvaluationCache
  This action disables the VP2 cache on the matched node and enables the evaluation cache instead.

Built-in Rules

• evaluationCache
  This rule has the same effect as using the evaluationCacheNodes filter with the enableEvaluationCache action.
• customEvaluators
  This rule ensures proper behavior for nodes claimed by a custom evaluator of a higher priority than the cache evaluator. First, it makes sure that caching is disabled for nodes claimed by a custom evaluator of a higher priority. Secondly, it makes sure input nodes to clusters belonging to a custom evaluator of a higher priority are marked as evaluation caching points if the evaluator needs data. This prevents pull evaluation from happening when the evaluator is evaluated.

Note that any combination of cache configuration rules other than the default modes is considered unsupported and to be used at one's own risk. The default modes are "Evaluation cache", "VP2 software cache" and "VP2 hardware cache". The sets of rules used to enable each mode are listed in the code examples.

Querying Cache Configuration Values

In order to get a cache configuration value for a given node or list of nodes, the cacheName flag can be used in query mode. Without any additional parameters, this query is the same as if the valueName flag was set to "active", i.e. it queries whether the given cache is active or not.

If the queried node is not a caching point, there will be no caching configuration information associated with it and the query will return an empty string (which is basically the same as all cache modes being inactive). If the queried node is a caching point, the returned string will be the requested information from the given cache. For example, querying the "active" value can return "0" or "1".

Return value

In query mode, return type is based on queried flag.

Keywords

Flags

Long name (short name)	Argument types	Properties
-cacheFillMode(-cfm)	string
Specifies the cache fill mode. Valid values are: "syncOnly" to fill cache during playback, "syncAsync" to cache during playback and in background, and "asyncOnly" to fill cache only in background. Query returns current mode.
-cacheFillOrder(-cfo)	string
Specifies in which order the cache fills the timeline. Valid values are: "forward" to fill cache in forward direction, "backward" to fill cache backwards, "bidirectional" to fill cache in forward and backward directions simultaneously, and "forwardFromBegin" to fill cache in forward direction from animation start. Query returns current cache fill mode.
-cacheInvalidate(-ci)	timerange
Specifies the frame range in which cache should be invalidated. The range should be specified as a pair of positive integers. Usage examples: -ci "10:20"{Python equivalent: ('10','20')} means all frames in the range from 10 to 20, inclusive, in the current time unit. Omitting one end of a range means using either end of the animation range (or both), as in the following examples: -ci "10:" means all frames from time 10 (in the current time unit) onwards to the maximum time in the animation range (on the timeline). -ci ":10" means all frames from the minimum time on the animation range (on the timeline) up to (and including) time 10 (in the current time unit). -ci ":" is a short form to specify all frames, from minimum to maximum time on the current animation range.
-cacheName(-cn)	string
Specifies the name of the cache from which to query a value. In query mode, this flag needs a value.
-cachingPoints(-cps)
Get list of nodes marked as caching points, i.e. nodes with at least one type of cache active.
-creationParameters(-cp)
Get the current mode creation parameters. The result is a JSON string which represents an array with an element for each rule. Each element is an association between the parameter name and its value when creating the rule.
-flushCache(-fc)	string
Specifies to flush the current cache. Valid values are: "keep" to store the existing cache as backup, and "destroy" to delete the current cache.
-flushCacheRange(-fcr)	timerange boolean
Specifies the frame range in which cache should be flushed. By default it will destroy the cache - if the 'flushCache' is also set then it will define what to do with the cache range being flushed. The range should be specified as a pair of positive integers and a boolean. Usage examples: -flushCacheRange "10:20" on {Python equivalent: ('10','20',True)} means all frames in the range from 10 to 20, inclusive, in the current time unit. -flushCacheRange "12:18" off {Python equivalent: ('12','18',False)} means all frames before 12 and after 18, not inclusive, in the current time unit. Omitting one end of a range means using either end of the animation range (or both), as in the following examples: -flushCacheRange "10:" on means all frames from time 10 (in the current time unit) onwards to the maximum time in the animation range (on the timeline). -flushCacheRange ":10" on means all frames from the minimum time on the animation range (on the timeline) up to (and including) time 10 (in the current time unit). -flushCacheRange ":" on is a short form to specify all frames, from minimum to maximum time on the current animation range.
-flushCacheSync(-fcs)	boolean
Specifies how to flush the cache: synchronously or asynchronously. True for synchronous, False for asynchronous.
-flushCacheWait(-fcw)
Wait for the cache destruction to be completed.
-listCacheNames(-lcn)
Return the list of existing cache names.
-listCachedNodes(-lcd)
Returns the list of cached nodes.
-listValueNames(-lvn)
Return the list of value names that can be queried for the given cache.
-newAction(-na)	string
Specifies the name of the new action to create in the new filter/action rule.
-newActionParam(-nap)	string
Specifies the parameter string to pass to the new action to create in the new filter/action rule.
-newFilter(-nf)	string
Specifies the name of the new filter to create in the new filter/action rule.
-newFilterParam(-nfp)	string
Specifies the parameter string to pass to the new filter to create in the new filter/action rule.
-newRule(-nr)	string
Specifies the name of the new rule to create.
-newRuleParam(-nrp)	string
Specifies the parameter string to pass to the new rule to create.
-pauseInvalidation(-pi)
Pause all incoming invalidation of the cache. Work in symmetry with resumeInvalidation flag. PauseInvalidation can be called several time, useful in nesting situation. The same number of resume need to be called to resume the invalidation. If queried it will return how much time caching is paused, 0 means it is resumed.
-preventFrameSkip(-pfs)	boolean
Specifies if frame skipping is enabled. Following behavior is seen when frame skipping is enabled, and playback is set to play in real-time. If cache can't be filled at real-time frame rate, frames will NOT be skipped. Once all frames have been looped over(and therefore all frames are cached), and if playing back from cache still can't be done at real-time frame rate; frames WILL be skipped. If memory limit is reached before all frames are cached, frames WILL be skipped. If cache is invalidated will playing(like flushing it), frames will NOT be skipped(until the cache is full again).
-resetRules(-rr)
Reset the cache configuration rules to an empty set of rules.
-resourceUsage(-ru)
Returns the current state of the resource usage as a string. 'unlimited' = the resource limits are being ignored, 'out' = the memory limit has been reached, 'low' = the memory usage is at 90% of the specified limit, 'okay' = memory usage is under 90% of the specified limit.
-resumeInvalidation(-ri)
Resume all incoming invalidation of the cache. Work in symmetry with pauseInvalidation flag. PauseInvalidation can be called several time, useful in nesting situation. The same number of resume need to be called to resume the invalidation. If queried it will return true if cache is resumed, false otherwise.
-safeMode(-sf)	boolean
Turns safe mode on or off. In query mode, it returns the status of the safe mode for cache evaluator.
-safeModeMessages(-sfm)
Prints the safe mode messages to the console.
-safeModeTriggered(-sft)
Returns if the safe mode was triggered for cache evaluator.
-valueName(-vn)	string
Specifies the name of the parameter for which to query the value. In query mode, this flag needs a value.
-waitForCache(-wfc)	float
Specifies to wait for cache to fill in background, with [Time to wait in seconds] timeout.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can be used more than once in a command.

MEL examples

// Enable evaluation cache.
cacheEvaluator -resetRules;
cacheEvaluator -newFilter "evaluationCacheNodes" -newAction "enableEvaluationCache";
cacheEvaluator -newRule "customEvaluators";

// Enable VP2 software cache.
cacheEvaluator -resetRules;
// VP2 cache only works on a subset of types (mesh, nurbsCurve, nurbsSurface, bezierCurve),
// so we still enable evaluation cache for other types.
cacheEvaluator -newFilter "evaluationCacheNodes" -newAction "enableEvaluationCache";
// Enabling VP2 cache will disable evaluation cache on the supported types.
// Note that using the vp2CacheNodes filter is equivalent to using the
// "nodeTypes" filter with the right types specified as the "newFilterParam"
// string, i.e. "types=+mesh,+nurbsCurve,+bezierCurve,+nurbsSurface".
cacheEvaluator -newFilter "vp2CacheNodes" -newAction "enableVP2Cache" -newActionParam "useHardware=0";
// Custom evaluators of a higher priority than the caching evaluator
// may need additional caching points around its boundary to evaluate properly.
cacheEvaluator -newRule "customEvaluators";

// Enable VP2 hardware cache.
cacheEvaluator -resetRules;
// VP2 cache only works on a subset of types (mesh, nurbsCurve, nurbsSurface, bezierCurve),
// so we still enable evaluation cache for other types.
cacheEvaluator -newFilter "evaluationCacheNodes" -newAction "enableEvaluationCache";
// Enabling VP2 cache will disable evaluation cache on the supported types.
cacheEvaluator -newFilter "vp2CacheNodes" -newAction "enableVP2Cache" -newActionParam "useHardware=1";
// Custom evaluators of a higher priority than the caching evaluator
// may need additional caching points around its boundary to evaluate properly.
cacheEvaluator -newRule "customEvaluators";

// Enable evaluation cache using explicit node types.
cacheEvaluator -resetRules;
cacheEvaluator -newFilter "nodeTypes" -newFilterParam "types=-constraint,+transform,+mesh,+nurbsCurve,+bezierCurve,+nurbsSurface,+subdiv,+lattice,+baseLattice,+cMuscleDebug,+cMuscleDirection,+cMuscleDisplace,+cMuscleDisplay,+cMuscleFalloff,+cMuscleKeepOut,+cMuscleObject,+cMuscleSmartCollide,+cMuscleSpline,+cMuscleSurfAttach,-THlocatorShape,+locator,+light,+camera,+imagePlane,+clusterHandle,+deformFunc,+hwShader,+pfxGeometry,+follicle" -newAction "enableEvaluationCache";

// Get the creation parameters.
cacheEvaluator -resetRules;
cacheEvaluator -q -creationParameters;
// Result: [] //

cacheEvaluator -resetRules;
cacheEvaluator -newFilter "evaluationCacheNodes" -newAction "enableEvaluationCache";
cacheEvaluator -q -creationParameters;
// Result: [
    {
        "newAction": "enableEvaluationCache",
        "newFilter": "evaluationCacheNodes"
    }
] //

// Query current cache fill mode.
cacheEvaluator -q -cacheFillMode;
// Result: syncAsync //

// Set new cache fill mode. Options are: 'asyncOnly', 'syncOnly', 'syncAsync'.
cacheEvaluator -cacheFillMode "syncAsync";

// Query current cache fill order.
cacheEvaluator -q -cacheFillOrder;
// Result: bidirectional //

// Set new cache fill order. Options are: 'forward', 'backward', 'bidirectional', 'forwardFromBegin'.
cacheEvaluator -cacheFillOrder "forward";

// Invalidate cache for all the frames in range from 10 to 20, inclusive, in current time unit.
cacheEvaluator -cacheInvalidate "10:20";

// Invalidate cache for all the frames in range from 10 onwards to the maximum time in the animation range, in current time unit.
cacheEvaluator -cacheInvalidate "10:";

// Invalidate cache for all the frames in range from minimum time on the animation range up to (and including) to 10, in current time unit.
cacheEvaluator -cacheInvalidate ":10";

// Invalidate cache from minimum to maximum time on the current animation range.
cacheEvaluator -cacheInvalidate ":";

// Check whether or not evaluation cache is active on a given node.
cacheEvaluator -q -cacheName "evaluation" "myNode";
// Result: 1 //
cacheEvaluator -q -cacheName "evaluation" -valueName "active" "myNode";
// Result: 1 //

// Check whether or not VP2 hardware is active, and using hardware cache.
cacheEvaluator -q -cacheName "VP2" "myNode";
// Result: 1 //
cacheEvaluator -q -cacheName "VP2" -valueName "active" "myNode";
// Result: 1 //
cacheEvaluator -q -cacheName "VP2" -valueName "useHardware" "myNode";
// Result: 1 //

// Check for the caching points in the scene.
cacheEvaluator -q -cachingPoints;
// Result: nurbsCone1 nurbsConeShape1 //

// Flush current cache. "keep" and "destroy" flags can be used to store or destroy the existing cache.
cacheEvaluator -flushCache "destroy";
// Result: destroy //

// Query the cache evaluator's flush synchronization mode.
cacheEvaluator -q -flushCacheSync;
// Result: 0 //

// Set the cache evaluator's flush synchronization mode. Valid values are: 1 for synchronous, 0 for asynchronous.
cacheEvaluator -flushCacheSync 1;

// Wait for cache destruction.
cacheEvaluator -flushCacheWait;

// Check the available types of cache.
cacheEvaluator -q -listCacheNames;
// Result: evaluation VP2 //

// Query the list of cached nodes.
cacheEvaluator -q -listCachedNodes;
// Result: nurbsSphere1,nurbsSphereShape1 //

// Check the available values that can be queried for available caches.
cacheEvaluator -q -cacheName "evaluation" -listValueNames;
// Result: active //

cacheEvaluator -q -cacheName "VP2" -listValueNames;
// Result: active useHardware //

// Query if prevent-frame-skipping is on.
cacheEvaluator -q -preventFrameSkip;
// Result: 1 //

// Set prevent-frame-skipping to on.
cacheEvaluator -preventFrameSkip 1;

// Query if the cache invalidation is paused. Returns how many times invalidation is paused.
cacheEvaluator -q -pauseInvalidation;
// Result: 0 //

// Pause cache invalidation.
cacheEvaluator -pauseInvalidation;

// Resume cache invalidation.
cacheEvaluator -resumeInvalidation;

// Query whether or not the resource limit has been reached.
cacheEvaluator -q -resourceUsage;
// Result: okay //

// Turn safe mode state for evaluator on.
cacheEvaluator -safeMode 1;

// Query the safe mode state for evaluator.
cacheEvaluator -q -safeMode;
// Result: 1 //

// If safe mode was triggered return the safe mode messages
cacheEvaluator -q -safeModeMessages;
// Result:  //

// Check if safe mode was triggered
cacheEvaluator -q -safeModeTriggered;
// Result: 0 //

// Wait for 10 seconds for cache to fill in background
cacheEvaluator -waitForCache 10;
// Result: 1 //

// Use the CacheEvaluatorManager to get/set modes.
python("from maya.plugin.evaluator.CacheEvaluatorManager import CacheEvaluatorManager");
python("manager = CacheEvaluatorManager()");
python("currentMode = manager.cache_mode");

python("from maya.plugin.evaluator.CacheEvaluatorManager import CACHE_STANDARD_MODE_VP2_HW, CACHE_STANDARD_MODE_VP2_SW, CACHE_STANDARD_MODE_EVAL");
// Enable evaluation cache.
python("manager.cache_mode = CACHE_STANDARD_MODE_EVAL");
// Enable VP2 software cache.
python("manager.cache_mode = CACHE_STANDARD_MODE_VP2_SW");
// Enable VP2 hardware cache.
python("manager.cache_mode = CACHE_STANDARD_MODE_VP2_HW");

// Restore the previous mode.
python("manager.cache_mode = currentMode");