FramePro
User Guide

Introduction
Setup
API Reference
Overview
Definitions
Session Macros
Scope Macros
Frame Stat Macros
HiRes Timer Macros
GUI
Main Toolbar
Threads View
CoresView
Scopes View
Frame Stats View
PureDev Logo FramePro logo
FramePro
Real-time C++ Profiler
line

FramePro API

Scope Macros

FRAMEPRO_SCOPE()

Starts a timer immediately and stops it when the current scope ends. The scope name will be the function name. This is typically the most used scope. Put it at the start of a function.
This macro has minimal overhead.

FRAMEPRO_NAMED_SCOPE(name)

name: string - NOTE: MUST be string literal

Starts a timer immediately and stops it when the current scope ends. This macro is used for timing any scope and allows you to explicitly set the scope name.
This macro has minimal overhead.

FRAMEPRO_NAMED_SCOPE_W(name)

name: wide string - NOTE: MUST be string literal

Starts a timer immediately and stops it when the current scope ends. This macro is used for timing any scope and allows you to explicitly set the scope name.
This macro has minimal overhead.

FRAMEPRO_ID_SCOPE(name_id)

name_id: FramePro::StringId

Starts a timer immediately and stops it when the current scope ends. This macro is used for timing any scope and allows you to explicitly set the scope name. The name_id is a FramePro string is returned from FRAMEPRO_REGISTER_STRING
This macro has minimal overhead.

FRAMEPRO_DYNAMIC_SCOPE(dynamic_string)

dynamic_string: dynamic string

Starts a timer immediately and stops it when the current scope ends. This macro is used for timing any scope and allows you to explicitly set the scope name. This macro has medium overhead beacuse it has to create a hash of the string and look it up on a hash map. Only use where absolutely necessary. In general, try and use the string literal or string id versions.

FRAMEPRO_CONDITIONAL_SCOPE()

Starts a timer immediately and stops it when the current scope ends. The scope name will be the function name. Put it at the start of a function. The data will only be sent to FramePro if the scope time is greater than the conditional scope threshold. The threshold is set in FramePro using the threshold slider and defaults to 50ms. Conditional scopes scan be useful for scopes that would be too numerous if always sent, but occasionally spike.

FRAMEPRO_CONDITIONAL_NAMED_SCOPE(name)

name: string - NOTE: MUST be string literal

Starts a timer immediately and stops it when the current scope ends. The name of the scope is set explicitly. The data will only be sent to FramePro if the scope time is greater than the conditional scope threshold. The threshold is set in FramePro using the threshold slider and defaults to 50ms. Conditional scopes scan be useful for scopes that would be too numerous if always sent, but occasionally spike.

FRAMEPRO_CONDITIONAL_NAMED_SCOPE_W(name)

name: string - NOTE: MUST be string literal

Starts a timer immediately and stops it when the current scope ends. The name of the scope is set explicitly. The data will only be sent to FramePro if the scope time is greater than the conditional scope threshold. The threshold is set in FramePro using the threshold slider and defaults to 50ms. Conditional scopes scan be useful for scopes that would be too numerous if always sent, but occasionally spike.

FRAMEPRO_START_NAMED_SCOPE(name)

name: string literal without quotes - see comment
name: string - NOTE: MUST be string literal

Start a named scope. Creates a local variable which stores the start time of the scope. This must be matched by a call to FRAMEPRO_STOP_NAMED_SCOPE with the same name passed in. In general, it is preferable to use the scope marcos that automatically close the scope on exit, but there are occasions when you need to start/sto explicitly. Be careful not to overlap scopes, and be careful to always end the scope that you started. Otherwise you will see strange behavour in the thread stack view in FramePro.

The name passed in is a string literal without the quotes, for example FRAMEPRO_START_NAMED_SCOPE(my_scope). This will create a local variable using called framepro_start_my_scope and send the scope using the "my_scope" string literal.

FRAMEPRO_STOP_NAMED_SCOPE(name)

name: string literal without quotes - this must be the same name that was passed in to FRAMEPRO_START_NAMED_SCOPE

Stop a scope started with FRAMEPRO_START_NAMED_SCOPE

FRAMEPRO_CONDITIONAL_START_SCOPE()

Starts a conditional scope. Note that you can only start one conditional scope per scope. Creates a local variable which stores the scope start time.

