Decoder

H264Decoder Class

The H264Decoder class provides an H.264 decoder based on Cisco's OpenH264 library. It allows you to decode H.264 video streams into YUV or RGB images.

Table of Contents

• Overview
• Constructors
• Properties
• Methods
• Decoding State
• Usage Examples
• Remarks

---

Overview

The H264Decoder class wraps the Cisco OpenH264 library to provide efficient H.264 decoding capabilities. It supports various initialization modes, runtime configuration adjustments, and decoding to different output image formats.

Features:

• Decodes H.264 streams to YUV 420P or RGB, BGR, RGBA or BGRA images.
• Supports runtime configuration adjustments (options).
• Provides multiple decoding methods for different scenarios.
• Implements IDisposable for proper resource management.

---

Constructors

Constructor	Description
H264Decoder()	Creates a new instance using the default Cisco DLL name defined in Defines.CiscoDllName. Will throw exception if library cant be found
H264Decoder(string ciscoDllPath)	Creates a new instance using the specified Cisco DLL path. Will throw exception if library cant be found

---

Properties

Property	Type	Description
EnableDebugPrints	bool	Enables or disables debug prints during initialization.

---

Methods

Method	Return Type	Description
Initialize()	int	Initializes decoder with default parameters.
Initialize(TagSVCDecodingParam param)	int	Initializes decoder with custom parameters.
GetOption<T>(DECODER_OPTION option, out T value)	bool	Gets a decoder option.
GetOptionRef<T>(DECODER_OPTION option, ref T value)	bool	Gets a decoder option, allowing reuse of the value.
SetOption<T>(DECODER_OPTION option, T value)	bool	Sets a decoder option.
Decode(byte[] encoded, int offset, int count, bool noDelay, out DecodingState state, out YUVImagePointer yuv)	bool	Decodes encoded data into YUV420Planar (YV12) image. Data is ephemeral, will be overwritten on next decode
Decode(EncodedData data, bool noDelay, out DecodingState state, out YUVImagePointer yuv)	bool	Decodes encoded data into YUV420Planar (YV12) image. Data is ephemeral, will be overwritten on next decode
Decode(EncodedData data, bool noDelay, out DecodingState state, ref YuvImage yuv)	bool	Decodes encoded data into provided YuvImage.
Decode(byte[] encoded, int offset, int count, bool noDelay, out DecodingState state, ref YuvImage yuv)	bool	Decodes encoded data into provided YuvImage memory.
Decode(EncodedData data, bool noDelay, out DecodingState state, ref RgbImage img)	bool	Decodes encoded data into an RGB image.
Decode(byte[] encoded, int offset, int count, bool noDelay, out DecodingState state, ref RgbImage img)	bool	Decodes encoded data into an RGB image.
Dispose()	void	Disposes of the decoder and releases native resources.

---

Decoding State Flags

Value	Name	Description	Category
0x00	dsErrorFree	bit stream error-free	Bitstream Parsing
0x01	dsFramePending	need more throughput to generate a frame output	Bitstream Parsing
0x02	dsRefLost	layer lost at reference frame with temporal id 0	Bitstream Parsing
0x04	dsBitstreamError	error bitstreams(maybe broken internal frame) the decoder cared	Bitstream Parsing
0x08	dsDepLayerLost	dependented layer is ever lost	Bitstream Parsing
0x10	dsNoParamSets	no parameter set NALs involved	Bitstream Parsing
0x20	dsDataErrorConcealed	current data error concealed specified	Bitstream Parsing
0x40	dsRefListNullPtrs	picure list contains null ptrs within uiRefCount range	Bitstream Parsing
0x1000	dsInvalidArgument	invalid argument specified	Logic Level
0x2000	dsInitialOptExpected	initializing operation is expected	Logic Level
0x4000	dsOutOfMemory	out of memory due to new request	Logic Level
0x8000	dsDstBufNeedExpan	actual picture size exceeds size of dst pBuffer feed in decoder, so need expand its size	Logic Level

---

Usage Examples

Creating and Initializing a Decoder

YUVImagePointer is ephemeral, refers to internal buffer, will be overwritten on next decode.

using (var decoder = new H264Decoder())
{
    decoder.Initialize(); // Initialize with default parameters

    byte[] buffer // some encoded data located
    int offset = 0 ;
    int count = 256;
    if (decoder.Decode(buffer, offset, count, noDelay: true, out DecodingState state, out YUVImagePointer  yuvPtr))
    {
        // Process YUV data
    }  
}

Decoding into RGB Image

Avoid creating new RgbImage for each decode, reuse it or pool it.

using (var decoder = new H264Decoder())
{
    decoder.Initialize();

    byte[] buffer // encoded data located
    int offset = 7 ;
    int count = 256;
    RgbImage rgbImage = new RgbImage(ImageFormat.Rgb, 1280, 720); // Create an RgbImage
    if (decoder.Decode(buffer, offset, count, noDelay: true, out DecodingState state, ref rgbImage))
    {
        // Process RGB image
    }
}

Remarks

Decode Return Value: * The return value of any Decode call indicates whether an image was produced on decode operation. * A return value of false signifies that no image was produced, and the referenced container (e.g., ref RgbImage img) remains unmodified.

• Decoding State :

  • The DecodingState enumerates decoder errors and status.
  • It is possible for a frame to yield dsErrorFree while returning false. This is expected and indicates that the decoder requires additional frames to produce a complete image.
  • It is crucial to check the DecodingState for error conditions, particularly in lossy transmission scenarios.
    • dsRefLost: Indicates a loss of reference. No further images will be produced until an IDR (Instantaneous Decoding Refresh) frame is received. The encoder should trigger an IDR frame using encoder.ForceIntraFrame().
    • dsDataErrorConcealed: Signifies that an image was produced despite data errors (artifacts). These errors can be corrected with an IDR frame or an LTR (Long-Term Reference) refresh if LTR is enabled.

• noDelay Option:

  • It is strongly recommended to set the noDelay option to true during decoding. This minimizes decoding latency.

• out YUVImagePointer yuv Parameter:

  • This parameter provides a pointer to the decoder's internal YUV buffer.
  • This buffer is ephemeral and will be overwritten on the next Decode call.
  • The Y plane has 64 bytes of padding, and the UV planes have 32 bytes of padding. Therefore, the strides will be 64 and 32 bytes larger than the respective widths.

• ref YuvImage yuv Parameter:

  • This parameter copies the Cisco native YUV image into the provided YuvImage instance, excluding any padding.

• ref RgbImage img Parameter:

  • This parameter converts the native YUV image into the specified RGB, BGR, RGBA, or BGRA format of the RgbImage instance.