class ImageFormatConstraints

Returns whether no field is set.

The [`fuchsia.images2/PixelFormat`] for which the following constraints

apply.

The `pixel_format` and `pixel_format_modifier` fields together are

treated by the server as one additional `pixel_format_and_modifiers`

entry.

A participant may have more than one

[`fuchsia.sysmem2/PixelFormatAndModifier`] that's supported.

* If image constraints are the same for different

`PixelFormatAndModifier`s, the participant may list additional

`PixelFormatAndModifier`s for which the constraints apply in the

`pixel_format_and_modifiers` field. This reduces the overall number of

`ImageFormatConstraints` that need to be sent, without changing the

meaning (vs for example sending a bunch of separate

`ImageFormatConstraints` that only differ by the `pixel_format` and

`pixel_format_modifier` which overall specify the same list of

`PixelFormatAndModifier`s).

* If image constraints differ for different `PixelFormatAndModifier`s,

the participant can convey this using a separate

`ImageFormatConstraints` entry in `image_format_constraints` for each

set of `PixelFormatAndModifier`s that have different image

constraints.

* It's ok for a participant to have two `image_format_constraints`

entries that only differ in their pixel_format_and_modifiers, but this

is isn't the most compact way to represent that situation since the

two entries could be combined by specifying two

`PixelFormatAndModifier`s within a single `ImageFormatConstraints`.

It's not uncommon for the other fields of `ImageFormatConstraints` to

vary by `pixel_format` or by `pixel_format_modifier` - for example for a

linear format to support smaller max size than a tiled format.

See also

[`fuchsia.sysmem2/ImageFormatConstraints.pixel_format_and_modifiers`].

Thie field must be set to a value other than

[`fuchsia.images2/PixelFormat.INVALID`] unless

`pixel_format_and_modifiers` is non-empty. In other words, there must be

at least one `PixelFormatAndModifier` per `ImageFormatConstraints`. If

`pixel_format_modifier` is set, this field must also be set.

The participant can specify [`fuchsia.images2/PixelFormat.DO_NOT_CARE`]

if the participant needs to specify `ImageFormatConstraints` without

constraining the `pixel_format`.

The [`fuchsia.images2/PixelFormat`] for which the following constraints

apply.

The `pixel_format` and `pixel_format_modifier` fields together are

treated by the server as one additional `pixel_format_and_modifiers`

entry.

A participant may have more than one

[`fuchsia.sysmem2/PixelFormatAndModifier`] that's supported.

* If image constraints are the same for different

`PixelFormatAndModifier`s, the participant may list additional

`PixelFormatAndModifier`s for which the constraints apply in the

`pixel_format_and_modifiers` field. This reduces the overall number of

`ImageFormatConstraints` that need to be sent, without changing the

meaning (vs for example sending a bunch of separate

`ImageFormatConstraints` that only differ by the `pixel_format` and

`pixel_format_modifier` which overall specify the same list of

`PixelFormatAndModifier`s).

* If image constraints differ for different `PixelFormatAndModifier`s,

the participant can convey this using a separate

`ImageFormatConstraints` entry in `image_format_constraints` for each

set of `PixelFormatAndModifier`s that have different image

constraints.

* It's ok for a participant to have two `image_format_constraints`

entries that only differ in their pixel_format_and_modifiers, but this

is isn't the most compact way to represent that situation since the

two entries could be combined by specifying two

`PixelFormatAndModifier`s within a single `ImageFormatConstraints`.

It's not uncommon for the other fields of `ImageFormatConstraints` to

vary by `pixel_format` or by `pixel_format_modifier` - for example for a

linear format to support smaller max size than a tiled format.

See also

[`fuchsia.sysmem2/ImageFormatConstraints.pixel_format_and_modifiers`].

Thie field must be set to a value other than

[`fuchsia.images2/PixelFormat.INVALID`] unless

`pixel_format_and_modifiers` is non-empty. In other words, there must be

at least one `PixelFormatAndModifier` per `ImageFormatConstraints`. If

`pixel_format_modifier` is set, this field must also be set.

The participant can specify [`fuchsia.images2/PixelFormat.DO_NOT_CARE`]

if the participant needs to specify `ImageFormatConstraints` without

constraining the `pixel_format`.

The pixel format modifier for which the following constraints apply.

The `pixel_format` and `pixel_format_modifier` fields together are

treated by the server as one additional `pixel_format_and_modifiers`

entry.

This is a [`fuchsia.images2/PixelFormatModifier`] that's acceptable to

the participant in combination with the `pixel_format`.

See also `pixel_format_and_modifiers`.

If `pixel_format` is set but `pixel_format_modifier` is un-set, the

default depends on other fields:

* If `pixel_format` is [`fuchsia.images2/PixelFormat.DO_NOT_CARE`], the

pixel format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`].

* else if `BufferCollectionConstraints.usage` isn't `NONE`, the pixel

format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.LINEAR`].

* else the pixel format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`].

The pixel format modifier for which the following constraints apply.

The `pixel_format` and `pixel_format_modifier` fields together are

treated by the server as one additional `pixel_format_and_modifiers`

entry.

This is a [`fuchsia.images2/PixelFormatModifier`] that's acceptable to

the participant in combination with the `pixel_format`.

See also `pixel_format_and_modifiers`.

If `pixel_format` is set but `pixel_format_modifier` is un-set, the

default depends on other fields:

* If `pixel_format` is [`fuchsia.images2/PixelFormat.DO_NOT_CARE`], the

pixel format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`].

* else if `BufferCollectionConstraints.usage` isn't `NONE`, the pixel

format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.LINEAR`].

* else the pixel format modifier is implicitly

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`].

