Timer: Add optional timestamp parameter.

[vanruesc]

Related PR: #17912

Description

This PR continues the discussion from #17912 (comment).

I've added an optional timestamp parameter to Timer.update() that allows the user to pass the same timestamp to multiple timers. This also avoids unnecessary calls to performance.now() when using requestAnimationFrame because the callback already receives a timestamp argument.

@Mugen87 previously raised some concerns regarding this parameter:

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).

We can clarify in the docs that using a fixedDelta overrides dynamic time deltas. I'm not sure if the timestamp parameter would somehow interfere with _startTime. Shouldn't this just work as if performance.now() was used?

[Mugen87]

Shouldn't this just work as if performance.now() was used?

This only works if the value of performance.now() and the value of the timestamp parameter are actually compatible to each other. Since we can't control what values users pass into update(), I was afraid of unexpected side effects.

However, the timestamp value you get from requestAnimationFrame() works in any case and I think this is the most common use case. The documentation is also clarified so I'm okay with this change.