class BufferCollectionConstraints

The `usage` is a hint to sysmem to potentially help choose a more

optimal [`fuchsia.images2/PixelFormat`] and/or `pixel_format_modifier`

when multiple compatible options exist.

When aggregating [`fuchsia.sysmem2/BufferCollectionConstraints`], these

values bitwise-OR.

At least one `usage` bit must be specified (however, it's permitted for

a [`fuchsia.sysmem2/BufferCollection.SetConstraints`] request to have

the request `constraints` field not set, in which case `kNoneUsage` is

the default, along with no constraints from the participant).

When `kNoneUsage` is specified it must be the only set bit, and no VMOs

will be sent in response to

[`fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated`].

The `usage` is a hint to sysmem to potentially help choose a more

optimal [`fuchsia.images2/PixelFormat`] and/or `pixel_format_modifier`

when multiple compatible options exist.

When aggregating [`fuchsia.sysmem2/BufferCollectionConstraints`], these

values bitwise-OR.

At least one `usage` bit must be specified (however, it's permitted for

a [`fuchsia.sysmem2/BufferCollection.SetConstraints`] request to have

the request `constraints` field not set, in which case `kNoneUsage` is

the default, along with no constraints from the participant).

When `kNoneUsage` is specified it must be the only set bit, and no VMOs

will be sent in response to

[`fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated`].

The `usage` is a hint to sysmem to potentially help choose a more

optimal [`fuchsia.images2/PixelFormat`] and/or `pixel_format_modifier`

when multiple compatible options exist.

When aggregating [`fuchsia.sysmem2/BufferCollectionConstraints`], these

values bitwise-OR.

At least one `usage` bit must be specified (however, it's permitted for

a [`fuchsia.sysmem2/BufferCollection.SetConstraints`] request to have

the request `constraints` field not set, in which case `kNoneUsage` is

the default, along with no constraints from the participant).

When `kNoneUsage` is specified it must be the only set bit, and no VMOs

will be sent in response to

[`fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated`].

Per-participant number of buffers that the participant may concurrently

hold for its exclusive use for more than a transient duration (camp on).

In this context, a "transient" duration is the time it takes to finish

running a small amount of non-blocking code that finishes transfering

away ownership of the buffer. Things like reading from storage, waiting

on hardware that isn't already known to be done, or doing things like

frame encode or decode are not considered transient durations, even if

they might sometimes complete quickly.

For example, a video decoder would specify (at least) the maximum number

of reference frames + 1 frame currently being decoded into. But not 1

more for the code that runs async and quickly to deliver a previously

decoded frame, even though that frame can potentially be owned for a

transient duration concurrent with decode of the next frame.

A participant must not camp on more buffers than specified here (except

for a transient duration) else processing may get stuck.

When aggregating BufferCollectionConstraints, these values add.

In testing scenarios, camping on more buffers than this for any

significant duration (one screen refresh period is "significant" in this

context) may (ideally will) be flagged as a failure. In testing

scenarios, the participant may not be provided with more buffers than

this concurrently.

Per-participant number of buffers that the participant may concurrently

hold for its exclusive use for more than a transient duration (camp on).

In this context, a "transient" duration is the time it takes to finish

running a small amount of non-blocking code that finishes transfering

away ownership of the buffer. Things like reading from storage, waiting

on hardware that isn't already known to be done, or doing things like

frame encode or decode are not considered transient durations, even if

they might sometimes complete quickly.

For example, a video decoder would specify (at least) the maximum number

of reference frames + 1 frame currently being decoded into. But not 1

more for the code that runs async and quickly to deliver a previously

decoded frame, even though that frame can potentially be owned for a

transient duration concurrent with decode of the next frame.

A participant must not camp on more buffers than specified here (except

for a transient duration) else processing may get stuck.

When aggregating BufferCollectionConstraints, these values add.

In testing scenarios, camping on more buffers than this for any

significant duration (one screen refresh period is "significant" in this

context) may (ideally will) be flagged as a failure. In testing

scenarios, the participant may not be provided with more buffers than

this concurrently.

Per-participant number of buffers that the participant may concurrently

hold for its exclusive use for more than a transient duration (camp on).

In this context, a "transient" duration is the time it takes to finish

running a small amount of non-blocking code that finishes transfering

away ownership of the buffer. Things like reading from storage, waiting

