Skip to content

Show the mouse pointer in a screen share (Windows, stage 1) - #898

Open
unRekable wants to merge 2 commits into
mainfrom
draft/797-cursor
Open

unRekable wants to merge 2 commits into
mainfrom
draft/797-cursor

Conversation

@unRekable

Copy link
Copy Markdown
Collaborator

What changed and why

A shared screen went out without the sharer's pointer on Windows and X11 — a plain pixel grab says
nothing about where the pointer is — so viewers could not follow what was being pointed at. The
share now carries the pointer where the platform can, on by default: Windows fetches it
(GetCursorInfo) and draws it into every captured frame (Desktop Duplication, the GDI fallback,
and a shared window), and on Wayland the portal already embeds it, so a share that wants none now
asks the portal to hide it. The sharer can turn it off with a Pointer switch in the share picker.

Type

  • feature
  • fix
  • perf
  • refactor
  • chore
  • docs

Fixes #797.

Platforms

  • windows
  • macos
  • linux
  • android
  • ios

The wire field and the mediad setting reach every desktop. The drawing itself: Windows draws the
pointer; Wayland keeps the portal's embedded one and honours hiding it; macOS cannot yet — a Core
Graphics grab has no pointer and no mode that draws one, and it comes with the ScreenCaptureKit
capture (#773), whose showsCursor is the native mode; X11 needs the XFixesGetCursorImage
blend and is the next stage. Phones have no pointer.

Proof

Scenario: e2e/scenarios/share-pointer

Lab run:

The scenario runs the real capture thread on the host's real screen, requires the share to go out
with the pointer shown (the default) and frames to flow with it, then requires a share that asks
for none to turn it off. The recording shows the pointer wherever the platform draws it; on a
macOS or X11 host it shows the change plumbing with the pointer still absent, as the README says.

Compatibility

One wire field grew: MediaRequest::ShareSend carries show_cursor: Option<bool> with
#[serde(default, skip_serializing_if = "Option::is_none")]. Absent is on, so an older shell —
which never sends the field — gets the pointer like everyone, and an older mediad ignores the
unknown field and keeps working; both directions of a mixed pair read the same frames. No field
was removed, renamed or retyped. chatd forwards the request unchanged, and no server is involved:
this rides the window → mediad wire only.

Risk and rollback

The drawing is off with one ShareSend (show_cursor: Some(false)), and the whole change reverts.
A wrong blend makes the pointer look off, not wrong data: the decode is cached per cursor shape,
only the pointer's own rectangle is touched per frame (no second full-frame copy, and none of it
runs on the call's tick), and a pointer Windows says is hidden or suppressed draws nothing, so a
game that draws its own stays as it was. Monochrome and masked cursors draw the old
inverted-screen pixel as white — noted in code; no current system cursor uses it.

Release note

Screen shares now show your mouse pointer (Windows and Wayland; macOS and X11 to follow), and the
share picker has a switch to hide it.

@unRekable unRekable left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

🟡 1 finding (1 blocking).

The design holds: the wire flag is additive with absent = on (internally tagged MediaRequest lets an older mediad ignore it), the decode cache is bounded to one entry and lives on the capture thread only, the DXGI path blends the pointer's own rectangle into the clean last frame with no second full-frame copy, and the CRLF files keep their line endings. The windows-sys 0.61 call shapes (GetCursorInfo, GetIconInfo, DrawIconEx, GetObjectW, GetDIBits) all match the crate source, and the straight-alpha blend matches how Windows keeps cursor bitmaps. What it fails on is the compiler: two windows-sys extern calls in the new cursor module sit outside unsafe blocks, so mediad's Windows build cannot compile.

Residual risk

  • decoded() clones the cached pointer's whole pixel buffer (about 4-16 KB) every frame on the capture thread; cheap next to the full-frame copy and encode that thread already does, but borrowing under the lock would avoid the allocation.
  • The decode cache is keyed by the HCURSOR value alone; if Windows hands a new cursor the recycled handle of the cached one, the previous shape draws briefly (cosmetic, one frame until a shape change).
  • Picker thumbnails now go through screens::capture too, so the pointer is baked into the share picker's preview images, frozen at capture time.
  • Cursor alpha is read as straight and the monochrome invert pixel draws white, as the PR says: a premultiplied third-party cursor would show a slightly too bright edge, with no system cursor affected.

Comment thread crates/mediad/src/picture/cursor.rs Outdated

/// A bitmap's rows, top down, `bits` a pixel (32 colour, 1 the masks), each row `stride`.
fn read(handle: HBITMAP, width: u32, height: u32, stride: u32, bits: u32) -> Option<Vec<u8>> {
let dc = GetDC(std::ptr::null_mut());

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Blocker: GetDC here and ReleaseDC (line 241) are unsafe extern functions, called in the safe fn read without an unsafe block: E0133, mediad's Windows build fails to compile. Wrap both: let dc = unsafe { GetDC(std::ptr::null_mut()) }; and unsafe { ReleaseDC(std::ptr::null_mut(), dc); }.

@unRekable
unRekable marked this pull request as ready for review November 18, 2026 16:12
@unRekable
unRekable requested a review from itz4blitz as a code owner November 18, 2026 16:12
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Tiny Code Review

⚠️ Code review unavailable · run

the AI provider rate-limited the request

This is advice, not a gate. Re-run with the agent:review label or a /review comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

App: show the mouse pointer in a screen share

1 participant