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

Session Macros

Session macros are macros that give general information about the session and threads, and start/stop recording sessions. The only macros that is required by FramePro is the FRAMEPRO_FRAME_START. It is also advised to set the thread name for each thread which is created.

FRAMEPRO_FRAME_START()

This must be called at the start of each frame. It tells FramePro when the old frame ends and the new frame starts

FRAMEPRO_SHUTDOWN()

Cleans up all FramePro resources. No thread can call into FramePro after this is called.

FRAMEPRO_SET_SESSION_INFO(name, build_id)

name: string - name of the session
build_id: string - build id of the build being profiled

The session name is typically the game name. The build can be anything. These values are shown in the session info panel in FramePro.

FRAMEPRO_SET_ALLOCATOR(p_allocator)

p_allocator: FramePro::Allocator*

Set the allocator that FramePro will use to allocate memory. This must be a class inherited from the FramePro::Allocator base class. NOTE: Call this before calling any other FramePro macro.

FRAMEPRO_SET_THREAD_NAME(name)

name: string (literal or dynamic)

Tell FramePro the name of the current thread. FramePro will pick a colour based on the thread name which will always stay the same.

FRAMEPRO_THREAD_ORDER(thread_name)

thread_name: string (literal or dynamic)

To keep the order of the threads in the thread view consistent for all users you can specify the thread ordering from your game. The threads will appear in the order that the macros are called. For example:

void InitialiseGame()
{
    FRAMEPRO_THREAD_ORDER("MainThread");
    FRAMEPRO_THREAD_ORDER("RenderTHread");
    FRAMEPRO_THREAD_ORDER("WorkerThread1");
    FRAMEPRO_THREAD_ORDER("WorkerThread2");
    FRAMEPRO_THREAD_ORDER("WorkerThread3");
    FRAMEPRO_THREAD_ORDER("WorkerThread4");
    ...

FRAMEPRO_REGISTER_STRING(str)

str: string (dynamic)
returns: FramePro::StringId

Passing in dynamic strings to scope macros is costly because the string has to be looked up ni a hashmap to determine if it needs to send the string value to FramePro. for dynamic strings that never change (for example the name of an entity) you can cache off the string id (in the entity) using this macro and pass that in to the scope instead of the string.

FRAMEPRO_START_RECORDING(filename, context_switches)

filename: string - the filename to write the recording out to. Extension should be .framepro_recording
context_switches: bool - whether to record context switches

Instead of connecting to your game with FramePro you can instead write all of the network data out to a file. This recording file can then be loaded in FramePro. This can be useful if you want to start/stop a recording at a specific point in code, or if you want to automate the profiling session capture. If a recording was already started that recording will be stopped and this recording will be started. Connections from FramePro are disabled while a recording is in progress.

FRAMEPRO_STOP_RECORDING()

Stop a recording started with FRAMEPRO_START_RECORDING.

FRAMEPRO_REGISTER_CONNECTION_CHANGED_CALLBACK(callback, context)

callback: ConnectionChangedCallback function pointer
context: void*

Add a callback to be called when a connection is made or lost.
context is passed in to the callback as user_data.
The callback is of the form:

typedef void (*ConnectionChangedCallback)(bool connected, void* user_data);

If already connected the callback will be called immediately. Multiple callbacks can be registered.

FRAMEPRO_UNREGISTER_CONNECTION_CHANGED_CALLBACK(callback)

Unregister a callback that was registered with FRAMEPRO_REGISTER_CONNECTION_CHANGED_CALLBACK

FRAMEPRO_SET_THREAD_PRIORITY(priority)

priority: int

Tell FramePro the priority of a thread. This will be displayed in the thread information (hover over the thread panel) It is often useful to be able to see the thread priorities in FramePro when looking at core usage.

FRAMEPRO_SET_THREAD_AFFINITY(affinity)

affinity: int

Tell FramePro the affinity of a thread. This will be displayed in the thread information (hover over the thread panel) It is often useful to be able to see the thread priorities in FramePro when looking at core usage.

FRAMEPRO_UNBLOCK_SOCKETS()

As a security measure you can define FRAMEPRO_SOCKETS_BLOCKED_BY_DEFAULT to true. This will disable all network access by default. You can then call FRAMEPRO_UNBLOCK_SOCKETS() to explicitly allow connections.

FRAMEPRO_CLEANUP_THREAD()

Call from a thread just before it exits to free the memory allocated for this thread. Do not call any other FramePro macros from the thread after calling this. FRAMEPRO_SHUTDOWN will automatically call this on all threads, so usually you don't need to call this. It is only necessary for threads that are created and destroyed. Note: Make sure that you don't call this inside a FramePro scope. during the session.

FRAMEPRO_THREAD_SCOPE(thread_name)

thraed_name: string (literal or dynamic)

Calls FRAMEPRO_SET_THREAD_NAME at the start of the scope, and FRAMEPRO_CLEANUP_THREAD at the end of the scope. Ensure that this is called outside of any other scopes.

FRAMEPRO_LOG(message)

message: string (literal or dynamic)

Calls FRAMEPRO_SET_THREAD_NAME at the start of the scope, and FRAMEPRO_CLEANUP_THREAD at the end of the scope. Ensure that this is called outside of any other scopes.

Related

© Copyright 2016 PureDev Software