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]	categoryName	The name of the category to add.
[in]	categoryInfo	The 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] categoryName The 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]	categoryNames	The names of all the existing categories.
[out]	categoryInfo	The descriptions of all the existing categories.

int getCategoryIndex ( const char * categoryName )

static

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

Parameters

[in] categoryName Name 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] categoryId Index of the category to query.

Returns: The name of the specified category.

const char * getCategoryInfo ( int categoryId )

static

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

Parameters

[in] categoryId Index 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] categoryName Name 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] categoryId Index 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]	categoryName	Name of the category to set.
[in]	active	If 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]	categoryId	The category to set.
[in]	active	If 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]	categoryId	The index of the category which the event belongs to.
[in]	colorIndex	The color to draw the profiling result in Profiler Window.
[in]	eventName	The name of the event.
[in]	description	Description of the event.

int eventBegin	(	int	categoryId,
		ProfilingColor	colorIndex,
		const char *	eventName,
		const char *	description = `NULL`
	)

static

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

Parameters

[in]	categoryId	The index of the category which the event belongs to.
[in]	colorIndex	The color to draw the profiling result in Profiler Window.
[in]	eventName	The name of the event.
[in]	description	Description of the event.

Returns: The index of the started event.

void eventEnd ( int eventId )

static

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

Parameters

[in] eventId The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] eventIndex The 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] sizeInMegaytes The 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] val Value for enabling

bool saveRecording ( const MString & fileName )

static

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

Parameters

[in] fileName File 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] fileName File 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] categoryName The 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] categoryNames The names of all the existing categories.

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

MProfiler.h
MProfiler.cpp

Public Types

Static Public Member Functions

Detailed Description

Member Function Documentation