C++ API Reference

Class for working with Maya's profiler. More...

#include <MProfiler.h>

Public Types

enum  ProfilingColor
 Colors for different profiling categories in Profiler Window.
 

Static Public Member Functions

static int addCategory (const char *categoryName, const char *categoryInfo)
 ====================================================================== Add a new profiling category with a description. More...
 
static int removeCategory (const char *categoryName)
 ====================================================================== Remove an existing profiling category. More...
 
static void getAllCategories (MStringArray &categoryNames, MStringArray &categoryInfo)
 ====================================================================== Return an array of the existing category names and descriptions. More...
 
static int getCategoryIndex (const char *categoryName)
 ====================================================================== Returns the category index. More...
 
static const char * getCategoryName (int categoryId)
 ====================================================================== Returns the category name. More...
 
static const char * getCategoryInfo (int categoryId)
 ====================================================================== Returns the category description. More...
 
static bool categoryRecording (const char *categoryName)
 ====================================================================== Determine if a given category is allowed to be recorded. More...
 
static bool categoryRecording (int categoryId)
 ====================================================================== Determine if a given category is allowed to be recorded. More...
 
static void setCategoryRecording (const char *categoryName, bool active)
 ====================================================================== Enable or disable the recording of the given category. More...
 
static void setCategoryRecording (int categoryId, bool active)
 ====================================================================== Enable or disable the recording of the given category. More...
 
static void signalEvent (int categoryId, ProfilingColor colorIndex, const char *eventName, const char *description=NULL)
 ====================================================================== Sending out a profiling signal. More...
 
static int eventBegin (int categoryId, ProfilingColor colorIndex, const char *eventName, const char *description=NULL)
 ====================================================================== Start a profiling event. More...
 
static void eventEnd (int eventId)
 ====================================================================== Stop a profiling event. More...
 
static int getEventCount ()
 ====================================================================== Returns the events count. More...
 
static MUint64 getEventTime (int eventIndex)
 ====================================================================== Returns the time the event happens in microseconds. More...
 
static int getEventDuration (int eventIndex)
 ====================================================================== Returns the duration of the event in microseconds. More...
 
static const char * getEventName (int eventIndex)
 ====================================================================== Returns the name of the specified event. More...
 
static const char * getDescription (int eventIndex)
 ====================================================================== Returns the event description. More...
 
static int getEventCategory (int eventIndex)
 ====================================================================== Returns the category the event belongs to. More...
 
static int getThreadId (int eventIndex)
 ====================================================================== Returns the thread id the event ran on. More...
 
static int getCPUId (int eventIndex)
 ====================================================================== Returns the CPU id the event ran on. More...
 
static bool isSignalEvent (int eventIndex)
 ====================================================================== Determine if a given event is a Signal Event. More...
 
static MProfiler::ProfilingColor getColor (int eventIndex)
 ====================================================================== Returns the color used to draw this event in the Profiler Window. More...
 
static int getThreadDuration (int eventIndex)
 ====================================================================== Returns the duration of the thread for a given event in microseconds. More...
 
static int getBufferSize ()
 ====================================================================== Returns the profiling buffer size. More...
 
static MStatus setBufferSize (int sizeInMegaytes)
 ====================================================================== Set the new profiling buffer size. More...
 
static bool recordingActive ()
 ====================================================================== Determine if recording is active. More...
 
static bool eventDataAvailable ()
 ====================================================================== Determine if any recorded event data is available. More...
 
static bool resetRecording ()
 ====================================================================== Clear out any recorded data. More...
 
static void setRecordingActive (bool val)
 ====================================================================== Enable or disable recording More...
 
static bool saveRecording (const MString &fileName)
 ====================================================================== Save recording to a specified file location More...
 
static bool loadRecording (const MString &fileName)
 ====================================================================== Load a recording from a specified file location More...
 
static bool isDataFromFile ()
 ====================================================================== Return if the current event data was loaded from file. More...
 
static int getNumberOfCPUs ()
 ====================================================================== Return the number of CPUS used for profiling. More...
 
static const char * className ()
 ====================================================================== Returns the name of this class. More...
 
static int addCategory (const char *categoryName)
 This method is obsolete. More...
 
static void getAllCategories (MStringArray &categoryNames)
 This method is obsolete. More...
 

Detailed Description

Class for working with Maya's profiler.

MProfiler is a static class which provides access to Maya's profiler. Maya's profiler is used to profile execution time of instrumented code. User can review the profiling result in the Profiler Window. Or use the MEL command "profiler" to save the profiling result to a file.

