StormByte-Multimedia 3.3.2
C++26 multimedia processing module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Multimedia::Pipeline::Frame Class Reference

One decoded access unit. More...

#include <StormByte/multimedia/pipeline/frame.hxx>

Inheritance diagram for StormByte::Multimedia::Pipeline::Frame:
Collaboration diagram for StormByte::Multimedia::Pipeline::Frame:

Public Types

using PointerType = StormByte::Safe::Shared<Frame>
 Base-heap shared owner of a frame; keep its providers loaded.

Public Member Functions

Construction
 Frame ()
 Empty frame.
 Frame (int track, enum StormByte::Multimedia::Type type, enum Producer producer, StormByte::Buffer::FIFO payload, StormByte::Safe::Optional< Property::Duration > pts, StormByte::Safe::Optional< Property::Duration > duration, StormByte::Safe::Optional< Property::Video > video, StormByte::Safe::Vector< class SideData > attachments, StormByte::Safe::Optional< Property::Audio > audio, std::uint64_t serial, std::uint64_t part)
 Builds a frame from supplied media bytes and properties.
 Frame (const Frame &other)
 Copy.
 Frame (Frame &&other) noexcept
 Move constructor.
 ~Frame () noexcept override
 Destructor.
Frame & operator= (const Frame &other)
 Copy assignment.
Frame & operator= (Frame &&other) noexcept
 Move assignment.
Timing and identity
const StormByte::Safe::Optional< Property::Duration > & Pts () const noexcept
 Presentation timestamp on the stream clock.
const StormByte::Safe::Optional< Property::Duration > & Dts () const noexcept
 Decode timestamp on the stream clock.
const StormByte::Safe::Optional< Property::Duration > & Duration () const noexcept
 Frame duration on the stream clock.
const StormByte::Safe::Optional< StormByte::Safe::String > & Language () const noexcept
 Stream language tag copied from File metadata.
const StormByte::Safe::Optional< StormByte::Safe::String > & Title () const noexcept
 Stream title tag copied from File metadata.
Lineage
const StormByte::Safe::Optional< std::uint64_t > & Serial () const noexcept
 Monotonic lineage id assigned when the unit enters the pipe.
std::uint64_t Part () const noexcept
 Sub-id inside Serial when one demuxed unit yields several frames.
Properties
const StormByte::Safe::Optional< Property::Video > & Video () const noexcept
 Video properties (includes HDR10 when set).
const StormByte::Safe::Optional< Property::Audio > & Audio () const noexcept
 Audio properties (layout, rate, channels).
const StormByte::Safe::Vector< class SideData > & Attachments () const noexcept
 Raw side data captured at receive.
Payload
StormByte::Buffer::FIFO & Payload () noexcept
 Payload.
const StormByte::Buffer::FIFO & Payload () const noexcept
 Payload already materialised, or empty.
StormByte::ByteSize BufferingWeight () const noexcept
 Estimates the retained media payload weight for queue accounting.
Public Member Functions inherited from StormByte::Multimedia::Pipeline::Item
Kind Kind () const noexcept
 Whether this unit is a frame or a packet.
enum StormByte::Multimedia::Type Type () const noexcept
 Media of this access unit.
int Track () const noexcept
 Origin track index.
enum Producer Producer () const noexcept
 Stage that created this unit.
virtual ~Item () noexcept=default
 Destructor.

Friends

class Backend::Pipeline::Frame
 Allows the backend holder to access the frame's media storage.
class Decoder
 Allows the decoder to populate decoded media and metadata.
class Encoder
 Allows the encoder to access the backend frame.
class Filter::FFmpeg
 Allows FFmpeg filters to update decoded media and metadata.
Decoder & operator>> (Decoder &decoder, Frame &frame) noexcept
 Allows the extraction operator to fill a frame from a decoder.
Frame & operator>> (Frame &frame, Encoder &encoder) noexcept
 Allows the insertion operator to submit a frame to an encoder.

Additional Inherited Members

Protected Types inherited from StormByte::Safe::Clonable< Item >
typedef SmartPointer PointerType
 Item (const Item &other) noexcept=default
 Copy constructor.
 Item (Item &&other) noexcept=default
 Move constructor.
Item & operator= (const Item &other) noexcept=default
 Copy assignment.
