Class TFramesPerSecond

Unit

Declaration

type TFramesPerSecond = class(TObject)

Description

Utility to measure frames per second, independent of actual rendering API. For example, it can be easily "plugged" into TCastleWindow (see TCastleWindow.Fps) or Lazarus GL control (see TCastleControl.Fps).

Things named "_" here are supposed to be internal to the TCastleWindow / TCastleControl and such implementations. Other properties can be controlled by the user of TCastleWindow / TCastleControl.

Hierarchy

Overview

Fields

Public nested const DefaultMaxSensibleSecondsPassed = 0.5;

Methods

Public constructor Create;
Public function ToString: string; override;
Public procedure ZeroNextSecondsPassed;
Public class function FrameId: TFrameId;
Public class function RenderFrameId: TFrameId;

Properties

Public property OnlyRenderFps: TFloatTime read FOnlyRenderFps;
Public property FrameTime: TFloatTime read FOnlyRenderFps; deprecated 'use OnlyRenderFps';
Public property RealFps: TFloatTime read FRealFps;
Public property RealTime: TFloatTime read FRealFps; deprecated 'use RealFps';
Public property WasSleeping: boolean read FWasSleeping;
Public property SecondsPassed: TFloatTime read FSecondsPassed;
Public property UpdateSecondsPassed: TFloatTime read FSecondsPassed; deprecated 'use SecondsPassed';
Public property MaxSensibleSecondsPassed: TFloatTime read FMaxSensibleSecondsPassed write FMaxSensibleSecondsPassed;
Public property UpdateStartTime: TTimerResult read FUpdateStartTime;

Description

Fields

Public nested const DefaultMaxSensibleSecondsPassed = 0.5;
 

Methods

Public constructor Create;
 
Public function ToString: string; override;

Display current FPS (RealFps, OnlyRenderFps, taking into account WasSleeping).

Public procedure ZeroNextSecondsPassed;

Forces SecondsPassed for the next "update" call to be zero.

This is useful if you just came back from some modal state, like a modal dialog box (like TCastleWindow.FileDialog or modal boxes in CastleMessages – they already call this method). SecondsPassed could be ridicoulously long in such case (if our message loop is totally paused, as in TCastleWindow.FileDialog on Windows) or not relevant (if we do our message loop, but we display something entirely different, like CastleMessages). So it's best to pretend that SecondsPassed is 0.0, so things such as TCastleSceneCore.Time do not advance wildly just because we did a modal dialog.

This forces the SecondsPassed to be zero at the next update event (_UpdateBegin).

Public class function FrameId: TFrameId;

Current frame identifier.

Changed when each container "update" event occurs, so this is equal during all TCastleUserInterface.Update, TCastleUserInterface.Render, TCastleTransform.Update, TCastleTransform.LocalRender occuring within the same frame. You can use this to avoid performing the same job many times in a single frame.

Never zero.

It's a class function, so you can access it like TFramesPerSecond.FrameId, no need to have a TFramesPerSecond instance (which is usually accessed from TCastleContainer, like TCastleContainer.Fps, TCastleWindow.Fps, TCastleControl.Fps.

Public class function RenderFrameId: TFrameId;

Frame identifier within which last render started.

This is usually equal to FrameId or FrameId - 1 (depending on the order, whether Update or Render happens first, which may be platform-dependent). Though if you disabled TCastleWindow.AutoRedisplay, it may be something even smaller than FrameId - 1.

Never zero. (This allows to easily treat "frame id = zero" as "frame id that never happened" in some logic.)

Properties

Public property OnlyRenderFps: TFloatTime read FOnlyRenderFps;

Rendering speed, measured in frames per second, but accounting only time spent inside "render" calls (thus ignoring time spent on physics and other logic).

This measures only time spend in TCastleContainer.EventRender method (and it's subordinates, like TCastleUserInterface.Render, TCastleScene.LocalRender, TCastleWindow.OnRender). It does not take into account time spent on other activities, like "update" calls, and it doesn't take into account that frames are possibly not rendered all the time (when AutoRedisplay = False).

See https://castle-engine.io/manual_optimization.php#section_fps for a detailed description what FPS mean and how they should be interpreted.

See also
RealFps
How many frames per second were actually rendered.
Public property FrameTime: TFloatTime read FOnlyRenderFps; deprecated 'use OnlyRenderFps';

Warning: this symbol is deprecated: use OnlyRenderFps

 
Public property RealFps: TFloatTime read FRealFps;

How many frames per second were actually rendered. This is the number of TCastleContainer.EventRender calls that actually happened within a real second of time. So it's an actual speed of your program. Anything can slow this down, not only long rendering, but also slow processing of other events (like "update" that does physics).

When TCastleWindow.AutoRedisplay or TCastleControl.AutoRedisplay is False, this may be very low, since we may not render the frames all the time (we may sleep for some time, or perform updates without rendering). In this case, the RealFps value may be confusing and useless (it does not reflect the speed of your application). Use the WasSleeping to detect this, and potentially hide the display of RealFps from user.

See https://castle-engine.io/manual_optimization.php#section_fps for a detailed description what FPS mean and how they should be interpreted.

See also
OnlyRenderFps
Rendering speed, measured in frames per second, but accounting only time spent inside "render" calls (thus ignoring time spent on physics and other logic).
Public property RealTime: TFloatTime read FRealFps; deprecated 'use RealFps';

Warning: this symbol is deprecated: use RealFps

 
Public property WasSleeping: boolean read FWasSleeping;

Some of the frames were not rendered, because the scene and camera were not moving. This happens only when TCastleWindow.AutoRedisplay or TCastleControl.AutoRedisplay are False, and it basically indicates that the RealFps value is not a useful indicator of your application speed.

See https://castle-engine.io/manual_optimization.php#section_fps for a detailed description what this means.

Public property SecondsPassed: TFloatTime read FSecondsPassed;

How much time passed since the last "update". You should use this inside "update" events and methods (TCastleContainer.EventUpdate, TCastleUserInterface.Update, TCastleTransform.Update...) to scale the movement. This way, your animation will work with the same speed (objects will travel at the same speed), regardless of the system performance (regardless of how often the "update" event occurs).

This is calculated as a time between start of previous "update" event and start of current "update" event.

Public property UpdateSecondsPassed: TFloatTime read FSecondsPassed; deprecated 'use SecondsPassed';

Warning: this symbol is deprecated: use SecondsPassed

 
Public property MaxSensibleSecondsPassed: TFloatTime read FMaxSensibleSecondsPassed write FMaxSensibleSecondsPassed;

Limit the SecondsPassed variable, to avoid increasing time in game a lot when a game was hanging or otherwise waiting for some exceptional event from OS. Used only when non-zero. By default it's DefaultMaxSensibleSecondsPassed.

Public property UpdateStartTime: TTimerResult read FUpdateStartTime;

Time of last Update call.


Generated by PasDoc 0.16.0.