carb::profiler::IProfiler

Defined in carb/profiler/IProfiler.h

struct carb::profiler::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
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.

Parameters

mask – Capture mask.

Returns

the previous Capture mask.

uint64_t (*getCaptureMask)()

Gets the current capture mask.

Returns

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.

Parameters
Returns

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.

Parameters
Returns

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.

Parameters

mask – Event capture mask.

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

Specifies frame separation.

Parameters

nameFmt – The frame name format, followed by args. For frameStatic() this must be a StaticStringType from registerStaticString().

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

Specifies frame separation.

Parameters

nameFmt – The frame 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.

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

Send floating point value to the profiler.

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

Send signed integer value to the profiler.

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

Send signed integer value to the profiler.

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

Send unsigned integer value to the profiler.

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

Send unsigned integer value to the profiler.

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

Sets a threads name.

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

Sets a threads name.

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

Returns

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.

Parameters

string – The static string to register. This must be a string literal or otherwise a string whose address will never change.

Returns

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.

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

  • size – Amount of bytes allocated.

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

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

  • size – Amount of bytes allocated.

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

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

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

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

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

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

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

Parameters

  • mask – Value capture mask.

  • ptr – Memory address.

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

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

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

Parameters
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().

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

Parameters
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().

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

Parameters

  • name – name of the context

  • correlatedCpuTimestampNs – correlated GPU clock timestamp (in ns)

  • correlatedGpuTimestamp – correlated GPU clock timestamp (raw value)

  • gpuTimestampPeriodNs – is the number of nanoseconds required for a GPU timestamp query to be incremented by 1.

  • graphicApi – string of graphic API used [‘vulkan’/’d3d12’]

Returns

a valid ID or kInvalidGpuContextId if creation fails

void (*destroyGpuContext)(GpuContextId contextId)

Destroy a previously created GPU Context.

Parameters

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.

Parameters

  • contextId – id of the context, returned by createGpuContext

  • correlatedCpuTimestampNs – the new CPU timestamp at the time of correlation (in ns)

  • previousCorrelatedCpuTimestamp – the CPU timestamp at the time of previous correlation (in ns)

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

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

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

Record the end of a new GPU timestamp query.

Parameters

  • mask – Event capture mask.

  • contextId – the id of the context as returned by createGpuContext

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

Parameters

  • contextId – the id of the context as returned by createGpuContext

  • queryId – unique query id specified at begin/end time

  • gpuTimestamp – raw GPU timestamp value

Public Static Functions

static inline carb::InterfaceDesc getInterfaceDesc()

Returns

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