Struct BufferCollectionConstraints

pub struct BufferCollectionConstraints {
    pub usage: Option<BufferUsage>,
    pub min_buffer_count_for_camping: Option<u32>,
    pub min_buffer_count_for_dedicated_slack: Option<u32>,
    pub min_buffer_count_for_shared_slack: Option<u32>,
    pub min_buffer_count: Option<u32>,
    pub max_buffer_count: Option<u32>,
    pub buffer_memory_constraints: Option<BufferMemoryConstraints>,
    pub image_format_constraints: Option<Vec<ImageFormatConstraints>>,
    /* private fields */
}

Constraints on allocated buffers and, optionally, constraints on images stored in the buffers. These constraints can be specified per-participant. The sysmem service implements aggregation of constraints from multiple participants.

Fields

usage: Option<BufferUsage>

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

min_buffer_count_for_camping: Option<u32>

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.

min_buffer_count_for_dedicated_slack: Option<u32>

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.

min_buffer_count_for_shared_slack: Option<u32>

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.

min_buffer_count: Option<u32>

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.

max_buffer_count: Option<u32>

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.

buffer_memory_constraints: Option<BufferMemoryConstraints>

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.

image_format_constraints: Option<Vec<ImageFormatConstraints>>

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.

Trait Implementations

impl Clone for BufferCollectionConstraints

fn clone(&self) -> BufferCollectionConstraints

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BufferCollectionConstraints

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<D: ResourceDialect> Decode<BufferCollectionConstraints, D> for BufferCollectionConstraints

fn new_empty() -> Self

Creates a valid instance of Self. The specific value does not matter, since it will be overwritten by decode.

unsafe fn decode( &mut self, decoder: &mut Decoder<'_, D>, offset: usize, depth: Depth, ) -> Result<()>

Decodes an object of type T from the decoder’s buffers into self.

impl Default for BufferCollectionConstraints

fn default() -> BufferCollectionConstraints

Returns the “default value” for a type.

impl<D: ResourceDialect> Encode<BufferCollectionConstraints, D> for &BufferCollectionConstraints

unsafe fn encode( self, encoder: &mut Encoder<'_, D>, offset: usize, depth: Depth, ) -> Result<()>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID.

impl PartialEq for BufferCollectionConstraints

fn eq(&self, other: &BufferCollectionConstraints) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TypeMarker for BufferCollectionConstraints

type Owned = BufferCollectionConstraints

The owned Rust type which this FIDL type decodes into.

fn inline_align(_context: Context) -> usize

Returns the minimum required alignment of the inline portion of the encoded object. It must be a (nonzero) power of two.

fn inline_size(_context: Context) -> usize

Returns the size of the inline portion of the encoded object, including padding for alignment. Must be a multiple of inline_align.

fn encode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and encoding requires no validation. When true, we can optimize encoding arrays and vectors of Self::Owned to a single memcpy.

fn decode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and decoding requires no validation. When true, we can optimize decoding arrays and vectors of Self::Owned to a single memcpy.

impl ValueTypeMarker for BufferCollectionConstraints

type Borrowed<'a> = &'a BufferCollectionConstraints

The Rust type to use for encoding. This is a particular Encode<Self> type cheaply obtainable from &Self::Owned. There are three cases:

fn borrow(value: &<Self as TypeMarker>::Owned) -> Self::Borrowed<'_>

Cheaply converts from &Self::Owned to Self::Borrowed.

impl Persistable for BufferCollectionConstraints

impl StructuralPartialEq for BufferCollectionConstraints