API (version 3.9)

EIL_GetErrorString

VN_EIL_PublicAPI const char* EIL_GetErrorString(EILReturnCode error);

Utility method for getting a string representation of an EIL return code in English.

EIL_OpenSettingsDefault and EIL_Open

EIL_OpenSettingsDefault

VN_EIL_PublicAPI EILReturnCode EIL_OpenSettingsDefault(EILOpenSettings* settings);

Initialises the members of an EILOpenSettings object to sensible default state. Some fields of the settings must still be populated by the integration before the settings can be used by the EIL.

EIL_Open

#define VN_EIL_OpenFnName VN_EIL_PP_Concat(EIL_Open_, VN_EIL_API_Version)

VN_EIL_PublicAPI EILReturnCode VN_EIL_OpenFnName(EILOpenSettings* settings, EILContext* output);

#define EIL_Open VN_EIL_OpenFnName

This is the entry point for creating an instance of the EIL. The open function will have the version of the API appended at the end of the function name to ensure that a newer or older version of the EIL that contains breaking changes cannot be mistakenly used. As such, the EIL_Open define is provided to aid in calling the correct open function.

If the EIL fails to open, then it is typically due to not being able to find and open the requested base encoder. A detailed message as to why the encoder failed to open should be sent to the log callback, if it is provided.

EILContext

typedef struct EILContextImpl* EILContext;

The EILContext is an opaque handle to the EIL's encoder instance. An EILContext is created when the EIL is opened using EIL_Open, and the same instance should be passed to all other functions. It is destroyed when EIL_Close is called.

EILOpenSettings

EILOpenSettings Overview

typedef struct EILOpenSettings
{
    const char* base_encoder;
    void*       base_encoder_userdata;
    void        (*log_callback)(void* userdata, int32_t level, const char* msg);
    void*       log_userdata;
    const char* log_filepath;
    void*       reserved;
    void*       reserved2;
} EILOpenSettings;

EILOpenSettings contains the information required to open the EIL. It can be default initialised using EIL_OpenSettingsDefault.

base_encoder

    const char* base_encoder;

[ Required ]

The name of the base encoder that the EIL uses for base encoding should not contain the preceding lcevc_eilp_ (liblcevc_eilp_ on Linux) or the platform's dynamic library extension. For example, if a plugin is called liblcevc_eilp_x264.so or lcevc_eilp_x264.dll, then the base_encoder string should be x264.

There are two special strings for base_encoder: none and inject:

• none is a pass-through plugin that sets the output recon to the input.

• inject allows for reserved2 to reference an EILPAPI object that contains function pointers for all of a plugin's methods.

base_encoder_userdata

    void*       base_encoder_userdata;

[ Dependent on the plugin | Default: NULL ]

The base_encoder_userdata is a handle that allows some arbitrary data to be passed through to a base plugin.

log_callback

    void        (*log_callback)(void* userdata, int32_t level, const char* msg);
    void*       log_userdata;

[ Optional | Default: NULL ]

log_callback can be set to a method that receives all log messages.

userdata is the value set in log_userdata, and level is one of the levels in the enumeration EILLogLevel. If left unset, then all logging is disabled.

All log messages are in the format level | group | message\n, and are limited to 4096 bytes.

log_filepath

    const char* log_filepath;

[ Optional | Default: NULL ]

log_filepath is an optional file path, that when specified , contains all log messages.

reserved, reserved2

    void*       reserved;
    void*       reserved2;

Reserved fields that should not be modified, unless specified elsewhere.

EIL_InitSettingsDefault and EIL_Initialise

EIL_InitSettingsDefault

VN_EIL_PublicAPI EILReturnCode EIL_InitSettingsDefault(EILInitSettings* settings);

Initialises the members of an EILInitSettings object to sensible defaults. Some fields of the structure must still be populated by the integration before the settings can be used by the EIL.

EIL_Initialise

VN_EIL_PublicAPI EILReturnCode EIL_Initialise(EILContext context, EILInitSettings* settings);

