API Definitions

Visionular’s Aurora5 HEVC encoder supports input of 8/10-bit YUV400/420/422/444 image/video and outputs a bitstream compliant with the HEVC/H.265 standard.

Note:

  • The encoding interface is defined in the file wz265enc.h.
  • For related integration examples, please refer to wz265_sample_encoder.c or wz265_sample_encoder_mvhevc.c if you are using stereoscopic content.
  • The encoder is built from WZ265EncConfig which exposes the core parameters needed to set up the encoder.
  • Further parameters can be passed in an extra configuration string by wz265-params.

Generate Default Configuration Parameters

_h_dll_export int wz265_param_default(WZ265EncConfig *pConfig, int preset, int tune);
  • Function: Generates default configuration parameters for pConfig by specifying preset and tune, where preset and tune are integers.
  • Return Value: Error code.
  • Parameters:
    • pConfig: Pointer to basic configuration parameters.
    • preset: Specifies the speed level.
    • tune: Specifies the application scenario.

Create Encoder

_h_dll_export void *wz265_encoder_open(WZ265EncConfig *pCfg, int *errorCode);
  • Function: Creates an encoder instance.
  • Return Value: Pointer to the encoder instance.

  • Parameters:

    • pCfg: Basic configuration parameters for the encoder.
    • errorCode: Returns the error code.

  • Note: Before calling this interface, the incoming pCfg must first be filled with default values using wz265_param_default, and then some parameters can be configured as needed.

Change Encoding Configuration Parameters

_h_dll_export int wz265_encoder_reconfig(void *pEncoder, WZ265EncConfig *pCfg);
  • Function: Adjusts the encoder parameters.
  • Return Value: Error code.
  • Parameters:
    • pEncoder: Pointer to the encoder instance.
    • pCfg: Basic configuration parameters for the encoder.
  • Note: Parameters that can be reset by wz265_encoder_rencofig are listed in the table - WZ265EncConfig.

Destroy Encoder

_h_dll_export void wz265_encoder_close(void *pEncoder);
  • Function: Destroys an encoder instance.
  • Return Value: None.
  • Parameters:
    • pEncoder: Pointer to the encoder instance.

Encode a Frame of Image

_h_dll_export int wz265_encoder_frame(void *pEncoder, WZ265Nal **pNals, int *iNalCount, WZ265Picture *pInpic, WZ265Picture *pOutpic);
  • Function: Encodes one frame of YUV image.
  • Return Value: Error code, 0 indicates normal operation.

  • Parameters:

    • pEncoder: Pointer to the encoder instance.
    • pNals: Pointer to the NAL units generated by encoding, where pNals[i] represents the pointer to number i NAL unit.
    • iNalCount: Number of NAL units generated by encoding.
    • pInpic: Pointer to the input YUV image structure, which is not synchronized with the output pNals.
    • pOutpic: Pointer to the output image frame, which serves as auxiliary information for the output pNals, synchronized with pNals. It is only for reference and can be discarded without affecting normal encoding.

  • Note:

    • When compressing multiview content, i.e. when using MV-HEVC, left and right views are submitted as frames to the encoder. These views are expected to be presented in an interleaved fashion, so that even numbered pictures are associated with the left view and odd numbered pictures are associated with the right view. Accordingly, a stereoscopic video file with N spatial frames, needs to have 2 x N views. To let the Aurora5 SDK be able to distinguish between left and right views, the field viewId needs to be set according to the following convention:
    • Left view : viewId=0
    • Right view : viewId=1
    • As mentioned, for multiview content, the wz265_encoder_frame is expected to have its pInpic with the following sequence of viewId values: viewId=0;viewId=1;...viewId=0;viewId=1;
    • The API will return an error if such interleaved order is violated. The Aurora5 encoder's API uses the recommended values and conventions of the Apple Stereo Video Interoperability profile. If the user wants to switch the order above, i.e. having right views submitted first, then the input viewId values need to be modified accordingly. Also, the left_view_id and right_view_id values in the threeDimRefDisplaysInfo field of the WZ265EncConfig object need to be modified so that the left and right views will now have value 1 and 0, respectively.

Encode Parameter Sets (VPS, SPS, PPS, etc. headers)

_h_dll_export int wz265_encode_headers(void *pEncoder, WZ265Nal **pNals, int *iNalCount);
  • Function: Encodes the VPS/SPS/PPS parameter sets.
  • Return Value: Error code, 0 indicates normal operation.
  • Parameters:
    • pEncoder: Pointer to the encoder instance.
    • pNals: Pointer to the NAL units generated by encoding, where pNals[i] represents the pointer to number i NAL unit.
    • iNalCount: Number of NAL units generated by encoding.

Key Frame Request

_h_dll_export void wz265_keyframe_request(void *pEncoder);
  • Function: Initiates a request for encoding a key frame; the encoder will encode a key frame during the next call to WZ265EncoderEncodeFrame.
  • Return Value: None.
  • Parameters:
    • pEncoder: Pointer to the encoder instance.
  • Note:
    • Aurora5 provides two methods for forcing keyframes:
    • Method 1 : Call the API of wz265_keyframe_request.
    • Method 2 : Before calling wz265_encoder_frame for the current frame, set inpic.iSliceType = 2.
    • These two methods have differences:
    • In scenarios where latency is not allowed or zero latency is required, both methods produce the same result.
    • In live streaming or on-demand scenarios where latency is allowed, wz265_keyframe_request sets the next available keyframe, taking into account the encoder's lookahead delay and GOP structure (i.e., the number of B-frames). A keyframe will only be inserted when the delay and GOP structure conditions are met. On the other hand, setting iSliceType = 2 for the current frame will force it to be a keyframe, and the original GOP structure will be adjusted accordingly.
    • Please choose the optimal keyframe insertion strategy according to your practical application requirements!

Query Delayed Frames Count

_h_dll_export int wz265_encoder_delayed_frames(void *pEncoder);
  • Function: Queries the number of frames that the encoder has yet to encode, only used at the end of a sequence. If the return value is greater than 0, it indicates that there are still delayed frames that have not been encoded, and wz265_encoder_frame must continue to be called until all frames are encoded.
  • Return Value: Number of delayed frames; 0 indicates all frames have been encoded.
  • Parameters:
    • pEncoder: Pointer to the encoder instance.