on hardware that isn't already known to be done, or doing things like

frame encode or decode are not considered transient durations, even if

they might sometimes complete quickly.

For example, a video decoder would specify (at least) the maximum number

of reference frames + 1 frame currently being decoded into. But not 1

more for the code that runs async and quickly to deliver a previously

decoded frame, even though that frame can potentially be owned for a

transient duration concurrent with decode of the next frame.

A participant must not camp on more buffers than specified here (except

for a transient duration) else processing may get stuck.

When aggregating BufferCollectionConstraints, these values add.

In testing scenarios, camping on more buffers than this for any

significant duration (one screen refresh period is "significant" in this

context) may (ideally will) be flagged as a failure. In testing

scenarios, the participant may not be provided with more buffers than

this concurrently.

Per-participant minimum number of buffers that are needed for slack

reasons, for better overlap of processing / better performance.

When aggregating `BufferCollectionConstraints`, these values add.

A participant should typically specify 0 or 1 here - typically 0 is

appropriate if `min_buffer_count_for_camping` is already enough to keep

the participant busy 100% of the time when the participant is slightly

behind, while 1 can be appropriate if 1 more buffer than strictly needed

for min-camping reasons gives enough slack to stay busy 100% of the time

(when slightly behind, vs. lower % without the extra buffer).

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

Per-participant minimum number of buffers that are needed for slack

reasons, for better overlap of processing / better performance.

When aggregating `BufferCollectionConstraints`, these values add.

A participant should typically specify 0 or 1 here - typically 0 is

appropriate if `min_buffer_count_for_camping` is already enough to keep

the participant busy 100% of the time when the participant is slightly

behind, while 1 can be appropriate if 1 more buffer than strictly needed

for min-camping reasons gives enough slack to stay busy 100% of the time

(when slightly behind, vs. lower % without the extra buffer).

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

Per-participant minimum number of buffers that are needed for slack

reasons, for better overlap of processing / better performance.

When aggregating `BufferCollectionConstraints`, these values add.

A participant should typically specify 0 or 1 here - typically 0 is

appropriate if `min_buffer_count_for_camping` is already enough to keep

the participant busy 100% of the time when the participant is slightly

behind, while 1 can be appropriate if 1 more buffer than strictly needed

for min-camping reasons gives enough slack to stay busy 100% of the time

(when slightly behind, vs. lower % without the extra buffer).

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

Similar to `min_buffer_count_for_dedicated_slack`, except when

aggregating these values max (instead of add). The value here is not

shared with any participant's `min_buffer_count_for_dedicated_slack`.

A participant can specify > 0 here if a participant would like to ensure

there's some slack overall, but doesn't need that slack to be dedicated.

The choice whether to use `min_buffer_count_for_dedicated_slack` or

`min_buffer_count_for_shared_slack` (or both) will typically be about

the degree to which the extra slack improves performance.

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

Similar to `min_buffer_count_for_dedicated_slack`, except when

aggregating these values max (instead of add). The value here is not

shared with any participant's `min_buffer_count_for_dedicated_slack`.

A participant can specify > 0 here if a participant would like to ensure

there's some slack overall, but doesn't need that slack to be dedicated.

The choice whether to use `min_buffer_count_for_dedicated_slack` or

`min_buffer_count_for_shared_slack` (or both) will typically be about

the degree to which the extra slack improves performance.

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

Similar to `min_buffer_count_for_dedicated_slack`, except when

aggregating these values max (instead of add). The value here is not

shared with any participant's `min_buffer_count_for_dedicated_slack`.

A participant can specify > 0 here if a participant would like to ensure

there's some slack overall, but doesn't need that slack to be dedicated.

The choice whether to use `min_buffer_count_for_dedicated_slack` or

`min_buffer_count_for_shared_slack` (or both) will typically be about

the degree to which the extra slack improves performance.

In testing scenarios, this field may be forced to 0, and all

participants are expected to continue to work without getting stuck. If

a buffer is needed for forward progress reasons, that buffer should be

accounted for in `min_buffer_count_for_camping`.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields as

appropriate.

If this field is un-set, the logical `min_buffer_count` is 0.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields as

appropriate.

If this field is un-set, the logical `min_buffer_count` is 0.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields as

appropriate.