Initialises the EIL so that it is ready to receive pictures for encoding. The context must have previously been created using EIL_Open.

EILInitSettings

EILInitSettingsOverview

typedef struct EILInitSettings
{
    EILColourFormat color_format;
    uint32_t        width;
    uint32_t        height;
    uint32_t        fps_num;
    uint32_t        fps_denom;
    uint32_t        bitrate;
    int32_t         gop_length;
    const char*     properties_json;
    uint8_t         external_input;
} EILInitSettings;

EILInitSettings contains the information required to initialise the EIL. It can be default initialised using EIL_InitSettingsDefault.

color_format

    EILColourFormat color_format;

[ Optional | Default: EIL_YUV_420P ]

The colour format of the input image. If it is not one of the YUV formats, then there will be an extra conversion step that converts the input into the YUV format. The matrix used for the colour conversion can be controlled using the picture_colorspace config option.

width, height

    uint32_t        width;
    uint32_t        height;

[ Required ]

The resolution of the input image. Once the EIL is initialised. then these are modified by the EIL to become the resolution of the base video. These modified values should be used by any operation or process that consumes the bitstream. Consult the LCEVC standard for supported resolutions.

fps_num

    uint32_t        fps_num;
    uint32_t        fps_denom;

[ Required ]

The framerate's numerator and denominator, e.g., 25/1 for 25fps or 30000/1001 for 29.97fps

bitrate

    uint32_t        bitrate;

[ Required ]

The target bitrate, in kilobits/s, at which to encode.

gop_length

    int32_t         gop_length;

[ Optional | Default: EIL_GOPLengthAuto ]

The GOP length in frames. There are three values to which gop_length can be set, subject to the base encoder's abilities:

• EIL_GOPLengthAuto: The EIL determines which GOP length to use.

• EIL_GOPLengthInfinite: Only the first frame is an I-frame.

• EIL_GOPLengthIntraOnly: Every frame is an I-frame.

properties_json

    const char*     properties_json;

[ Required ]

A string containing json properties for the EIL's user-specified options.

external_input

    uint8_t         external_input;

[ Optional | Default: 0 ]

Whether or not the input image's planes should be allocated by the integration or the EIL.

• When set to 0, the EIL allocates and manages the lifetimes of an image's planes.

• When set to 1, the planes are expected to be allocated and managed external to the EIL.

EIL_GetPicture

EIL_GetPicture Overview

VN_EIL_PublicAPI EILReturnCode EIL_GetPicture(EILContext context, EILFrameType frameType, EILPicture** picture);

When the EIL is configured to operate in internal input mode (see external_input under EIL_InitSettings), this method is used to obtain a picture object with preallocated planes. The planes can then be populated with frame data and passed to EIL_Encode. A picture obtained using this method is owned by the integration until that picture is passed back through EIL_Encode.

The EIL internally creates a pool of pictures from which this method extracts. The most common reason for the failure of this method, is that the pool of pictures is empty. This can occur if this function is called too frequently without returning the pictures through EIL_Encode. The size of the pool depends on the base encoder's frame delay plus the EIL's frame delay, where frame delay is the number of frames that must be provided to the encoder before any output is produced.

EILPicture

EILPicture Overview

typedef struct EILPicture
{
    EILMemoryType   memory_type;
    uint32_t        num_planes;
    void*           plane[EIL_MaxPlanes];
    uint32_t        stride[EIL_MaxPlanes];
    EILBaseType     base_type;
    EILFrameType    frame_type;
    EILFieldType    field_type;
    int64_t         pts;
    void*           user_data;
    const void*     reserved;
} EILPicture;

An EILPicture is in the input to the encoder, containing all information needed to encode a single frame of video. If the EIL is configured to operate in external input mode, then it is up to the integration to set the fields of this struct, in which case it can be default initialised using EIL_InitPictureDefault. Otherwise, the EIL will populate the fields of the struct, and the integration should populate the preallocated planes.

memory_type

    EILMemoryType   memory_type;