The profiling results are represented by two types of events: Normal Event and Signal Event. Normal Event has a duration representing the execution time of the instrumented code. A Signal Event only remembers the start moment and has no knowledge about duration. It can be used in cases when the user does not care about the duration but only cares if this event does happen.

This class provides access to profiler settings and the profiling result. To instrument a specific code snippet you must create an instance of MProfilerScope. See that class for more details.

This class does not provide the ability to start/stop the recording. Recording can be started/stopped using either the Profiler Window or the "profiler -sampling true/false" command. When recording is active only those categories which have been set to be recorded (i.e. categoryRecording(categoryId) returns true) will have their profiling data included in the recording.

There are two ways to instrument code, one is to use MProfiler::eventBegin and MProfier::eventEnd, which give user more flexible control over when to start and stop the profiling for certain part of code, but it is also the user's responsibility to call eventEnd for eventBegin, if user fails to do so, the event will be taken as a signal event. The other way is to use MProfilingScope, which will stop the event automatically when the MProfilingScope object is out of its life scope.

Member Function Documentation

int addCategory ( const char *  categoryName,
const char *  categoryInfo 
)
static

====================================================================== Add a new profiling category with a description.

Categories can only be added when sampling is off and the buffer is empty.

Parameters
[in]categoryNameThe name of the category to add.
[in]categoryInfoThe description of the category to add.
Returns
Index of the newly added category or -1 if fail to add the category.
Examples:
constraintEvaluator/constraintEvaluator.cpp, simpleEvaluator/simpleEvaluator.cpp, and testMTopologyEvaluator/testMTopologyEvaluator.cpp.
int removeCategory ( const char *  categoryName)
static

====================================================================== Remove an existing profiling category.

User can only remove category when the sampling is off and the buffer is empty.

Parameters
[in]categoryNameThe name of the category to remove.
Returns
Index of the removed category or -1 if fail to remove the category..
void getAllCategories ( MStringArray categoryNames,
MStringArray categoryInfo 
)
static

====================================================================== Return an array of the existing category names and descriptions.

The two arrays have matching indices.

Parameters
[out]categoryNamesThe names of all the existing categories.
[out]categoryInfoThe descriptions of all the existing categories.
int getCategoryIndex ( const char *  categoryName)
static

====================================================================== Returns the category index.

Parameters
[in]categoryNameName of the category to query.
Returns
The index of the specified category. -1 if no category with this name.
const char * getCategoryName ( int  categoryId)
static

====================================================================== Returns the category name.

Parameters
[in]categoryIdIndex of the category to query.
Returns
The name of the specified category.
const char * getCategoryInfo ( int  categoryId)
static

====================================================================== Returns the category description.

Parameters
[in]categoryIdIndex of the category to query.
Returns
The description of the specified category.
bool categoryRecording ( const char *  categoryName)
static

====================================================================== Determine if a given category is allowed to be recorded.

Parameters
[in]categoryNameName of the category to query.
Returns
True if the specified category is currently being recorded, otherwise false.
bool categoryRecording ( int  categoryId)
static

====================================================================== Determine if a given category is allowed to be recorded.

Parameters
[in]categoryIdIndex of the category to query.
Returns
True if the specified category is currently being recorded, otherwise false.
void setCategoryRecording ( const char *  categoryName,
bool  active 
)
static

====================================================================== Enable or disable the recording of the given category.

Parameters
[in]categoryNameName of the category to set.
[in]activeIf True, the category will be recorded when profiling starts. If False, the category will not be recorded when profiling starts.
void setCategoryRecording ( int  categoryId,
bool  active 
)
static

====================================================================== Enable or disable the recording of the given category.

Parameters
[in]categoryIdThe category to set.
[in]activeIf True, the category will be recorded when profiling starts. If False, the category will not be recorded when profiling starts.
void signalEvent ( int  categoryId,
ProfilingColor  colorIndex,
const char *  eventName,
const char *  description = NULL 
)
static

====================================================================== Sending out a profiling signal.

Parameters
[in]categoryIdThe index of the category which the event belongs to.
[in]colorIndexThe color to draw the profiling result in Profiler Window.
[in]eventNameThe name of the event.
[in]descriptionDescription of the event.
int eventBegin ( int  categoryId,
ProfilingColor  colorIndex,
const char *  eventName,
const char *  description = NULL 
)
static

====================================================================== Start a profiling event.

Parameters
[in]categoryIdThe index of the category which the event belongs to.
[in]colorIndexThe color to draw the profiling result in Profiler Window.
[in]eventNameThe name of the event.
[in]descriptionDescription of the event.
Returns
The index of the started event.
void eventEnd ( int  eventId)
static

