class WireTableBuilder

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

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

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.