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

Closed job intention: owned location reader, writer and tracks. More...

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

Classes

class  Policies
 Bitmask of Policy flags. More...
class  m_policies
 Intention flags. More...

Public Types

enum class  State : std::uint8_t {
  Created , Running , Finished , Failed ,
  Aborted
}
 Shared execution state of the pipeline plan. More...
enum class  Policy : std::uint32_t { None = 0 , EnforceFeatures = 1u << 0 }
 Job-intention flags. More...

Public Member Functions

enum State State () const noexcept
 Reads the synchronized execution state.
StormByte::Safe::Optional< StormByte::Safe::String > Error () const
 Copies the synchronized first failure reason.
 operator bool () const
 Same as Check having a value.
virtual CheckResult Check () const
 Whether this intention is well formed.
Lifecycle
 Plan (const StormByte::Safe::String &source, const StormByte::Safe::String &destination, StormByte::Safe::Optional< std::int64_t > duration={})
 Builds reader and writer from paths.
 Plan (const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration={})
 Builds a local reader and takes writer.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, StormByte::Safe::Optional< std::int64_t > duration={})
 Takes reader and builds a local writer.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration={})
 Takes both location owners without slicing.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, StormByte::Safe::Optional< std::int64_t > duration, const StormByte::Safe::Function< void(double)> *progress)
 Takes both owners and observes automatic duration resolution.
 Plan (const StormByte::Safe::String &source, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
 Builds local locations with an owned explicit container copy.
 Plan (const StormByte::Safe::String &source, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
 Builds a local reader and owns the writer and a container copy.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, const StormByte::Safe::String &destination, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
 Owns the reader and a container copy and builds a local writer.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration={})
 Owns both locations and a copy of the explicit destination identity.
 Plan (StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader, StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer, const class Container &container, StormByte::Safe::Optional< std::int64_t > duration, const StormByte::Safe::Function< void(double)> *progress)
 Owns locations and a container copy while observing duration resolution.
 Plan (const Plan &other)=delete
 Copy construction is not supported.
 Plan (Plan &&other) noexcept=delete
 Move construction is not supported; stages retain shared ownership.
virtual ~Plan () noexcept
 Destructor.
Plan & operator= (const Plan &other)=delete
 Copy assignment is not supported.
Plan & operator= (Plan &&other) noexcept=delete
 Move assignment is not supported; stages retain shared ownership.
Job
StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > InputTelemetry () const noexcept
 Shared telemetry for the owned input reader.
StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > OutputTelemetry () const noexcept
 Shared telemetry for the owned output writer.
void add (const Track &track)
 Appends a clone of track.
void add (Track &&track)
 Appends track.
const class Tracks & Tracks () const noexcept
 Tube tracks.
const class Policies & Policies () const noexcept
 Active intention flags.
void Policies (enum Policy policy) noexcept
 Adds policy, or clears it when passed as ~policy.
constexpr ResourceUsage Resources () const noexcept
 Resource policy carried by this plan.
void Resources (ResourceUsage usage) noexcept
 Sets the resource policy before pipeline stages bind.
const BufferingPolicy & Buffering () const noexcept
 Queue capacity policy shared with manually mounted pipelines.
bool Buffering (const BufferingPolicy &policy) noexcept
 Set queue capacity overrides before stages start.

Static Public Member Functions

static constexpr const char * ToString (enum Policy policy) noexcept
 Converts a Policy to a stable token.

Friends

class Demuxer
 Allows the input stage to consume source data.
class Decoder
 Allows decoder snapshot consultation.
class Encoder
 Allows encoder track consultation.
class Remuxer
 Allows remux snapshot consultation.
class Muxer
 Allows the output stage to consume destination data.
class Filters
 Allows filter matching against the source snapshot.
class Backend::Pipeline::Demuxer
 Allows backend source restoration.
class Backend::Pipeline::Ceiling
 Allows backend capacity calculation.
class Backend::Pipeline::Detail::Muxer::FFmpeg::Container
 Allows muxing with the resolved FFmpeg identity.
class Step
 Allows stages to register state notifications.
class Filter::FFmpeg
class Route
 Allows private route snapshot consultation.
class Transcoder
 Allows the public facade to publish failure and cancellation.
class Backend::Pipeline::Transcoder
 Allows the backend coordinator to publish execution state.
constexpr enum Policy operator~ (enum Policy policy) noexcept
 Bitwise complement of one flag, for Policies(Policy).

Detailed Description

Closed job intention: owned location reader, writer and tracks.

Octets are held as StormByte::Safe::Unique of the location bases. Paths build local BufferedFile leaves; supplied owners retain their dynamic types without slicing. The constructor probes the reader once into a consultation File snapshot (streams, attachments, metadata). That File is not the octet origin. Progress uses a positive explicit duration or the container estimate. Only when neither is usable is the full source scanned before pipeline stages are created. Explicit File::Duration() queries retain their full-scan behavior.

Destination container is an owned copy of an explicit identity, or the registry identity matched to FFmpeg's filename guess. Explicit identities ignore the filename when selecting the muxer. Stages retain this noncopyable, nonmovable intention exclusively through StormByte::Safe::Shared.

Mux output order is the order of add. add is not idempotent. A track omitted from Tracks is dropped.

Check tests formation of this intention only. Success does not mean the tube will run. Boolean conversion reports whether Check succeeds. Policy::EnforceFeatures, set on construction, makes Check reject an encode that would drop source features. Policies(Policy) adds a flag. Policies with ~flag clears that flag. Neither call replaces the rest of the mask.

Member Enumeration Documentation

◆ Policy

enum class StormByte::Multimedia::Pipeline::Plan::Policy : std::uint32_t
strong

Job-intention flags.

Bits must be disjoint; Has() is a bitmask test.

None is zero and is not a policy. EnforceFeatures is the first flag. Further policies take the next free bit.

Enumerator
None 

No flags.

EnforceFeatures 

Check rejects an encode that drops source features.

◆ State

enum class StormByte::Multimedia::Pipeline::Plan::State : std::uint8_t
strong

Shared execution state of the pipeline plan.

Enumerator
Created 

Constructed and not yet running.

Running 

Pipeline execution has started.

Finished 

Pipeline execution completed successfully.

Failed 

Pipeline formation or execution failed.

Aborted 

Intentional cancellation; a genuine in-flight failure may still win.

Constructor & Destructor Documentation

◆ Plan() [1/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( const StormByte::Safe::String & source,
const StormByte::Safe::String & destination,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Builds reader and writer from paths.

Parameters
sourceInput path.
destinationOutput path.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [2/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( const StormByte::Safe::String & source,
StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Builds a local reader and takes writer.

Parameters
sourceInput path.
writerOwned output location (moved).
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [3/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader,
const StormByte::Safe::String & destination,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Takes reader and builds a local writer.

Parameters
readerOwned input location (moved).
destinationOutput path.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [4/12]

Takes both location owners without slicing.

Parameters
readerOwned input location (moved).
writerOwned output location (moved).
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [5/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader,
StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer,
StormByte::Safe::Optional< std::int64_t > duration,
const StormByte::Safe::Function< void(double)> * progress )

Takes both owners and observes automatic duration resolution.

Parameters
readerOwned input location.
writerOwned output location.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.
progressBorrowed observer for this call only; null disables updates.

◆ Plan() [6/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( const StormByte::Safe::String & source,
const StormByte::Safe::String & destination,
const class Container & container,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Builds local locations with an owned explicit container copy.

Parameters
sourceInput path.
destinationOutput path; its suffix does not select the format.
containerRegistered writable destination identity to copy.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [7/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( const StormByte::Safe::String & source,
StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer,
const class Container & container,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Builds a local reader and owns the writer and a container copy.

Parameters
sourceInput path.
writerOwned output location.
containerRegistered writable destination identity to copy.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [8/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader,
const StormByte::Safe::String & destination,
const class Container & container,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Owns the reader and a container copy and builds a local writer.

Parameters
readerOwned input location.
destinationOutput path; its suffix does not select the format.
containerRegistered writable destination identity to copy.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [9/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader,
StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer,
const class Container & container,
StormByte::Safe::Optional< std::int64_t > duration = {} )

Owns both locations and a copy of the explicit destination identity.

Parameters
readerOwned input location.
writerOwned output location.
containerRegistered writable destination identity to copy.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.

◆ Plan() [10/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationReader > reader,
StormByte::Safe::Unique< StormByte::Buffer::IO::BufferedLocationWriter > writer,
const class Container & container,
StormByte::Safe::Optional< std::int64_t > duration,
const StormByte::Safe::Function< void(double)> * progress )

Owns locations and a container copy while observing duration resolution.

Parameters
readerOwned input location.
writerOwned output location.
containerRegistered writable destination identity to copy.
durationAuthoritative nanoseconds; otherwise use the container estimate, scanning only if unavailable.
progressBorrowed duration observer; null disables updates.

◆ Plan() [11/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( const Plan & other)
delete

Copy construction is not supported.

Parameters
otherSource plan.

◆ Plan() [12/12]

StormByte::Multimedia::Pipeline::Plan::Plan ( Plan && other)
deletenoexcept

Move construction is not supported; stages retain shared ownership.

Parameters
otherSource plan.

◆ ~Plan()

virtual StormByte::Multimedia::Pipeline::Plan::~Plan ( )
virtualnoexcept

Destructor.

Member Function Documentation

◆ add() [1/2]

void StormByte::Multimedia::Pipeline::Plan::add ( const Track & track)
inline

Appends a clone of track.

Not idempotent.

Parameters
trackTrack to copy.

◆ add() [2/2]

void StormByte::Multimedia::Pipeline::Plan::add ( Track && track)
inline

Appends track.

Not idempotent. Order is mux order.

Parameters
trackTrack to take.

◆ Buffering() [1/2]

const BufferingPolicy & StormByte::Multimedia::Pipeline::Plan::Buffering ( ) const
noexcept

Queue capacity policy shared with manually mounted pipelines.

Returns
The policy configured for this plan.

◆ Buffering() [2/2]

bool StormByte::Multimedia::Pipeline::Plan::Buffering ( const BufferingPolicy & policy)
noexcept

Set queue capacity overrides before stages start.

Parameters
policyAutomatic, bounded, or unlimited queue element caps.
Returns
False when a bounded cap is below its functional minimum or the plan has already started.

◆ Check()

virtual CheckResult StormByte::Multimedia::Pipeline::Plan::Check ( ) const
virtual

Whether this intention is well formed.

Publishes Failed and preserves the first reason on validation failure. Construction validates locations and format separately, without tracks. Fails when: either location owner is empty; the constructor snapshot failed; no registered buffered muxer resolves; Tracks is empty; Track::In is negative; Track::Type is Type::Unknown; an attachment MIME is empty or is not an exact type/subtype, a type-star category, or star-star (all). Duplicate Track::In is allowed. Encode knobs on a remux track (Codec() == nullptr) are ignored. With Policy::EnforceFeatures, an encode whose destination codec has no implementation that keeps the source HDR10, HDR10+ or Dolby Vision features also fails. Other checks run either way.

Returns
Empty value, or PlanException.

◆ Error()

StormByte::Safe::Optional< StormByte::Safe::String > StormByte::Multimedia::Pipeline::Plan::Error ( ) const

Copies the synchronized first failure reason.

Returns
Failure message, if one has been provided.

◆ InputTelemetry()

StormByte::Safe::Shared< StormByte::Buffer::ReadTelemetry > StormByte::Multimedia::Pipeline::Plan::InputTelemetry ( ) const
noexcept

Shared telemetry for the owned input reader.

Returns
Shared handle. Retain it to inspect final I/O counters after this Plan dies.

◆ operator bool()

StormByte::Multimedia::Pipeline::Plan::operator bool ( ) const
explicit

Same as Check having a value.

Returns
true if this intention is well formed.

◆ operator=() [1/2]

Plan & StormByte::Multimedia::Pipeline::Plan::operator= ( const Plan & other)
delete

Copy assignment is not supported.

Parameters
otherSource plan.
Returns
This plan.

◆ operator=() [2/2]

Plan & StormByte::Multimedia::Pipeline::Plan::operator= ( Plan && other)
deletenoexcept

Move assignment is not supported; stages retain shared ownership.

Parameters
otherSource plan.
Returns
This plan.

◆ OutputTelemetry()

StormByte::Safe::Shared< StormByte::Buffer::WriteTelemetry > StormByte::Multimedia::Pipeline::Plan::OutputTelemetry ( ) const
noexcept

Shared telemetry for the owned output writer.

Returns
Shared handle. Retain it to inspect final I/O counters after this Plan dies.

◆ Policies() [1/2]

const class Policies & StormByte::Multimedia::Pipeline::Plan::Policies ( ) const
inlinenoexcept

Active intention flags.

Returns
Mask. EnforceFeatures is set at construction.

◆ Policies() [2/2]

void StormByte::Multimedia::Pipeline::Plan::Policies ( enum Policy policy)
inlinenoexcept

Adds policy, or clears it when passed as ~policy.

Parameters
policyFlag to add, or the complement from operator~(Policy).

A value that only has defined bits is added. Other flags stay set. ~Policy::EnforceFeatures clears only that flag. This does not replace the mask and does not take Policies.

◆ Resources() [1/2]

ResourceUsage StormByte::Multimedia::Pipeline::Plan::Resources ( ) const
inlineconstexprnoexcept

Resource policy carried by this plan.

Returns
Best-effort policy, defaulting to ResourceUsage::Full.

◆ Resources() [2/2]

void StormByte::Multimedia::Pipeline::Plan::Resources ( ResourceUsage usage)
inlinenoexcept

Sets the resource policy before pipeline stages bind.

Parameters
usageBest-effort CPU and in-memory frame queue policy.

◆ State()

Reads the synchronized execution state.

Returns
Current plan state.

◆ ToString()

constexpr const char * StormByte::Multimedia::Pipeline::Plan::ToString ( enum Policy policy)
inlinestaticconstexprnoexcept

Converts a Policy to a stable token.

Parameters
policyPolicy value.
Returns
Literal. Unknown bits return "UnknownPolicy".

◆ Tracks()

const class Tracks & StormByte::Multimedia::Pipeline::Plan::Tracks ( ) const
inlinenoexcept

Tube tracks.

Index is mux slot.

Returns
Track list.

◆ Backend::Pipeline::Ceiling

friend class Backend::Pipeline::Ceiling
friend

Allows backend capacity calculation.

◆ Backend::Pipeline::Demuxer

friend class Backend::Pipeline::Demuxer
friend

Allows backend source restoration.

◆ Backend::Pipeline::Detail::Muxer::FFmpeg::Container

friend class Backend::Pipeline::Detail::Muxer::FFmpeg::Container
friend

Allows muxing with the resolved FFmpeg identity.

◆ Backend::Pipeline::Transcoder

friend class Backend::Pipeline::Transcoder
friend

Allows the backend coordinator to publish execution state.

◆ Decoder

friend class Decoder
friend

Allows decoder snapshot consultation.

◆ Demuxer

friend class Demuxer
friend

Allows the input stage to consume source data.

◆ Encoder

friend class Encoder
friend

Allows encoder track consultation.

◆ Filter::FFmpeg

friend class Filter::FFmpeg
friend

◆ Filters

friend class Filters
friend

Allows filter matching against the source snapshot.

◆ Muxer

friend class Muxer
friend

Allows the output stage to consume destination data.

◆ operator~

enum Policy operator~ ( enum Policy policy)
friend

Bitwise complement of one flag, for Policies(Policy).

Parameters
policyFlag to negate.
Returns
Policy whose defined bits are inverted.

Policies(~Policy::EnforceFeatures) clears that flag and leaves every other flag as it was.

◆ Remuxer

friend class Remuxer
friend

Allows remux snapshot consultation.

◆ Route

friend class Route
friend

Allows private route snapshot consultation.

◆ Step

friend class Step
friend

Allows stages to register state notifications.

◆ Transcoder

friend class Transcoder
friend

Allows the public facade to publish failure and cancellation.


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