Table of Contents

Class HevcStreamDecoder

Namespace
Egami.Heic
Assembly
Egami.Heic.dll

Decodes an HEVC (H.265) video stream an access unit at a time, as MP4, Matroska and raw .h265 files carry it: intra and inter pictures of the Main, Main 10, Main Still Picture, Main 12 and range extensions profiles to 12 bits, 4:0:0 to 4:4:4, with tiles, wavefronts and every inter tool. The pictures equal the HEVC reference decoder's (HM) sample for sample. Containers are not read here: Egami.Video reads them and uses this decoder, and any other source of HEVC access units can too.

public sealed class HevcStreamDecoder : IDisposable
Inheritance
HevcStreamDecoder
Implements
Inherited Members

Examples

// An HEVC stream from any source: Annex B here, or SetConfiguration with an MP4 track's hvcC and its samples.
using HevcStreamDecoder decoder = new(context: heic);
decoder.Send(File.ReadAllBytes("clip.h265"));
decoder.Flush();                                    // the end of the stream: the last pictures come out
int shown = 0;
while (decoder.NextFrame is HevcFrameInfo next)
{
    using YuvRaster<byte> frame = YuvRaster.Create(next.Width, next.Height, next.Chroma, YuvColor.Bt709Limited);
    decoder.TryReceiveFrame(frame, out HevcFrameInfo info);     // info.Poc, info.Kind, info.Color
    shown++;
}

Remarks

Send(ReadOnlySpan<byte>) takes the NAL units of one access unit or more: an Annex B byte stream (start codes), or after SetConfiguration(ReadOnlySpan<byte>) with an MP4 or Matroska hvcC record, NAL units each after a size field. Pictures come out in output order once the stream's reordering allows, through TryReceiveFrame(YuvRaster, out HevcFrameInfo); Flush() lets the rest out at the end of the stream.

Decoding starts at an IRAP picture (IDR, CRA or BLA); leading pictures of a CRA or BLA picture that starts the stream are left out, as the specification says. Only the base layer of a layered stream (Dolby Vision's enhancement layer, MV-HEVC) decodes. The decoder decodes a picture's tiles and wavefront rows on up to MaxParallelism threads and checks its size against the context's Limits. An instance is not thread-safe.

Constructors

HevcStreamDecoder(HevcDecoderOptions?, EgamiContext?)

Starts a stream.

public HevcStreamDecoder(HevcDecoderOptions? options = null, EgamiContext? context = null)

Parameters

options HevcDecoderOptions

How to decode; Default when null.

context EgamiContext

The threads and limits to use; Default when null.

Examples

// An HEVC stream from any source: Annex B here, or SetConfiguration with an MP4 track's hvcC and its samples.
using HevcStreamDecoder decoder = new(context: heic);
decoder.Send(File.ReadAllBytes("clip.h265"));
decoder.Flush();                                    // the end of the stream: the last pictures come out
int shown = 0;
while (decoder.NextFrame is HevcFrameInfo next)
{
    using YuvRaster<byte> frame = YuvRaster.Create(next.Width, next.Height, next.Chroma, YuvColor.Bt709Limited);
    decoder.TryReceiveFrame(frame, out HevcFrameInfo info);     // info.Poc, info.Kind, info.Color
    shown++;
}

Properties

NextFrame

Gets the information of the next frame TryReceiveFrame(YuvRaster, out HevcFrameInfo) gives, to size its raster, or null when there is none.

public HevcFrameInfo? NextFrame { get; }

Property Value

HevcFrameInfo?

Methods

Dispose()

Drops the pictures.

public void Dispose()

Flush()

Ends the stream: the last picture completes and every picture still waiting comes out.

public void Flush()

Reset()

Drops the pictures, decoded and waiting, and the parameter sets' pictures; the next data must start at an IRAP picture.

public void Reset()

Send(ReadOnlySpan<byte>)

Decodes NAL units: an Annex B byte stream, or after SetConfiguration(ReadOnlySpan<byte>) NAL units after size fields. Pictures that are ready in output order wait for TryReceiveFrame(YuvRaster, out HevcFrameInfo).

public void Send(ReadOnlySpan<byte> data)

Parameters

data ReadOnlySpan<byte>

Whole NAL units, of one access unit or more.

Exceptions

CorruptDataException

The data is broken.

UnsupportedFormatException

The stream uses a profile the decoder does not have (16-bit, High Throughput bypass alignment, separate colour planes).

LimitExceededException

A picture's size breaks the context's safety limits.

SetConfiguration(ReadOnlySpan<byte>)

Takes an MP4 or Matroska codec configuration record (hvcC, ISO/IEC 14496-15 8.3.3): its parameter sets, and the size of the NAL unit size fields that Send(ReadOnlySpan<byte>) then expects.

public void SetConfiguration(ReadOnlySpan<byte> hvcC)

Parameters

hvcC ReadOnlySpan<byte>

The record's bytes, from configurationVersion on.

Exceptions

CorruptDataException

The record is broken.

TryReceiveFrame(YuvRaster, out HevcFrameInfo)

Copies the next picture in output order into destination, cropped to its conformance window.

public bool TryReceiveFrame(YuvRaster destination, out HevcFrameInfo info)

Parameters

destination YuvRaster

A raster of the frame's size (NextFrame) and chroma format: 8-bit for an 8-bit stream, else 16-bit of the stream's bit depth. Its color is left as it is.

info HevcFrameInfo

What the frame was.

Returns

bool

True when a frame was copied; false when none is ready.

Exceptions

ArgumentException

destination does not match the frame.

Edit this page