Empty is an error. Duplicate entries are an error. Arbitrary ordering is

not an error.

The client can specify a single entry

[`fuchsia.sysmem2/ColorSpace.DO_NOT_CARE`] if the client doesn't want to

constrain which `ColorSpace` is chosen. At least one participant must

specify at least one `ColorSpace` value other than

`ColorSpace.DO_NOT_CARE`, or allocation will fail.

Empty is an error. Duplicate entries are an error. Arbitrary ordering is

not an error.

The client can specify a single entry

[`fuchsia.sysmem2/ColorSpace.DO_NOT_CARE`] if the client doesn't want to

constrain which `ColorSpace` is chosen. At least one participant must

specify at least one `ColorSpace` value other than

`ColorSpace.DO_NOT_CARE`, or allocation will fail.

Minimum permitted size in pixels.

For example a video decoder participant may set this field to the

minimum size that might potentially be specified by a stream. In

contrast, `required_min_size` would be set to the current size specified

by the stream. While `min_size` aggregates by taking the max,

`required_min_size` aggregates by taking the min.

When sending to sysmem, this field can be un-set if the participant is

prepared to deal with the smallest possible non-zero image layout

limited only by the constraints implicitly imposed by the `pixel_format`

and `pixel_format_modifier`. Or this field can be set to the actual

minimum size the participant can handle.

Producers should set `min_size` and set both width and height to the

actual non-zero smallest width and height that the producer might

generate. For example, a video decoder can set the size of a single

macroblock here.

When receiving from sysmem, this field will always be set, and neither

width nor height will be 0, because at least one participant must

specify a non-zero minimum size (where both width and height aren't

zero).

See also `required_min_size`.

Minimum permitted size in pixels.

For example a video decoder participant may set this field to the

minimum size that might potentially be specified by a stream. In

contrast, `required_min_size` would be set to the current size specified

by the stream. While `min_size` aggregates by taking the max,

`required_min_size` aggregates by taking the min.

When sending to sysmem, this field can be un-set if the participant is

prepared to deal with the smallest possible non-zero image layout

limited only by the constraints implicitly imposed by the `pixel_format`

and `pixel_format_modifier`. Or this field can be set to the actual

minimum size the participant can handle.

Producers should set `min_size` and set both width and height to the

actual non-zero smallest width and height that the producer might

generate. For example, a video decoder can set the size of a single

macroblock here.

When receiving from sysmem, this field will always be set, and neither

width nor height will be 0, because at least one participant must

specify a non-zero minimum size (where both width and height aren't

zero).

See also `required_min_size`.

Maximum size in pixels. For example Scenic may set this field (directly

or via sub-participants) to the maximum size that can be composited.

Sending to sysmem, un-set is treated as 0xFFFFFFFF, 0xFFFFFFFF.

Receiving from sysmem, this field will always be set. For width and

height separately, if there is no enforced max, that sub-field will be

0xFFFFFFFF.

See also `required_max_size`.

Maximum size in pixels. For example Scenic may set this field (directly

or via sub-participants) to the maximum size that can be composited.

Sending to sysmem, un-set is treated as 0xFFFFFFFF, 0xFFFFFFFF.

Receiving from sysmem, this field will always be set. For width and

height separately, if there is no enforced max, that sub-field will be

0xFFFFFFFF.

See also `required_max_size`.

The minimum number of bytes per row, including any padding beyond the

last image data in a row.

This is sometimes called the "stride in bytes" or the "line to line

offset". For single-plane formats, this is the number of bytes per row

of pixels. For multi-plane formats, this is the number of bytes per row

of samples in plane 0 (for example, the number of bytes per row of luma

samples in the case of a multi-plane YUV format). For multi-plane

formats, the bytes per row in planes other than plane 0 is format

specific, but always a specific relationship to the plane 0 bytes per

row.

When sending `ImageFormatConstraints` to sysmem, setting this field is

optional. Not setting this field is recommended unless the participant

needs to force the `bytes_per_row` to be larger than the minimum value

implied by `min_size.width`, the "stride bytes per width pixel" of the

`pixel_format` plus `pixel_format_modifier` (see also

`ImageFormatStrideBytesPerWidthPixel`), and `bytes_per_row_divisor`.

When this structure is received from sysmem, this field will always be

set (when the parent structure is present), and will always be at least

the value implied by `min_size.width`, the "stride bytes per width

pixel" of the `pixel_format` plus `pixel_format_modifier`, and

`bytes_per_row_divisor`.

Some producer participants may prefer to simply set

`ImageFormat.bytes_per_row` to

`ImageFormatConstraints.min_bytes_per_row` since sysmem is guaranteeing

that `min_bytes_per_row` is compatible with an image of width

`min_size.width`. However, producer participants that need to have

`size.width` > `min_size.width` can get a corresponding

`min_bytes_per_row` from `ImageFormatMinimumRowBytes` (in C++), or can

just calculate the `bytes_per_row` directly.

The minimum number of bytes per row, including any padding beyond the

last image data in a row.

This is sometimes called the "stride in bytes" or the "line to line

offset". For single-plane formats, this is the number of bytes per row

of pixels. For multi-plane formats, this is the number of bytes per row

of samples in plane 0 (for example, the number of bytes per row of luma

samples in the case of a multi-plane YUV format). For multi-plane

formats, the bytes per row in planes other than plane 0 is format

specific, but always a specific relationship to the plane 0 bytes per

row.

When sending `ImageFormatConstraints` to sysmem, setting this field is

optional. Not setting this field is recommended unless the participant

needs to force the `bytes_per_row` to be larger than the minimum value

implied by `min_size.width`, the "stride bytes per width pixel" of the

