class ImageFormatConstraints

Defined at line 2509 of file fidling/gen/sdk/fidl/fuchsia.sysmem2/fuchsia.sysmem2/cpp/fidl/fuchsia.sysmem2/cpp/natural_types.h

Describes constraints on layout of image data in buffers.

Public Methods

void ImageFormatConstraints (Storage_ storage)

void ImageFormatConstraints ()

Defined at line 2514 of file fidling/gen/sdk/fidl/fuchsia.sysmem2/fuchsia.sysmem2/cpp/fidl/fuchsia.sysmem2/cpp/natural_types.h

void ImageFormatConstraints (ImageFormatConstraints && )

Defined at line 2515 of file fidling/gen/sdk/fidl/fuchsia.sysmem2/fuchsia.sysmem2/cpp/fidl/fuchsia.sysmem2/cpp/natural_types.h

void ImageFormatConstraints (const ImageFormatConstraints & other)

ImageFormatConstraints & operator= (ImageFormatConstraints && )

Defined at line 2516 of file fidling/gen/sdk/fidl/fuchsia.sysmem2/fuchsia.sysmem2/cpp/fidl/fuchsia.sysmem2/cpp/natural_types.h

ImageFormatConstraints & operator= (const ImageFormatConstraints & other)

bool operator== (const ImageFormatConstraints & other)

bool operator!= (const ImageFormatConstraints & other)

bool IsEmpty ()

const std::optional< ::fuchsia_images2::PixelFormat> & 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 `required_max_size`.

const std::optional<uint32_t> & min_bytes_per_row ()

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.

::std::optional<uint32_t> & min_bytes_per_row ()

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.

ImageFormatConstraints & min_bytes_per_row (std::optional<uint32_t> value)

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.

const std::optional<uint32_t> & max_bytes_per_row ()

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

::std::optional<uint32_t> & max_bytes_per_row ()

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

ImageFormatConstraints & max_bytes_per_row (std::optional<uint32_t> value)

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

const std::optional<uint64_t> & max_width_times_height ()

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.

::std::optional<uint64_t> & max_width_times_height ()

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.

ImageFormatConstraints & max_width_times_height (std::optional<uint64_t> value)

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.

const std::optional< ::fuchsia_math::SizeU> & size_alignment ()

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.

::std::optional< ::fuchsia_math::SizeU> & size_alignment ()

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.

ImageFormatConstraints & size_alignment (std::optional< ::fuchsia_math::SizeU> value)

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.

const std::optional< ::fuchsia_math::SizeU> & display_rect_alignment ()

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.

::std::optional< ::fuchsia_math::SizeU> & display_rect_alignment ()

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.

ImageFormatConstraints & display_rect_alignment (std::optional< ::fuchsia_math::SizeU> value)

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.

const std::optional< ::fuchsia_math::SizeU> & required_min_size ()

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.

::std::optional< ::fuchsia_math::SizeU> & required_min_size ()

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.

ImageFormatConstraints & required_min_size (std::optional< ::fuchsia_math::SizeU> value)

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.

const std::optional< ::fuchsia_math::SizeU> & required_max_size ()

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.

::std::optional< ::fuchsia_math::SizeU> & required_max_size ()