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
• ConfigType Enum

---

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
H264Encoder(string ciscoDllPath)	Creates a new instance using the specified Cisco DLL path.(LoadLibraryW on windows,dlopen with RTLD_LAZY on linux)

---

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 for camera capture.
ScreenCaptureAdvanced	Advanced configuration 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);
    }
}