Add a --vsync command line argument to control V-Sync status on startup

[Calinou]

Describe the project you are working on

The Godot editor 🙂

Describe the problem or limitation you are having in your project

When playing a game made by someone else, it's sometimes desired to override the V-Sync behavior if the developer doesn't provide any way to control it. This is common in gamejam games, for instance.

Since disabling V-Sync allows to decrease the input lag noticeably (even on 144 Hz displays), I almost always prefer playing with V-Sync disabled.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

I propose adding a --vsync CLI argument that handles overall V-Sync status when the project starts:

  --vsync    The type of vertical synchronization to request ('disabled', 'enabled', 'adaptive', 'mailbox').

Like with --video-driver (for instance), the argument value is required.

If adaptive or mailbox V-Sync is requested but unsupported by the OS, graphics driver or rendering API, it falls back to enabled with a warning message printed. This is already built-in behavior for run-time V-Sync changes, so there shouldn't be any need to replicate those checks in main.cpp.

Old version of this proposal (outdated for 4.x as V-Sync via compositor was removed)

We currently have the following command line arguments:

  --enable-vsync-via-compositor    When vsync is enabled, vsync via the OS' window compositor (Windows only).
  --disable-vsync-via-compositor   Disable vsync via the OS' window compositor (Windows only).

I propose replacing it with a single argument that handles overall V-Sync status:

  --vsync    The type of vertical synchronization to request ('disabled', 'enabled', 'compositor').

Like with --video-driver (for instance), the argument value is required.

In the future, we can extend this to support adaptive (if #1283 is implemented) and possibly even more options such as half.

When using --vsync compositor on platforms other than Windows, a warning message should be printed to state that the setting will be ignored. The "enabled" behavior will be used instead.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

main/main.cpp should be modified to accomodate for the new CLI arguments.

In the process, --disable-vsync (which was added in godotengine/godot#62122) should be removed in favor of --vsync disabled.

4.0 update: We'll have to keep --disable-vsync for compatibility reasons (with a deprecation warning if used), but we can remove it from the command line help.

If this enhancement will not be used often, can it be worked around with a few lines of script?

Technically, yes, but the project will need to be modified for it (see below). Also, implementing this functionality with a script will not make this option easy to discover as it won't be standardized across all Godot projects. It will not be mentioned in the command line help either, and the legacy V-Sync options will remain available.

Is there a reason why this should be core and not an add-on in the asset library?

It can technically be an add-on, but the point here is that this functionality must be built-in to achieve the desired goal (which is, forcing V-Sync behavior on any project made with Godot).

[poiati]

How does this stack up with the --disable-vsync cmd opt that was introduced?

[Calinou]

How does this stack up with the --disable-vsync cmd opt that was introduced?

The --disable-vsync CLI argument was added after this proposal was opened. I'd suggest removing --disable-vsync and replacing it with the --vsync argument proposed here, as --vsync will also cover the use case of --disable-vsync.