FRAMEPRO_CONDITIONAL_STOP_NAMED_SCOPE(name)

name: string - NOTE: MUST be string literal

Stop a scope started with FRAMEPRO_CONDITIONAL_START_SCOPE. The name passed in is the name of the scope. The data will only be sent to FramePro if the scope time is greater than the conditional scope threshold. The threshold is set in FramePro using the threshold slider and defaults to 50ms. Conditional scopes scan be useful for scopes that would be too numerous if always sent, but occasionally spike.

FRAMEPRO_CONDITIONAL_STOP_DYNAMIC_SCOPE(dynamic_string)

name: string - dynamic string

Stop a scope started with FRAMEPRO_CONDITIONAL_START_SCOPE. The name passed in is the name of the scope. The data will only be sent to FramePro if the scope time is greater than the conditional scope threshold. The threshold is set in FramePro using the threshold slider and defaults to 50ms. Conditional scopes scan be useful for scopes that would be too numerous if always sent, but occasionally spike. This scope is particularly useful for dynamic strings that are slow to evaluate. The string will only be evaluated if the scope time exceeds the threshold. For example: FRAMEPRO_CONDITIONAL_STOP_DYNAMIC_SCOPE(GetEntityName()) Where GetEntityName() is too expensive to call all of the time, but if the scopes takes > 50ms it is worth calling it so that the name shows up in FramePro.


FRAMEPRO_CONDITIONAL_PARENT_SCOPE(name, callback, pre_duration, post_duration)

name: string literal - unique name of the parent
callback: FramePro::ConditionalParentScopeCallback - called at the end of the parent scope. Return true form the callback to send the child scopes.
pre_duration: int64 - how long to keep the child scopes if the callback returns false (in micro-sec). When the callback returns true all of these scopes will be sent.
post_duration: int64 - how long to keep sending the child scopes after the callback has returned false (in micro-sec)

The callback is called at the end of the scope. If the callback returns false the child scopes are not sent, instead they are added to a list. The child scopes are kept on the list for pre_duration us. If the callback reutrns true all of the child scopes for this frame and previous frames are sent, and the child scopes are continued to be sent for post_duration after the callback returns false. Note that nesting conditional parent scopes is not supported.

Idle Scope Macros

All scope macros have an idle scope equivalent. An idle scope shows up as semi-transparent in FramePro. Separate macros were created to avoid having to add the overhead of an extra conditional to each scope. Idle scopes are typically used in Sleep or Event wait calls.

FRAMEPRO_IDLE_SCOPE()

Idle version of FRAMEPRO_SCOPE

FRAMEPRO_IDLE_NAMED_SCOPE(name)

Idle version of FRAMEPRO_NAMED_SCOPE

FRAMEPRO_IDLE_NAMED_SCOPE_W(name)

Idle version of FRAMEPRO_NAMED_SCOPE_W

FRAMEPRO_IDLE_ID_SCOPE(name_id)

Idle version of FRAMEPRO_ID_SCOPE

FRAMEPRO_IDLE_DYNAMIC_SCOPE(dynamic_string)

Idle version of FRAMEPRO_DYNAMIC_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_SCOPE()

Idle version of FRAMEPRO_CONDITIONAL_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_NAMED_SCOPE(name)

Idle version of FRAMEPRO_CONDITIONAL_NAMED_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_NAMED_SCOPE_W(name)

Idle version of FRAMEPRO_CONDITIONAL_NAMED_SCOPE_W

FRAMEPRO_IDLE_START_NAMED_SCOPE(name)

Idle version of FRAMEPRO_START_NAMED_SCOPE

FRAMEPRO_IDLE_STOP_NAMED_SCOPE(name)

Idle version of FRAMEPRO_STOP_NAMED_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_START_SCOPE()

Idle version of FRAMEPRO_CONDITIONAL_START_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_STOP_NAMED_SCOPE(name)

Idle version of FRAMEPRO_CONDITIONAL_STOP_NAMED_SCOPE

FRAMEPRO_IDLE_CONDITIONAL_STOP_DYNAMIC_SCOPE(dynamic_string)

Idle version of FRAMEPRO_CONDITIONAL_STOP_DYNAMIC_SCOPE

Related

© Copyright 2016 PureDev Software