Item & operator= (Item &&other) noexcept=default
 Move assignment.
Protected Member Functions inherited from StormByte::Safe::Clonable< Item >
constexpr Clonable ()=default
constexpr Clonable & operator= (const Clonable &)=default
virtual constexpr ~Clonable () noexcept=default
Static Protected Member Functions inherited from StormByte::Safe::Clonable< Item >
static PointerType MakePointer (Args &&... args)

Detailed Description

One decoded access unit.

One picture or one block of decoded samples, consumed by process and analytics filters and Encoder. Provides pixels or samples, timestamps and the stream tags the decoder copied across.

Copies and Clone share media buffers rather than duplicating pixels or samples. Metadata accessors borrow their wrappers until this frame is modified or destroyed. Safe optional arrow access returns a read-only snapshot for the current full expression, not a stable pointer into the frame.

See also
Item
Packet

Member Typedef Documentation

◆ PointerType

Base-heap shared owner of a frame; keep its providers loaded.

Constructor & Destructor Documentation

◆ Frame() [1/4]

Empty frame.

Item::Type is StormByte::Multimedia::Type::Unknown. Item::Track is -1. Item::Kind is Kind::Frame.

Exceptions
StormByte::ExceptionIf safe metadata storage cannot be allocated.

◆ Frame() [2/4]

Builds a frame from supplied media bytes and properties.

Parameters
trackOrigin container stream index.
typeMedia of this unit (Video, Audio or Subtitle).
producerStep that created this unit.
payloadOwned sample / plane bytes.
ptsPresentation timestamp, if known.
durationFrame duration, if known.
videoVideo properties, if this is a video frame.
attachmentsRaw side-data blobs.
audioAudio properties, if this is an audio frame.
serialLineage id born at the demuxer for this origin track.
partSub-id inside serial. Zero when the demuxed unit did not split.

Dts starts empty. Decoder stamps it from the packet that produced this frame. There is no public setter.

Exceptions
StormByte::ExceptionIf safe metadata storage cannot be allocated.

◆ Frame() [3/4]

Copy.

Metadata and FIFO handle are copied; the libav frame is referenced (av_frame_ref).

Parameters
otherSource frame.

Not a deep copy of planes. Clone uses this constructor. Filter::FFmpeg::Save still emits a new frame when a filter paints.

Exceptions
StormByte::ExceptionIf safe metadata storage cannot be copied.
std::bad_allocIf the private backend holder cannot be allocated.

◆ Frame() [4/4]

Move constructor.

Parameters
otherFrame to take.

Container-safe: other becomes the empty sentinel (Item::Type Unknown, track -1, no media). ~Frame on a moved-from object is a no-op.

◆ ~Frame()

StormByte::Multimedia::Pipeline::Frame::~Frame ( )
overridenoexcept

Destructor.

Member Function Documentation

◆ Attachments()

const StormByte::Safe::Vector< class SideData > & StormByte::Multimedia::Pipeline::Frame::Attachments ( ) const
inlinenoexcept

Raw side data captured at receive.

Read-only.

Returns
Blobs. MDM/CLL also appear in Video() HDR10 when the decoder could map them.

◆ Audio()

const StormByte::Safe::Optional< Property::Audio > & StormByte::Multimedia::Pipeline::Frame::Audio ( ) const
inlinenoexcept

Audio properties (layout, rate, channels).

Returns
Audio, or empty.

◆ BufferingWeight()

StormByte::ByteSize StormByte::Multimedia::Pipeline::Frame::BufferingWeight ( ) const
noexcept

Estimates the retained media payload weight for queue accounting.

Returns
Bytes from FFmpeg plane strides or the materialized payload.

This is a logical estimate, not RSS or uniquely-owned physical memory. Cloned frames may share the same FFmpeg planes.

◆ Dts()

const StormByte::Safe::Optional< Property::Duration > & StormByte::Multimedia::Pipeline::Frame::Dts ( ) const
inlinenoexcept

Decode timestamp on the stream clock.

Copied by Decoder from the compressed packet that produced this frame. Empty when that packet had no Dts, or when the unit was not stamped. There is no public setter.

Returns
Dts, or empty.

◆ Duration()

const StormByte::Safe::Optional< Property::Duration > & StormByte::Multimedia::Pipeline::Frame::Duration ( ) const
inlinenoexcept

