add animationFrameProvider map option

[ansis]

This option allows the user to implement requestAnimationFrame and cancelAnimationFrame in order to synchronize map rendering with their external rendering. While it is generally recommended to let the browser schedule map rendering frames this may be useful for synchronizing with external content in some cases (fix #7893).

This could also be useful for synchronizing multiple maps.

const animationFrameProvider = {
    requestAnimationFrame: fn => { ... },
    cancelAnimationFrame: handle => { ... }
};
const map = new Map({
    animationFrameProvider: animationFrameProvider,
    ...
});

As an alternative to synchronous render frames

#7893 explains the reasons why synchronous rendering is necessary in some cases. An animationFrameProvider option seemed preferable to implementing a map.synchronousRepaint() because:

• it prevents all renders that aren't directly triggered by use (instead of just allowing renders to be triggered by you)
• it could be harder to abuse

class SynchronizedFrameProvider {
    constructor() {
        this._requests = [];
        this._nextHandle = 0;
    }

    requestAnimationFrame(fn) {
        this._requests.push({
            handle: this._nextHandle++,
            fn
        });
    }

    cancelAnimationFrame(handle) {
        this._requests = this._requests.filter(req => req.handle !== handle);
    }

    // called by you to trigger synchronous rendering
    dispatchFrame() {
        // clear array before dispatching to handle case where user calls
        // `requestAnimationFrame` from within the dispatched function.
        const requests = this._requests;
        this._requests = [];

        const now = performance.now();
        for (const req of requests) {
            req.fn(now);
        }
    }
}

const provider = new SynchronizedFrameProvider();

const map = new Map({
    animationFrameProvider: provider
    ...
});

...

provider.dispatchFrame();

Launch Checklist

• briefly describe the changes in this PR
• write tests for all new functionality
• document any changes to public APIs
• post benchmark scores
• manually test the debug page

@mourner @ryanhamley does this approach seem preferable? Or would it be better just implement a map.synchronousRender()?

[jahow]

Hi!

The OpenLayers community is looking forward to this improvement as it will allow keeping an OpenLayers map and Mapbox in sync, thus giving people the best of both worlds! There is currently a working example but it uses an undocumented API, as was described in #7893 (comment)

Please let me know if there is anything we can do to help, inc. contribution proposal if necessary. Thanks a lot

[mourner]

It appears that there's no consensus on whether we should commit to this API — it doesn't solve the original issue that prompted it according to the author, and there are concerns over its ergonomics. Let's close the PR for now and re-evaluate the problem.