class ImagePipe2

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 BufferCollections to the image pipe to allow

consumer to set constraints.

- 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 memory objects associated with the images in the pipe.

- Close all BufferCollection resources.

- 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.