`pixel_format` plus `pixel_format_modifier` (see also

`ImageFormatStrideBytesPerWidthPixel`), and `bytes_per_row_divisor`.

When this structure is received from sysmem, this field will always be

set (when the parent structure is present), and will always be at least

the value implied by `min_size.width`, the "stride bytes per width

pixel" of the `pixel_format` plus `pixel_format_modifier`, and

`bytes_per_row_divisor`.

Some producer participants may prefer to simply set

`ImageFormat.bytes_per_row` to

`ImageFormatConstraints.min_bytes_per_row` since sysmem is guaranteeing

that `min_bytes_per_row` is compatible with an image of width

`min_size.width`. However, producer participants that need to have

`size.width` > `min_size.width` can get a corresponding

`min_bytes_per_row` from `ImageFormatMinimumRowBytes` (in C++), or can

just calculate the `bytes_per_row` directly.

The maximum number of bytes per row, including any padding beyond the

last image data in a row.

When sent to sysmem, must be >= the value implied by `max_size.width`,

"stride bytes per width pixel", and `bytes_per_row_divisor`, or

constraints aggregation will fail. Un-set means the participant doesn't

need/want to set a strict max.

Sending to sysmem, un-set is treated as 0xFFFFFFFF.

When received from sysmem, this field will always be set. If the max is

effectively infinite, the value will be 0xFFFFFFFF (not zero).

The maximum number of bytes per row, including any padding beyond the

last image data in a row.

When sent to sysmem, must be >= the value implied by `max_size.width`,

"stride bytes per width pixel", and `bytes_per_row_divisor`, or

constraints aggregation will fail. Un-set means the participant doesn't

need/want to set a strict max.

Sending to sysmem, un-set is treated as 0xFFFFFFFF.

When received from sysmem, this field will always be set. If the max is

effectively infinite, the value will be 0xFFFFFFFF (not zero).

The maximum number of pixels.

The max image area in pixels is limited indirectly via

[`fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes`] and the

resulting [`fuchsia.sysmem/BufferSettings.size_bytes`], and can also be

enforced directly via this field.

In contrast to the [`fuchsia.sysmem2/ImageFormatConstraints.max_size`]

field which limits width and height separately, this field limits the

total number of pixels.

In contrast to

[`fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes`], this field

doesn't limit the number of non-pixel padding bytes after each row of

pixels, and doesn't limit the number of non-pixel bytes in the case of

tiled `pixel_format_modifier`.

Very narrow or very short image aspect ratios can have worse performance

per pixel in comparison to more typical aspect ratios. Padding and/or

memory bandwidth overheads tend to increase for extreme aspect ratios.

Participants can indicate lack of support for very narrow or very short

