DecoderThreading.hpp File Reference

Which of libavcodec's threading models a decoder runs, and how wide. More...

Detailed Description

Which of libavcodec's threading models a decoder runs, and how wide.

Frame threading works for any stream but delays output by one frame per thread and keeps a frame per thread alive. Slice threading adds no delay but only scales with the slices / tiles / rows of the bitstream (single-tile JPEG 2000: 6x slower than frame threads; ProRes: 1.7x faster).

libavcodec does not report how many slices a stream carries, so the choice uses the decoder's capabilities, the DecodeUseCase, and a list of formats whose bitstream mandates many slices per frame.

Go to the source code of this file.

Classes
struct	Video::DecoderThreading

Enumerations
enum class	Video::DecodeUseCase : uint8_t { Playback , FrameExact , Live , Thumbnail }
	What consumes the decoded frames, which sets how much delay is acceptable. More...

Functions
bool	Video::threading::sliceRich (const AVCodec &codec) noexcept
bool	Video::threading::ownPoolHasNoFrameDelay (const AVCodec &codec) noexcept
bool	Video::threading::ownPoolHasDelayOption (const AVCodec &codec) noexcept
	Wrappers whose pipelining can be switched off (libdav1d).
int	Video::threading::cpuCount () noexcept
int64_t	Video::threading::frameBytes (const AVCodecParameters *par) noexcept
int	Video::threading::frameThreads (const AVCodecParameters *par) noexcept
int	Video::threading::sliceThreads (const AVCodecParameters *par) noexcept
int	Video::threading::envThreadType (bool &set) noexcept
int	Video::threading::envThreadCount () noexcept
DecoderThreading	Video::chooseDecoderThreading (const AVCodec &codec, const AVCodecParameters *par, DecodeUseCase use, int userThreads=0, bool hardware=false) noexcept
void	Video::applyDecoderThreading (AVCodecContext &ctx, const DecoderThreading &t) noexcept
	Applies to a context allocated for its codec, before avcodec_open2.
std::string	Video::describeDecoderThreading (const AVCodecContext &ctx, const DecoderThreading &t)

Variables
constexpr int	Video::threading::max_frame_threads = 16
constexpr int	Video::threading::max_slice_threads = 64
constexpr int64_t	Video::threading::frame_memory_budget = int64_t(1) << 30
	Upper bound for the decoded frames frame threading keeps in flight.

Enumeration Type Documentation

DecodeUseCase

enum class Video::DecodeUseCase : uint8_t

strong

What consumes the decoded frames, which sets how much delay is acceptable.

Enumerator
Playback	Frames are queued ahead of display: throughput first, the queue absorbs the frame-threading delay.
FrameExact	A packet in must give its frame out (per-frame seeking, scrubbing).
Live	Cameras and network streams: any delay is visible latency.
Thumbnail	One frame is decoded, then the context is dropped.

Function Documentation

chooseDecoderThreading()

DecoderThreading Video::chooseDecoderThreading ( const AVCodec &  codec, const AVCodecParameters *  par, DecodeUseCase  use, int  userThreads = 0, bool  hardware = false  )

inlinenoexcept

Parameters

userThreads	a thread count the user asked for, 0 for automatic. It sets the width only: the model stays the policy's, since forcing slices on a single-slice stream would single-thread it.
hardware	the context decodes through a hardware device.

describeDecoderThreading()

std::string Video::describeDecoderThreading ( const AVCodecContext &  ctx, const DecoderThreading &  t  )

inline

One line for the log, from the context once avcodec_open2 succeeded: libavcodec may have narrowed the request.

envThreadType()

int Video::threading::envThreadType ( bool &  set )

inlinenoexcept

SCORE_VIDEO_THREADING=frame|slice|none|auto forces the model, SCORE_VIDEO_THREADS=N the count; for diagnosing a misbehaving codec.

ownPoolHasNoFrameDelay()

bool Video::threading::ownPoolHasNoFrameDelay ( const AVCodec &  codec )

inlinenoexcept

Wrappers whose own thread pool splits a frame (tiles, rows) rather than pipelining frames, and therefore never delays output.

sliceRich()

bool Video::threading::sliceRich ( const AVCodec &  codec )

inlinenoexcept

Formats whose bitstream mandates many independent units per frame, so that slice threads match or beat frame threads at no delay. Keyed by decoder name, which is stable across libavcodec versions where some codec ids are not.

Variable Documentation

max_frame_threads

constexpr int Video::threading::max_frame_threads = 16

inlineconstexpr

ffmpeg's own cap on automatic thread counts. Frame threads beyond it were measured slower, not faster, on 4K JPEG 2000.

max_slice_threads

constexpr int Video::threading::max_slice_threads = 64

inlineconstexpr

Slice threads do keep scaling past 16 on slice-rich formats (ProRes 4K: +30% from 16 to 32 threads).