====================================================================== Stop a profiling event.

Parameters
[in]eventIdThe index of the event to stop.
int getEventCount ( )
static

====================================================================== Returns the events count.

Returns
The number of events in the profiling buffer.
MUint64 getEventTime ( int  eventIndex)
static

====================================================================== Returns the time the event happens in microseconds.

If you need to convert this time to other time unit, please create a MTime(microseconds/1000, kMilliSeconds) then do all time conversions by MTime.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The time the event happens in microseconds.
int getEventDuration ( int  eventIndex)
static

====================================================================== Returns the duration of the event in microseconds.

Note that a signal event has a 0 duration. If you need to convert this time to other time unit, please create a MTime(microseconds/1000, kMilliSeconds) then do all time conversions by MTime.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The duration of the event in microseconds.
const char * getEventName ( int  eventIndex)
static

====================================================================== Returns the name of the specified event.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The name of the specified event.
const char * getDescription ( int  eventIndex)
static

====================================================================== Returns the event description.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The event description.
int getEventCategory ( int  eventIndex)
static

====================================================================== Returns the category the event belongs to.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The category the event belongs to.
int getThreadId ( int  eventIndex)
static

====================================================================== Returns the thread id the event ran on.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The thread id the event ran on.
int getCPUId ( int  eventIndex)
static

====================================================================== Returns the CPU id the event ran on.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The CPU id the event ran on.
bool isSignalEvent ( int  eventIndex)
static

====================================================================== Determine if a given event is a Signal Event.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
True if the event is a Single Event, false otherwise.
MProfiler::ProfilingColor getColor ( int  eventIndex)
static

====================================================================== Returns the color used to draw this event in the Profiler Window.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The color used to draw this event in the Profiler Window.
int getThreadDuration ( int  eventIndex)
static

====================================================================== Returns the duration of the thread for a given event in microseconds.

Parameters
[in]eventIndexThe index of the event in the profiling buffer.
Returns
The duration of the thread in microseconds.
int getBufferSize ( )
static

====================================================================== Returns the profiling buffer size.

Returns
The profiling buffer size in megabytes.
MStatus setBufferSize ( int  sizeInMegaytes)
static

====================================================================== Set the new profiling buffer size.

The new buffer size will take effect for next recording. Before next recording started, the events already in the buffer won't be affected.

Parameters
[in]sizeInMegaytesThe new profiling buffer size in megabytes.
Returns
  • MS::kSuccess operation successful
  • MS::kFailure operation failed
bool recordingActive ( )
static

====================================================================== Determine if recording is active.

Returns
True if recording is active
bool eventDataAvailable ( )
static

====================================================================== Determine if any recorded event data is available.

Returns
True if data is available
bool resetRecording ( )
static

====================================================================== Clear out any recorded data.

If a recording is active (samplingActive() returns True) then the data will not be cleared.

Returns
True if data was cleared
void setRecordingActive ( bool  val)
static

====================================================================== Enable or disable recording

Parameters
[in]valValue for enabling
bool saveRecording ( const MString fileName)
static

====================================================================== Save recording to a specified file location

Parameters
[in]fileNameFile location to save to.
Returns
True if recording was saved.
bool loadRecording ( const MString fileName)
static

====================================================================== Load a recording from a specified file location

Parameters
[in]fileNameFile location to load from.
Returns
True if recording was loaded.
bool isDataFromFile ( )
static

====================================================================== Return if the current event data was loaded from file.

Returns
True if event data was loaded from file.
int getNumberOfCPUs ( )
static

====================================================================== Return the number of CPUS used for profiling.

If the current event data is loaded from file (Events().fromFile() returns True) then the number from the loaded data will be returned.

Returns
Number of CPUs.
const char * className ( )
static

====================================================================== Returns the name of this class.

Returns
The name of this class.
int addCategory ( const char *  categoryName)
static

This method is obsolete.

====================================================================== Add a new profiling category.

[as of Maya 2019]

Deprecated:
Call addCategory(const char*, const char*) instead.

Categories can only be added when sampling is off and the buffer is empty.

Parameters
[in]categoryNameThe name of the category to add.
Returns
Index of the newly added category or -1 if fail to add the category.
void getAllCategories ( MStringArray categoryNames)
static

This method is obsolete.

====================================================================== Return an array of the existing category names.

[as of Maya 2019]

Deprecated:
Call getAllCategories(MStringArray&, MStringArray&) instead.
Parameters
[out]categoryNamesThe names of all the existing categories.

The documentation for this class was generated from the following files: