fuchsia.images

PROTOCOLS

ImagePipe

Defined in fuchsia.images/image_pipe.fidl

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.

AddImage

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

Request

NameType
image_id uint32
image_info ImageInfo
memory handle<vmo>
offset_bytes uint64
size_bytes uint64
memory_type MemoryType

RemoveImage

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

Request

NameType
image_id uint32

PresentImage

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

Request

NameType
image_id uint32
presentation_time uint64
acquire_fences vector<event>
release_fences vector<event>

Response

NameType
presentation_info PresentationInfo

STRUCTS

EncodedImage

Defined in fuchsia.images/encoded_image.fidl

NameTypeDescriptionDefault
vmo handle<vmo> The vmo. No default
size uint64 The size of the image in the vmo in bytes. No default

ImageInfo

Defined in fuchsia.images/image_info.fidl

Information about a graphical image (texture) including its format and size.

NameTypeDescriptionDefault
transform Transform Specifies if the image should be mirrored before displaying. Transform.NORMAL
width uint32 The width and height of the image in pixels. No default
height uint32 No default
stride uint32 The number of bytes per row in the image buffer. No default
pixel_format PixelFormat The pixel format of the image. PixelFormat.BGRA_8
color_space ColorSpace The pixel color space. ColorSpace.SRGB
tiling Tiling The pixel arrangement in memory. Tiling.LINEAR
alpha_format AlphaFormat Specifies the interpretion of the alpha channel, if one exists. AlphaFormat.OPAQUE

PresentationInfo

Defined in fuchsia.images/presentation_info.fidl

Information returned by methods such as ImagePipe.PresentImage() and Session.Present(), when the consumer begins preparing the first frame which includes the presented content.

NameTypeDescriptionDefault
presentation_time uint64 The actual time at which the enqueued operations are anticipated to take visible effect, expressed in nanoseconds in the `CLOCK_MONOTONIC` timebase. This value increases monotonically with each new frame, typically in increments of the `presentation_interval`. No default
presentation_interval uint64 The nominal amount of time which is anticipated to elapse between successively presented frames, expressed in nanoseconds. When rendering to a display, the interval will typically be derived from the display refresh rate. This value is non-zero. It may vary from time to time, such as when changing display modes. No default

ENUMS

PixelFormat

Type: uint32

Defined in fuchsia.images/image_info.fidl

Specifies how pixels are represented in the image buffer.

NameValueDescription
BGRA_8 0
YUY2 1
NV12 2
YV12 3

ColorSpace

Type: uint32

Defined in fuchsia.images/image_info.fidl

Specifies how pixel color information should be interpreted.

NameValueDescription
SRGB 0

Tiling

Type: uint32

Defined in fuchsia.images/image_info.fidl

Specifies how pixels are arranged in memory.

NameValueDescription
LINEAR 0
GPU_OPTIMAL 1

AlphaFormat

Type: uint32

Defined in fuchsia.images/image_info.fidl

Specifies how alpha information should be interpreted.

NameValueDescription
OPAQUE 0
PREMULTIPLIED 1
NON_PREMULTIPLIED 2

Transform

Type: uint32

Defined in fuchsia.images/image_info.fidl

NameValueDescription
NORMAL 0
FLIP_HORIZONTAL 1
FLIP_VERTICAL 2
FLIP_VERTICAL_AND_HORIZONTAL 3

MemoryType

Type: uint32

Defined in fuchsia.images/memory_type.fidl

Specifies the type of VMO's memory.

NameValueDescription
HOST_MEMORY 0
VK_DEVICE_MEMORY 1