frame

Documentation

Overview

Package frame defines decoded frames shared between analyzers.

A frame is decoded once and fanned out to every analyzer: it is reference counted and its buffers return to a pool when the last user releases it.

Index

• type Frame
  • func (f *Frame) Release()
  • func (f *Frame) Retain()
• type Plane
  • func (p *Plane) Row(y int) []byte
  • func (p *Plane) Uint16() []uint16
• type Pool
  • func NewPool(width, height int, opts PoolOptions) *Pool
  • func (p *Pool) BuildThumb(f *Frame)
  • func (p *Pool) Chroma() bool
  • func (p *Pool) Get() *Frame
  • func (p *Pool) GridSize() [2]int
  • func (p *Pool) Height() int
  • func (p *Pool) HighBitDepth() bool
  • func (p *Pool) Planes(f *Frame) []*Plane
  • func (p *Pool) SamplePlanes(f *Frame) []*Plane
  • func (p *Pool) SampleStep() int
  • func (p *Pool) Width() int
• type PoolOptions
• type Samples

Types

type Frame

type Frame struct {
	Index int
	PTS   media.Duration
	Luma  Plane
	Cb    Plane
	Cr    Plane
	Thumb Plane
	// Samples is a sparse grid of the decoded 10-bit Y′CbCr samples, when
	// the pool keeps one (PoolOptions.SampleStep): the colour and light of
	// an HDR frame, next to its 8-bit luma.
	Samples Samples
	// contains filtered or unexported fields
}

Frame is a decoded picture. Luma is the full-resolution luma plane; Cb and Cr are the 4:2:0 chroma planes when the pool carries chroma. Thumb is a small box-filtered copy of the luma computed once for cheap analyzers (scene cuts, black, freeze, crop) when the pool builds thumbnails.

func (*Frame) Release

func (f *Frame) Release()

Release drops a reference and recycles the frame when none remain. Frames that do not come from a Pool are simply left to the garbage collector.

func (*Frame) Retain

func (f *Frame) Retain()

Retain adds a reference. Every Retain must be paired with a Release.

type Plane

type Plane struct {
	Width          int
	Height         int
	Stride         int
	BytesPerSample int
	Pix            []byte
}

Plane is an image plane of 8-bit samples, or of 16-bit little-endian samples when BytesPerSample is 2. Stride is in bytes.

func (*Plane) Row

func (p *Plane) Row(
	y int,
) []byte

Row returns the bytes of row y.

func (*Plane) Uint16

func (p *Plane) Uint16() []uint16

Uint16 sees a plane of 16-bit samples as a slice of samples, without copying it: row y starts at y·Stride/2. Like the libvmaf binding and quality/xpsnr, it relies on a little-endian host (arm64, amd64), where the bytes of ffmpeg's little-endian rawvideo are the samples.

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool recycles frames of a fixed geometry to avoid per-frame allocations.

func NewPool

func NewPool(
	width, height int,
	opts PoolOptions,
) *Pool

NewPool returns a pool for width×height frames.

func (*Pool) BuildThumb

func (p *Pool) BuildThumb(
	f *Frame,
)

BuildThumb fills f.Thumb from f.Luma with a box filter. It is a no-op when the pool has no thumbnails.

func (*Pool) Chroma

func (p *Pool) Chroma() bool

Chroma reports whether frames carry chroma planes.

func (*Pool) Get

func (p *Pool) Get() *Frame

Get returns a frame holding one reference.

func (*Pool) GridSize

func (p *Pool) GridSize() [2]int

GridSize is the width and height of the sample grid of pooled frames: one point per cell of SampleStep pixels, partial cells included.

func (*Pool) Height

func (p *Pool) Height() int

Height is the luma height of pooled frames.

func (*Pool) HighBitDepth

func (p *Pool) HighBitDepth() bool

HighBitDepth reports whether samples are stored on 16 bits.

func (*Pool) Planes

func (p *Pool) Planes(
	f *Frame,
) []*Plane

Planes returns the planes of f in raw video order (Y, then Cb and Cr when the pool carries chroma).

func (*Pool) SamplePlanes

func (p *Pool) SamplePlanes(
	f *Frame,
) []*Plane

SamplePlanes returns the planes of the sample grid of f in raw video order (Y, Cb, Cr), as a sampling pool's decoder reads them.

func (*Pool) SampleStep

func (p *Pool) SampleStep() int

SampleStep is the spacing of the sample grid of pooled frames, 0 when they have none (see PoolOptions.SampleStep).

func (*Pool) Width

func (p *Pool) Width() int

Width is the luma width of pooled frames.

type PoolOptions

type PoolOptions struct {
	// ThumbMaxWidth enables thumbnails: the luma is downscaled by the smallest
	// integer factor that brings its width to at most ThumbMaxWidth.
	ThumbMaxWidth int
	// Chroma adds 4:2:0 Cb and Cr planes.
	Chroma bool
	// HighBitDepth stores samples on 16 bits (10-bit video); thumbnails
	// are not available then.
	HighBitDepth bool
	// SampleStep, when positive, gives the frames of the pool, next to
	// their 8-bit luma (the pixel analyzers'), a grid of 10-bit Y′CbCr
	// samples (Samples) of one point per SampleStep×SampleStep cell
	// (rounded up to an even step), for the light analyzer. Chroma and
	// HighBitDepth are ignored then.
	SampleStep int
}

PoolOptions selects what a pooled frame carries. The zero value is luma only.

type Samples

type Samples struct {
	Step      int
	Y, Cb, Cr Plane
}

Samples holds the 10-bit Y′CbCr samples of a grid of points of a frame, one per Step×Step cell of luma pixels: the pixel at the centre of the cell (Step/2 right and down of its corner) and the chroma sample covering it, as ffmpeg's neighbour scaler picks them. Planes store 16-bit little-endian samples, the three at the grid's size.