class ImageFormat

Returns whether no field is set.

Describes the manner in which pixels are encoded.

Describes the manner in which pixels are encoded.

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

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

Indicates the color space used to interpret pixel values.

Indicates the color space used to interpret pixel values.

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

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 field has no assigned meaning when 'pixel_format_modifier' isn't

'PixelFormatModifier::Linear'. Instead participants are expected to

implicitly know that a tiled (not linear) format will contain `size`

pixels by rounding up to the closest tile boundary greater than or equal

to width and same separately for height, without any "extra" tiles in

either direction. Tiled (not linear) formats don't have any way to

specify more blocks in either direction than are implied by `size`. When

relevant consumers support display_rect, `size` can imply more tiles

than display_rect touches.

This is not "row stride in pixels", nor is it "per-pixel stride" (which

themselves are two different things both distinct from bytes_per_row).

The number in this field is also known as the "row stride in bytes",

"line to line offset in bytes", "row to row offset in bytes", and other

variants of these names, sometimes just "stride", but only when

understood to be in bytes.

Regarding "row stride in pixels" vs `bytes_per_row`, as an example, it's

not uncommon 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. 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`.

When `pixel_format_modifier` == `PixelFormatModifier.Linear`, this is

the offset in bytes of byte 0 of row 1 of plane 0 minus the offset in

bytes of byte 0 of row 0 of plane 0.

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 field has no assigned meaning when 'pixel_format_modifier' isn't

'PixelFormatModifier::Linear'. Instead participants are expected to

implicitly know that a tiled (not linear) format will contain `size`

pixels by rounding up to the closest tile boundary greater than or equal

to width and same separately for height, without any "extra" tiles in

either direction. Tiled (not linear) formats don't have any way to

specify more blocks in either direction than are implied by `size`. When

relevant consumers support display_rect, `size` can imply more tiles

than display_rect touches.

This is not "row stride in pixels", nor is it "per-pixel stride" (which

themselves are two different things both distinct from bytes_per_row).

The number in this field is also known as the "row stride in bytes",

"line to line offset in bytes", "row to row offset in bytes", and other

variants of these names, sometimes just "stride", but only when

understood to be in bytes.

Regarding "row stride in pixels" vs `bytes_per_row`, as an example, it's

not uncommon 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. 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`.

When `pixel_format_modifier` == `PixelFormatModifier.Linear`, this is

the offset in bytes of byte 0 of row 1 of plane 0 minus the offset in

bytes of byte 0 of row 0 of plane 0.

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.

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.

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.

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.

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.

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

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.