Frame duration on the stream clock.

Returns
Duration, or empty.

◆ Language()

const StormByte::Safe::Optional< StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Frame::Language ( ) const
inlinenoexcept

Stream language tag copied from File metadata.

Returns
Language, or empty if the stream had none.

◆ operator=() [1/2]

Frame & StormByte::Multimedia::Pipeline::Frame::operator= ( const Frame & other)

Copy assignment.

Same as the copy constructor.

Parameters
otherSource frame.
Returns
*this.
Note
The destination is unchanged if copying fails.
Exceptions
StormByte::ExceptionIf safe metadata storage cannot be copied.
std::bad_allocIf the private backend holder cannot be allocated.

◆ operator=() [2/2]

Frame & StormByte::Multimedia::Pipeline::Frame::operator= ( Frame && other)
noexcept

Move assignment.

Parameters
otherFrame to take.
Returns
*this.

Same as the move constructor: other is left empty.

◆ Part()

std::uint64_t StormByte::Multimedia::Pipeline::Frame::Part ( ) const
inlinenoexcept

Sub-id inside Serial when one demuxed unit yields several frames.

Returns
Zero when the unit did not split; 0, 1, … after a split.

Downstream stages copy this value. It is not a pipe-wide counter.

◆ Payload() [1/2]

const StormByte::Buffer::FIFO & StormByte::Multimedia::Pipeline::Frame::Payload ( ) const
inlinenoexcept

Payload already materialised, or empty.

Returns
FIFO. Does not materialize decoded media bytes.

◆ Payload() [2/2]

StormByte::Buffer::FIFO & StormByte::Multimedia::Pipeline::Frame::Payload ( )
noexcept

Payload.

Materializes decoded media bytes on first access.

Returns
FIFO.

Materialization preserves the decoded media. Filtering that replaces the media invalidates the previously materialized bytes.

◆ Pts()

const StormByte::Safe::Optional< Property::Duration > & StormByte::Multimedia::Pipeline::Frame::Pts ( ) const
inlinenoexcept

Presentation timestamp on the stream clock.

Returns
Pts, or empty.

◆ Serial()

const StormByte::Safe::Optional< std::uint64_t > & StormByte::Multimedia::Pipeline::Frame::Serial ( ) const
inlinenoexcept

Monotonic lineage id assigned when the unit enters the pipe.

Returns
Serial born at the demuxer for this origin track; empty on the sentinel.

This is not a decoded-frame count and not an FFmpeg nb_frames / nb_read_frames figure. It identifies one demuxed access unit as it travels Demuxer → … → Muxer. Downstream stages copy it. Part distinguishes several frames born from the same serial.

◆ Title()

const StormByte::Safe::Optional< StormByte::Safe::String > & StormByte::Multimedia::Pipeline::Frame::Title ( ) const
inlinenoexcept

Stream title tag copied from File metadata.

Returns
Title, or empty if the stream had none.

◆ Video()

const StormByte::Safe::Optional< Property::Video > & StormByte::Multimedia::Pipeline::Frame::Video ( ) const
inlinenoexcept

Video properties (includes HDR10 when set).

Returns
Video, or empty.

◆ Backend::Pipeline::Frame

friend class Backend::Pipeline::Frame
friend

Allows the backend holder to access the frame's media storage.

◆ Decoder

friend class Decoder
friend

Allows the decoder to populate decoded media and metadata.

◆ Encoder

friend class Encoder
friend

Allows the encoder to access the backend frame.

◆ Filter::FFmpeg

friend class Filter::FFmpeg
friend

Allows FFmpeg filters to update decoded media and metadata.

◆ operator>> [1/2]

Decoder & operator>> ( Decoder & decoder,
Frame & frame )
friend

Allows the extraction operator to fill a frame from a decoder.

Parameters
decoderDecoder supplying decoded media.
frameDestination frame.
Returns
Decoder supplying the frame.

◆ operator>> [2/2]

Frame & operator>> ( Frame & frame,
Encoder & encoder )
friend

Allows the insertion operator to submit a frame to an encoder.

Parameters
frameFrame supplying decoded media.
encoderEncoder receiving the frame.
Returns
Submitted frame.

The documentation for this class was generated from the following file:
  • lib/public/StormByte/multimedia/pipeline/frame.hxx