dimensions using ['fuchsia.sysmem/ImageFormatConstraints.min_size`].

Sending to sysmem, un-set is treated as 0xFFFFFFFF.

Receiving from sysmem, this field will always be set, and can be set to

0xFFFFFFFF.

The maximum number of pixels.

The max image area in pixels is limited indirectly via

[`fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes`] and the

resulting [`fuchsia.sysmem/BufferSettings.size_bytes`], and can also be

enforced directly via this field.

In contrast to the [`fuchsia.sysmem2/ImageFormatConstraints.max_size`]

field which limits width and height separately, this field limits the

total number of pixels.

In contrast to

[`fuchsia.sysmem/BufferMemoryConstraints.max_size_bytes`], this field

doesn't limit the number of non-pixel padding bytes after each row of

pixels, and doesn't limit the number of non-pixel bytes in the case of

tiled `pixel_format_modifier`.

Very narrow or very short image aspect ratios can have worse performance

per pixel in comparison to more typical aspect ratios. Padding and/or

memory bandwidth overheads tend to increase for extreme aspect ratios.

Participants can indicate lack of support for very narrow or very short

dimensions using ['fuchsia.sysmem/ImageFormatConstraints.min_size`].

Sending to sysmem, un-set is treated as 0xFFFFFFFF.

Receiving from sysmem, this field will always be set, and can be set to

0xFFFFFFFF.

Alignment requirements on the image `size`.

* `size.width % size_alignment.width` must be 0.

* `size.height % size_alignment.height` must be 0.

Both `size_alignment.width` and `size_alignment.height` must be non-zero

and a power of 2.

Un-set is treated as 1, 1.

Alignment requirements on `display_rect`.

* `display_rect.x % display_rect_alignment.width` must be 0.

* `display_rect.y % display_rect_alignment.height` must be 0.

* `display_rect.width % display_rect_alignment.width` must be 0.

* `display_rect.height % display_rect_alignment.height` must be 0.

Un-set is treated as 1, 1.

Alignment requirements on `display_rect`.

* `display_rect.x % display_rect_alignment.width` must be 0.

* `display_rect.y % display_rect_alignment.height` must be 0.

* `display_rect.width % display_rect_alignment.width` must be 0.

* `display_rect.height % display_rect_alignment.height` must be 0.

Un-set is treated as 1, 1.

These fields can be used to ensure the aggregated constraints have

`min_size` and `max_size` such that both `required_min_size` and

`required_max_size` (and anything in between that satisfies alignment

requirements) are permitted values of `ImageFormat.size`.

For example, a producer video decoder doesn't want to constrain the

allowed `ImageFormat.size`, as a compressed stream can change dimensions

mid-stream, but the producer video decoder needs to ensure that the

aggregated constraints allow for at least the current dimensions of

uncompressed frames at the current position in the stream.

As another example, an initiator that's intending to decode video may

know what the maximum expected size of frames in the stream(s) can be,

so by setting `required_max_size`, can ensure that the allocated buffers

are large enough to support that max `size`. In addition on successful

allocation the initiator also knows that the consumer participants are

ok with receiving up to that max `size`.

It's much more common for a producer or initiator to set these fields

than for a consumer to set these fields.

While `min_size` and `max_size` aggregate by effectively taking the

intersection, the `required_min_size` and `required_max_size` aggregate

by effectively taking the union.

This field aggregates by taking the min per component, and

required_max_size aggregates by taking the max per component. In

addition the aggregated required_max_size is included in the aggregated

required_max_size_list.

Un-set is treated as 0xFFFFFFFF, 0xFFFFFFFF.

These fields can be used to ensure the aggregated constraints have

`min_size` and `max_size` such that both `required_min_size` and

`required_max_size` (and anything in between that satisfies alignment

requirements) are permitted values of `ImageFormat.size`.

For example, a producer video decoder doesn't want to constrain the

allowed `ImageFormat.size`, as a compressed stream can change dimensions

mid-stream, but the producer video decoder needs to ensure that the

aggregated constraints allow for at least the current dimensions of

uncompressed frames at the current position in the stream.

As another example, an initiator that's intending to decode video may

know what the maximum expected size of frames in the stream(s) can be,

so by setting `required_max_size`, can ensure that the allocated buffers

are large enough to support that max `size`. In addition on successful

allocation the initiator also knows that the consumer participants are

ok with receiving up to that max `size`.

It's much more common for a producer or initiator to set these fields

than for a consumer to set these fields.

While `min_size` and `max_size` aggregate by effectively taking the

intersection, the `required_min_size` and `required_max_size` aggregate

by effectively taking the union.

This field aggregates by taking the min per component, and

required_max_size aggregates by taking the max per component. In

addition the aggregated required_max_size is included in the aggregated

required_max_size_list.

Un-set is treated as 0xFFFFFFFF, 0xFFFFFFFF.

This field is deprecated. The replacement is required_max_size_list.

See also `required_min_size` and `required_max_size_list`. Un-set is

treated as 0, 0.

In the BufferCollectionInfo returned from sysmem, this field has the max

across all participants' required_max_size fields, for width and height

separately. In addition, the allocated buffer is large enough to store

an image that is this max-of-all-widths by max-of-all-heights. This has

the potential to allocate buffers that are larger than necessary, for

example if the participant is trying to make sure the buffer can store

both landscape and portrait images. In contrast, required_max_size_list

allows listing those separately so they can be handled better by the

server. See required_max_size_list and please switch to that field.

When this field is set, the provided size is aggregated by taking max of

across all participants' required_max_size fields, and that aggregated

result is put in this field in the BufferCollectionInfo from the server,

and is also treated as an additional item in the aggregated

required_max_size_list (even if that field is not set by any client).

See required_max_size_list. This behavior is for maintaining backward

compatibility for clients using required_max_size before it was

deprecated, and for overall compatibility with required_max_size_list,

but this behavior is itself deprecated as well. Please switch to only

using required_max_size_list.

Please don't add additional usages of this field.

This field is deprecated. The replacement is required_max_size_list.

See also `required_min_size` and `required_max_size_list`. Un-set is

treated as 0, 0.

In the BufferCollectionInfo returned from sysmem, this field has the max

across all participants' required_max_size fields, for width and height

separately. In addition, the allocated buffer is large enough to store

an image that is this max-of-all-widths by max-of-all-heights. This has

the potential to allocate buffers that are larger than necessary, for

example if the participant is trying to make sure the buffer can store

both landscape and portrait images. In contrast, required_max_size_list

allows listing those separately so they can be handled better by the

server. See required_max_size_list and please switch to that field.

When this field is set, the provided size is aggregated by taking max of

across all participants' required_max_size fields, and that aggregated

result is put in this field in the BufferCollectionInfo from the server,

and is also treated as an additional item in the aggregated

required_max_size_list (even if that field is not set by any client).

See required_max_size_list. This behavior is for maintaining backward

compatibility for clients using required_max_size before it was

deprecated, and for overall compatibility with required_max_size_list,

but this behavior is itself deprecated as well. Please switch to only

using required_max_size_list.

Please don't add additional usages of this field.

`fuchsia_images2.ImageFormat.bytes_per_row % bytes_per_row_divisor` must

be 0. Un-set is treated as 1.

Prefer to use `require_bytes_per_row_at_pixel_boundary` when the intent

is to ensure that `bytes_per_row' will be a multiple of the pixel size

in bytes.

Prefer to use `size_alignment.width` when the intent is to ensure that

the width in pixels is aligned. In contrast, this field can specify that

the "stride in bytes" (byte offset from start of image to start of row n

minus byte offset from start of image to start of row n-1, with result

in bytes) needs to be aligned to the specified number of bytes. For

example, when `PixelFormat.BGR24` (24 bit color; 3 bytes per pixel) is

used, it's not uncommon for a participant to need each row of pixels to

start at a 4 byte aligned offset from the start of the image, which can

imply some padding bytes at the end of each row of pixels, before the

start of the next row of pixels.

While any value of `bytes_per_row_divisor` could instead be enforced by

setting `size_alignment.width` to the least-common-multiple of the

"stride bytes per width pixel" and the stride alignment requirement,

enforcing the stride alignment requirement that way can lead to more

padding than necessary (implying larger buffer than necessary), and can

also result in a "fake" `size.width` values that other participants

would need to care about; this field exists to avoid that situation.

Instead, the stride alignment requirement in bytes is specified directly

here.

`fuchsia_images2.ImageFormat.bytes_per_row % bytes_per_row_divisor` must

be 0. Un-set is treated as 1.

Prefer to use `require_bytes_per_row_at_pixel_boundary` when the intent

is to ensure that `bytes_per_row' will be a multiple of the pixel size

in bytes.

Prefer to use `size_alignment.width` when the intent is to ensure that

the width in pixels is aligned. In contrast, this field can specify that

the "stride in bytes" (byte offset from start of image to start of row n

minus byte offset from start of image to start of row n-1, with result

in bytes) needs to be aligned to the specified number of bytes. For

example, when `PixelFormat.BGR24` (24 bit color; 3 bytes per pixel) is

used, it's not uncommon for a participant to need each row of pixels to

start at a 4 byte aligned offset from the start of the image, which can

imply some padding bytes at the end of each row of pixels, before the

start of the next row of pixels.

While any value of `bytes_per_row_divisor` could instead be enforced by

setting `size_alignment.width` to the least-common-multiple of the

"stride bytes per width pixel" and the stride alignment requirement,

enforcing the stride alignment requirement that way can lead to more

padding than necessary (implying larger buffer than necessary), and can

also result in a "fake" `size.width` values that other participants

would need to care about; this field exists to avoid that situation.

Instead, the stride alignment requirement in bytes is specified directly

here.

`vmo_usable_start % start_offset_divisor` must be 0. Un-set is treated

as 1.

Producer participants are discouraged from setting non-zero image start

offset (from the buffer base) unless actually required, as not all

participants correctly handle non-zero image start offset.

The (additional) [`fuchsia.sysmem2/PixelFormatAndModifier`]s for which

the following constraints apply.

As a non-limiting example, if a participant only wants to set a single

`PixelFormatAndModifier` for this

[`fuchsia.sysmem2/ImageFormatConstraints`], the participant can either

(a) use `pixel_format` and `pixel_format_modifier` fields to specify the

fields of the one `PixelFormatAndModifier` and leave

`pixel_format_and_modifiers` un-set, or (b) leave `pixel_format` and

`pixel_format_modifier` fields un-set and put the one

`PixelFormatAndModifier` in `pixel_format_and_modifiers`.

If `pixel_format` is set, the server will take pixel_format and

pixel_format_modifier fields (un-setting them in the process), pack them

into a `PixelFormatAndModifier`, and move it into this vector as one

additional entry, with an overall size limit of

`MAX_COUNT_PIXEL_FORMAT_AND_MODIFIERS + 1`.

After the server moves `pixel_format`, `pixel_format_modifier` into one

additional entry in this vector, this vector must not be empty. When the

resulting list has more than 1 item, the entries in this vector are

equivalent to (shorthand for) listing (size) separate

`ImageFormatConstraints` entries, one per `pixel_format_and_modifiers`

entry, each with one `PixelFormatAndModifier`, where all the separate

`ImageFormatConstraints` entries have the same constraints (compared

field by field, not including `pixel_format`, `pixel_format_modifier`,

or `pixel_format_and_modifiers` fields).

In `SetConstraints` message, each entry specifies a

`PixelFormatAndModifier` which is acceptable to the participant

(assuming the following constraints fields are also satisfied).

In the response to `WaitForAllBuffersAllocated`, this field will be

un-set and the one chosen `PixelFormatAndModifier` will be indicated

using the `pixel_format` and `pixel_format_modifier` fields.

All the `PixelFormatAndModifiers` in a `SetConstraints` message from a

participant must be unique across all the entries under

`image_format_constraints`. If

[`fuchsia.images2/PixelFormat.DO_NOT_CARE`] is used in an entry, there

must not be any other entry (considering all the entries under

`image_format_constraints`) with matching `pixel_format_modifier`. If

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] is used, there must

not be any other entry (considering all the entries under

`image_format_constraints`) with matching `pixel_format`.

A `PixelFormatAndModifier` value with either

[`fuchsia.images2/PixelFormat.DO_NOT_CARE`] or

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] (but not both, for

purposes of this example) can be combined with a

