blob: 6c8695bdd8d923a7939f01348e7d5716eba03f71 [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.images;
/// ImagePipe is a mechanism for streaming shared images between a producer
/// and a consumer which may be running in different processes.
/// Conceptually, the image pipe maintains a table of image resources supplied
/// by the producer into which graphical content may be stored as well as a
/// presentation queue containing a sequence of images which the producer has
/// asked the consumer to present.
/// The presentation queue is initially empty.
/// Each entry in the presentation queue consists of an image together with a
/// pair of optional synchronization fences:
/// - Acquire fence: signaled by the producer when the image is ready to be consumed
/// - Release fence: signaled by the consumer when the image is free to be freed or
/// modified by the producer
/// The producer performs the following sequence of steps to present content:
/// - Allocate and add some number of images (often 2 or 3) to the image pipe
/// to establish a pool using `AddImage()`.
/// - Obtain the next available image from the pool.
/// - Ask the consumer to enqueue an image for presentation and provide fences
/// using `PresentImage()`.
/// - Start rendering the image.
/// - Signal the image's acquire fence when rendering is complete.
/// - Loop to present more image, listen for signals on release fences to recycle
/// images back into the pool.
/// The consumer performs the following sequence of steps for each image which
/// is enqueued in the presentation queue:
/// - Await signals on the image's acquire fence.
/// - If the fence wait cannot be satisfied or if some other error is detected,
/// close the image pipe.
/// Otherwise, begin presenting the image's content.
/// - Retire the previously presented image (if any) from the presentation queue
/// and signal its release fence when no longer needed.
/// - Continue presenting the same image until the next one is ready. Loop.
/// If the producer wants to close the image pipe, it should:
/// - Close its side of the connection.
/// - Wait on all release fences for buffers that it has submitted with
/// `PresentImage()`.
/// - Proceed with resource cleanup.
/// When the consumer detects the image pipe has closed, it should:
/// - Stop using/presenting any images from the pipe.
/// - Unmap all VMOs associated with the images in the pipe.
/// - Close all handles to the VMOs.
/// - Signal all release fences for presented and queued buffers.
/// - Close all handles to fences.
/// - Close its side of the connection.
/// When either party detects that a fence has been abandoned (remotely closed
/// without being signaled) it should assume that the associated image is in
/// an indeterminate state. This will typically happen when the other party
/// (or one of its delegates) has crashed. The safest course of action is to
/// close the image pipe, release all resources which were shared with the
/// other party, and re-establish the connection to recover.
protocol ImagePipe {
/// Adds an image resource to image pipe.
/// The `memory` is the handle of a memory object which contains the image
/// data. It is valid to create multiple images backed by the same memory
/// object; they may even overlap. Consumers must detect this and handle
/// it accordingly. The `offset_bytes` indicates the offset within the
/// memory object at which the image data begins. The `size_bytes`
/// indicates the amount of memory from `memory` that should be utilized.
/// The type of memory stored in the VMO is `memory_type` (e.g. GPU memory,
/// host memory).
/// The following errors will cause the connection to be closed:
/// - `image_id` is already registered
/// - `image_info` represents a format not supported by the consumer
/// - `memory` is not a handle for a readable VMO
/// - the image data expected at `offset_bytes` according to the `image_info`
/// exceeds the memory object's bounds
AddImage(uint32 image_id, ImageInfo image_info,
handle<vmo> memory, uint64 offset_bytes, uint64 size_bytes, MemoryType memory_type);
/// Removes an image resource from the pipe.
/// The `image_id` is detached from the image resource and is free to be
/// reused to add a new image resource.
/// Removing an image from the image pipe does not affect the presentation
/// queue or the currently presented image.
/// The producer must wait for all release fences associated with the image to
/// be signaled before freeing or modifying the underlying memory object since
/// the image may still be in use in the presentation queue.
/// The following errors will cause the connection to be closed:
/// - `image_id` does not reference a currently registered image resource
RemoveImage(uint32 image_id);
/// Enqueues the specified image for presentation by the consumer.
/// The `acquire_fences` are a set of fences which must all be signaled by the
/// producer before the consumer presents the image.
/// The `release_fences` are set of fences which must all be signaled by the
/// consumer before it is safe for the producer to free or modify the image.
/// `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.
/// `presentation_info` returns timing information about the submitted frame
/// and future frames (see presentation_info.fidl).
/// The following errors will cause the connection to be closed:
/// - `image_id` does not reference a currently registered image resource
PresentImage(uint32 image_id, uint64 presentation_time,
vector<handle<event>> acquire_fences, vector<handle<event>> release_fences)
-> (PresentationInfo presentation_info);