In query mode, return type is based on queried flag.
Long name (short name) |
Argument types |
Properties |
combineType(ct)
|
boolean
|
|
|
Causes all nodes of the same type (e.g. animCurveTA) to be combined in the
output display.
|
|
hierarchy(h)
|
boolean
|
|
|
Used to specify that a hierarchy of the dependency graph be affected,
thus "-reset -hierarchy -name ball" will reset the timers on the node
named "ball" and all of its descendents in the dependency graph.
|
|
uniqueName(un)
|
boolean
|
|
|
Used to specify that the DAG nodes listed in the output should be
listed by their unique names. The full DAG path to the object
will be printed out instead of just the node name.
|
|
maxDisplay(m)
|
int
|
|
|
Truncates the display so that only the most expenive "n" entries are
printed in the output display.
|
|
name(n)
|
string
|
|
|
Used in conjunction with -reset or -query to specify the name of the node
to reset or print timer values for. When querying a single timer, only a
single line of output is generated (i.e. the global timers and header
information is omitted). Note that one can force output to the script editor
window via the "-outputFile MEL" option to make it easy to grab the values
in a MEL script. Note: the -name and -type flag cannot be used together.
|
|
noHeader(nh)
|
boolean
|
|
|
Used in conjunction with -query to prevent any header or footer information
from being printed. All that will be output is the per-node timing data.
This option makes it easier to parse the output such as when you output the
query to a file on disk using the -outputFile option.
|
|
show(sh)
|
string
|
|
|
Used in conjunction with -query to specify which columns are to be displayed
in the per-node section of the output. -show takes an argument, which can
be
"all" (to display all columns),
"callback" (to display the time spent during any callback processing on the node not due to evaluation),
"compute" (to display the time spent in the node's compute methods),
"dirty" (to display time spent propagating dirtiness on behalf of the node),
"draw" (to display time spent drawing the node),
"compcb" (to display time spent during callback processing on node due to compute),
and
"compncb" (to display time spent during callback processing on node NOT due to compute).
The -show flag can be used multiple
times, but cannot be specified with -hide. By default, if neither -show,
-hide, or -sort are given, the effective display mode is:
"dgtimer -show compute -query".
|
|
hide(hi)
|
string
|
|
|
This flag is the converse of -show. As with -show, it is a query-only
flag which can be specified multiple times. If you do specify -hide, we display
all columns except those listed by the -hide flags.
|
|
overhead(oh)
|
boolean
|
|
|
Turns on and off the measurement of timing overhead. Under ordinary circumstances the
amount of timing overhead is minimal compared with the events being measured, but in
complex scenes, one might find the overhead to be measurable. By default this option
is turned off. To enable it, specify "dgtimer -overhead true" prior to starting timing.
When querying timing, the overhead is reported in SECTION 1.2 of the dgtimer output and
is not factored out of each individual operation.
|
|
sortMetric(sm)
|
string
|
|
|
Used in conjunction with -query to specify which metric is to be sorted on
when the per-node section of the output is generated, for example "draw" time.
Note that the -sortType flag can also be specified to define which timer is
sorted on: for example "dgtimer -sortMetric draw -sortType count -query" will
sort the output by the number of times each node was drawn. Both -sortMetric and
-sortType are optional and you can specify one without the other. The -sortMetric
flag can only be specified at most once. The flag takes the following arguments:
"callback" (to sort on time spent during any callback processing on the node),
"compute" (to sort on the time spent in the node's compute methods),
"dirty" (to sort on the time spent propagating dirtiness on behalf of the node),
"draw" (to sort on time spent drawing the node),
"fetch" (to sort on time spent copying data from the datablock),
The default, if -sortMetric is omitted, is to sort on the first displayed column.
Note that the sortMetric is
independent of which columns are displayed via -show and -hide. Sort on a hidden
column is allowed.
The column selected by -sortMetric and -sortType specifies which total is returned
by the dgtimer command on the MEL command line.
This flag is also used with -updateHeatMap to specify which metric to build the heat map for.
|
|
sortType(st)
|
string
|
|
|
Used in conjunction with -query to specify which timer is to be sorted on
when the per-node section of the output is generated, for example "self" time.
Note that the -sortMetric flag can also be specified to define which metric is
sorted on: for example "dgtimer -sortMetric draw -sortType count -query" will
sort the output by the number of times each node was drawn. Both -sortMetric and
-sortType are optional and you can specify one without the other. The -sortType
flag can be specified at most once. The flag takes the following arguments:
"self" (to sort on self time, which is the time specific to the node and not its children),
"inclusive" (to sort on the time including children of the node),
"count" (to sort on the number of times the node was invoked).
and
"none" (to sort on self time, but do not display the Percent and Cumulative columns
in the per-node display, as well as cause the total number of nodes in Maya to be
returned on the command line).
The default, if -sortType is omitted, is to sort on self time.
The column selected by -sortMetric and -sortType specifies which total is returned
by the dgtimer command on the MEL command line. The global total as displayed in
SECTION 1 of the listing is returned. The special case of "-sortType none"
causes the number of nodes in Maya to instead be returned.
This flag is also used with -updateHeatMap to specify which metric to build the heat map for.
|
|
timerOff(off)
|
boolean
|
|
|
Turns off node timing. By default, the timers on all nodes are turned off,
but if specified with the -name or
-type flags, only the timers on specified nodes are turned off.
If the timers on all nodes become turned off, then global timing is also
turned off as well.
|
|
timerOn(on)
|
boolean
|
|
|
Turns on node timing. By default, the timers on all nodes are turned on,
but if specified with the -name or
-type flags, only the timers on specified nodes are turned on.
The global timers are also turned on by this command.
Note that turning on timing does NOT reset the timers to zero. Use the -reset
flag to reset the timers. The idea for NOT resetting the timers is to allow the
user to arbitrarily turn timing on and off and continue to add to the
existing timer values.
|
|
returnCode(rc)
|
string
|
|
|
This flag has been replaced by the more general -returnType flag.
The -returnCode flag was unfortunately specific to the compute metric only.
It exists only for backwards compatability purposes.
It will be removed altogether in a future release.
Here are some handy equivalences:
To get the total number of nodes:
OLD WAY: dgtimer -rc nodecount -q;
// Result:325//
NEW WAY: dgtimer -returnType total -sortType none -q;
// Result:325//
OLD WAY: dgtimer -rc count -q;
// Result:1270//
To get the sum of the compute count column:
NEW WAY: dgtimer -returnType total -sortMetric compute -sortType count -q;
// Result:1270//
OLD WAY: dgtimer -rc selftime -q;
// Result:0.112898//
To get the sum of the compute self column:
NEW WAY: dgtimer -returnType total -sortMetric compute -sortType self -q;
// Result:0.112898//
|
|
returnType(rt)
|
string
|
|
|
This flag specifies what the double value returned by the dgtimer command represents.
By default, the value returned is the global total as displayed in SECTION 1 for the
column we are sorting on in the per-node output (the sort column can be specified
via the -sortMetric and -sortType flags). However, instead of the
total being returned, the user can instead request the individual entries for
the column. This flag is useful mainly for querying without forcing any output.
The flag accepts the values "total", to just display the column total, or
"all" to display all entries individually.
For example, if you want to get the total of draw self time without any other
output simply specify the following:
dgtimer -returnType total -sortMetric draw -sortType self -threshold 100 -noHeader -query;
// Result: 7718.01 //
To instead get each individual entry, change the above query to:
dgtimer -returnType all -sortMetric draw -sortType self -threshold 100 -noHeader -query;
// Result: 6576.01 21.91 11.17 1108.92 //
To get the inclusive dirty time for a specific node, use -name as well as -returnType all:
dgtimer -name "virginia" -returnType all -sortMetric dirty -sortType inclusive -threshold 100 -noHeader -query;
Note: to get the total number of nodes, use "-sortType none -returnType total". To get
the on/off status for each node, use "-sortType none -returnType all".
|
|
outputFile(o)
|
string
|
|
|
Used in conjunction with the -query flag to cause output to be directed to
an output file. By default, output is to stdout, but can be redirected e.g.
-outputFile "/home/virginia/timing/dgtrace.txt". This makes it handy to load
the data into an external application such as a spreadsheet program. To force
output to the script editor, use "-outputFile MEL" which makes it easy to
grab the values from within a MEL script.
In query mode, this flag needs a value.
|
|
reset(r)
|
boolean
|
|
|
Resets the node timers to zero. By default, the timers on all nodes as
well as the global timers are reset, but if specified with the -name or
-type flags, only the timers on specified nodes are reset.
|
|
threshold(th)
|
float
|
|
|
Truncates the display once the value falls below the threshold value. The
threshold applies to whatever timer is being used for sorting. For example, if
our sort key is self compute time (i.e. -sortMetric is "compute" and -sortType
is "self") and the threshold parameter is 20.0, then only nodes with a compute
self-time of 20.0 or higher will be displayed. (Note that -threshold uses
absolute time. There are the similar -rangeUpper and -rangeLower parameters
which specify a range using percentage).
|
|
trace(tr)
|
boolean
|
|
|
Turns on or off detailed execution tracing to the terminal window (stderr
on Linux and Macintosh), and the status window on Windows. By default, tracing
is off. If enabled, each timeable operation is logged when it starts and
again when it ends. The following example shows how the output is formatted:
dgtimer:begin: compute 3 particleShape1Deformed particleShape1Deformed.lastPosition
The above is an example of the output when -trace is true that marks the start
of an operation. For specific details on each field: the "dgtimer:begin:" string
is an identifying marker to flag that this is a begin operation record. The
second argument, "compute" in our example, is the operation metric. You can view
the output of each given metric via "dgtimer -q" by specifying the -show flag.
The integer which follows (3 in this case) is the depth in the operation stack,
and the third argument is the name of the node (particleShape1Deformed). The
fourth argument is specific to the metric. For "compute", it gives the name of
the plug being computed. For "callback", its the internal Maya name of the callback.
For "dirty", its the name of the plug that dirtiness is being propagated from.
dgtimer:end: compute 3 particleShape1Deformed 0.000305685 0.000305685
The above is the end operation record. The "compute", "3" and "particleShapeDeformed"
arguments were described in the "dgtimer:begin" overview earlier. The two floating-point
arguments are self time and inclusive time for the operation measured in seconds.
The inclusive measure lists the total time since the matching "dgtimer:begin:" entry
for this operation, while the self measure lists the inclusive time minus any time
consumed by child operations which may have occurred during execution of the current operation.
As noted elsewhere in this document, these two times are "wall clock times", measuring
elapsed time including any time in which Maya was idle or performing system calls.
Since dgtimer can measure some non-node qualities in Maya, such as global message
callbacks, a "-" is displayed where the node name would ordinarily be displayed.
The "-" means "not applicable".
|
|
type(t)
|
string
|
|
|
Used in conjunction with -reset or -query to specify the type of the node(s)
(e.g. animCurveTA) to reset or print timer values for.
When querying, use of the -combineType flag will cause all nodes of the
same type to be combined into one entry, and only one line of output is
generated (i.e. the global timers and header information is omitted).
Note that one can force output to the script editor
window via the "-outputFile MEL" option to make it easy to grab the values
in a MEL script. Note: the -name and -type flag cannot be used together.
|
|
updateHeatMap(uhm)
|
int
|
|
|
Forces Maya's heat map to rebuild based on the specified parameters.
The heat map is an internal dgtimer structure used in mapping
intensity values to colourmap entries during display by the HyperGraph
Editor. There is one heat map shared by all editors that are using heat
map display mode. Updating the heat map causes the timer values on all
nodes to be analysed to compose the distribution of entries in the heat map.
The parameter is the integer number of divisions in the map and should equal
the number of available colours for displaying the heat map. This flag can
be specified with the -rangeLower and -rangeUpper flags
to limit the range of displayable to lie between the percentile range.
The dgtimer command returns the maximum timing value for all nodes in Maya
for the specified metric and type.
Note: when the display range includes 0, the special zeroth (exactly zero)
slot in the heat map is avilable.
|
|
rangeLower(rgl)
|
float
|
|
|
This flag can be specified to limit the range of nodes which are displayed
in a query, or the limits of the heat map with -updateHeatMap. The value
is the lower percentage cutoff for the nodes which are processed. There is also
a -rangeLower flag which sets the lower range limit. The default value is 0,
meaning that all nodes with timing value below the upper range limit are considered.
|
|
rangeUpper(rgu)
|
float
|
|
|
This flag can be specified to limit the range of nodes which are displayed
in a query, or the limits of the heat map with -updateHeatMap. The value
is the upper percentage cutoff for the nodes which are processed. There is also
a -rangeLower flag which sets the lower range limit. The default value is 100,
meaning that all nodes with timing value above the lower range limit are considered.
|
|