Wayland Frame Timing: Separate Draw Scheduling, Buffer Release and Presentation Feedback

A Wayland HMI logs a frame callback and labels it “displayed.” Another path reuses the submitted image buffer at that same callback. Both conclusions need different evidence: the redraw hint, the buffer’s release and the update’s presentation outcome are separate protocol events.

This guide pins Wayland core 1.23.1 and the presentation-time protocol from wayland-protocols 1.36. The buffer example uses one core wl_shm buffer on one surface, with no other outstanding object using the same backing storage. Explicit-synchronization extensions require their own additional contracts.

Use frame callbacks to schedule drawing

wl_surface.frame requests a one-shot notification that it is a good time to draw another frame. The request takes effect with the next wl_surface.commit. For continued animation, request the next callback again; one callback is not a permanent stream of refresh events.

This is a throttling hint, not a permission token that forbids earlier commits. The protocol explains that drawing and committing too early can waste work because some updates may never reach the display. Using the hint can help pace animation without turning it into a presentation receipt.

The compositor should avoid signaling frame callbacks for a surface that is not visible, for example one completely obscured by opaque content. An animation waiting on a hidden surface is therefore not, by itself, evidence of a dead compositor. Keep visibility and connection-health observations separate.

Track release against the actual buffer

wl_buffer.release reports that the compositor no longer uses that buffer. In the narrowly scoped shared-memory example, with no other outstanding use of its backing, the application can then reuse the storage according to its own ownership rules.

Release can arrive before the frame callback associated with the commit that attached the buffer. The core protocol gives copying the surface content into a compositor texture as an example. The source storage can become reusable while a separate copy remains relevant to future presentation.

Do not invert that example into a mandatory event order. Nor should a frame callback release whichever buffer happens to be called “current” in the application. Associate release with the particular buffer object and account for all outstanding uses of shared backing before recycling it.

Ask for a presentation outcome when supported

The presentation extension associates a feedback object with a content submission. Request feedback for the intended surface update and retain the object’s association with that commit. Verify the compositor’s advertised protocol support and the version actually bound before relying on this path.

The feedback has two terminal outcomes. presented supplies the update’s presentation timestamp and related information. discarded means that update was never displayed, for example because it was superseded. Either terminal event destroys the feedback object.

An update can therefore have a submitted buffer and ordinary scheduling activity without a successful presentation outcome. A ledger that increments its “displayed frames” counter for every callback cannot represent discarded content correctly. Keep submitted, released and presented counts named separately rather than forcing them into one frame counter.

Preserve the timestamp’s clock domain

The frame callback carries milliseconds with an undefined base. The presentation extension instead announces a clock_id when bound; that clock remains fixed for the connection. On POSIX systems, its identifier can be used with clock_gettime().

Do not subtract the frame callback’s raw timestamp from a presentation timestamp and label the result latency. The units and clock origin are not established as the same. If application timestamps are to be compared with presentation feedback, sample the advertised presentation clock or establish a valid mapping explicitly.

Also retain the feedback’s reliability flags. hw_clock indicates a hardware-derived presentation timestamp; hw_completion indicates hardware signaled the start of using the new image. vsync and zero_copy describe other presentation properties. None should be inferred merely from receiving a feedback event.

Record a per-commit event ledger

A proposed ledger identifies the surface, commit, buffer, frame-callback object and presentation-feedback object. It records each event independently, including callback arrival, buffer release, terminal presentation outcome, presentation clock and flags. Buffer identity and commit identity must remain distinct if an allocation is reused later.

Use two synthetic cases in the review. In the first, the compositor copies an image and releases its source before the frame callback. The storage becomes available under the stated assumptions, but presentation still needs its own record. In the second, a newer update supersedes an earlier one, and the earlier feedback ends with discarded rather than a timestamp.

No frame was submitted and no latency measured here. The presentation protocol permits compositors to approximate the physical presentation time from system events and known display-path latency. Its feedback is useful protocol evidence, but an optical end-to-end measurement remains a different experiment. The immediate acceptance criterion is a ledger that cannot mistake redraw scheduling or storage release for proof that a particular update was displayed.