`PixelFormatAndModifier` from a separate participant with the other

field indicating "do not care", resulting in a complete

`PixelFormatAndModifier` that can succeed allocation. However, at least

for now, it's not permitted for a single participant to specify two

separate `PixelFormatAndModifier` values which have "do not care" in

different fields. This does not prohibit a single

`PixelFormatAndModifier` with both `PixelFormat.DO_NOT_CARE` and

`PixelFormatModifier.DO_NOT_CARE` (which is only a single

`PixelFormatAndModifier` value). If a client really needs to specify

some constraints relevant to `pixel_format`(s) with

`pixel_format_modifier` `DO_NOT_CARE`, and other constraints relevant to

`pixel_format_modifier`(s) with `pixel_format` `DO_NOT_CARE`, the client

can do so by duplicating the token and using/driving two separate

participants.

See also `pixel_format` for more comments relevant to multiple

`PixelFormatAndModifier`s in a single `ImageFormatConstraints`.

The (additional) [`fuchsia.sysmem2/PixelFormatAndModifier`]s for which

the following constraints apply.

As a non-limiting example, if a participant only wants to set a single

`PixelFormatAndModifier` for this

[`fuchsia.sysmem2/ImageFormatConstraints`], the participant can either

(a) use `pixel_format` and `pixel_format_modifier` fields to specify the

fields of the one `PixelFormatAndModifier` and leave

`pixel_format_and_modifiers` un-set, or (b) leave `pixel_format` and

`pixel_format_modifier` fields un-set and put the one

`PixelFormatAndModifier` in `pixel_format_and_modifiers`.

If `pixel_format` is set, the server will take pixel_format and

pixel_format_modifier fields (un-setting them in the process), pack them

into a `PixelFormatAndModifier`, and move it into this vector as one

