// 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);
};