In order to start adding scopes to your codebase and connect with FramePro you need to compile with the FramePro code. There are two ways of achieving this:
- Add FramePro.cpp and FramePro.h to your codebase
- Dynamically link with FramePro.dll
Option 1 is the recommended way. It is more portable, easier to integrate and maintain and allows more for greater compiler optimisation.
If you are profiling an application with multiple dlls you can use option 1 on condition that you have a shared dll that is used by all other dlls that you want to profile. If this is the case add FramePro.cpp to the shared dll and define the FRAMEPRO_DLL_EXPORT macro to export and import as required. If you do not have a shared dll then you can use option 2.
Option 1: Compiling with FramePro.cpp/h
FramePro.cpp and FramePro.h can be found in the FramePro install folder:
Copy these files to your codebase. Typicallly you will want to add them to your core library so that FramePro.h can be included from anywhere.
Option 2: Dynamically linking to FramePro.dll
The library files can be found here:
- Include FramePro.h from the file that you want to profile
- Make sure that the linker can find the FramePro.lib file (the header automatically links to FramePro.lib with a pragma)
- Copy FramePro.dll to the same folder as your exe.
Using the recording marcos
Once you have linked with the FramePro code, with either option 1 or option 2, you can start using the FramePro profiling macros.
The only required macro that you need to use is FRAMEPRO_FRAME_START. This tells FramePro when the frame starts and finishes. This should be put into your main game loop. For example:
FRAMEPRO_FRAME_START(); // a frame starts here
Next, you can start profiling your code with the timing scope macros. The most common macro that you will use is the FRAMEPRO_SCOPE macro. Put this at the start of a function to record the start and end time of the function. The scope name will be the name of the function. For example:
FRAMEPRO_SCOPE(); // adds a scope called "UpdateGame"
You can find a list of all macros here: FramePro API
Once you have linked tot the FramePro code, added the frame start macro and added some scopes you can connect to your game with FramePro.
FramePro can be completely defined out for retail builds by setting the FRAMEPRO_ENABLED define to 0. For this reason it is recommended that you always use the macros rather than calling in to the FramePro code directly.
Recording to a File
Instead of connecting over TCP and collecting the data in real-time, it can be useful to instead record to a file. This can be useful when profiling deviced that don't have network capabilities, and it can also be useful when automating collection of specific part of the game.
To start profiling and capture data to a file use the FRAMEPRO_START_RECORDING and FRAMEPRO_STOP_RECORDING macros. The filename passed in to FRAMEPRO_START_RECORDING must have the extension .framepro_recording. This recording file can then be loaded into FRamePro.
Please note that it is recommended to read the API documentation if you are using any of the other timing scope macros. For most timing macros FramePro requires you to pass in string literals. If you start passing in dynamic string where a string literal is expected bad things will happen.
If you have any problems setting up FramePro:
- email firstname.lastname@example.org