[Feature Request] Add retro_set_raster_poll API Proposal (To Incubate Beam Raced Outputs)

UPDATE December 2023: Bounty Requirements Reduction

Completing #10758 qualifies for the full bounty published at #6984 ... See latest comment https://github.com/libretro/RetroArch/issues/10758#issuecomment-1839907540

Original

We need a very simple per-raster callback function called "retro_set_raster_poll" whose arguments are identical to "retro_set_video_refresh".

Once the centralized hook is done, all emulator modules can just chain it to retro_set_video_refresh by default. This will be default behavior, for beamrace-unaware backwards compatibility

This API is a prerequisite for multiple GitHub items:

• #6984 aka Add Beam Racing/Scanline Sync to RetroArch (aka Lagless VSYNC)
• #10757 aka (BFIv3) Emulate a CRT Electron Gun Via Rolling-Scan BFI

Either or both may be implemented at some time in the future. Having this feature trailblazed will help.

Stage 1: Start with dummy hooking all emulator modules

Initially, retro_set_raster_poll would just do nothing .... It would never be used. Just add the hook, and make sure that there are do-nothing hooks compatible in all emulator module header files.

Stage 2: Make at least one module support beamraced output

I would pick the NES module since from a quick glance, that module seems to only need potentially maybe just only 10 to 20 lines of modifications to support retro_set_raster_poll (to beam race its output to whomever programs future beamraced outputs within #6984 or #10757).

By having one emulator module already support beamraced output capability, this would make it much easier for develoeprs to begin implementing any kind of beamraced outputs

Behavior for emulator modules that choose to support beamraced outputs,

• Emulator module calls retro_set_raster_poll everytime an emulator scan line is plotted
• It provides the frame buffer containing the incompletely-rendered emulator framebuffer (complete up to the most recently plotted emulator scanline).
• Whomever programs future beamraced outputs can choose to do it in a chunked method (frameslice), per pixel row (scanline method), full-screen (no output beamracing)

You wouldn't have to worry about it, that's the responsibility of whomever programs the handling of retro_set_raster_poll -- the only responsibility for emulator module maintainers is to simply call it when an emulated raster is complete (one pixel row completed into emulator frame buffer).

How many calls per emulator refresh cycle?

• retro_set_raster_poll should be called once every emulator scan line is rendered. The count of calls is equal to the vertical resolution of the original machine (including any overscan area).
• retro_set_video_refresh should be called once per emulator refresh (right after the last call to the retro_set_raster_call for the final scan line).

This allows supporting beamraced outputs in a simple & cross-platform way.

Start by locating the retro_set_video_refresh API and the emulator module header files mentioned in the proposal. Review how refresh callbacks are registered and how modules render scan lines. Done means the new raster-poll hook is added with no-op compatibility hooks, with at least one module calling it per completed scan line before the final video refresh.