[ Optional if externally allocated | Default EIL_MT_Host ]

memory_type specifies the type of memory stored in the picture's planes. This can currently only be either:

• EIL_MT_Host is memory that is accessible from the device's CPU, i.e., allocated using malloc or some device memory that has been mapped. If the memory is externally allocated, then the memory must be aligned for 8- or 16-bit access, depending upon the bitdepth.

• EIL_MT_AHardwareBuffer indicates that the planes are Android hardware buffers

  (AHardwareBuffer). The encoder must be configured to use the GPU for this to be accepted, when used in conjunction with external input.

Other memory types:

• EIL_MT_TextureGL is currently unsupported as input to the EIL. The EIL may pass this type of

  memory to the base encoder, depending upon the configuration.

• EIL_MT_Unknown is used only to indicate that the memory type is not yet defined. memory_type should not be set to EIL_MT_Unknown by the point of ingest.

num_planes, plane[EIL_MaxPlanes]

    uint32_t        num_planes;
    void*           plane[EIL_MaxPlanes];

[ Required if externally allocated ]

Pointers to the appropriate structures holding the plane data, as defined by the memory_type. These planes can be interleaved in the cases of the RGB formats. As such, num_planes indicates the number of plane pointers rather than the number of channels. In the case of contiguous memory, each pointer should be set to the starting address of each plane, and the number of planes should be set as if the memory is not contiguous.

stride[EIL_MaxPlanes]

    uint32_t        stride[EIL_MaxPlanes];

[ Required if externally allocated ]

The stride, in bytes, for each plane defined in plane.

base_type

    EILBaseType     base_type;

[ Optional | Default: EIL_BT_Uknown ]

If set to a value other than the default, then when this picture is encoded, the EIL will attempt to force the requested type of picture from the base encoder. Whether or not the requested type of frame is produced, is subject to a base encoder's capabilities.

frame_type, field_type

    EILFrameType    frame_type;
    EILFieldType    field_type;

[ Optional if externally allocated | Default: EIL_FrameType_Progressive ]

Whether this frame is progressive, a single field, or interlaced, and if it is a single field, then whether the frame is the top or bottom field.

pts

    int64_t         pts;

[ Optional | Defaut: -1 ]

The presentation timestamp of the picture. If left as the default, then it is determined by the EIL.

user_data

    void*           user_data;

[ Optional | Default: NULL ]

A handle to some arbitrary data that is set on the EILOutput produced by the picture.

reserved

    const void*     reserved;

Internally used field. Do not modify.

EIL_Encode

VN_EIL_PublicAPI EILReturnCode EIL_Encode(EILContext context, EILPicture* picture);

Passes a picture that is ready for encode to the EIL. A picture can be obtained from the EI, either:

• Using EIL_GetPicture, if external input is disabled; or,

• Created and populated by the integration, if external input is enabled.

EIL_GetOutput and EIL_ReleaseOutput

Get_Output

VN_EIL_PublicAPI EILReturnCode EIL_GetOutput(EILContext context, EILOutput** output);

Gets the next output available from the EIL. The integration has ownership of the EILOutput until it has been passed back through EIL_ReleaseOutput. This can return one of two return codes upon success:

• EIL_RC_Success: Successfully got the next frame of output.

• EIL_RC_Finished: No errors occurred but there there is currently no output available.

Release_Output

VN_EIL_PublicAPI EILReturnCode EIL_ReleaseOutput(EILContext context, EILOutput* output);

Returns an output obtained using EIL_GetOutput back to the encoder.

EILOutput

• EILOutput Overview

typedef struct EILOutput
{
    EILFrameType    frame_type;
    EILFieldType    field_type;
    EILBaseType     base_type;
    int8_t          keyframe;
    int32_t         qp;
    int64_t         pts;
    int64_t         dts;
    int8_t          config;
    const uint8_t*  data;
    uint32_t        data_length;
    const uint8_t*  lcevc;
    uint32_t        lcevc_length;
    void*           user_data;
    const void*     reserved;
} EILOutput;

