HOTSPOT PROPERTIES(9)

✨ hotspot properties(9) ✨

okay so vibe check, bestie: you're reading the Kernel API Manual page for hotspot properties(9), and we're about to make mouse cursor internals make sense. 🖱️🎀 no cap.

• HOTSPOT_X — the property to set the mouse hotspot x offset. ✨
• HOTSPOT_Y — the property to set the mouse hotspot y offset. 💅

When the plane is being used as a cursor image to display a mouse pointer, the "hotspot" is the offset within the cursor image where mouse events are expected to go. Positive values move the hotspot from the top-left corner of the cursor plane towards the right and bottom.

Most display drivers do not need this information because the hotspot is not actually connected to anything visible on screen. However, this is necessary for display drivers like the para-virtualized drivers (eg qxl, vbox, virtio, vmwgfx), that are attached to a user console with a mouse pointer. Since these consoles are often being remoted over a network, they would otherwise have to wait to display the pointer movement to the user until a full network round-trip has occurred. New mouse events have to be sent from the user's console, over the network to the virtual input devices, forwarded to the desktop for processing, and then the cursor plane's position can be updated and sent back to the user's console over the network. it's giving "network round-trip trauma" 😭

Instead, with the hotspot information, the console can anticipate the new location, and draw the mouse cursor there before the confirmation comes in. To do that correctly, the user's console must be able predict how the desktop will process mouse events, which normally requires the desktop's mouse topology information, ie where each CRTC sits in the mouse coordinate space. This is typically sent to the para-virtualized drivers using some driver-specific method, and the driver then forwards it to the console by way of the virtual display device or hypervisor. 🌈

The assumption is generally made that there is only one cursor plane being used this way at a time, and that the desktop is feeding all mouse devices into the same global pointer. Para-virtualized drivers that require this should only be exposing a single cursor plane, or find some other way to coordinate with a userspace desktop that supports multiple pointers. If the hotspot properties are set, the cursor plane is therefore assumed to be used only for displaying a mouse cursor image, and the position of the combined cursor plane + offset can therefore be used for coordinating with input from a mouse device. 🫶

The cursor will then be drawn either at the location of the plane in the CRTC console, or as a free-floating cursor plane on the user's console corresponding to their desktop mouse position. 🌸

DRM clients which would like to work correctly on drivers which expose hotspot properties should advertise DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT. Setting this property on drivers which do not special case cursor planes will return EOPNOTSUPP, which can be used by userspace to gauge requirements of the hardware/drivers they're running on. Advertising DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT implies that the userspace client will be correctly setting the hotspot properties. periodt, that's the contract 💖

💖 SEE ALSO 💖

• Kernel file ./drivers/gpu/drm/drm_plane.c overview(9)
• standard plane properties(9)
• drm_plane_create_hotspot_properties(9)
• drm_universal_plane_init(9)
• drm_plane_cleanup(9)
• drm_plane_from_index(9)
• drm_plane_force_disable(9)
• drm_mode_plane_set_obj_prop(9)
• drm_plane_has_format(9)
• drm_any_plane_has_format(9)
• damage tracking(9)
• drm_plane_enable_fb_damage_clips(9)
• drm_plane_get_damage_clips_count(9)
• drm_plane_get_damage_clips(9)
• drm_plane_create_scaling_filter_property(9)
• drm_plane_add_size_hints_property(9)
• drm_plane_create_color_pipeline_property(9)

okay that's the tea ☕ — this was hotspot properties(9), source/version ./drivers/gpu/drm, dated October 2026. bye bestie, go set those hotspots correctly! 💖🦋