Project: /_project.yaml Book: /_book.yaml
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:
The producer performs the following sequence of steps to present content:
AddImage()
.PresentImage()
.The consumer performs the following sequence of steps for each image which is enqueued in the presentation queue:
If the producer wants to close the image pipe, it should:
PresentImage()
.When the consumer detects the image pipe has closed, it should:
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.
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 registeredimage_info
represents a format not supported by the consumermemory
is not a handle for a readable VMOoffset_bytes
according to the image_info
exceeds the memory object's boundsRemoves 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 resourceEnqueues 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 resourceDefined in fuchsia.images/image_pipe2.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:
The producer performs the following sequence of steps to present content:
AddImage()
.PresentImage()
.The consumer performs the following sequence of steps for each image which is enqueued in the presentation queue:
If the producer wants to close the image pipe, it should:
PresentImage()
.When the consumer detects the image pipe has closed, it should:
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.
Adds a BufferCollection resource to the image pipe.
The producer is expected to set constraints on this resource for images added via AddImage()
. The consumer can set its constraints on buffer_collection_token
before or after. Note that the buffers won’t be allocated until all BufferCollectionToken instances are used to set constraints, on both the producer and consumer side. See collection.fidl for details.
The following errors will cause the connection to be closed:
buffer_collection_id
is already registeredAdds an image resource to image pipe.
buffer_collection_id
refers to the BufferCollectionToken instance that is registered via AddBufferCollection()
. The underlying memory objects allocated are used to address to the image data. buffer_collection_id
refers to the index of the memory object allocated in BufferCollection.
image_format
specifiies image properties. coded_width
and coded_height
are used to set image dimensions.
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 following errors will cause the connection to be closed:
image_id
is already registeredbuffer_collection_id
refers to an unregistered BufferCollection.buffer_collection_index
points to a resource index out of the initialized BufferCollection boundsRemoves a BufferCollection resource from the pipe.
The buffer_collection_id
resource is detached as well as all Images that are associated with that BufferCollection. Leads to the same results as calling RemoveImage()
on all Images for buffer_collection_id
.
The producer must wait for all release fences associated with the Images 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:
buffer_collection_id
does not reference a currently registered BufferCollectionRemoves 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 resourceEnqueues 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 producer may decide not to signal acquire_fences
for an image. In that case, if a later image is enqueued and later image’s presentation_time
is reached, the consumer presents the later image when later image’s acquire_fences
are signaled. The consumer also signals earlier image’s release_fences
and removes it from the presentation queue. This sequence works as a cancellation mechanism.
The following errors will cause the connection to be closed:
image_id
does not reference a currently registered image resourceDefined 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:
The producer performs the following sequence of steps to present content:
AddImage()
.PresentImage()
.The consumer performs the following sequence of steps for each image which is enqueued in the presentation queue:
If the producer wants to close the image pipe, it should:
PresentImage()
.When the consumer detects the image pipe has closed, it should:
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.
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 registeredimage_info
represents a format not supported by the consumermemory
is not a handle for a readable VMOoffset_bytes
according to the image_info
exceeds the memory object's boundsRemoves 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 resourceEnqueues 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 resourceDefined in fuchsia.images/image_pipe2.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:
The producer performs the following sequence of steps to present content:
AddImage()
.PresentImage()
.The consumer performs the following sequence of steps for each image which is enqueued in the presentation queue:
If the producer wants to close the image pipe, it should:
PresentImage()
.When the consumer detects the image pipe has closed, it should:
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.
Adds a BufferCollection resource to the image pipe.
The producer is expected to set constraints on this resource for images added via AddImage()
. The consumer can set its constraints on buffer_collection_token
before or after. Note that the buffers won’t be allocated until all BufferCollectionToken instances are used to set constraints, on both the producer and consumer side. See collection.fidl for details.
The following errors will cause the connection to be closed:
buffer_collection_id
is already registeredAdds an image resource to image pipe.
buffer_collection_id
refers to the BufferCollectionToken instance that is registered via AddBufferCollection()
. The underlying memory objects allocated are used to address to the image data. buffer_collection_id
refers to the index of the memory object allocated in BufferCollection.
image_format
specifiies image properties. coded_width
and coded_height
are used to set image dimensions.
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 following errors will cause the connection to be closed:
image_id
is already registeredbuffer_collection_id
refers to an unregistered BufferCollection.buffer_collection_index
points to a resource index out of the initialized BufferCollection boundsRemoves a BufferCollection resource from the pipe.
The buffer_collection_id
resource is detached as well as all Images that are associated with that BufferCollection. Leads to the same results as calling RemoveImage()
on all Images for buffer_collection_id
.
The producer must wait for all release fences associated with the Images 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:
buffer_collection_id
does not reference a currently registered BufferCollectionRemoves 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 resourceEnqueues 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 producer may decide not to signal acquire_fences
for an image. In that case, if a later image is enqueued and later image’s presentation_time
is reached, the consumer presents the later image when later image’s acquire_fences
are signaled. The consumer also signals earlier image’s release_fences
and removes it from the presentation queue. This sequence works as a cancellation mechanism.
The following errors will cause the connection to be closed:
image_id
does not reference a currently registered image resourceDefined in fuchsia.images/encoded_image.fidl
Defined in fuchsia.images/image_info.fidl
Information about a graphical image (texture) including its format and size.
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.
This value increases monotonically with each new frame, typically in increments of the presentation_interval
.
This value is non-zero. It may vary from time to time, such as when changing display modes.
Defined in fuchsia.images/encoded_image.fidl
Defined in fuchsia.images/image_info.fidl
Information about a graphical image (texture) including its format and size.
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.
This value increases monotonically with each new frame, typically in increments of the presentation_interval
.
This value is non-zero. It may vary from time to time, such as when changing display modes.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixels are represented in the image buffer.
A 32-bit four-component unsigned integer format. Byte order: B, G, R, A (little-endian ARGB packed 32-bit word). Equivalent to Skia kBGRA_8888_SkColorType
color type. Equivalent to Zircon ARGB_8888
pixel format on little-endian arch.
4:2:2 (2x down-sampled UV horizontally; full res UV vertically)
A 32-bit component that contains information for 2 pixels: Byte order: Y1, U, Y2, V Unpacks to 2 RGB pixels, where RGB1 = func(Y1, U, V) and RGB2 = func(Y2, U, V) Equivalent to YUV422
4:2:0 (2x down-sampled UV in both directions)
Offset 0: 8 bit per pixel Y plane with bytes YYY. Offset height * stride: 8 bit UV data interleaved bytes as UVUVUV.
Y plane has line stride >= width.
In this context, both width and height are required to be even.
The UV data is separated into “lines”, with each “line” having same byte width as a line of Y data, and same “line” stride as Y data's line stride. The UV data has height / 2 “lines”.
In converting to RGB, the UV data gets up-scaled by 2x in both directions overall. This comment is intentionally silent on exactly how UV up-scaling phase/filtering/signal processing works, as it's a complicated topic that can vary by implementation, typically trading off speed and quality of the up-scaling. See comments in relevant conversion code for approach taken by any given convert path. The precise relative phase of the UV data is not presently conveyed.
Like I420, except with V and U swapped.
4:2:0 (2x down-sampled UV in both directions)
Offset 0: 8 bit per pixel Y plane with bytes YYY. Offset height * stride: 8 bit V data with uv_stride = stride / 2 Offset height * stride + uv_stride * height / 2: 8 bit U data with uv_stride = stride / 2
Y plane has line stride >= width.
Both width and height are required to be even.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixel color information should be interpreted.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixels are arranged in memory.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how alpha information should be interpreted.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Type: uint32
Defined in fuchsia.images/memory_type.fidl
Specifies the type of VMO's memory.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixels are represented in the image buffer.
A 32-bit four-component unsigned integer format. Byte order: B, G, R, A (little-endian ARGB packed 32-bit word). Equivalent to Skia kBGRA_8888_SkColorType
color type. Equivalent to Zircon ARGB_8888
pixel format on little-endian arch.
4:2:2 (2x down-sampled UV horizontally; full res UV vertically)
A 32-bit component that contains information for 2 pixels: Byte order: Y1, U, Y2, V Unpacks to 2 RGB pixels, where RGB1 = func(Y1, U, V) and RGB2 = func(Y2, U, V) Equivalent to YUV422
4:2:0 (2x down-sampled UV in both directions)
Offset 0: 8 bit per pixel Y plane with bytes YYY. Offset height * stride: 8 bit UV data interleaved bytes as UVUVUV.
Y plane has line stride >= width.
In this context, both width and height are required to be even.
The UV data is separated into “lines”, with each “line” having same byte width as a line of Y data, and same “line” stride as Y data's line stride. The UV data has height / 2 “lines”.
In converting to RGB, the UV data gets up-scaled by 2x in both directions overall. This comment is intentionally silent on exactly how UV up-scaling phase/filtering/signal processing works, as it's a complicated topic that can vary by implementation, typically trading off speed and quality of the up-scaling. See comments in relevant conversion code for approach taken by any given convert path. The precise relative phase of the UV data is not presently conveyed.
Like I420, except with V and U swapped.
4:2:0 (2x down-sampled UV in both directions)
Offset 0: 8 bit per pixel Y plane with bytes YYY. Offset height * stride: 8 bit V data with uv_stride = stride / 2 Offset height * stride + uv_stride * height / 2: 8 bit U data with uv_stride = stride / 2
Y plane has line stride >= width.
Both width and height are required to be even.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixel color information should be interpreted.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how pixels are arranged in memory.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Specifies how alpha information should be interpreted.
Type: uint32
Defined in fuchsia.images/image_info.fidl
Type: uint32
Defined in fuchsia.images/memory_type.fidl
Specifies the type of VMO's memory.