Profiler API documentation

Version: alpha

FUNCTIONS
profiler.enable_ui() enables or disables the on-screen profiler ui
profiler.get_cpu_usage() get current CPU usage for app reported by OS
profiler.get_memory_usage() get current memory usage for app reported by OS
profiler.log_text() send a text to the profiler
profiler.recorded_frame_count() get the number of recorded frames in the on-screen profiler ui
profiler.scope_begin() start a profile scope
profiler.scope_end() end the current profile scope
profiler.set_ui_mode() sets the the on-screen profiler ui mode
profiler.set_ui_view_mode() sets the the on-screen profiler ui view mode
profiler.set_ui_vsync_wait_visible() Shows or hides the vsync wait time in the on-screen profiler ui
profiler.view_recorded_frame() displays a previously recorded frame in the on-screen profiler ui
CONSTANTS
profiler.MODE_PAUSE pause on current frame
profiler.MODE_RECORD start recording
profiler.MODE_RUN continously show latest frame
profiler.MODE_SHOW_PEAK_FRAME pause at peak frame
profiler.VIEW_MODE_FULL show full profiler ui
profiler.VIEW_MODE_MINIMIZED show mimimal profiler ui

Functions

profiler.enable_ui()

profiler.enable_ui(enabled)

Creates and shows or hides and destroys the on-sceen profiler ui The profiler is a real-time tool that shows the numbers of milliseconds spent in each scope per frame as well as counters. The profiler is very useful for tracking down performance and resource problems.

PARAMETERS

enabled boolean true to enable, false to disable

EXAMPLES

-- Show the profiler UI
profiler.enable_ui(true)

profiler.get_cpu_usage()

profiler.get_cpu_usage()

Get the percent of CPU usage by the application, as reported by the OS. This function is not available on HTML5. For some platforms ( Android, Linux and Windows), this information is only available by default in the debug version of the engine. It can be enabled in release version as well by checking track_cpu under profiler in the game.project file. (This means that the engine will sample the CPU usage in intervalls during execution even in release mode.)

PARAMETERS

None

RETURNS

percent number of CPU used by the application

profiler.get_memory_usage()

profiler.get_memory_usage()

Get the amount of memory used (resident/working set) by the application in bytes, as reported by the OS. This function is not available on HTML5. The values are gathered from internal OS functions which correspond to the following;

OS Value
iOS
MacOS

Android
Linux		 Resident memory
Windows Working set
HTML5 Not available

PARAMETERS

None

RETURNS

bytes number used by the application

EXAMPLES

Get memory usage before and after loading a collection: 
print(profiler.get_memory_usage())
msg.post("#collectionproxy", "load")
...
print(profiler.get_memory_usage()) -- will report a higher number than the initial call

profiler.log_text()

profiler.log_text(text)

Send a text to the profiler

PARAMETERS

text string the string to send to the profiler

EXAMPLES

profiler.log_text("Event: " .. name)

profiler.recorded_frame_count()

profiler.recorded_frame_count()

Get the number of recorded frames in the on-screen profiler ui recording buffer

PARAMETERS

None

RETURNS

frame_count number the number of recorded frames, zero if on-screen profiler is disabled

EXAMPLES

-- Show the last recorded frame
local recorded_frame_count = profiler.recorded_frame_count()
profiler.view_recorded_frame(recorded_frame_count)

profiler.scope_begin()

profiler.scope_begin(name)

Starts a profile scope.

PARAMETERS

name string The name of the scope

EXAMPLES

-- Go back one frame
profiler.scope_begin("test_function")
  test_function()
profiler.scope_end()

profiler.scope_end()

profiler.scope_end()

End the current profile scope.

PARAMETERS

None

profiler.set_ui_mode()

profiler.set_ui_mode(mode)

Set the on-screen profile mode - run, pause, record or show peak frame

PARAMETERS

mode constant the mode to set the ui profiler in
  • profiler.MODE_RUN This is default mode that continously shows the last frame
  • profiler.MODE_PAUSE Pauses on the currently displayed frame
  • profiler.MODE_SHOW_PEAK_FRAME Pauses on the currently displayed frame but shows a new frame if that frame is slower
  • profiler.MODE_RECORD Records all incoming frames to the recording buffer
To stop recording, switch to a different mode such as MODE_PAUSE or MODE_RUN. You can also use the view_recorded_frame function to display a recorded frame. Doing so stops the recording as well. Every time you switch to recording mode the recording buffer is cleared.

EXAMPLES

function start_recording()
     profiler.set_ui_mode(profiler.MODE_RECORD)
end

function stop_recording()
     profiler.set_ui_mode(profiler.MODE_PAUSE)
end

profiler.set_ui_view_mode()

profiler.set_ui_view_mode(mode)

Set the on-screen profile view mode - minimized or expanded

PARAMETERS

mode constant the view mode to set the ui profiler in
  • profiler.VIEW_MODE_FULL The default mode which displays all the ui profiler details
  • profiler.VIEW_MODE_MINIMIZED Minimized mode which only shows the top header (fps counters and ui profiler mode)

EXAMPLES

-- Minimize the profiler view
profiler.set_ui_view_mode(profiler.VIEW_MODE_MINIMIZED)

profiler.set_ui_vsync_wait_visible()

profiler.set_ui_vsync_wait_visible(visible)

Shows or hides the time the engine waits for vsync in the on-screen profiler Each frame the engine waits for vsync and depending on your vsync settings and how much time your game logic takes this time can dwarf the time in the game logic making it hard to see details in the on-screen profiler graph and lists. Also, by hiding this the FPS times in the header show the time spent each time excuding the time spent waiting for vsync. This shows you how long time your game is spending actively working each frame. This setting also effects the display of recorded frames but does not affect the actual recorded frames so it is possible to toggle this on and off when viewing recorded frames. By default the vsync wait times is displayed in the profiler.

PARAMETERS

visible boolean true to include it in the display, false to hide it.

EXAMPLES

-- Exclude frame wait time form the profiler ui
profiler.set_ui_vsync_wait_visible(false)

profiler.view_recorded_frame()

profiler.view_recorded_frame(frame_index)

Pauses and displays a frame from the recording buffer in the on-screen profiler ui The frame to show can either be an absolute frame or a relative frame to the current frame.

PARAMETERS

frame_index table a table where you specify one of the following parameters:
  • distance The offset from the currently displayed frame (this is truncated between zero and the number of recorded frames)
  • frame The frame index in the recording buffer (1 is first recorded frame)

EXAMPLES

-- Go back one frame
profiler.view_recorded_frame({distance = -1})

Constants

profiler.MODE_PAUSE

pause on current frame

profiler.MODE_RECORD

start recording

profiler.MODE_RUN

continously show latest frame

profiler.MODE_SHOW_PEAK_FRAME

pause at peak frame

profiler.VIEW_MODE_FULL

show full profiler ui

profiler.VIEW_MODE_MINIMIZED

show mimimal profiler ui