Encoder

H264Encoder Class

The H264Encoder class provides an H.264 encoder based on Cisco's OpenH264 library. It allows you to encode RGB and YUV images into H.264 video streams.

Table of Contents

• Overview
• Constructors
• Properties
• Methods
• Usage Examples
• Premade Configurations
• Remarks

---

Overview

The H264Encoder class wraps the Cisco OpenH264 library and acts as a facade for ease of use. It supports various initialization modes, runtime configuration adjustments, and different input image formats.

Features:

• Encodes RGB,BGR,RGBA,BGRA and YUV(I420Planar or NV12 interleaved) images to H.264.
• Supports runtime configuration adjustments (bitrate, FPS, options).
• Provides multiple initialization methods for different scenarios.
• Implements IDisposable for proper resource management.

---

Constructors

Constructor	Description
H264Encoder()	Creates a new instance using the default Cisco DLL name which is defined in. Defines.CiscoDllName Will throw exception if library cant be found.
H264Encoder(string ciscoDllPath)	Creates a new instance using the specified Cisco DLL path.(LoadLibraryW on windows,dlopen with RTLD_LAZY on linux)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
GetDefaultParameters()	TagEncParamExt	Retrieves the default advanced configuration parameters.
Initialize(int width, int height, int bitrate, int fps, ConfigType configType)	int	Initializes the encoder with basic parameters and a pre-configured configuration type.
Initialize(TagEncParamBase param)	int	Initializes the encoder with base encoding parameters.
Initialize(TagEncParamExt param)	int	Initializes the encoder with advanced encoding parameters.
ForceIntraFrame()	bool	Forces an intra frame(IDR) on the next encode.
SetMaxBitrate(int target)	void	Sets the maximum bitrate.
SetTargetFps(float target)	void	Sets the target frames per second.
GetOption<T>(ENCODER_OPTION option, out T value)	bool	Gets an encoder option.
GetOptionRef<T>(ENCODER_OPTION option, ref T value)	bool	Gets an encoder option, allowing reuse of the value.
SetOption<T>(ENCODER_OPTION option, T value)	bool	Sets an encoder option.
Encode(RgbImage im, out EncodedData[] ed)	bool	Encodes an RGB image.
Encode(YUVNV12ImagePointer yuv, out EncodedData[] ed)	bool	Encodes a YUV NV12 image.
Encode(YUVImagePointer yuv, out EncodedData[] ed)	bool	Encodes a YUV I420P image.
Encode(YuvImage yuv, out EncodedData[] ed)	bool	Encodes a YUV I420P image from reference.
Dispose()	void	Disposes of the encoder and releases native resources.

---

Premade Configurations

Enum Member	Description
CameraBasic	Standard setting for camera capture.
ScreenCaptureBasic	Standard setting for screen capture.
CameraCaptureAdvanced	Advanced configuration aiming for more quality and complexity for camera capture.
ScreenCaptureAdvanced	Advanced configuration aiming for more quality and complexity for screen capture.
CameraCaptureAdvancedHP	Advanced camera capture with parallel encoder(might sacrifice quality).
ScreenCaptureAdvancedHp	Advanced screen capture with parallel encoder(might sacrifice quality).

---

Usage Examples

Encoder(also Decoder) is a stateful object and you should manage the lifetimes on your program.

Creating and Initializing an Encoder with Basic Parameters

using (var encoder = new H264Encoder())
{
    int width = 1280;
    int height = 720;
    int bitrate = 2000000; // 2 Mbps
    int fps = 30;
    ConfigType configType = ConfigType.CameraCaptureAdvanced;

    encoder.Initialize(width, height, bitrate, fps, configType);

    // Encode an RgbImage
    RgbImage image = new RgbImage(ImageFormat.Rgb, width, height);
    if (encoder.Encode(image, out EncodedData[] encodedData))
    {
            // Process encoded data
    }

}

Creating and Initializing an Encoder with Advanced Parameters

using (var encoder = new H264Encoder())
{
    var param = encoder.GetDefaultParameters();
    // modify the parameters..
    encoder.Initialize(param);

    // Encode an YUV NV12(emulate some source)
    var nv12 = new YUVNV12ImagePointer(...);
    if (encoder.Encode(nv12, out EncodedData[] encodedData))
    {
        // Process encoded data
    }
}

Setting Runtime Configuration

encoder.SetMaxBitrate(2000000); // 2 Mbps
encoder.SetTargetFps(30.0f);
encoder.ForceIntraFrame();

Getting and Setting Options

int idrInterval;
if (encoder.GetOption(ENCODER_OPTION.ENCODER_OPTION_IDR_INTERVAL, out idrInterval))
{
    if (idrInterval<120)
    {
        encoder.SetOption(ENCODER_OPTION.ENCODER_OPTION_IDR_INTERVAL, 120);
    }
}

Remarks

• encoder.Encode(...) Return Value:

  • The bool value = encoder.Encode(..., out EncodedData[] encodedData) method returns a boolean value indicating whether encoding was performed.
  • A return value of false signifies that the frame was skipped and encodedData will be empty, typically to maintain the target bitrate.

• EncodedData for IDR Frames (Single Layer):

  • For IDR frames in a single-layer encoding scenario (standard usage), the Encode method produces multiple EncodedData entries.
  • The first EncodedData entry contains metadata and will not produce an image or an error when decoded.

• Decoder Input:

  • The decoder supports both frame-by-frame and merged input(EncodedData elements from single encode operation).
  • You can provide encoded frames individually or concatenate them into a single contiguous byte array for one-shot decoding.

• Encoder Input Format:

  • The Cisco encoder exclusively supports YUV I420 planar format.
  • RGB and YUV NV12 (interleaved UV) input formats are automatically converted to YUV I420 internally.
  • Encoding is more efficient when the source is already in YUV I420 or NV12 format, as it minimizes conversion overhead.