feat: let a video processor change camera and desktop frames

[devopvoid]

The counterpart of Android's VideoSource.setVideoProcessor: a hook between a camera or desktop source and its tracks, to blur a background, draw an overlay, mirror the picture, or drop frames.

API

dev.onvoid.webrtc.media.video.VideoProcessor, shaped like Android's:

public interface VideoProcessor {
    void setSink(VideoTrackSink sink);
    void onFrameCaptured(VideoFrame frame);
}

VideoTrackSource.setVideoProcessor(VideoProcessor) sets it, replacing any previous one; null removes it. The source hands each frame to onFrameCaptured() after adapting it to what its tracks ask for (the encoder's resolution and frame rate requests, the desktop source's maximum size), so the processor only works on frames that will be sent, at their final size. The processor delivers the frames to send to its sink: the same frame, a new one, or none; it may deliver later and from another thread.

• Camera (VideoDeviceSource) and desktop (VideoDesktopSource) sources take a processor. CustomVideoSource throws UnsupportedOperationException: its frames come from Java anyway, and a frame replaced in Java would lose the NTP time and frame ID the custom source sets.
• The frame passed to onFrameCaptured() is released when it returns; a processor that keeps or forwards it later retains it, as with frames elsewhere. The sink does not take over a delivered frame's reference.
• An exception from the processor goes to the capture thread's uncaught exception handler (as in fix: stop exceptions from callbacks unwinding through WebRTC #335), and the frame is dropped.

Lifetime

The sink a processor gets is a small Java object that forwards to its source until it is detached: when the processor is replaced, or before the source is disposed. Delivery and detaching synchronize on the sink, so a frame delivered from another thread never reaches a disposed source. To detach first, VideoDeviceSource.dispose() and VideoDesktopSource.dispose() are now Java methods around the native disposeInternal(), which also removes the processor before releasing the source, so a source that a track keeps alive stops calling into Java.

Native

• VideoProcessorHost (own file pair) holds the Java processor and turns frames into Java frames, holding a buffer reference for the duration of the call. Setting a processor swaps a shared_ptr under a mutex, so a frame being processed keeps its processor.
• VideoTrackDeviceSource, VideoTrackDeviceSourceMac and VideoTrackDesktopSource derive from it and pass their final frame through ProcessFrame(), delivering it themselves when no processor is set. DeliverProcessedFrame() sends to the broadcaster or AdaptedVideoTrackSource::OnFrame.
• The Java base class reaches the host through its own processorHostHandle field, set by each source's initialize, so no cast of the native source type is needed. JNI_VideoTrackSource holds setVideoProcessorNative and deliverProcessedFrame, which accepts native and Java I420 buffers through VideoFrame::toNativeBuffer.

The macOS camera source was changed the same way but could not be compiled here; CI will tell.

Docs

camera-capture.md gains "Changing Frames Before They Are Sent" with an example and the ownership rules; desktop-capture.md points to it.

Tests

VideoProcessorTests:

• customSourceRejectsProcessor, setAndRemove (camera and desktop sources), staleSinkDropsFrames (a replaced processor's sink and sinks after dispose drop frames without failing).
• processedDesktopFramesReachTrack: real screen capture through a processor that replaces every frame with a grey one; the track receives the grey frames.
• processorCanDropFrames: a processor that delivers nothing; the track receives nothing.

The two screen tests skip themselves where there is no screen or no frames. The full webrtc suite passes on Windows (266 run, 0 failures, 2 skipped), also under -Pjni-check with no JNI errors; both screen tests ran.