carb::profiler::IProfiler

struct IProfiler

Defines the profiler system that is associated with the Framework.

It is not recommended to use this interface directly, rather use macros provided in Profile.h, such as CARB_PROFILE_ZONE().

Event names are specified as string which can have formatting, which provides string behavior hints, but whether to use those hints is up to the profiler backend implementation.

Public Functions

template<typename T> inline void valueStatic(uint64_t mask, T value, StaticStringType valueFmt)

Helper functions to send a arbitrary type to the profiler.

Template Parameters

T – The type of the parameter to send to the profiler.

Parameters

mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueStatic() this must be a StaticStringType from registerStaticString().

template<typename T, typename ...Args> inline void valueDynamic(uint64_t mask, T value, const char *valueFmt, Args&&... args)

Helper functions to send a arbitrary type to the profiler.

Template Parameters

T – The type of the parameter to send to the profiler.

Parameters

mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueStatic() this must be a StaticStringType from registerStaticString().
args – Additional arguments that correspond to printf-style format string valueFmt.

Public Members

void (*startup)(): Starts up the profiler for use.

void (*shutdown)(): Shuts down the profiler and cleans up resources.

uint64_t (*setCaptureMask)(const uint64_t mask)

Set capture mask.

Capture mask provides a way to filter out certain profiling events. Condition (eventMask & captureMask) == eventMask is evaluated, and if true, event is recorded. The default capture mask is kCaptureMaskAll

Note

Calling from multiple threads is not recommended as threads will overwrite each values. Calls to this function should be serialized.

Warning

Changing the capture mask after the profiler has been started causes undefined behavior.

Param mask: Capture mask.
Return: the previous Capture mask.

uint64_t (*getCaptureMask)()

Gets the current capture mask.

Return: The current capture mask

ZoneId (*beginStatic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, StaticStringType nameFmt)

Starts the profiling event.