The EILOutput struct contains all information for an encoded frame of video. These should never have to be created manually, and should be treated as read-only.

• frame_type, field_type

    EILFrameType    frame_type;
    EILFieldType    field_type;

Whether the frame that produced this output is progressive, interlaced or a field. field_type is applicable, only if the type is EIL_FT_Field.

• base_type, keyframe

    EILBaseType     base_type;
    int8_t          keyframe;

The type of frame that the base encoder produced, and whether or not it is flagged as a keyframe. Refer to the appropriate base encoder's standard for their meanings.

• qp

    int32_t         qp;

The Quantisation Parameter (QP) of the frame, as reported by the base encoder.

• pts

    int64_t         pts;

The presentation timestamp of the encoded frame. This is the input frame's pts, if it was specified; otherwise, it is the pts that the base encoder produced.

• dts

    int64_t         dts;

The decode timestamp of the encoded frame, as produced by the base encoder.

• config

    int8_t          config;

Whether the data in this output is the encoder's config. For example, if the base encoder is an H264 encoder and config is 1, then the output contains only the SPS and PPS NAL units. The config output is always presented before any frame data.

• data, data_length, lcevc, lcevc_length

    const uint8_t*  data;
    uint32_t        data_length;
    const uint8_t*  lcevc;
    uint32_t        lcevc_length;

The encoded bitstream for the frame and its length. If the separate_output config option is set, then the LCEVC data is on the lcevc field; otherwise, it is contained in the data field, along with the base bitstream.

• user_data

    void*           user_data;

The user data that was set on the picture that produced this frame.

• reserved

    const void*     reserved;

Internally used field. Do not modify.

EIL_QueryPropertyGroups, EIL_QueryProperty

EIL_QueryPropertyGroups, EIL_QueryProperty Overview

VN_EIL_PublicAPI EILReturnCode EIL_QueryPropertyGroups(EILContext context, EILPropertyGroups* output);
VN_EIL_PublicAPI EILReturnCode EIL_QueryProperty(EILContext context, const char* name, EILProperty* output);

This group of methods is used to query the options available through the EIL. These are usually controlled by the user.

• EIL_QueryPropertyGroups returns a collection of all properties in their logical groupings.

• EIL_QueryProperty obtains an individual property by its name.

The properties and their values are passed to the EIL in JSON format on the EILInitSettings structure through the properties_json field.

EILPropertyGroups

typedef struct EILPropertyGroups
{
    EILPropertyGroup*   group;
    uint32_t            group_count;
} EILPropertyGroups;

This structure contains an array of all property groups.

typedef struct EILPropertyGroup
{
    const char*     name;
    const char*     description;
    EILProperty*    properties;
    uint32_t        property_count;
} EILPropertyGroup;

The property group contains a logical grouping of all properties available through the EIL and base encoders.

EILProperty

EILProperty Overview

typedef struct EILProperty
{
    const char*     name;
    const char*     description;
    EILPropertyType type;

    union
    {
        int32_t     i32;
        int64_t     i64;
        uint32_t    u32;
        uint64_t    u64;
        float       f;
        double      d;
        const char* str;
    } value;

    const uint8_t*  blob;
    uint32_t        blob_size;
} EILProperty;

This structure is used to describe config properties or metadata of the EIL and the base encoder.

name, description

    const char*     name;
    const char*     description;

A short name and description of the property that was queried.

type

    EILPropertyType type;

The type of value contained in this property. This value should be used to determine which field of the value union is set:

• EIL_PT_Int32: value.i32

• EIL_PT_Int64: value.i64

• EIL_PT_Uint32: value.u32

• EIL_PT_Uint64: value.u64

• EIL_PT_Float: value.f

• EIL_PT_Double: value.d

• EIL_PT_String: value.str

• EIL_PT_Boolean: value.i32

blob, blob_size

    const uint8_t*  blob;
    uint32_t        blob_size;

blob and blob_size are used when the property type is EIL_PT_Blob. This is only ever the case when querying metadata.