Documentation
[SDK Documentation] [CGapiTimer]

CGapiTimer

Overview

CGapiTimer contains functions to limit the maximum number of frame updates each second for better battery usage. You can also use CGapiTimer to retrieve average frame render time and frame rate.

This document has been updated for use with GapiDraw 4.0 or later.
Last updated on October 5, 2008.

CGapiTimer::StartTimer

This method initializes the timer object and sets the target frame rate.

Parameters

dwMaxFrameRate

Specifies the maximum number of frame updates each second for your application. CGapiTimer will adjust the sleep time in WaitForNextFrame so that the target frame rate is always reached. Set this value to 0 to avoid sleeping in Update() to synchronize to the vertical blanking on some devices.

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS

Remarks

The max frame rate is the maximum number of display updates that will be shown each second. If this value is set to 0, UpdateTimer will return immediately, which is useful if you are synchronizing the final blit to the vertical blanking period of the display and still want to know the actual frame rate of your application.

It is safe to call StartTimer multiple times for the same object, in case the frame rate needs to be adjusted during game play.

CGapiTimer::UpdateTimer

This method waits a number of milliseconds for the next frame to be rendered.

Parameters

None

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_FRAMETIMEOVERFLOW
GDERR_NOTINITIALIZED

Remarks

If your target framerate is set to 0, UpdateTimer will return immediately. This is useful when you are synchronizing the final blit to the vertical blanking period of the display.

If your application is set to display 30 updates each second, this gives each frame a maximum time of 1000/30 = 33 milliseconds to perform its calculations. If each frame takes 10 milliseconds to create, and you update the display continously, your game will run too fast (1000/10 = 100 frames each second). Each call to UpdateTimer analyzes the time previous frames have taken to render, and anticipates how long it should sleep to reach its target goal set in CGapiTimer::StartTimer. In the previous example, each call to UpdateTimer would cause the thread to sleep for 23 milliseconds. If one frame takes longer to render than others, the other frames will sleep less.

CGapiTimer always tries to use the highest resolution timer available. Internally, it tries to query the High Performance timer, the Windows Multimedia timer, and lastly the System Tick counter if none of the others were available.

If each frame takes longer than (1000/target frame rate) to render, UpdateTimer will do nothing and return GDERR_FRAMETIMEOVERFLOW. You should always check the return code from WaitForNextFrame, and adjust your game parameters accordingly.

CGapiTimer::GetActualFrameRate

This method returns the actual number of frame updates each second.

Parameters

pActualFrameRate

Address of a FLOAT that will be filled with the number of frame updates each second.

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED

CGapiTimer::GetActualFrameTime

This method returns the time each frame takes to render, not counting the sleep period.

Parameters

pActualFrameTime

Address of a FLOAT that will be filled with the time each frame takes to render, not counting sleep periods. The time is an average of all frames for one second.

Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS
GDERR_NOTINITIALIZED