#include <MProfiler.h>

Class 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.

Public Types
enum	ProfilingColor
	Colors for different profiling categories in Profiler Window.

Static Public Member Functions
static int	addCategory (const char *categoryName)
	Add a new profiling category. More...

static int	removeCategory (const char *categoryName)
	Remove an existing profiling category. More...

static void	getAllCategories (MStringArray &categoryNames)
	Return an array of the existing category names. More...

static int	getCategoryIndex (const char *categoryName)
	Returns the category index. More...

static const char *	getCategoryName (int categoryId)
	Returns the category name. 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	getBufferSize ()
	Returns the profiling buffer size. More...

static MStatus	setBufferSize (int sizeInMegaytes)
	Set the new profiling buffer size. More...

static const char *	className ()
	Returns the name of this class. More...

Member Function Documentation

int addCategory ( const char * categoryName )

static

Add a new profiling category.

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.

Examples:: constraintEvaluator/constraintEvaluator.cpp, and simpleEvaluator/simpleEvaluator.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 )

static

Return an array of the existing category names.

Parameters

[out] categoryNames The names 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.

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 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

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

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

MProfiler.h
MProfiler.cpp

MProfiler Class Reference

Class Description

Public Types

Static Public Member Functions

Member Function Documentation