additional entry, with an overall size limit of

`MAX_COUNT_PIXEL_FORMAT_AND_MODIFIERS + 1`.

After the server moves `pixel_format`, `pixel_format_modifier` into one

additional entry in this vector, this vector must not be empty. When the

resulting list has more than 1 item, the entries in this vector are

equivalent to (shorthand for) listing (size) separate

`ImageFormatConstraints` entries, one per `pixel_format_and_modifiers`

entry, each with one `PixelFormatAndModifier`, where all the separate

`ImageFormatConstraints` entries have the same constraints (compared

field by field, not including `pixel_format`, `pixel_format_modifier`,

or `pixel_format_and_modifiers` fields).

In `SetConstraints` message, each entry specifies a

`PixelFormatAndModifier` which is acceptable to the participant

(assuming the following constraints fields are also satisfied).

In the response to `WaitForAllBuffersAllocated`, this field will be

un-set and the one chosen `PixelFormatAndModifier` will be indicated

using the `pixel_format` and `pixel_format_modifier` fields.

All the `PixelFormatAndModifiers` in a `SetConstraints` message from a

participant must be unique across all the entries under

`image_format_constraints`. If

[`fuchsia.images2/PixelFormat.DO_NOT_CARE`] is used in an entry, there

must not be any other entry (considering all the entries under

`image_format_constraints`) with matching `pixel_format_modifier`. If

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] is used, there must

not be any other entry (considering all the entries under

`image_format_constraints`) with matching `pixel_format`.

A `PixelFormatAndModifier` value with either

[`fuchsia.images2/PixelFormat.DO_NOT_CARE`] or

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] (but not both, for

purposes of this example) can be combined with a

`PixelFormatAndModifier` from a separate participant with the other

field indicating "do not care", resulting in a complete

`PixelFormatAndModifier` that can succeed allocation. However, at least

for now, it's not permitted for a single participant to specify two

separate `PixelFormatAndModifier` values which have "do not care" in

different fields. This does not prohibit a single

`PixelFormatAndModifier` with both `PixelFormat.DO_NOT_CARE` and

`PixelFormatModifier.DO_NOT_CARE` (which is only a single

`PixelFormatAndModifier` value). If a client really needs to specify

some constraints relevant to `pixel_format`(s) with

`pixel_format_modifier` `DO_NOT_CARE`, and other constraints relevant to

`pixel_format_modifier`(s) with `pixel_format` `DO_NOT_CARE`, the client

can do so by duplicating the token and using/driving two separate

participants.

See also `pixel_format` for more comments relevant to multiple

`PixelFormatAndModifier`s in a single `ImageFormatConstraints`.

Iff set and true, bytes_per_row_divisor in the resulting

ImageFormatConstraints is guaranteed to be a value which requires

bytes_per_row to be an integral number of pixels. This can result in

more padding at the end of each row than when this field is not set to

true, but ensures that the stride can be expressed as an integral number

of pixels.

For example, if the chosen `PixelFormat` is `B8G8R8`, if this field is

set to true, the resulting bytes_per_row_divisor will be a multiple of

3. In this example, if another participant sets `bytes_per_row_divisor`

to 4, the resulting `bytes_per_row_divisor` will be a multiple of 12.

Iff set and true, bytes_per_row_divisor in the resulting

ImageFormatConstraints is guaranteed to be a value which requires

bytes_per_row to be an integral number of pixels. This can result in

more padding at the end of each row than when this field is not set to

true, but ensures that the stride can be expressed as an integral number

of pixels.

For example, if the chosen `PixelFormat` is `B8G8R8`, if this field is

set to true, the resulting bytes_per_row_divisor will be a multiple of

3. In this example, if another participant sets `bytes_per_row_divisor`

to 4, the resulting `bytes_per_row_divisor` will be a multiple of 12.

If unset, any A channel of any format in this ImageFormatConstraints is

is ignored or not ignored according to semantics conveyed out of band.

If set to false, the A channel of any format in this

ImageFormatConstraints is arbitrary values that don't mean anything.

Producers don't need to ensure any particular values in the A channel

and consumers should ignore the A channel. This is the same thing as

calling the 'A' channel 'X' instead.

If set to true, the A channel of any format in this

ImageFormatConstraints is set to meaningful values. A producer should

fill out the A values, and a consumer should pay attention to the A

values as appropriate.

If set values of this field don't match for the same pixel format and

modifier, that format and modifier will be eliminated from

consideration.

A participant that knows that the semantics of the A channel are

conveyed via out of band means can leave this field un-set, even if the

out of band means is already known to specify alpha present or not

present, but in this situation it's also ok to fill out this field for

informational / debugging purposes.

If no participant sets this field, the default is un-set.

If the format chosen for allocation doesn't have an A channel, this

field will be un-set in the allocation result.

If unset, any A channel of any format in this ImageFormatConstraints is

is ignored or not ignored according to semantics conveyed out of band.

If set to false, the A channel of any format in this

ImageFormatConstraints is arbitrary values that don't mean anything.

Producers don't need to ensure any particular values in the A channel

and consumers should ignore the A channel. This is the same thing as

calling the 'A' channel 'X' instead.

If set to true, the A channel of any format in this

ImageFormatConstraints is set to meaningful values. A producer should

fill out the A values, and a consumer should pay attention to the A

values as appropriate.

If set values of this field don't match for the same pixel format and

modifier, that format and modifier will be eliminated from

consideration.

A participant that knows that the semantics of the A channel are

conveyed via out of band means can leave this field un-set, even if the

out of band means is already known to specify alpha present or not

present, but in this situation it's also ok to fill out this field for

informational / debugging purposes.

