Added THREE.Timer.

[Mugen87]

Related #17679

This is a new alternative to THREE.Clock with a different API design and behavior. It should make it easier to implement three.js apps FPS independent which becomes more and more important with faster refresh rates.

Background: Some time ago, I've realized on a 144 Hz gaming laptop that (at least in Chrome and Firefox) WebGL apps run with 144 FPS. Some three.js examples now look weird because they assume fix update steps (around 60 FPS). Since certain laptops already offer 240 Hz screens, I think we should reconsider how a time class works. The main differences of THREE.Timer compared to THREE.Clock are:

• THREE.Timer has an update method that updates its internal state.
• That makes it possible to call .getDeltaTime() and .getElapsedTime() multiple times per simulation step without getting different values.
• The class uses the Page Visibility API to avoid large time delta values when the app is inactive (e.g. tab switched or browser hidden).
• It's possible to configure a fixed time delta and a time scale value (similar to Unity's Time interface).
• No public properties, no ctor parameter. The public API only consists of methods.

THREE.Timer is located in examples/jsm/misc/ for now. I personally think THREE.Timer (or a similar class) should replace THREE.Clock at some point since the class has some conceptual design flaws. The example webgl_morphtargets_sphere already uses THREE.Timer in order to replace the existing FPS workaround.

The method names are quite descriptive now. If e.g. getDelta() is preferred over getDeltaTime(), I'm happy to shorten the names.

[fernandojsg]

I like it! Just a question, what is the expected use of now() if fixedTime is enabled? maybe is safer to return elapsedTime in that case? as it could be inconsistent to use now() together with the elapsedTime provided by the fixed steps.

[Mugen87]

Just a question, what is the expected use of now() if fixedTime is enabled?

Um, it's probably better to make now() private in order to avoid this confusion. The method should just return a time stamp which is used to compute the delta time when no fixed deltas are used.

Timer.now() should not be affected by timeScale. If elapsedTime is used in now(), that would be the case.

[fernandojsg]

So in that case I agree on making now() private

[looeee]

If getDelta() is preferred over getDeltaTime(), I'm happy to shorten the names.

I think getDelta() is fine - in the context of a timer, it's very clear that we are talking about time deltas.

[looeee]

In what situations would you want to use fixedDeltaTime?

[Mugen87]

It's actually useful for testing and debugging if a timer can produce deterministic values.

[Mugen87]

I think getDelta() is fine - in the context of a timer, it's very clear that we are talking about time deltas.

Okay, I've shorten the method names and variables.

[CreaticDD]

Nice.

Is there a reason you've chosen to add a separate "update()" call?

I.e. why not update the timer when "getDelta()" is called like the current Clock?

[Mugen87]

I.e. why not update the timer when "getDelta()" is called like the current Clock?

Because many users complained about the fact that multiple calls of getDelta() within a single frame produces wrong results. getElapsedTime() has similar issues, see #5696.

To avoid these design problems, the state of the timer is now explicitly updated by calling update(). Yes, it is an additional method call but it avoids confusing behaviors of the current Clock class.

[ycw]

would you mind elaborate that how the Timer solves this "design flaw" of Clock #26806 (comment)? any help is appreciated.

[Mugen87]

Updating the timer per frame before querying data is the intended usage.

[Mugen87]

I've seen projects in the past copying this code or use an adapted version of it so I think it's better to provide an alternative to THREE.Clock in three.js.

[vanruesc]

The update method also has an optional timestamp parameter which can be obtained from the requestAnimationFrame callback to avoid unnecessary calls to performance.now:

That is a good idea! I'll add it to the PR.

Just curious: why was this removed in d443665? 🤔

[WestLangley]

I personally think THREE.Timer (or a similar class) should replace THREE.Clock at some point

How about adding it to core now, with documentation? Then, deprecate THREE.Clock eventually.

If you don't want to do that now, how about adding the above comprehensive description to the header of Timer.js?

[Mugen87]

Just curious: why was this removed in d443665? 🤔

I was unsure about this feature since the parameter has no effect when a fixed time delta is used. Besides, I couldn't decide how the parameter should play together with _startTime (which was added to support multiple timers).

That said, not including a timestamp parameter in this PR does not mean we shouldn't support it. I just had the feeling this needs more discussion. A separate PR adding timestamp would be fine!

If you don't want to do that now, how about adding the above comprehensive description to the header of Timer.js?

That sounds good to me!

[Mugen87]

If you don't want to do that now, how about adding the above comprehensive description to the header of Timer.js?

That sounds good to me!

Done! 46b6bb0

For r161, I'll try to add a documentation page.

[mrdoob]

Sorry for the huge delay dealing with this... 🙏

[mrdoob]

Hmmm... I'm not sure about the API for fixedTime.
I'll open a new PR for it... 🤔