Struct ImageFormat

pub struct ImageFormat {
    pub pixel_format: Option<PixelFormat>,
    pub pixel_format_modifier: Option<PixelFormatModifier>,
    pub color_space: Option<ColorSpace>,
    pub size: Option<SizeU>,
    pub bytes_per_row: Option<u32>,
    pub display_rect: Option<RectU>,
    pub valid_size: Option<SizeU>,
    pub pixel_aspect_ratio: Option<SizeU>,
    /* private fields */
}

Describes the format of images.

Fields

pixel_format: Option<PixelFormat>

Describes the manner in which pixels are encoded.

pixel_format_modifier: Option<PixelFormatModifier>

Vendor-specific pixel format modifier. See format_modifier.fidl.

color_space: Option<ColorSpace>

Indicates the color space used to interpret pixel values.

size: Option<SizeU>

The size of the image in pixels.

See also bytes_per_row which is also necessary (along with size) to find where each pixel’s data is within a buffer.

Not all of the addressable pixel positions in the buffer are necessarily populated with valid pixel data. See valid_size for the potentially-smaller rectangle of valid pixels.

The right and bottom of the image may have some valid pixels which are not to be displayed. See display_rect.

bytes_per_row: Option<u32>

Number of bytes per row. For multi-plane YUV formats, this is the number of bytes per row in the Y plane.

When this field is not set, there is no padding at the end of each row of pixels. In other words, when not set, the stride is equal to the “stride bytes per width pixel” times the size.width.

When set, the value in this field must be >= the “stride bytes per width pixel” times the size.width. If equal, there is no padding at the end of each row of pixels. If greater, the difference is how much padding is at the end of each row of pixels, in bytes.

This is also known as the “stride”, “line to line offset”, “row to row offset”, and other names.

As a specific example, it’s not uncommon (but also not always required) for BGR24 (3 bytes per pixel) to have some padding at the end of each row so that each row of pixels starts at a 4 byte aligned offset from the start of the image (the upper left pixel). That padding’s size is not necessarily divisible by the size in bytes of a pixel (“stride bytes per width pixel”), so we indicate the padding using this field rather than trying to incorporate the padding as a larger “fake” size.width.

display_rect: Option<RectU>

The rect within a frame that’s for display. This is the location and size in pixels of the rectangle of pixels that should be displayed, when displaying the “whole image” in a UI display sense.

The x + width must be <= size.width, and the y + height must be <= size.height.

For output from a video decoder, pixels outside the display_rect are never to be displayed (outside of test programs), but must be preserved for correct decoder function. The display_rect will always fall within the rect starting at (0, 0) and having valid_size size, when valid_size is set. In other words, display_rect is a subset (not necessarily a proper subset) of valid_size, and valid_size is a subset (not necessarily a proper subset) of size.

Downstream texture filtering operations should avoid letting any pixel outside of display_rect influence the visual appearance of any displayed pixel, to avoid the potential for the right or bottom edge leaking in arbitrary pixels defined by the decode process but not intended for display.

Behavior when this field is not set is protocol-specific. In some protocols, fallback to valid_size, then to size may be implemented. In others, fallback directly to size may be implemented. In others, this field must be set or the channel will close.

WARNING: fuchsia.sysmem.Images2 (V1) doesn’t handle non-zero x, y, so any non-zero x, y here (V2) will prevent conversion to V1. Due to the rarity of non-zero x, y in practice, even components that have moved to V2 may in some cases still assume both x and y are 0, until there’s a practical reason to implment and test handling of non-zero x, y. The symptom of sending non-zero x, y to a downstream render and/or display pipeline that assumes 0, 0 will be incorrect display, but not a crash, since assuming 0, 0 for x, y does not cause reading out of buffer bounds.

valid_size: Option<SizeU>

The size of a frame in terms of the number of pixels that have valid pixel data in terms of video decoding, but not in terms of which pixels are intended for display.

To convert valid_size into a rect that’s directly comparable to display_rect, one can make a rect with (x: 0, y: 0, width: valid_size.width, height: valid_size.height).

In the case of a video decoder, valid_size can include some pixels outside display_rect. The extra pixels are not meant to be displayed, and may or may not contain any real image data. Typically anything that looks like real image data in these regions is only an artifact of video compression and the existence of the remainder of a macroblock which can be referenced by later frames despite not being within the displayed region, and not really any additional “real” pixels from the source. The pixel values in this region are defined by the codec decode process and must be retained for correct decoder operation. Typically the pixels inside valid_size but outside display_rect will be up to the size of a macroblock minus 1. The valid_size is can be useful for testing video decoders and for certain transcoding scenarios.

pixel_aspect_ratio: Option<SizeU>

Aspect ratio of a single pixel as the video is intended to be displayed.

For YUV formats, this is the pixel aspect ratio (AKA sample aspect ratio aka SAR) for the luma (AKA Y) samples.

Producers should ensure the width and height values are relatively prime by reducing the fraction (dividing both by GCF) if necessary.

A consumer should interpret this field being un-set as an unknown pixel aspect ratio. A default of 1:1 can be appropriate in some cases, but a consumer may determine the actual pixel aspect ratio by OOB means.

Trait Implementations

impl Clone for ImageFormat

fn clone(&self) -> ImageFormat

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ImageFormat

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

Formats the value using the given formatter.

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

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 ImageFormat

fn default() -> ImageFormat

Returns the “default value” for a type.

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

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 ImageFormat

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

type Owned = ImageFormat

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 ImageFormat

type Borrowed<'a> = &'a ImageFormat

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 ImageFormat

impl StructuralPartialEq for ImageFormat