If no participant sets this field, the default is un-set.

If the format chosen for allocation doesn't have an A channel, this

field will be un-set in the allocation result.

If an entry in this list has width or height greater than max_size width

or height respectively (evaluated both before and again after

aggregation), allocation will fail.

This field aggregates by appending the entries to an overall list, or in

other words, this field does not aggregate; all entries from all

participants must be satisfied by the allocated buffer(s) or the

allocation will fail. This lack of aggregation is to avoid

larger-than-necessary buffers if one participant specifies a large width

and small height and another participant specifies a small width and

large height, or more likely, if a single participant specifies those

two entries (for example). In that case, the buffer's

`BufferMemorySettings.size_bytes` needs to be large enough to store the

larger (in bytes) of the specified sizes (given available ranges of

other ImageFormatConstraints), but not the max width and max height

across all specified sizes used as the width and height of a single

image.

Under the resulting `BufferCollectionInfo`, `max_size` is the max

allowed value for each dimension separately, but this does not imply

that an image of max_size can fit in the buffer (typically won't). In

contrast, any image that's no bigger than an entry in the returned

`required_max_size_list` will fit in the buffer. The returned list will

have redundant entries removed, so a client's entry may not be present

if another entry covers the client's entry; this also removes any

duplicates. The correct way to check if an image will fit is to check

that `ImageFormatImageSize()` is less than or equal to

`BufferMemorySettings.size_bytes`.

Until `required_max_size` is removed, the returned

`required_max_size_list` will, if any participants specified

`required_max_size`, ensure that the aggregated (using max width and max

height) `required_max_size` will fit in the allocated buffer. This does

not imply that there will necessarily be an entry that indicates this

specific aggregated `required_max_size`, as that entry can be removed if

it's covered by another entry.

In contrast to `max_size`, an entry can be added to

`required_max_size_list` to ensure the buffer actually has the capacity

to store an image that has both width and height less than or equal to

the entry's width and height respectively. See

`BufferMemorySettings.size_bytes` for more on what "capacity" means

here.

A typical usage of more than one entry in this list would be specifying

that each buffer needs to be able to store up to a given portrait size

and also up to a given landscape size. In general, more than one entry

makes sense if the participant needs to ensure that the buffer can be

used to store images of a few different aspect ratios at up to the

listed size per aspect ratio. In the response from the server, redundant

entries are removed.

If an entry in this list has width or height greater than max_size width

or height respectively (evaluated both before and again after

aggregation), allocation will fail.

This field aggregates by appending the entries to an overall list, or in

other words, this field does not aggregate; all entries from all

participants must be satisfied by the allocated buffer(s) or the

allocation will fail. This lack of aggregation is to avoid

larger-than-necessary buffers if one participant specifies a large width

and small height and another participant specifies a small width and

large height, or more likely, if a single participant specifies those

two entries (for example). In that case, the buffer's

`BufferMemorySettings.size_bytes` needs to be large enough to store the

larger (in bytes) of the specified sizes (given available ranges of

other ImageFormatConstraints), but not the max width and max height

across all specified sizes used as the width and height of a single

image.

Under the resulting `BufferCollectionInfo`, `max_size` is the max

allowed value for each dimension separately, but this does not imply

that an image of max_size can fit in the buffer (typically won't). In

contrast, any image that's no bigger than an entry in the returned

`required_max_size_list` will fit in the buffer. The returned list will

have redundant entries removed, so a client's entry may not be present

if another entry covers the client's entry; this also removes any

duplicates. The correct way to check if an image will fit is to check

that `ImageFormatImageSize()` is less than or equal to

`BufferMemorySettings.size_bytes`.

Until `required_max_size` is removed, the returned

`required_max_size_list` will, if any participants specified

`required_max_size`, ensure that the aggregated (using max width and max

height) `required_max_size` will fit in the allocated buffer. This does

not imply that there will necessarily be an entry that indicates this

specific aggregated `required_max_size`, as that entry can be removed if

it's covered by another entry.

In contrast to `max_size`, an entry can be added to

`required_max_size_list` to ensure the buffer actually has the capacity

to store an image that has both width and height less than or equal to

the entry's width and height respectively. See

`BufferMemorySettings.size_bytes` for more on what "capacity" means

here.

A typical usage of more than one entry in this list would be specifying

that each buffer needs to be able to store up to a given portrait size

and also up to a given landscape size. In general, more than one entry

makes sense if the participant needs to ensure that the buffer can be

used to store images of a few different aspect ratios at up to the

listed size per aspect ratio. In the response from the server, redundant

entries are removed.

`pad_for_block_size` ensures that a participant will be able to access

pixel data in blocks of the specified size, even for the lower right

pixel whose access block can extend beyond that pixel, sometimes

requiring more page(s) in the VMO to avoid access fault or out-of-bounds

DMA. The extra "pixel" data of blocks on the right and bottom will not

overlap with any other pixel (or "pixel") data.

At least for now this field is only accepted for linear single-plane

formats. This corresponds to `PixelFormatModifier.Linear` and

`ImageFormatPlaneByteOffset` returning false when plane is 1.

This field being set is not accepted if the ImageFormatConstraints has

PixelFormat.DO_NOT_CARE or PixelFormatModifier.DO_NOT_CARE.

For linear single-plane formats, we don't need to force size_alignment

to be the access block size, as (a) there's no intent by any participant

to actually store more (valid) pixels in the buffer, and (b) no other

non-block-accessing participant needs to know about block access by a

different participant to correctly locate the data of any pixel. The

accesses by the block-accessing participant just need to remain within

the VMO, so that all accesses remain within the VMO's pages.

This field ensures the VMO size is sufficient to store the lower right

"pixel" of the lower right block, but by design, that "pixel" data is

not necessarily within `BufferMemorySettings.size_bytes`. Participants

specifying `pad_for_block_size` are allowed to access beyond

`BufferMemorySettings.size_bytes`. Block access per `pad_for_block_size`

will automatically be within the VMO sze (but participants may check as

well of course).

For a motivating example, see the top of pad_for_block_size_test.cc.

If setting `pad_for_block_size.height` to a value greater than 1, the

same participant must (enforced) set a `max_size.width` less than

0xFFFFFFFF (preferably no more than a small multiple of the expected

actual max width). This helps in controlling the space overhead incurred

by the participant's use of blocks. If not burdensome, any of the

following can also help:

* `min_size.height` - any participant setting a value greater than 1

* `size_alignment.height` - any participant setting to a value greater

than 1

`pad_for_block_size` ensures that a participant will be able to access

pixel data in blocks of the specified size, even for the lower right

pixel whose access block can extend beyond that pixel, sometimes

requiring more page(s) in the VMO to avoid access fault or out-of-bounds

DMA. The extra "pixel" data of blocks on the right and bottom will not

overlap with any other pixel (or "pixel") data.

At least for now this field is only accepted for linear single-plane

formats. This corresponds to `PixelFormatModifier.Linear` and

`ImageFormatPlaneByteOffset` returning false when plane is 1.

This field being set is not accepted if the ImageFormatConstraints has

PixelFormat.DO_NOT_CARE or PixelFormatModifier.DO_NOT_CARE.

For linear single-plane formats, we don't need to force size_alignment

to be the access block size, as (a) there's no intent by any participant

to actually store more (valid) pixels in the buffer, and (b) no other

non-block-accessing participant needs to know about block access by a

different participant to correctly locate the data of any pixel. The

accesses by the block-accessing participant just need to remain within

the VMO, so that all accesses remain within the VMO's pages.

This field ensures the VMO size is sufficient to store the lower right

"pixel" of the lower right block, but by design, that "pixel" data is

not necessarily within `BufferMemorySettings.size_bytes`. Participants

specifying `pad_for_block_size` are allowed to access beyond

`BufferMemorySettings.size_bytes`. Block access per `pad_for_block_size`

will automatically be within the VMO sze (but participants may check as

well of course).

For a motivating example, see the top of pad_for_block_size_test.cc.

If setting `pad_for_block_size.height` to a value greater than 1, the

same participant must (enforced) set a `max_size.width` less than

0xFFFFFFFF (preferably no more than a small multiple of the expected

actual max width). This helps in controlling the space overhead incurred

by the participant's use of blocks. If not burdensome, any of the

following can also help:

* `min_size.height` - any participant setting a value greater than 1

* `size_alignment.height` - any participant setting to a value greater

than 1

pad_beyond_image_size_bytes ensures that there will be at least this

many bytes in the VMO beyond the image size. Some SW video codecs need

this for performance reasons.

Some video decoders and encoders can require that a few more bytes be

safe to access beyond the image's size as calculated by

ImageFormatImageSize. This can sometimes require an additional page to

be allocated. The padding specified by this field starts at byte 0 of

the row beyond the last image row.

This semantic is chosen because (a) it makes some video decoders used in

ffmpeg happy (needs 16 bytes fully after the image as a run-out zone),

and (b) it can serve as a not-particularly-wastful way to avoid adding

pad_beyond_last_pixel_bytes as well, because this padding always starts

at or beyond where that padding would without wasting more than

bytes_per_row - pixel_stride_in_bytes * width which is very unlikely to

result in wasting more than 1 page (and won't typically waste any

pages).

If the participant needs extra bytes beyond the image size to accomodate

performance optimization(s), the number of extra bytes needed goes here.

Do _not_ store valid pixels or metadata in these bytes; some or all of

these bytes may be the same bytes requested via other participant's

pad_* constraints.

Do not write to these bytes outside time intervals during which

writing to pixel data is permitted.

pad_beyond_image_size_bytes ensures that there will be at least this

many bytes in the VMO beyond the image size. Some SW video codecs need

this for performance reasons.

Some video decoders and encoders can require that a few more bytes be

safe to access beyond the image's size as calculated by

ImageFormatImageSize. This can sometimes require an additional page to

be allocated. The padding specified by this field starts at byte 0 of

the row beyond the last image row.

This semantic is chosen because (a) it makes some video decoders used in

ffmpeg happy (needs 16 bytes fully after the image as a run-out zone),

and (b) it can serve as a not-particularly-wastful way to avoid adding

pad_beyond_last_pixel_bytes as well, because this padding always starts

at or beyond where that padding would without wasting more than

bytes_per_row - pixel_stride_in_bytes * width which is very unlikely to

result in wasting more than 1 page (and won't typically waste any

pages).

If the participant needs extra bytes beyond the image size to accomodate

performance optimization(s), the number of extra bytes needed goes here.

Do _not_ store valid pixels or metadata in these bytes; some or all of

these bytes may be the same bytes requested via other participant's

pad_* constraints.

Do not write to these bytes outside time intervals during which

writing to pixel data is permitted.

Alignment requirements on the image `size`.

* `size.width % size_alignment.width` must be 0.

* `size.height % size_alignment.height` must be 0.

Both `size_alignment.width` and `size_alignment.height` must be non-zero

and a power of 2.

Un-set is treated as 1, 1.

`vmo_usable_start % start_offset_divisor` must be 0. Un-set is treated

as 1.

Producer participants are discouraged from setting non-zero image start

offset (from the buffer base) unless actually required, as not all

participants correctly handle non-zero image start offset.