# API (version 3.9) ## EIL\_GetErrorString ```c 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 ```c 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 ```c #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 ```c 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*** ```c 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*** ```c 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*** ```c 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*** ```c 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*** ```c const char* log_filepath; ``` \[ Optional | Default: `NULL` ] `log_filepath` is an optional file path, that when specified , contains all log messages. #### ***reserved, reserved2*** ```c void* reserved; void* reserved2; ``` Reserved fields that should not be modified, unless specified elsewhere. ## EIL\_InitSettingsDefault and EIL\_Initialise ### EIL\_InitSettingsDefault ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c 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 ```c uint32_t bitrate; ``` \[ Required ] The target bitrate, in *kilo*bits/s, at which to encode. #### gop\_length ```c 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 ```c const char* properties_json; ``` \[ Required ] A string containing json properties for the EIL's user-specified options. #### external\_input ```c 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 ```c 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*** ```c 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*** ```c 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]*** ```c 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]*** ```c uint32_t stride[EIL_MaxPlanes]; ``` \[ Required if externally allocated ] The stride, in bytes, for each plane defined in `plane`. ***base\_type*** ```c 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*** ```c 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*** ```c 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*** ```c void* user_data; ``` \[ Optional | Default: `NULL` ] A handle to some arbitrary data that is set on the `EILOutput` produced by the picture. ***reserved*** ```c const void* reserved; ``` Internally used field. Do not modify. ## EIL\_Encode ```c 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 ```c 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 ```c VN_EIL_PublicAPI EILReturnCode EIL_ReleaseOutput(EILContext context, EILOutput* output); ``` Returns an output obtained using `EIL_GetOutput` back to the encoder. ***EILOutput*** * **EILOutput Overview** ```c 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** ```c 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** ```c 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** ```c int32_t qp; ``` The Quantisation Parameter (QP) of the frame, as reported by the base encoder. * **pts** ```c 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** ```c int64_t dts; ``` The decode timestamp of the encoded frame, as produced by the base encoder. * **config** ```c 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** ```c 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** ```c void* user_data; ``` The user data that was set on the picture that produced this frame. * **reserved** ```c const void* reserved; ``` Internally used field. Do not modify. ## EIL\_QueryPropertyGroups, EIL\_QueryProperty ### EIL\_QueryPropertyGroups, EIL\_QueryProperty Overview ```c 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 ```c typedef struct EILPropertyGroups { EILPropertyGroup* group; uint32_t group_count; } EILPropertyGroups; ``` This structure contains an array of all property groups. ```c 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*** ```c 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*** ```c const char* name; const char* description; ``` A short name and description of the property that was queried. ***type*** ```c 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*** ```c 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.