Struct ImageFormatConstraints

pub struct ImageFormatConstraints {

    pub pixel_format: Option<PixelFormat>,
    pub pixel_format_modifier: Option<PixelFormatModifier>,
    pub color_spaces: Option<Vec<ColorSpace>>,
    pub min_size: Option<SizeU>,
    pub max_size: Option<SizeU>,
    pub min_bytes_per_row: Option<u32>,
    pub max_bytes_per_row: Option<u32>,
    pub max_width_times_height: Option<u64>,
    pub size_alignment: Option<SizeU>,
    pub display_rect_alignment: Option<SizeU>,
    pub required_min_size: Option<SizeU>,
    pub required_max_size: Option<SizeU>,
    pub bytes_per_row_divisor: Option<u32>,
    pub start_offset_divisor: Option<u32>,
    pub pixel_format_and_modifiers: Option<Vec<PixelFormatAndModifier>>,
    pub require_bytes_per_row_at_pixel_boundary: Option<bool>,
    pub is_alpha_present: Option<bool>,
    /* private fields */
}

Describes constraints on layout of image data in buffers.

Fields

pixel_format: Option<PixelFormat>

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 PixelFormatAndModifiers, the participant may list additional PixelFormatAndModifiers 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 PixelFormatAndModifiers).
• If image constraints differ for different PixelFormatAndModifiers, the participant can convey this using a separate ImageFormatConstraints entry in image_format_constraints for each set of PixelFormatAndModifiers 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 PixelFormatAndModifiers 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.

pixel_format_modifier: Option<PixelFormatModifier>

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

color_spaces: Option<Vec<ColorSpace>>

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.

min_size: Option<SizeU>

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.

max_size: Option<SizeU>

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.

min_bytes_per_row: Option<u32>

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.

max_bytes_per_row: Option<u32>

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

max_width_times_height: Option<u64>

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.

size_alignment: Option<SizeU>

Alignment requirements on the image size.

• size.width % size_alignment.width must be 0.
• size.height % size_alignment.height must be 0.

Un-set is treated as 1, 1.

display_rect_alignment: Option<SizeU>

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.

required_min_size: Option<SizeU>

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.

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

required_max_size: Option<SizeU>

See also required_min_size. Un-set is treated as 0, 0.

bytes_per_row_divisor: Option<u32>

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; this field exists to avoid that situation. Instead, the stride alignment requirement in bytes is specified directly here.

start_offset_divisor: Option<u32>

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.

pixel_format_and_modifiers: Option<Vec<PixelFormatAndModifier>>

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 PixelFormatAndModifiers in a single ImageFormatConstraints.

require_bytes_per_row_at_pixel_boundary: Option<bool>

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.

is_alpha_present: Option<bool>

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.

Trait Implementations

impl Clone for ImageFormatConstraints

fn clone(&self) -> ImageFormatConstraints

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ImageFormatConstraints

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

Formats the value using the given formatter.

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

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 ImageFormatConstraints

fn default() -> ImageFormatConstraints

Returns the “default value” for a type.

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

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 ImageFormatConstraints

fn eq(&self, other: &ImageFormatConstraints) -> 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 ImageFormatConstraints

type Owned = ImageFormatConstraints

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 ImageFormatConstraints

type Borrowed<'a> = &'a ImageFormatConstraints

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 ImageFormatConstraints

impl StructuralPartialEq for ImageFormatConstraints