docs: vrr clarifications

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"
         }
       ]
     },

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:
 <a name="types-VrrHz"></a>
 ### `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.
 
 
 <a name="types-VrrMode"></a>
@@ -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.
 
 
 

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.
+      description: |
-    - kind: number
+        The string `none` can be used to disable the limit.
-      description: The refresh rate in HZ.
 
+        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