If this field is un-set, the logical `min_buffer_count` is 0.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields.

If this field is un-set, the logical `max_buffer_count` is 0xFFFFFFFF.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields.

If this field is un-set, the logical `max_buffer_count` is 0xFFFFFFFF.

A particularly-picky participant may unfortunately need to demand a

tight range of `buffer_count`, or even a specific `buffer_count`. This

field should remain 0 unless a participant really must set this field to

constrain the overall `BufferCollectionInfo.buffer_count`. Any such

participant should still fill out the min_buffer_count_for_* fields.

If this field is un-set, the logical `max_buffer_count` is 0xFFFFFFFF.

Optional constraints on `BufferCollectionSettings.buffer_settings`.

A participant that intends to set `image_format_constraints` will

typically specify the minimum buffer size implicitly via

`image_format_constraints`, and possibly specify only the max buffer

size via `buffer_memory_constraints`.

If un-set, the client is specifying "don't care" re. any buffer memory

constraints.

Optional constraints on `BufferCollectionSettings.buffer_settings`.

A participant that intends to set `image_format_constraints` will

typically specify the minimum buffer size implicitly via

`image_format_constraints`, and possibly specify only the max buffer

size via `buffer_memory_constraints`.

If un-set, the client is specifying "don't care" re. any buffer memory

constraints.

Optional constraints on `BufferCollectionSettings.buffer_settings`.

A participant that intends to set `image_format_constraints` will

typically specify the minimum buffer size implicitly via

`image_format_constraints`, and possibly specify only the max buffer

size via `buffer_memory_constraints`.

If un-set, the client is specifying "don't care" re. any buffer memory

constraints.

Optional constraints on the image format parameters of an image stored

in a buffer of the collection. This includes

[`fuchsia.images2/PixelFormat`] and `pixel_format_modifier` (for tiling

and the like). These constraints can be specified separately per

`pixel_format` `pixel_format_modifier` pair. Duplicated `pixel_format`

`pixel_format_modifier` pairs aren't permitted.

When aggregating, only `pixel_format` `pixel_format_modifier` pairs that

are specified by all participants with non-zero

`image_format_constraints` size (and non-null)

BufferCollectionConstraints) are retained.

A participant can specify `pixel_format`

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

`pixel_format_modifier`

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] to permit any value

to be selected, but at least one participant must specify a specific

format for overall allocation to succeed.

In a SetConstraints message, un-set or zero length means no image format

constraints; a raw buffer can be allocated if no other participants

specify any `image_format_constraints` entries.

Optional constraints on the image format parameters of an image stored

in a buffer of the collection. This includes

[`fuchsia.images2/PixelFormat`] and `pixel_format_modifier` (for tiling

and the like). These constraints can be specified separately per

`pixel_format` `pixel_format_modifier` pair. Duplicated `pixel_format`

`pixel_format_modifier` pairs aren't permitted.

When aggregating, only `pixel_format` `pixel_format_modifier` pairs that

are specified by all participants with non-zero

`image_format_constraints` size (and non-null)

BufferCollectionConstraints) are retained.

A participant can specify `pixel_format`

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

`pixel_format_modifier`

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] to permit any value

to be selected, but at least one participant must specify a specific

format for overall allocation to succeed.

In a SetConstraints message, un-set or zero length means no image format

constraints; a raw buffer can be allocated if no other participants

specify any `image_format_constraints` entries.

Optional constraints on the image format parameters of an image stored

in a buffer of the collection. This includes

[`fuchsia.images2/PixelFormat`] and `pixel_format_modifier` (for tiling

and the like). These constraints can be specified separately per

`pixel_format` `pixel_format_modifier` pair. Duplicated `pixel_format`

`pixel_format_modifier` pairs aren't permitted.

When aggregating, only `pixel_format` `pixel_format_modifier` pairs that

are specified by all participants with non-zero

`image_format_constraints` size (and non-null)

BufferCollectionConstraints) are retained.

A participant can specify `pixel_format`

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

`pixel_format_modifier`

[`fuchsia.images2/PixelFormatModifier.DO_NOT_CARE`] to permit any value

to be selected, but at least one participant must specify a specific

format for overall allocation to succeed.

In a SetConstraints message, un-set or zero length means no image format

constraints; a raw buffer can be allocated if no other participants

specify any `image_format_constraints` entries.