PROTOCOLS
Scenic
Defined in fuchsia.ui.scenic/scenic.fidl
CreateSession
Create a new Session, which is the primary way to interact with Scenic.
Request
| Name | Type |
|---|---|
session |
server_end:Session
|
listener |
client_end:SessionListener?
|
CreateSession2
Create a new Session, which is the primary way to interact with Scenic.
In this variant, the caller may register a request for focus management.
The view_focuser's client is coupled to the requested session, and
this coupling acts as a security boundary: the ViewRef used as the basis
for authority by view_focuser must come from session.
Request
| Name | Type |
|---|---|
session |
server_end:Session
|
listener |
client_end:SessionListener?
|
view_focuser |
server_end:fuchsia.ui.views/Focuser?
|
CreateSessionT
Create a new Session, which is the primary way to interact with Scenic.
In this variant, the caller may submit a combination of protocols that make sense for it. The Session protocol is the only required protocol. The SessionEndpoints table may be extended with more protocol fields, but these extensions should retain ABI and API compatibility with existing (pre-compiled) clients.
The response acknowledges the request to create a Session, but actual creation may happen later.
Request
| Name | Type |
|---|---|
endpoints |
SessionEndpoints
|
Response
<EMPTY>
GetDisplayInfo
Get information about the Scenic's primary display.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
info |
fuchsia.ui.gfx/DisplayInfo
|
GetDisplayOwnershipEvent
Gets an event signaled with displayOwnedSignal or displayNotOwnedSignal when display ownership changes.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
ownership_event |
handle<event>
|
TakeScreenshot
Take a screenshot and return the data in img_data. img_data will
not contain BGRA data if success is false.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
img_data |
ScreenshotData
|
success |
bool
|
UsesFlatland
Returns whether the clients should use fuchsia.ui.composition/Flatland protocol to interact with Scenic instead.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
flatland_enabled |
bool
|
Session
Defined in fuchsia.ui.scenic/session.fidl
Client use Sessions to interact with a Scenic instance by enqueuing commands that create or modify resources.
DeregisterBufferCollection
Deregisters the BufferCollection previously registered with the buffer_id and sets it
to be garbage collected as soon as it is no longer referenced by any resources.
Only buffer_id that have been previously registered and not yet deregistered are valid.
Request
| Name | Type |
|---|---|
buffer_id |
uint32
|
Enqueue
Request
| Name | Type |
|---|---|
cmds |
vector<Command>
|
OnFramePresented
This event is fired whenever a set of one or more Present2s are presented simultaenously, and are therefore no longer in flight.
Response
| Name | Type |
|---|---|
frame_presented_info |
fuchsia.scenic.scheduling/FramePresentedInfo
|
Present
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.
SCHEDULING PRESENTATION
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.
SYNCHRONIZATION
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:
- create two Image with resource IDs #1 and #2.
- create two Materials with resource IDs #3 and #4, which respectively use Images #1 and #2 as their texture.
- create a tree of Nodes and attach them to the scene.
- set one of the nodes above, say #5, to use Material #3.
- submit a Vulkan command-buffer which renders into Image #1, and will signal a VkSemaphore.
- 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.
Request
| Name | Type |
|---|---|
presentation_time |
uint64
|
acquire_fences |
vector<handle<event>>
|
release_fences |
vector<handle<event>>
|
Response
| Name | Type |
|---|---|
presentation_info |
fuchsia.images/PresentationInfo
|
Present2
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.
When a client calls Present2, they receive an immediate callback
consisting of the same information they would get as if they had called
RequestPresentationTimes with the equivalent
requested_prediction_span. See its documentation below for more
information, as Present2's functionality is a superset of it.
Then, when the commands flushed by Present2 make it to display, an
OnFramePresented event is fired. This event includes information
pertaining to all Present2s that had content that were part of that
frame.
Clients may only use one of Present/Present2 per Session. Switching between both is an error that will result in the Session being closed.
See Present2Args documentation above for more detailed information on
what arguments are passed in and their role.
Request
| Name | Type |
|---|---|
args |
Present2Args
|
Response
| Name | Type |
|---|---|
request_presentation_times_info |
fuchsia.scenic.scheduling/FuturePresentationTimes
|
RegisterBufferCollection
Registers BufferCollection referenced by the token and sets contraints on it.
It does not block on the buffers being allocated until content backed by one of the
collection's VMOs is created, e.g. an Image2.
A value of 0 for the buffer_id is invalid. All other values are valid as long as they
are not currently in use.
Request
| Name | Type |
|---|---|
buffer_id |
uint32
|
token |
client_end:fuchsia.sysmem/BufferCollectionToken
|
RequestPresentationTimes
Returns information about future presentation times, and their
respective latch points. Clients can use the returned information to
make informed scheduling decisions: if a client wants their frame to be
displayed at a given presentation_time, they should aim to have all
acquire_fences fired before the associated latch_point.
Scenic will attempt to return predictions that span a duration equal to
requested_prediction_span, up to a limit.
A value of 0 is guaranteed to give at least one future presentation info.
Request
| Name | Type |
|---|---|
requested_prediction_span |
zx/Duration
|
Response
| Name | Type |
|---|---|
request_presentation_times_info |
fuchsia.scenic.scheduling/FuturePresentationTimes
|
SetDebugName
Set an optional debug name for the session. The debug name will be output in things such as logging and trace events.
Request
| Name | Type |
|---|---|
debug_name |
string
|
SessionListener
Defined in fuchsia.ui.scenic/session.fidl
Listens for events which occur within the session.
OnScenicError
Called when an error has occurred and the session will be torn down.
Request
| Name | Type |
|---|---|
error |
string
|
OnScenicEvent
Called to deliver a batch of one or more events to the listener.
Use SetEventMaskCmd to enable event delivery for a resource.
Request
| Name | Type |
|---|---|
events |
vector<Event>
|
STRUCTS
ScreenshotData resource
Defined in fuchsia.ui.scenic/scenic.fidl
Scenic.TakeScreenshot() returns a raw BGRA formatted image in sRGB color space and with a non-linear transfer function in this struct.
| Field | Type | Description | Default |
|---|---|---|---|
info |
fuchsia.images/ImageInfo
|
No default | |
data |
fuchsia.mem/Buffer
|
No default |
TABLES
Present2Args resource
Defined in fuchsia.ui.scenic/session.fidl
Arguments passed into Present2(). Note that every argument is mandatory.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
requested_presentation_time |
zx/Time
|
Using a Using a Each rendered frame has a target presentation time. This is when Scenic
aims to have the frame presented to the user. Before rendering a frame,
the scene manager applies all enqueued operations associated with all
prior calls to Present2 whose |
2 |
acquire_fences |
vector<handle<event>>
|
Scenic will wait until all of a session's |
3 |
release_fences |
vector<handle<event>>
|
|
4 |
requested_prediction_span |
zx/Duration
|
|
SessionEndpoints resource
Defined in fuchsia.ui.scenic/scenic.fidl
The protocol endpoints used in creating a Scenic Session.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
session |
server_end:Session
|
Enqueue commands and present content. Required. |
2 |
session_listener |
client_end:SessionListener
|
Receive session-related events. Optional. |
3 |
view_focuser |
server_end:fuchsia.ui.views/Focuser
|
Change view focus, within the session view's subtree. Optional. |
4 |
view_ref_focused |
server_end:fuchsia.ui.views/ViewRefFocused
|
Learn when this session view receives or loses view focus. Optional. |
5 |
touch_source |
server_end:fuchsia.ui.pointer/TouchSource
|
Ask for touch events and negotiate for gesture ownership. Optional. |
6 |
mouse_source |
server_end:fuchsia.ui.pointer/MouseSource
|
Ask for mouse events. Optional. |
UNIONS
Command strict resource
Defined in fuchsia.ui.scenic/commands.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
gfx |
fuchsia.ui.gfx/Command
|
|
3 |
views |
fuchsia.ui.views/Command
|
Deprecated: 10
|
4 |
input |
fuchsia.ui.input/Command
|
Deprecated: 10
|
Event strict resource
Defined in fuchsia.ui.scenic/events.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
gfx |
fuchsia.ui.gfx/Event
|
|
2 |
input |
fuchsia.ui.input/InputEvent
|
Deprecated: 10
|
3 |
unhandled |
Command
|
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| displayNotOwnedSignal |
16777216
|
uint32 |
|
| displayOwnedSignal |
33554432
|
uint32 |