From dbdc919e46f12c50ea6d98840c7b31a4d3ef3775 Mon Sep 17 00:00:00 2001 From: Stipe Kotarac Date: Mon, 19 Jan 2026 16:31:54 +0100 Subject: [PATCH] docs: vrr clarifications --- toml-spec/spec/spec.generated.json | 8 +++---- toml-spec/spec/spec.generated.md | 33 ++++++++++++++++++++++---- toml-spec/spec/spec.yaml | 37 +++++++++++++++++++++++++----- 3 files changed, 63 insertions(+), 15 deletions(-) diff --git a/toml-spec/spec/spec.generated.json b/toml-spec/spec/spec.generated.json index c855205a..08713987 100644 --- a/toml-spec/spec/spec.generated.json +++ b/toml-spec/spec/spec.generated.json @@ -2094,22 +2094,22 @@ "$ref": "#/$defs/VrrMode" }, "cursor-hz": { - "description": "The VRR cursor refresh rate.\n\nLimits the rate at which cursors are updated on screen when VRR is active.\n", + "description": "The VRR cursor refresh rate.\n\nLimits the rate at which cursor movement forces a screen update\nwhen VRR is active.\n", "$ref": "#/$defs/VrrHz" } }, "required": [] }, "VrrHz": { - "description": "A VRR refresh rate limiter.\n\n- Example 1:\n\n ```toml\n vrr = { cursor-hz = 90 }\n ```\n\n- Example 2:\n\n ```toml\n vrr = { cursor-hz = \"none\" }\n ```\n", + "description": "A VRR cursor refresh rate limit.\n\n- Example 1:\n\n ```toml\n vrr = { cursor-hz = 90 }\n ```\n\n- Example 2:\n\n ```toml\n vrr = { cursor-hz = \"none\" }\n ```\n", "anyOf": [ { "type": "string", - "description": "The string `none` can be used to disable the limiter." + "description": "The string `none` can be used to disable the limit.\n\nThis means the cursor refresh rate is unbounded, meaning every mouse\nmovement will update the screen.\n\nIf the mouse reporting interval (polling rate) is >= screen refresh\nrate, this results in the screen spiking to maximum refresh rate on\nmouse movement.\n" }, { "type": "number", - "description": "The refresh rate in HZ." + "description": "The cursor refresh rate limit in Hz.\n\nThis means the cursor is updated whenever the rest of the screen is\nupdated but no later than `1 / cursor-hz` after the last screen update.\n\nIf the application's content refresh rate is higher than `cursor-hz`,\nthe cursor will update with the content.\n\nSetting `cursor-hz = 1` would force it to always match content refresh\nrate.\n\nHowever, if content refresh rate regularly drops low, cursor movement\nwill feel choppy. Consider setting `cursor-hz` to a reasonable minimum\nvalue to keep cursor movement smooth.\n" } ] }, diff --git a/toml-spec/spec/spec.generated.md b/toml-spec/spec/spec.generated.md index 369cb4c7..526e657c 100644 --- a/toml-spec/spec/spec.generated.md +++ b/toml-spec/spec/spec.generated.md @@ -4787,7 +4787,8 @@ The table has the following fields: The VRR cursor refresh rate. - Limits the rate at which cursors are updated on screen when VRR is active. + Limits the rate at which cursor movement forces a screen update + when VRR is active. The value of this field should be a [VrrHz](#types-VrrHz). @@ -4795,7 +4796,7 @@ The table has the following fields: ### `VrrHz` -A VRR refresh rate limiter. +A VRR cursor refresh rate limit. - Example 1: @@ -4813,11 +4814,31 @@ Values of this type should have one of the following forms: #### A string -The string `none` can be used to disable the limiter. +The string `none` can be used to disable the limit. + +This means the cursor refresh rate is unbounded, meaning every mouse +movement will update the screen. + +If the mouse reporting interval (polling rate) is >= screen refresh +rate, this results in the screen spiking to maximum refresh rate on +mouse movement. #### A number -The refresh rate in HZ. +The cursor refresh rate limit in Hz. + +This means the cursor is updated whenever the rest of the screen is +updated but no later than `1 / cursor-hz` after the last screen update. + +If the application's content refresh rate is higher than `cursor-hz`, +the cursor will update with the content. + +Setting `cursor-hz = 1` would force it to always match content refresh +rate. + +However, if content refresh rate regularly drops low, cursor movement +will feel choppy. Consider setting `cursor-hz` to a reasonable minimum +value to keep cursor movement smooth. @@ -4853,7 +4874,9 @@ The string should have one of the following values: - `variant3`: - VRR is enabled when a single game or video is displayed fullscreen. + VRR is enabled when a single application is displayed fullscreen and + describes its content type as video or game through the + wp_content_type_v1 protocol. diff --git a/toml-spec/spec/spec.yaml b/toml-spec/spec/spec.yaml index 14d3ec17..e56c039d 100644 --- a/toml-spec/spec/spec.yaml +++ b/toml-spec/spec/spec.yaml @@ -3178,7 +3178,8 @@ Vrr: description: | The VRR cursor refresh rate. - Limits the rate at which cursors are updated on screen when VRR is active. + Limits the rate at which cursor movement forces a screen update + when VRR is active. VrrMode: @@ -3201,12 +3202,15 @@ VrrMode: - value: variant2 description: VRR is enabled when a single application is displayed fullscreen. - value: variant3 - description: VRR is enabled when a single game or video is displayed fullscreen. + description: | + VRR is enabled when a single application is displayed fullscreen and + describes its content type as video or game through the + wp_content_type_v1 protocol. VrrHz: description: | - A VRR refresh rate limiter. + A VRR cursor refresh rate limit. - Example 1: @@ -3222,10 +3226,31 @@ VrrHz: kind: variable variants: - kind: string - description: The string `none` can be used to disable the limiter. - - kind: number - description: The refresh rate in HZ. + description: | + The string `none` can be used to disable the limit. + This means the cursor refresh rate is unbounded, meaning every mouse + movement will update the screen. + + If the mouse reporting interval (polling rate) is >= screen refresh + rate, this results in the screen spiking to maximum refresh rate on + mouse movement. + - kind: number + description: | + The cursor refresh rate limit in Hz. + + This means the cursor is updated whenever the rest of the screen is + updated but no later than `1 / cursor-hz` after the last screen update. + + If the application's content refresh rate is higher than `cursor-hz`, + the cursor will update with the content. + + Setting `cursor-hz = 1` would force it to always match content refresh + rate. + + However, if content refresh rate regularly drops low, cursor movement + will feel choppy. Consider setting `cursor-hz` to a reasonable minimum + value to keep cursor movement smooth. Tearing: kind: table