class CodecBuffer

Each successful call to this method dups the VMO handle, with basic rights

+ read + optional write depending on is_for_write.

In buffer-per-packet mode this is equal to the corresponding packet index,

for purposes of mapping from packet_index to buffer_index.

The vaddr of the start of the mapped VMO for this buffer.

This will return nullptr if there's no VMO mapping because CPU access isn't

possible. In that case the vaddr data pointer passed around regarding a

packet will be an offset into the buffer / VMO, and is only meaningful

with respect to a CodecBuffer that's also passed alongside.

The CodecAdapter can set a CodecAdapterBufferContextBase to avoid needing

to look up a CodecBuffer* later to find the relevant "buffer context" (from

the CodecAdapter's point of view).

This is the same value as buffer_lifetime_ordinal in StreamProcessor FIDL.

This matches the buffer_index field of fuchsia::media::Packet when the packet refers to this

buffer.

This will ZX_PANIC() if the buffer hasn't been pinned yet, or if !is_known_contiguous().

The max size in bytes of meaningful/valid content starting at vmo_offset()

(from sysmem BufferMemorySettings.size_bytes). Producers must fit all

valid image/packet data within size().

The total VMO size in bytes (from sysmem BufferMemorySettings.raw_vmo_size /

zx_vmo_get_size). When sysmem pad_* constraints are used, raw_vmo_size()

includes trailing padding space beyond vmo_offset() + size() that is mapped

and accessible for padding/over-read/over-write, but must not hold

meaningful content.

This VMO is owned by CodecBuffer, but can be used temporarily (in a

non-owned fashion) to get VMO info or similar.

If the CodecAdapter wants to hold a VMO handle, a mapping, or a pin of its

own, the CodecAdapter should start with GetChildVmo() instead of vmo().

Holding a handle, mapping, or pin based on vmo() won't keep the CodecBuffer

instance allocated (but it will prevent the underlying memory from being

reused). Instead, by using GetChildVmo(), the CodecBuffer instance stays

allocated until the CodecAdapter has closed all its GetChildVmo-derived

handles to the buffer and unmapped all its GetChildVmo-derived mappings to

the buffer (and all pins). This helps avoid potential use-after-free of the

CodecBuffer and can make debugging / diagnosing simpler.

Up until the first buffer-relevant call to CoreCodecRemoveBuffer or

CoreCodecEnsureBuffersNotConfigured, the CodecBuffer will remain allocated

even if the CodecAdapter is not holding a handle obtained from

GetChildVmo() or anything derived from such a handle. If the CodecAdapter

wants/needs the CodecBuffer to remain allocated beyond said call, the

CodecAdapter must hold at least one handle obtained from GetChildVmo(), or

something derived from such a handle that keeps the VMO alive.

If a CodecAdapter does not keep any vmo(s) from GetChildVmo(), including

duplicates, mappings, or pins, that CodecAdapter must ensure that no buffer

usage of any form will occur beyond the first relevant

CoreCodecRemoveBuffer or CoreCodecEnsureBuffersNotConfigured.

If a CodecAdapter makes a separate pin of its own using GetChildVmo() (or a

duplicate and/or descendent), the CodecAdapter can continue doing DMA

to/from the buffer until its own unpin.

Calling GetChildVmo() (directly or indirectly via CodecPacket::SetBuffer())

after the first buffer-relevant CoreCodecRemoveBuffer or

CoreCodecEnsureBuffersNotConfigured is only valid while the CodecAdapter

still holds at least one open handle derived from an earlier GetChildVmo()

call.

The CodecAdapter should not rely on the returned VMO to be derived from

vmo(), though the returned vmo does refer to the same underlying buffer.

The offset within the main VMO where data of this CodecBuffer starts. The vmo_offset() is not

required to be divisible by page size.

Deprecated. See SetCodecAdapterFrame and/or

SetCodecAdapterBufferContext instead.

The CodecAdapter can set a CodecAdapterFrameBase to avoid needing to

look up a CodecBuffer* later to find the relevant "frame" (from the

CodecAdapter's point of view).

Unpin is automatic during ~CodecBuffer.

For testing.

This returns true from just before CoreCodecRemoveBuffer or CoreCodecEnsureBuffersNotConfigured

is called, until destruction.

A CodecAdapter may choose to ignore this accessor (relying only on CoreCodecRemoveBuffer and/or

CoreCodecEnsureBuffersNotConfigured).

If a CodecAdapter does not support dynamic buffers, this bool isn't particularly interesting

other than possibly for some debug asserts.

If a CodecAdapter does support dynamic buffers, this bool being true means it's appropriate to

close all handles derived from GetChildVmo() (and any derived from vmo(), though creating those

isn't recommended in the first place). Upon parent_vmo_ seeing ZX_VMO_ZERO_CHILDREN, the

CodecBuffer will be deleted, so the CodecAdapter should take care to remove all dependence on

the CodecBuffer* before closing the last handle.

For output buffers, the CodecAdapter can look at is_remove_pending() just before it would

otherwise be putting an output buffer back on its free list, for buffers that weren't already

free when CoreCodecRemoveBuffer or mid-stream CoreCodecEnsureBuffersNotConfigured was called.

For input buffers, this will only become true if the buffer is not with the CodecAdapter and

won't be referenced by any subsequent input packet sent to the CodecAdapter. So for most

CodecAdapter(s), input buffer removal can happen during the call to CoreCodecRemoveBuffer or

CoreCodecEnsureBuffersNotConfigured, without needing to call is_remove_pending() (may still be

useful for asserts).

This is public to avoid the CodecAdapter needing to keep a redundant bool in VideoFrame,

CodecAdapterFrame, or CodecAdapterBufferContext.