Struct FormatCostEntry

pub struct FormatCostEntry {
    pub key: Option<FormatCostKey>,
    pub cost: Option<f32>,
    /* private fields */
}

A FormatCostEntry can be used to influence which PixelFormatAndModifier is chosen for a buffer collection, optionally taking BufferUsage into account.

The default cost is f32::MAX, so any specified cost with a non-MAX value will prefer the specified format over any formats that don’t have any FormatCost entry.

Entries which have the same pixel_format, pixel_format_modifier, and required_usage_bits as a previous entry will override that previous entry. For matching purposes, an absent pixel_format_modifier matches LINEAR, and an absent required_buffer_usage_bits matches all-0 usage bits.

Board info sysmem_defaults entries are logically before platform sysmem entries.

Sysmem uses the resulting aggregated list of FormatCostEntry(s) when breaking ties among the set of formats which are supported by all participants of a buffer collection. For each mutually-supported format, entries with non-matching format are ignored, and entries with extra buffer_usage_bits set are ignored. Among the remaining entries, the entry with the most usage bits in common with the aggregated participant usages is selected to determine the cost (if a tie, the later entry wins). Then the format with the lowest cost is chosen. If it’s still a tie (equal cost), the tie is broken arbitrarily but not randomly.

This is not intended as a mechanism to disallow selection of a format that is supported by all participants of a buffer collection. If a participant claims support for a format but fails to handle that format correctly, it should be fixed to handle that format correctly or changed to stop claiming support for that format.

This mechanism is intended to influence format selection toward more efficient formats with better performance, lower memory bandwidth usage, etc, for a given set of usage bits, taking into account quirks that may be unique to a given board or overall platform config.

Fields

key: Option<FormatCostKey>

Must be set. If two entries have logically equal key (after field defaults are applied), the later entry will override the earlier entry.

cost: Option<f32>

Must be set. Lower costs win, but see also FormatCostKey fields re. filtering entries by format and usage bits first.

When two entries (each with format supported by all the participants of a buffer collection) have different costs, the lower cost entry (and its format) is chosen.

For non-test scenarios, only use cost values > 0.0 (typically at least 1.0 as of this comment), with 0.0 and negative values reserved for testing.

Trait Implementations

impl Clone for FormatCostEntry

fn clone(&self) -> FormatCostEntry

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for FormatCostEntry

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

Formats the value using the given formatter.

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

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 FormatCostEntry

fn default() -> FormatCostEntry

Returns the “default value” for a type.

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

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 FormatCostEntry

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

type Owned = FormatCostEntry

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 FormatCostEntry

type Borrowed<'a> = &'a FormatCostEntry

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 FormatCostEntry

impl StructuralPartialEq for FormatCostEntry