blob: 5ddd7782f6186dfc1a4c4f208f9d8bb9b038116a [file] [log] [blame]
// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.ui.scenic;
using fuchsia.images;
// Client use Sessions to interact with a Scenic instance by enqueuing commands
// that create or modify resources.
protocol Session {
Enqueue(vector<Command> cmds);
// Present all previously enqueued operations. In order to pipeline the
// preparation of the resources required to render the scene, two lists of
// fences (implemented as events) are passed.
// |presentation_time| specifies the time on or after which the
// client would like the enqueued operations should take visible effect
// (light up pixels on the screen), expressed in nanoseconds in the
// |CLOCK_MONOTONIC| timebase. Desired presentation times must be
// monotonically non-decreasing.
// Using a desired presentation time in the present or past (such as 0)
// schedules enqueued operations to take visible effect as soon as possible
// (during the next frame to be prepared).
// Using a desired presentation time in the future schedules the enqueued
// operations to take visible effect as closely as possible to or after
// the stated time (but no earlier).
// Each rendered frame has a target presentation time. Before rendering
// a frame, the scene manager applies all enqueued operations associated
// with all prior calls to |Present()| whose desired presentation time
// is on or before the frame's target presentation time.
// The |Present()| method does not return until the scene manager begins
// preparing the first frame which includes its presented content.
// Upon return, the |PresentationInfo| provides timing information for the
// frame which includes the presented content.
// To present new content on each successive frame, wait for |Present()|
// to return before calling |Present()| again with content for the next
// frame.
// It is also possible to enqueue and present successive frames of content
// all at once with increasing desired presentation times, incrementing by
// |PresentationInfo.presentation_interval| for each one.
// Animation updates are also coordinated in terms of presentation time.
// TODO(jeffbrown): Defining presentation time in terms of |CLOCK_MONOTONIC|
// simplifies synchronization across subsystems but it might be too simple.
// We should consider using a synthetic timebase and describing its relation
// to other clocks separately. That would make it possible to present
// content (animations, media, and UI) in "slow mode" simply by varying the
// timing relation, assuming clients play along.
// |acquire_fences| are used by Scenic to wait until all of the session's
// resources are ready to render (or to allow downstream components, such as
// the Vulkan driver, to wait for these resources).
// For example, Fuchsia's Vulkan driver allows an zx::event to be obtained
// from a VkSemaphore. This allows a Scenic client to submit a Vulkan command
// buffer to generate images/meshes/etc., and instructing Vulkan to signal a
// VkSemaphore when it is done. By inserting the zx::event corresponding to
// this semaphore into |acquire_fences|, the client allows Scenic to submit work
// to the Vulkan driver without waiting on the CPU for the event to be
// signalled.
// |release_fences| is a list of events that will be signalled by Scenic when
// the updated session state has been fully committed: future frames will be
// rendered using this state, and all frames generated using previous session
// states have been fully-rendered and presented to the display.
// Together, |acquire_fences| and |release_fences| are intended to allow clients
// to implement strategies such as double-buffering. For example, a client
// might do the following in the Scenic subsystem:
// 1) create two Image with resource IDs #1 and #2.
// 2) create two Materials with resource IDs #3 and #4, which respectively
// use Images #1 and #2 as their texture.
// 3) create a tree of Nodes and attach them to the scene.
// 4) set one of the nodes above, say #5, to use Material #3.
// 5) submit a Vulkan command-buffer which renders into Image #1, and
// will signal a VkSemaphore.
// 6) call Present() with one acquire-fence (obtained from the VkSemaphore
// above) and one newly-created release-fence.
// After the steps above, Scenic will use the committed session state to render
// frames whenever necessary. When the client wants to display something
// different than Image #1, it would do something similar to steps 4) to 6):
// 7) set Node #5 to use Material #4.
// 8) submit a Vulkan command-buffer which renders into Image #1, and
// will signal a VkSemaphore.
// 9) call Present() with one acquire-fence (obtained from the VkSemaphore
// above) and one newly-created release-fence.
// Finally, to continually draw new content, the client could repeat steps
// 4) to 9), with one important difference: step 5) must wait on the event
// signalled by step 9). Otherwise, it might render into Image #1 while that
// image is still being used by Scenic to render a frame. Similarly, step 8)
// must wait on the event signalled by step 6).
// The scenario described above uses one acquire-fence and one release-fence,
// but it is easy to imagine cases that require more. For example, in addition
// to using Vulkan to render into Images #1 and #2, the client might also
// upload other resources to Vulkan on a different VkQueue, which would
// would signal a separate semaphore, and therefore require an additional
// acquire-fence.
// Note: |acquire_fences| and |release_fences| are only necessary to synchronize
// access to memory (and other external resources). Any modification to
// resources made via the Session API are automatically synchronized.
// TODO(SCN-400): document invariants that apply to |presentation_info|. Is it
// strong enough to guarantee that receiving the response means that all
// previously-enqueued Commands have been applied? Or does it need to be stronger,
// e.g. that all frames based on previous presentations are completely done,
// and subsequent frames will be rendered based on the most recent presented
// content?
Present(uint64 presentation_time,
vector<handle<event>> acquire_fences, vector<handle<event>> release_fences)
-> (fuchsia.images.PresentationInfo presentation_info);
// Set an optional debug name for the session. The debug name will be
// output in things such as logging and trace events.
SetDebugName(string debug_name);
// Listens for events which occur within the session.
protocol SessionListener {
// Called when an error has occurred and the session will be torn down.
OnScenicError(string error);
// Called to deliver a batch of one or more events to the listener.
// Use |SetEventMaskCmd| to enable event delivery for a resource.
OnScenicEvent(vector<Event> events);