This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper startFiber/stopFiber calls.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the function where the profile zone is located (usually __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the filename where the profile zone was started (usually __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: Line number in the file where the profile zone was started (usually LINE).
Param nameFmt: The event name format, followed by args. For beginStatic() this must be a StaticStringType from registerStaticString().
Return: An opaque ZoneId that should be passed to endEx().

ZoneId (*beginDynamic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, const char *nameFmt, ...)

Starts the profiling event.

This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper startFiber/stopFiber calls.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the function where the profile zone is located (usually __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the filename where the profile zone was started (usually __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: Line number in the file where the profile zone was started (usually LINE).
Param nameFmt: The event name format, followed by args. For beginStatic() this must be a StaticStringType from registerStaticString().
Return: An opaque ZoneId that should be passed to endEx().

void (*end)(const uint64_t mask)

Stops the profiling event.

This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper startFiber/stopFiber calls.

Warning

This call is deprecated. Please use endEx() instead. This function will not be removed but should also not be called in new code.

Param mask: Event capture mask.

void (*frameStatic)(const uint64_t mask, StaticStringType nameFmt)

Inserts a frame marker for the calling thread in the profiling output, for profilers that support frame markers.

Note

The name provided below must be the same for each set of frames, and called each time from the same thread. For example you might have main thread frames that all are named “frame” and GPU frames that are named “GPU

frame”. Some profilers (i.e. profiler-cpu to Tracy conversion) require that the name contain the word “frame.”

Param mask: Deprecated and ignored for frame events.
Param nameFmt: The frame set name format, followed by args. For frameStatic() this must be a StaticStringType from registerStaticString().

void (*frameDynamic)(const uint64_t mask, const char *nameFmt, ...)

Inserts a frame marker for the calling thread in the profiling output, for profilers that support frame markers.

Note

The name provided below must be the same for each set of frames, and called each time from the same thread. For example you might have main thread frames that all are named “frame” and GPU frames that are named “GPU

frame”. Some profilers (i.e. profiler-cpu to Tracy conversion) require that the name contain the word “frame.”

Param mask: Deprecated and ignored for frame events.
Param nameFmt: The frame set name format, followed by args. For frameStatic() this must be a StaticStringType from registerStaticString().

void (*valueFloatStatic)(const uint64_t mask, float value, StaticStringType valueFmt)

Send floating point value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueFloatStatic() this must be a StaticStringType from registerStaticString().

void (*valueFloatDynamic)(const uint64_t mask, float value, const char *valueFmt, ...)

Send floating point value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueFloatStatic() this must be a StaticStringType from registerStaticString().

void (*valueIntStatic)(const uint64_t mask, int32_t value, StaticStringType valueFmt)

Send signed integer value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueIntStatic() this must be a StaticStringType from registerStaticString().

void (*valueIntDynamic)(const uint64_t mask, int32_t value, const char *valueFmt, ...)

Send signed integer value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueIntStatic() this must be a StaticStringType from registerStaticString().

void (*valueUIntStatic)(const uint64_t mask, uint32_t value, StaticStringType valueFmt)

Send unsigned integer value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueUIntStatic() this must be a StaticStringType from registerStaticString().

void (*valueUIntDynamic)(const uint64_t mask, uint32_t value, const char *valueFmt, ...)

Send unsigned integer value to the profiler.

Param mask: Value capture mask.
Param value: Value.
Param valueFmt: The value name format, followed by args. For valueUIntStatic() this must be a StaticStringType from registerStaticString().

void (*nameThreadStatic)(uint64_t tidOrZero, StaticStringType threadName)

Sets a threads name.

Param tidOrZero: The thread ID to name, or 0 to name the current thread.
Param nameFmt: The thread name format, followed by args. For nameThreadStatic() this must be a StaticStringType from registerStaticString().

void (*nameThreadDynamic)(uint64_t tidOrZero, const char *threadName, ...)

Sets a threads name.

Param tidOrZero: The thread ID to name, or 0 to name the current thread.
Param nameFmt: The thread name format, followed by args. For nameThreadStatic() this must be a StaticStringType from registerStaticString().

bool (*supportsDynamicSourceLocations)()

Checks if the profiler supports dynamic source locations.

Dynamic source locations allow the file and func parameters to functions such as beginStatic() and beginDynamic() to be a transient non-literal string on the heap or stack.

Return: true if dynamic source locations are supported; false if they are not supported.

StaticStringType (*registerStaticString)(const char *string)

Helper function for registering a static string.

Note

The profiler must copy all strings. By registering a static string, you are making a contract with the profiler that the string at the provided address will never change. This allows the string to be passed by pointer as an optimization without needing to copy the string.

Note

This function should be called only once per string. The return value should be captured in a variable and passed to the static function such as beginStatic(), frameStatic(), valueStatic(), etc.

Param string: The static string to register. This must be a string literal or otherwise a string whose address will never change.
Return: A StaticStringType that represents the registered static string. If the string could not be registered, kInvalidStaticString is returned.

void (*allocNamedStatic)(const uint64_t mask, const void *ptr, uint64_t size, StaticStringType name)

Send memory allocation event to the profiler for custom pools.

Param mask: Value capture mask.
Param ptr: Memory address.
Param size: Amount of bytes allocated.
Param name: Static or formatted string which contains the name of the pool.

void (*allocNamedDynamic)(const uint64_t mask, const void *ptr, uint64_t size, const char *nameFmt, ...)

Send memory allocation event to the profiler for custom pools.

Param mask: Value capture mask.
Param ptr: Memory address.
Param size: Amount of bytes allocated.
Param name: Static or formatted string which contains the name of the pool.

void (*freeNamedStatic)(const uint64_t mask, const void *ptr, StaticStringType valueFmt)

Send memory free event to the profiler for custom pools.

Param mask: Value capture mask.
Param ptr: Memory address.
Param name: Static or formatted string which contains the name of the pool.

void (*freeNamedDynamic)(const uint64_t mask, const void *ptr, const char *nameFmt, ...)

Send memory free event to the profiler for custom pools.

Param mask: Value capture mask.
Param ptr: Memory address.
Param name: Static or formatted string which contains the name of the pool.

void (*allocStatic)(const uint64_t mask, const void *ptr, uint64_t size)

Send memory allocation event to the profiler on the default pool.

Param mask: Value capture mask.
Param ptr: Memory address.
Param size: Amount of bytes allocated.

void (*freeStatic)(const uint64_t mask, const void *ptr)

Send memory free event to the profiler on the default pool.

Param mask: Value capture mask.
Param ptr: Memory address.

void (*endEx)(const uint64_t mask, ZoneId zoneId)

Stops the profiling event that was initiated by beginStatic() or beginDynamic().

Param mask: Event capture mask.
Param zoneId: The ZoneId returned from beginStatic() or beginDynamic().

void (*emitInstantStatic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, InstantType type, StaticStringType nameFmt)

Records an instant event on a thread’s timeline at the current time.

Generally not used directly; instead use the CARB_PROFILE_EVENT() macro.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event (typically __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param type: The type of instant event.
Param nameFmt: The name for the event.

void (*emitInstantDynamic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, InstantType type, const char *nameFmt, ...)

Records an instant event on a thread’s timeline at the current time.

Generally not used directly; instead use the CARB_PROFILE_EVENT() macro.

Note

This function is slower than using emitInstanceStatic().

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event (typically __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param type: The type of instant event.
Param nameFmt: The name for the event.
Param …: printf-style varargs for nameFmt.

void (*emitFlowStatic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, FlowType type, uint64_t id, StaticStringType name)

Puts a flow event on the timeline at the current line.

Generally not used directly; instead use the CARB_PROFILE_FLOW_BEGIN() and CARB_PROFILE_FLOW_END() macros.

Flow events draw an arrow from one point (the FlowType::Begin location) to another point (the FlowType::End location). These two points can be in different threads but must have a matching id field. Only the FlowType::Begin event must specify a name. The id field is meant to be unique across profiler runs, but may be reused as long as the name field matches across all FlowType::Begin events and events occur on the global timeline as FlowType::Begin followed by FlowType::End.

A call with FlowType::Begin will automatically insert an instant event on the current thread’s timeline.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event. If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param type: The type of flow marker.
Param id: A unique identifier to tie Begin and End events together.
Param name: The name for the flow event. Only required for FlowType::Begin; if specified for FlowType::End it must match exactly or be nullptr.

void (*emitFlowDynamic)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, FlowType type, uint64_t id, const char *name, ...)

Puts a flow event on the timeline at the current line.

Generally not used directly; instead use the CARB_PROFILE_FLOW_BEGIN() and CARB_PROFILE_FLOW_END() macros.

Flow events draw an arrow from one point (the FlowType::Begin location) to another point (the FlowType::End location). These two points can be in different threads but must have a matching id field. Only the FlowType::Begin event must specify a name. The id field is meant to be unique across profiler runs, but may be reused as long as the name field matches across all FlowType::Begin events and events occur on the global timeline as FlowType::Begin followed by FlowType::End.

A call with FlowType::Begin will automatically insert an instant event on the current thread’s timeline.

Note

This function is slower than using emitFlowStatic().

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event. If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param type: The type of flow marker.
Param id: A unique identifier to tie Begin and End events together.
Param name: The name for the flow event. Only required for FlowType::Begin; if specified for FlowType::End it must match exactly or be nullptr.
Param …: printf-style varargs for nameFmt.

GpuContextId (*createGpuContext)(const char *name, int64_t correlatedCpuTimestampNs, int64_t correlatedGpuTimestamp, float gpuTimestampPeriodNs, const char *graphicApi)

Create a new GPU profiling context that allows injecting timestamps coming from a GPU in a deferred manner.

Param name: name of the context
Param correlatedCpuTimestampNs: correlated GPU clock timestamp (in nanoseconds)
Param correlatedGpuTimestamp: correlated GPU clock timestamp (raw value)
Param gpuTimestampPeriodNs: is the number of nanoseconds required for a GPU timestamp query to be incremented by 1.
Param graphicApi: string of graphic API used [‘vulkan’/’d3d12’]
Return: a valid ID or kInvalidGpuContextId if creation fails

void (*destroyGpuContext)(GpuContextId contextId)

Destroy a previously created GPU Context.

Param contextId: id of the context, returned by createGpuContext

bool (*calibrateGpuContext)(GpuContextId contextId, int64_t correlatedCpuTimestampNs, int64_t previousCorrelatedCpuTimestampNs, int64_t correlatedGpuTimestamp)

Submit context calibration information that allows correlating CPU and GPU clocks.

Param contextId: id of the context, returned by createGpuContext
Param correlatedCpuTimestampNs: the new CPU timestamp at the time of correlation (in nanoseconds)
Param previousCorrelatedCpuTimestamp: the CPU timestamp at the time of previous correlation (in nanoseconds)
Param correlatedGpuTimestamp: the new raw GPU timestamp at the time of correlation

void (*beginGpuQueryStatic)(const uint64_t mask, StaticStringType functionName, StaticStringType fileName, int line, GpuContextId contextId, uint32_t queryId, StaticStringType name)

Record the beginning of a new GPU timestamp query.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event (typically __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param contextId: the id of the context as returned by createGpuContext
Param queryId: unique query id (for identification when passing to setGpuQueryValue)
Param name: The name for the event.

void (*beginGpuQueryDynamic)(const uint64_t mask, StaticStringType functionName, StaticStringType fileName, int line, GpuContextId contextId, uint32_t queryId, const char *nameFmt, ...)

Record the beginning of a new GPU timestamp query.

Param mask: Event capture mask.
Param function: Static string (see registerStaticString()) of the name of the function containing this event (typically __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param file: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).
Param contextId: the id of the context as returned by createGpuContext
Param queryId: unique query id (for identification when passing to setGpuQueryValue)
Param name: The name for the event.

void (*endGpuQuery)(const uint64_t mask, GpuContextId contextId, uint32_t queryId)

Record the end of a new GPU timestamp query.

Param mask: Event capture mask.
Param contextId: the id of the context as returned by createGpuContext
Param queryId: unique query id (for identification when passing to setGpuQueryValue)

void (*setGpuQueryValue)(const uint64_t mask, GpuContextId contextId, uint32_t queryId, int64_t gpuTimestamp)

Set the value we’ve received from the GPU for a query (begin or end) we’ve issued in the past.

Param contextId: the id of the context as returned by createGpuContext
Param queryId: unique query id specified at begin/end time
Param gpuTimestamp: raw GPU timestamp value

LockableId (*createLockable)(const uint64_t mask, const char *name, const bool isSharedLock, StaticStringType functionName, StaticStringType fileName, int line)

Create a lockable context which we can use to tag lock operation.

Param mask: Event capture mask. If the mask does not match the current capture mask, the lockable is not created and kInvalidLockableId is returned.
Param name: context name
Param isSharedLock: if this shared for a shared lock
Param functionName: Static string (see registerStaticString()) of the name of the function containing this event (typically __func__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param fileName: Static string (see registerStaticString()) of the name of the source file containing this event (typically __FILE__). If supportsDynamicSourceLocations(), this may be a const char* cast to StaticStringType.
Param line: The line number in file containing this event (typically __LINE__).

void (*destroyLockable)(LockableId lockableId)

Destroy a lockable context.

Param lockableId: the id of the lockable as returned by createLockable

void (*lockableOperation)(LockableId lockableId, LockableOperationType operation)

Record a lockable operation.

Param lockableId: the id of the lockable as returned by createLockable
Param operation: which lock operation to tag

uint64_t (*setMaskCallback)(MaskCallbackFn func, bool enabled)

Used by carb::profiler::registerProfilerForClient() and carb::profiler::deregisterProfilerForClient() to register a callback for keeping the profiler mask up to date.

Param func: The callback function to register.
Param enabled: true to register the callback, false to unregister the callback.
Return: The current profiler mask.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.