API Encoder

API reference: Encoder

The encoder module turns frames from a FrameSource channel into H.264, H.265 or JPEG streams. An encoder channel belongs to a group; the group is bound to a FrameSource channel with IMP_System_Bind. The application pulls finished streams with GetStream (or waits with PollingStream first) and gives them back with ReleaseStream.

Typical call order: CreateGroup, CreateChn with a IMPEncoderChnAttr (use SetDefaultParam to fill it), RegisterChn, bind the group to the FrameSource, StartRecvPic, then the loop PollingStream, GetStream, process, ReleaseStream. Stop with StopRecvPic, UnRegisterChn, DestroyChn, DestroyGroup.

Rate-control behaviour differs between SoCs; the pages state where a setting is only stored. The rate-control modes are FIXQP, CBR, VBR, CAPPED_VBR and CAPPED_QUALITY (some SoCs also SMART). What OpenIMP does beyond the vendor library (closed-loop capped modes, HEVC on T31, telemetry) is collected in Beyond the Vendor. Calls whose status is · on a SoC do not exist in that SoC's vendor library.

Status columns: T10 T20 T21 T23 T30 T31 T40 T41. As of 2026-10-26. Part of the API reference.

Contents

• Groups and channels (8)
• Streams (8)
• Channel attributes and defaults (3)
• Rate control (9)
• GOP, key frames and frame rate (11)
• Quantiser, regions and picture quality (14)
• H.264 and H.265 options (7)
• JPEG (4)
• Unbound encoding of own frames (YUV interface) (15)
• Memory, buffer sharing and pools (9)
• Other (6)

Status symbols are those of the feature matrix (API coverage tables):

• ✅ works, device-tested
• ✅+ works, device-tested, better than the vendor
• ✅rt API round trip on device, no visible effect expected
• ✅r works: called by the streamer on fleet cameras of this SoC that passed the fleet soak
• ✅○ vendor no-op, OpenIMP matches that
• 🔧h implemented, host tests only (no camera run yet)
• 🔧a really connected per static audit, no device test tracked
• 🔧+ API round trip in QEMU, no camera
• ⚠c value only stored and read back, nothing applied
• ⚠s returns 0 without any effect
• ❌e exported but fails or has a known defect
• ❌ not exported by OpenIMP
• · function does not exist on this SoC (not in that SoC's vendor API; not a gap)
• ? state not determined
• 📋 no OpenIMP build for this SoC yet (planned)

Groups and channels

IMP_Encoder_CreateGroup

int IMP_Encoder_CreateGroup(int encGroup);

Creates an encoder group, the container a FrameSource channel is bound to.

Parameters

• encGroup: Group number.

Returns: 0 on success, -1 if the group number is invalid. Creating a group twice is not an error.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

See also: IMP_Encoder_CreateChn, IMP_Encoder_RegisterChn

IMP_Encoder_DestroyGroup

int IMP_Encoder_DestroyGroup(int encGroup);

Removes a group. All channels must be unregistered from it first.

Returns: 0 on success, -1 for an invalid or never created group, or when a channel is still registered in it.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_CreateChn

int IMP_Encoder_CreateChn(int encChn, IMPEncoderCHNAttr *attr);

Creates an encoder channel from an attribute structure (profile, size, rate control, GOP). The channel is idle until it is registered and receives pictures.

Parameters

• encChn: Channel number.
• attr: Encoder, rate control and GOP attributes.

Returns: 0 on success, -1 on an invalid channel number or NULL attribute, a channel that already exists, invalid rate-control attributes, or a profile the SoC cannot encode (H.265 on a SoC without HEVC).

Create the channel before RegisterChn. The picture size has to match the FrameSource channel, and the rate-control block has to belong to the selected mode. The log prints the rate control that is really used; the requested mode can map to a different one on some SoCs.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

Difference from the vendor library: Asking for H.265 on a SoC without HEVC hardware fails with -1 and a log line. The vendor library returns 0 and creates a channel that never produces a frame.

See also: IMP_Encoder_SetDefaultParam, IMP_Encoder_RegisterChn

IMP_Encoder_DestroyChn

int IMP_Encoder_DestroyChn(int encChn);

Destroys a channel and frees its buffers. The channel has to be unregistered first (StopRecvPic, then UnRegisterChn).

Returns: 0 on success, -1 for an invalid or never created channel, a channel that is still registered, or a stream that has not been released.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_RegisterChn

int IMP_Encoder_RegisterChn(int encGroup, int encChn);

Attaches a created channel to a group, which makes it a destination of the FrameSource bound to that group.

Parameters

• encGroup: Group number.
• encChn: Channel number.

Returns: 0 on success, -1 for an invalid group or channel, a channel that was not created, or one that is already registered.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_UnRegisterChn

int IMP_Encoder_UnRegisterChn(int encChn);

Detaches a channel from its group. Stop the channel with StopRecvPic first.

Returns: 0 on success, -1 for an invalid, not created or not registered channel, or one that is still receiving pictures.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_StartRecvPic

int IMP_Encoder_StartRecvPic(int encChn);

Starts encoding. Pictures that arrive after this call are encoded.

Returns: 0 on success, -1 for an invalid channel or one that is not registered.

Call after RegisterChn and after the bind.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

See also: IMP_Encoder_StopRecvPic

IMP_Encoder_StopRecvPic

int IMP_Encoder_StopRecvPic(int encChn);

Stops encoding. A stream that is already encoded can still be fetched.

Returns: 0 on success, -1 for an invalid or not created channel.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

Streams

One call chain per picture - PollingStream (wait), GetStream (take), ReleaseStream (return). OpenIMP keeps one outstanding stream per channel, so release it before the next fetch.

IMP_Encoder_GetStream

int IMP_Encoder_GetStream(int encChn, IMPEncoderStream *stream, int block);

Takes the next encoded stream of a channel. The stream consists of packs that point into the stream buffer of the channel.

Parameters

• encChn: Channel number.
• stream: Receives the pack list and the stream description.
• block: Non-zero waits for a stream (up to 1 second, as PollingStream does), zero returns at once.

Returns: 0 on success, -1 when there is no stream (timeout or block 0 without a ready stream), the channel is invalid, or on error.

A stream is one picture, in several packs (parameter sets and slices). Return it with ReleaseStream before you take the next one: OpenIMP keeps one outstanding stream per channel.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

Difference from the vendor library: On T40 and T41 the picture is encoded when the application polls, not ahead of time; the encoder keeps at most one finished stream.

See also: IMP_Encoder_PollingStream, IMP_Encoder_ReleaseStream

IMP_Encoder_GetStream_Impl

/* IMP_Encoder_GetStream_Impl: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Internal worker behind GetStream (GetStream(chn, stream, block) is GetStream_Impl(chn, stream, block, 0) in the vendor library); the extra argument only matters for the vendor's internal drain path.

Returns: Same as GetStream.

Exported for compatibility with the vendor library; applications call IMP_Encoder_GetStream. In OpenIMP the extra argument is ignored.

IMP_Encoder_ReleaseStream

int IMP_Encoder_ReleaseStream(int encChn, IMPEncoderStream *stream);

Returns a stream taken with GetStream.

Returns: 0 on success, -1 when the channel has no stream outstanding (nothing was fetched, or it was already released).

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_PollingStream

int IMP_Encoder_PollingStream(int encChn, uint32_t timeoutMsec);

Waits until the channel has a stream or the timeout expires.

Parameters

• encChn: Channel number.
• timeoutMsec: Maximum wait in milliseconds.

Returns: 0 when a stream is ready, -1 on timeout, for an invalid channel, or for a channel that is not created or not registered.

A second thread that polls the same channel waits for the first to finish.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

Difference from the vendor library: On T40 the wait honours its timeout even when the ISP delivers no frames.

See also: IMP_Encoder_GetStream

IMP_Encoder_PollingModuleStream

int IMP_Encoder_PollingModuleStream(uint32_t *encChnBitmap, uint32_t timeoutMsec);

Waits until at least one of the selected channels has a stream ready and reports which ones.

Parameters

• encChnBitmap: Bit mask of channels to wait on; on return the channels that are ready.
• timeoutMsec: Maximum wait in milliseconds.

Returns: 0 when at least one channel is ready, -1 on timeout or for a NULL pointer.

The bitmap is input and output: a 0 on input means all channels, on output only channels of the input set are reported. The wait is shared over the selected active channels in short slices, so one idle channel does not starve the others.

SoC: not in the vendor API of T10, T20, T30

T10	T20	T21	T23	T30	T31	T40	T41
·	·	✅	🔧a	·	✅	✅	🔧a

IMP_Encoder_FlushStream

int IMP_Encoder_FlushStream(int encChn);

Requests a key frame and drops a finished stream that nobody has taken yet, so the next stream is fresh.

Returns: 0 on success, -1 for an invalid or not created channel.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor.

IMP_Encoder_GetFd

int IMP_Encoder_GetFd(int encChn);

Returns a file descriptor that becomes readable while a finished stream waits for GetStream, for use with select or poll.

Returns: The descriptor, or -1 for an invalid or not created channel.

In OpenIMP the descriptor is the read end of a pipe. The first call starts a helper thread that polls the channel and fills the pipe; ReleaseStream and FlushStream empty it again. UnRegisterChn and DestroyChn stop the helper and close the pipe. Not in the vendor library of T10 and T20.

SoC: not in the vendor API of T10, T20

T10	T20	T21	T23	T30	T31	T40	T41
·	·	✅	✅	?	✅	✅	✅

Used by: raptor.

Difference from the vendor library: See Beyond the Vendor: New in RC1 (since the 2026-10-06 state).

IMP_Encoder_Query

int IMP_Encoder_Query(int encChn, IMPEncoderCHNStat *stat);

Reads the channel statistics: registration state, pictures and streams waiting, and whether the encoder is working.

Parameters

• encChn: Channel number.
• stat: Receives the six-word statistics structure (registered, leftPics, leftStreamBytes, leftStreamFrames, curPacks, work_done).

Returns: 0 on success, -1 for an invalid channel, a NULL pointer or a channel that was not created. On T41 the channel errors are the vendor codes 0x80040001 and 0x80040008.

leftPics is 1 while a picture is being encoded, otherwise 0. leftStreamFrames is 1 while a finished stream waits for GetStream; leftStreamBytes and curPacks are filled from it on T41 and the other SoCs built on the same backend, and stay 0 on T40. work_done is 0 while a picture is being encoded and 1 when idle. There are no bit rate counters.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: raptor, timps.

Difference from the vendor library: OpenIMP has no input queue on T40 and T41: the encoder works on demand in PollingStream / GetStream, so leftPics is at most 1 and the number of waiting pictures is not a measure of load.

Channel attributes and defaults

IMP_Encoder_GetChnAttr

int IMP_Encoder_GetChnAttr(int encChn, IMPEncoderChnAttr *attr);

Reads the attribute structure of a channel as it is currently stored.

Returns: 0 on success, -1 for an invalid channel, a NULL pointer or a channel that was not created.

The structure reflects what the Set calls stored; on T41 the rate-control and GOP members are the read-back values, and the GOP length is reported the way the vendor does: GOP length times the same-scene count (the key frame distance).

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor.

See also: IMP_Encoder_CreateChn

IMP_Encoder_SetDefaultParam

int IMP_Encoder_SetDefaultParam(IMPEncoderChnAttr *attr, IMPEncoderProfile profile, IMPEncoderRcMode rcMode, int width, int height, int fpsNum, int fpsDen, int gopLen, int maxSameSceneCnt, int quality, int bitrate);

Fills an attribute structure with defaults for a profile, rate-control mode, size, frame rate, GOP length, quality and bitrate.

Parameters

• attr: Structure to fill (cleared first).
• profile: IMP_ENC_PROFILE_*, for example AVC main or HEVC main.
• rcMode: Rate-control mode (IMP_ENC_RC_MODE_*, 0 to 8; JPEG accepts any).
• width: Picture width.
• height: Picture height.
• fpsNum: Frame rate numerator.
• fpsDen: Frame rate denominator.
• gop_length: GOP length in frames.
• max_same_scene: Maximum length of an unchanged scene (uMaxSameSenceCnt).
• quality: Initial QP (for FIXQP the QP itself).
• bitrate: Target bitrate in kbit/s. For VBR and the capped modes the maximum is set to 4/3 of it.

Returns: 0 on success, -1 for a NULL attribute, a size or frame rate of 0, an unknown codec type or an unknown rate-control mode (the structure is not touched then).

Start from this and then change the fields you need.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

Used by: timps.

IMP_Encoder_GetChnEncType

int IMP_Encoder_GetChnEncType(int encChn, IMPPayloadType *encType);

Reads the payload type (H.264, H.265 or JPEG) of a channel.

Returns: 0 on success, -1 for an invalid channel, a NULL pointer or a channel that was not created.

The type is an IMPPayloadType (PT_H264, PT_H265, PT_JPEG) on T21, T23 and T30 and an IMPEncoderEncType on the other SoCs.

SoC: not in the vendor API of T10, T20

T10	T20	T21	T23	T30	T31	T40	T41
·	·	✅	✅	?	✅	✅	✅

Used by: raptor.

Rate control

Modes: FIXQP keeps one quantiser, CBR holds the bitrate, VBR lets it vary within a range, the capped modes limit the quality-driven rate to a ceiling. Bitrate is in kbit/s in the attribute structures.

IMP_Encoder_Get/SetChnAttrRcMode

int IMP_Encoder_GetChnAttrRcMode(int encChn, IMPEncoderAttrRcMode *rcMode);
int IMP_Encoder_SetChnAttrRcMode(int encChn, IMPEncoderAttrRcMode *rcMode);

Reads or changes the rate-control attribute (mode and its parameters) of a created channel.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer, or a rate-control mode the SoC does not know or the codec refuses. On T41 the codes 0x80040001 (bad channel), 0x80040008 (channel not created) and 0x80040010 (bad argument) are used where the vendor does.

Bit rates are in kbit/s. On T31, T40 and T41 the QP values are normalised before they reach the codec.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: raptor, timps.

Difference from the vendor library: On T21 and T23 the getter returns the values the running controller actually uses (clamped), so a read after a write can differ from what was written. On T41 the call at run time only changes the bit rate (target and maximum) and the QP window, and only when they differ from the current values; the mode, initial QP, deltas, maximum picture size and PSNR are ignored and not read back, and a FIXQP target is ignored. On a JPEG channel the T41 getter returns 0 and leaves the structure alone.

See also: IMP_Encoder_Get/SetChnRcAttr

IMP_Encoder_Get/SetChnRcAttr

int IMP_Encoder_SetChnRcAttr(int encChn, void *rcAttr);
int IMP_Encoder_GetChnRcAttr(int encChn, void *rcAttr);

Reads or sets the rate-control block of a channel through a generic pointer.

Returns: Declared in the header only.

OpenIMP does not implement these two calls on any SoC, so a program that uses them does not link. Use SetChnAttrRcMode and the other rate-control calls of this page.

SoC: only in the vendor API of T10, T20

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	·	·	·	·	·	·

IMP_Encoder_SetChnBitRate

int IMP_Encoder_SetChnBitRate(int encChn, int bitrate, int bitrateMax);

Changes the target and maximum bitrate of a channel without touching the other rate-control settings.

Parameters

• bitrate: Target in bit/s (not kbit/s; OpenIMP divides by 1000).
• bitrateMax: Upper limit in bit/s. 0 or less uses the target; in CBR mode the maximum equals the target.

Returns: 0 on success, -1 for an invalid or not created channel or a bitrate of 0 or less. On T41, calls with no target bitrate, with FIXQP, or with a missing maximum in a mode other than CBR are ignored and return 0.

The bitrate fields of the attribute structures (uTargetBitRate, outBitRate) are in kbit/s; this call takes bit/s.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

Used by: timps.

IMP_Encoder_Get/SetMbRC

int IMP_Encoder_GetMbRC(int encChn, int *enable);
int IMP_Encoder_SetMbRC(int encChn, int enable);

Switches macroblock-level rate control on or off for a created channel. When on, the quantiser can change inside a picture to hold the picture budget.

Parameters

• channel: Channel number.
• enable: 0 or 1; any other value is refused.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer or an enable value other than 0 and 1.

On T21 and T23 the switch is passed to the macroblock rate control of the Helix encoder; its default is chosen with the OPENIMP_EPRC_MBRC variable. On the other SoCs that have the call the value is stored and read back. Only on the legacy encoder API (T10, T20, T21, T23, T30); T31, T40 and T41 do not have the call.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
✅○	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetSuperFrameCfg

int IMP_Encoder_GetSuperFrameCfg(int encChn, IMPEncoderSuperFrmCfg *config);
int IMP_Encoder_SetSuperFrameCfg(int encChn, const IMPEncoderSuperFrmCfg *config);

Configures what happens when a single picture gets much larger than planned (a super frame): the size thresholds for I and P pictures and the action.

Returns: 0 on success, -1 for an invalid or not created channel or a NULL pointer. T20 accepts only the modes none and re-encode, T21 only none (no super-frame control in its rate controller); other modes return -1.

The configuration is stored and read back by the getter. On T20 it is passed to the rate controller, on T23 to the encoder worker.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetChnMaxPictureSize

int IMP_Encoder_GetChnMaxPictureSize(int encChn, uint32_t *maxPictureSizeI, uint32_t *maxPictureSizeP);
int IMP_Encoder_SetChnMaxPictureSize(int encChn, uint32_t maxPictureSizeI, uint32_t maxPictureSizeP);

Sets or reads the largest size of an I and a P picture before the encoder lowers the quality. On T41 the sizes are in kbit and the encoder keeps both pictures at about 95 percent of the limit; on T23 one shared limit (the larger of the two) is used.

Parameters

• maximum_i: Limit for I pictures; 0 is refused (T23) or ignored (T41).
• maximum_p: Limit for P pictures; 0 is refused (T23) or ignored (T41).

Returns: 0 on success, -1 for an invalid or not created channel or when a value is 0 (T23); on T41 a value of 0 is ignored with return 0, and the codec refusing the limit gives -1. The getter exists on T23 only; it reports the shared limit for both pictures.

SoC: T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	✅

Used by: raptor.

IMP_Encoder_SetChnRcTrigLevel

int IMP_Encoder_SetChnRcTrigLevel(int encChn, float level, int mode);

Sets the trigger level and mode of the rate controller's re-encode. The pair is only stored in OpenIMP; there is no getter.

Returns: 0 for a valid channel (also for one that was not created), -1 for an invalid channel.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
?	?	❌	?	?	·	·	·

IMP_Encoder_GetChnAveBitrate

int IMP_Encoder_GetChnAveBitrate(int encChn, IMPEncoderStream *stream, int frames, double *bitrate);

Averages the bitrate over a number of streams that you pass in one by one.

Parameters

• stream: A stream just fetched; its pack sizes are added up.
• frames: Window length in streams; when that many have been counted the average is published and the window restarts.
• bitrate: Receives the result in kbit/s (a double on T40 and T41, an int on the others).

Returns: 0 on success, -1 for an invalid channel, a NULL pointer or frames of 0 or less.

SoC: only in the vendor API of T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

Used by: timps.

IMP_Encoder_SetFrameRelease

int IMP_Encoder_SetFrameRelease(int encChn, int num, int den);

Stores a ratio (num/den of a frame interval) at which the vendor library hands the source frame back before the encoder has finished with it.

Returns: 0 on success, -1 for an invalid or not created channel.

OpenIMP always returns each capture frame as soon as the hardware encoder has consumed it, so the stored ratio has no effect.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅○	✅○	❌

Difference from the vendor library: Stored only; the early release of the vendor library is not needed here.

GOP, key frames and frame rate

IMP_Encoder_Get/SetChnFrmRate

int IMP_Encoder_GetChnFrmRate(int encChn, IMPEncoderFrmRate *rate);
int IMP_Encoder_SetChnFrmRate(int encChn, const IMPEncoderFrmRate *rate);

Reads or changes the output frame rate of a created channel.

Parameters

• rate: Frame rate as numerator and denominator; either value 0 is refused.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer, a zero numerator or denominator, or when the codec refuses the rate. On T41 the codes 0x80040001, 0x80040008 and 0x80040010 are used where the vendor does.

The call takes effect at run time; the output time stamps restart at the next picture. On T21, T23 and T30 the functions take only the channel and the rate; on T31, T40 and T41 the header declares an additional, unused third argument. Keep the rate at or below the FrameSource rate.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor.

IMP_Encoder_Get/SetGOPSize

int IMP_Encoder_GetGOPSize(int encChn, IMPEncoderGOPSizeCfg *cfg);
int IMP_Encoder_SetGOPSize(int encChn, const IMPEncoderGOPSizeCfg *gop);

Reads or sets the GOP length - the number of pictures between two key frames - through the legacy IMPEncoderGOPSizeCfg structure.

Parameters

• gop: Structure holding gopsize.

Returns: 0 on success, -1 for a NULL pointer, a gopsize of 0 or less, or an invalid or not created channel (T20 getter: -1 for a channel that was not created).

The setter changes the maximum GOP length of the channel (the same value SetChnGopLength changes). A short GOP recovers faster after packet loss, a long one gives a smaller stream. The legacy structure exists on T10, T20, T21, T23 and T30; T31, T40 and T41 use SetChnGopLength.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetChnGopAttr

int IMP_Encoder_GetChnGopAttr(int encChn, IMPEncoderGopAttr *gopAttr);
int IMP_Encoder_SetChnGopAttr(int encChn, IMPEncoderGopAttr *gopAttr);

Reads or sets the GOP attributes of a channel.

Returns: 0 on success, -1 for an invalid or not created channel or a NULL pointer; on T41 an error from the channel check, and the encoder result on Set.

T23 and T30 only carry the GOP length (the maximum GOP of the rate-control attribute); Get zeroes the rest of the structure. On T41 Set stores the attribute without a range check and applies it when uGopLength is non-zero, combined with the same-scene count (uMaxSameSenceCnt).

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

IMP_Encoder_SetChnGopLength

int IMP_Encoder_SetChnGopLength(int encChn, int gopLength);

Changes the GOP length of a created channel and applies it to the running encoder.

Returns: 0 on success, an error for an invalid or not created channel or a length of 0 or less (T41: a length of 0 or less returns 0 without applying anything).

On T41 the length is combined with the same-scene count of the GOP attribute (uMaxSameSenceCnt), so the key frame distance is length times that count; a length of 0 or less is stored without being applied and returns 0. On T23 and T30 the length is the maximum GOP of the rate-control attribute.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

IMP_Encoder_RequestIDR

int IMP_Encoder_RequestIDR(int encChn);

Asks the encoder to make the next picture a key frame (IDR), with fresh parameter sets.

Returns: 0 on success, -1 for an invalid or not created channel. On a JPEG channel the call does nothing and returns 0.

Use it when a new client connects, or after a loss.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: prudynt, raptor, timps.

IMP_Encoder_Get/SetGDRCfg

int IMP_Encoder_GetGDRCfg(int encChn, IMPEncoderGDRCfg *cfg);
int IMP_Encoder_SetGDRCfg(int encChn, const IMPEncoderGDRCfg *cfg);

Sets or reads gradual decoder refresh, which refreshes the picture in slices over several frames instead of one large key frame.

Parameters

• cfg: IMPEncoderGDRCfg: enable, gdrCycle (frames between refreshes) and gdrFrames (frames one refresh is spread over).

Returns: 0 on success; -1 for an invalid channel, a NULL pointer (Set) or a channel that is not created.

With enable set, a gdrCycle outside 3 to 65535 becomes 120 and a gdrFrames outside 2 to 10 becomes 6. Setting enable to 0 switches it off. Get returns the values as stored. Encoder_RequestGDR starts one refresh on demand.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

IMP_Encoder_RequestGDR

int IMP_Encoder_RequestGDR(int encChn, int gdrFrames);

Starts a gradual refresh cycle (GDR) of the given number of frames: instead of one IDR picture the channel refreshes the picture over those frames.

Parameters

• encChn: Channel number.
• gdrFrames: Number of frames of the cycle, 2 to 10.

Returns: 0 on success; -1 for a bad channel, a channel that was not created, or a frame count outside 2 to 10.

T23 only; the request is passed to the encoder with the frame control of the next picture. Checked in the userspace audit only.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

IMP_Encoder_Get/SetChangeRef

int IMP_Encoder_GetChangeRef(int encChn, int *bEnable);
int IMP_Encoder_SetChangeRef(int encChn, int bEnable);

Reads or sets the switch for changing the reference picture.

Returns: The setter returns 0 for a created channel and -1 for one that does not exist (T20: -1 also for a started channel). The getter returns 0, also for a channel that does not exist (T20: -1).

OpenIMP keeps the value; only the vendor encoder's reference-structure code reads it, so there is no visible effect on the Helix encoder.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	⚠c	✅	✅	⚠c	·	·	·

IMP_Encoder_Get/SetChnHSkip

int IMP_Encoder_GetChnHSkip(int encChn, IMPEncoderAttrHSkip *attr);
int IMP_Encoder_SetChnHSkip(int encChn, const IMPEncoderAttrHSkip *attr);

Reads or sets the hierarchical skip attribute (skip type, same-scene count and related words) of a channel.

Returns: 0 on success, -1 for an invalid channel, a NULL pointer, a skip type above the channel's maxHSkipType, or (T20 and T10 only) a channel that was never created.

On T21 and T23 the value is also used for the key frame period: the same-scene count sets the IDR period in GOPs for the skip types N1X and H1M, and a change makes the encoder code a new IDR and restart rate control. The skip reference structure itself is not coded on the Helix path of these SoCs. On T10, T20 and T30 the value is only stored. On an idle channel Get answers all zero (T21, T30). Reading before the channel exists is an error on T20.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	⚠c	✅	✅	⚠c	·	·	·

IMP_Encoder_SetChnHSkipBlackEnhance

int IMP_Encoder_SetChnHSkipBlackEnhance(int encChn, const int bBlackEnhance);

Sets the black enhancement flag of the skip mode.

Returns: -1 for an invalid channel, otherwise 0 (the flag is kept; the Helix path codes no skip structure).

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	⚠c	⚠c	✅	⚠c	·	·	·

IMP_Encoder_Get/SetChnFrmUsedMode

int IMP_Encoder_GetChnFrmUsedMode(int encChn, IMPEncoderAttrFrmUsed *attr);
int IMP_Encoder_SetChnFrmUsedMode(int encChn, const IMPEncoderAttrFrmUsed *attr);

Stores or reads the frame use mode (enable, mode, times). The vendor encoder uses it to reuse or skip input frames when the source is slower than the encoder.

Returns: 0 on success, -1 for an invalid channel or a NULL pointer.

OpenIMP paces every channel at its frame rate, so the setting is only stored and read back. It can be set before or after CreateChn.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	🔧h	·	·	·

Quantiser, regions and picture quality

IMP_Encoder_SetChnQp

int IMP_Encoder_SetChnQp(int encChn, int iQP);

Fixes the quantiser (QP) of the channel to one value for I, P and B pictures.

Returns: 0 on success, -1 for an invalid or not created channel or a QP outside 0 to 51.

SoC: T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

IMP_Encoder_SetChnQpBounds

int IMP_Encoder_SetChnQpBounds(int encChn, int minQp, int maxQp);

Sets the lowest and highest quantiser the rate control may use.

Parameters

• minQp: Lowest QP, lower means better quality.
• maxQp: Highest QP (51 at most).

Returns: 0 on success, -1 for an invalid or not created channel, a minimum below 0, a maximum above 51, or a minimum above the maximum. On T41 values of 0 or less are ignored and return 0.

On T41 the values are clamped to what the hardware accepts.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

Used by: timps.

IMP_Encoder_SetChnQpBoundsPerFrame

int IMP_Encoder_SetChnQpBoundsPerFrame(int encChn, int minQpI, int maxQpI, int minQpP, int maxQpP);

Sets separate QP bounds for I and P pictures.

Returns: 0 on success, -1 for an invalid or not created channel, or values outside 0 to 51 or a minimum above a maximum. On T41 the codes of SetChnQpBounds are used, and the call is silently ignored (return 0) unless all four values are above 0. Where the backend has one QP window only, the union of the two windows is applied.

SoC: T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	✅

IMP_Encoder_SetChnQpIPDelta

int IMP_Encoder_SetChnQpIPDelta(int encChn, int delta);

Sets the QP difference between I and P pictures.

Returns: 0 on success, -1 for an invalid or not created channel or when the codec refuses the value.

SoC: T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

Used by: timps.

IMP_Encoder_SetChnInitQP

int IMP_Encoder_SetChnInitQP(int encChn, uint32_t initQP);

Sets the quantiser of the first picture (T23).

Returns: 0 on success, -1 for an invalid channel or a QP outside 1 to 51.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

IMP_Encoder_Get/SetQpgMode

int IMP_Encoder_GetQpgMode(int encChn, IMPEncoderQpgMode *mode);
int IMP_Encoder_SetQpgMode(int encChn, const IMPEncoderQpgMode *mode);

Selects the quantiser generator mode (ENC_QPG_CLOSE to ENC_QPG_SASM_TAB, 0 to 7).

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer or a mode outside 0 to 7. T21 does not check the range and returns 0 for a channel that does not exist, as the vendor library does.

The mode is stored and read back. On T23 it is passed to the encoder worker; on T21 nothing reads it.

SoC: only in the vendor API of T21, T23, T30

T10	T20	T21	T23	T30	T31	T40	T41
·	·	✅○	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetChnROI

int IMP_Encoder_GetChnROI(int encChn, IMPEncoderROICfg *config);
int IMP_Encoder_SetChnROI(int encChn, const IMPEncoderROICfg *config);

Defines up to eight regions of interest (index 0 to 7) in which the picture is coded with a different quantiser.

Parameters

• config: Index of the region, enable flag, relative or absolute QP and the rectangle.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer or an index of 8 or more. A non-H.264 channel accepts the call and ignores it. On T23 a channel that was not created also returns 0. The T30 build refuses an enabled region with -1.

The rectangle is converted to the 16-pixel macroblock grid, so the getter returns the rounded rectangle. The relative QP range is -25 to 25, the absolute range 0 to 51; values outside are clamped (a warning is logged once). The T21 region can be turned off with OPENIMP_T21_ROI=0. Only on the legacy encoder API (T10, T20, T21, T23); T31, T40 and T41 use SetChnRoiAttr.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅+	✅	?	·	·	·

Used by: raptor.

Difference from the vendor library: Better than the vendor on T21.

IMP_Encoder_Get/SetChnRoiAttr

int IMP_Encoder_GetChnRoiAttr(int encChn, IMPEncoderRoiAttr *roiAttr);
int IMP_Encoder_SetChnRoiAttr(int encChn, IMPEncoderRoiAttr *roiAttr);

Sets or reads the ROI windows (several regions, each with a QP value) of an H.264 channel; the windows go into the macroblock QP table from the next picture on.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer, a channel that is not H.264, or when the encoder refuses the windows (H.265, absolute QP, a window outside the picture). Get returns the stored attribute.

On T40 the function can be switched off with OPENIMP_T40_ROI=0; see the status row for what the hardware does with the table.

SoC: T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	✅	⚠c

Difference from the vendor library: See Beyond the Vendor: New in RC1 (since the 2026-10-06 state).

IMP_Encoder_SetChnMapRoi

int IMP_Encoder_SetChnMapRoi(int encChn, IMPEncoderMapRoiAttr *pstMapRoi);

Sets a region of interest from a map with one entry per macroblock; H.264 channels only.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer, a channel that is not H.264, or when the encoder refuses the map.

The map is copied. On T40 the function can be switched off with OPENIMP_T40_ROI=0.

SoC: T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	🔧h	⚠c

IMP_Encoder_Get/SetChnColor2Grey

int IMP_Encoder_GetChnColor2Grey(int encChn, IMPEncoderColor2GreyCfg *config);
int IMP_Encoder_SetChnColor2Grey(int encChn, const IMPEncoderColor2GreyCfg *config);

Makes the encoder code an H.264 picture without colour (the chroma plane is neutral), which saves bits at night.

Returns: 0 on success, -1 for an invalid or not created channel or a NULL pointer.

The enable flag is stored and read back. On T10, T20 and T21 it is applied from the next IDR picture on, and only on an H.264 channel; on T23 it is passed to the encoder worker.

SoC: T10, T20, T21, T23, T30

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetChnDenoise

int IMP_Encoder_GetChnDenoise(int encChn, IMPEncoderAttrDenoise *config);
int IMP_Encoder_SetChnDenoise(int encChn, const IMPEncoderAttrDenoise *config);

Reads or sets the encoder-side noise filter (type and the QP values for I and P pictures).

Returns: 0 on success. -1 for an invalid channel or a NULL pointer; the setter on T23 and the other SoCs also -1 for a channel that was not created (T20 and T21: 0). The setter on T30 returns -1 for a filter type other than 0 when the channel was created with denoise enabled.

The on/off switch of the filter is the one given at channel creation; the setter changes only the type and the QP values. T20 and T21 check the combination of values in the same way as the vendor library.

SoC: T10, T20, T21, T23

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetChnDemask

int IMP_Encoder_GetChnDemask(int encChn, IMPEncoderAttrDemask *attr);
int IMP_Encoder_SetChnDemask(int encChn, const IMPEncoderAttrDemask *attr);

Stores or reads the demask attribute (enable and auto flags, count, threshold). The values are stored in the channel attribute; the Helix path has no demask stage.

Returns: 0 on success, -1 for an invalid channel or a NULL pointer.

Valid before and after CreateChn, which copies the same block in from the rate-control attribute.

SoC: T10, T20

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	⚠c	·	·	·	·	·	·

IMP_Encoder_Get/SetChnCrop

int IMP_Encoder_GetChnCrop(int encChn, IMPEncoderCropCfg *cfg);
int IMP_Encoder_SetChnCrop(int encChn, const IMPEncoderCropCfg *cfg);

Sets or reads the crop window (x, y, w, h and an enable flag) at the encoder input of an H.264 channel.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer, a window that leaves the encoded picture, or on Set any of x, y, w, h being odd.

Get on a non-H.264 channel returns zero values. The window is passed to the running encoder.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	✅	❌	·	·	·

IMP_Encoder_SetChnResizeMode

int IMP_Encoder_SetChnResizeMode(int encChn, int en);

Stores the resize mode (0 or 1) of the channel.

Returns: 0 on success, -1 for an invalid channel or a value other than 0 or 1.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	?	✅	✅	✅

H.264 and H.265 options

IMP_Encoder_Get/SetH264TransCfg

int IMP_Encoder_GetH264TransCfg(int encChn, IMPEncoderH264TransCfg *config);
int IMP_Encoder_SetH264TransCfg(int encChn, const IMPEncoderH264TransCfg *config);

Reads or sets the H.264 chroma QP index offset.

Returns: 0 on success, -1 for an invalid or not created channel, a NULL pointer or an offset outside -12 to 12. The T30 build accepts only an offset of 0.

The offset applies from the next IDR picture on (written into the picture parameter set). Stored and read back on all SoCs of the legacy encoder API.

SoC: T10, T20, T21, T23

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	✅	✅	✅	?	·	·	·

Used by: raptor.

IMP_Encoder_Get/SetH265TransCfg

int IMP_Encoder_GetH265TransCfg(int encChn, IMPEncoderH265TransCfg *config);
int IMP_Encoder_SetH265TransCfg(int encChn, const IMPEncoderH265TransCfg *config);

Reads or sets the H.265 chroma QP offsets for Cb and Cr. Stored and read back on T30; dropped on T21 and T23.

Returns: 0 on success. -1 for an invalid channel or a NULL pointer; on T30 also a channel that was not created or an offset outside -12 to 12. T21 and T23 check only channel and pointer, store nothing, and the getter returns zeros.

SoC: T20, T21, T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	✅○	✅○	?	·	·	·

Used by: raptor.

IMP_Encoder_SetChnEntropyMode

int IMP_Encoder_SetChnEntropyMode(int encChn, IMPEncoderEntropyMode mode);

Chooses CAVLC or CABAC for H.264. It can be called before the channel is created, in which case the mode is used at creation.

Returns: 0 on success, -1 for an invalid channel or any mode other than CAVLC or CABAC; otherwise the result of the encoder when the channel already exists.

SoC: T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

IMP_Encoder_Get/SetChnSeiAttr

int IMP_Encoder_GetChnSeiAttr(int encChn, IMPEncoderSeiAttr *SeiAttr);
int IMP_Encoder_SetChnSeiAttr(int encChn, IMPEncoderSeiAttr *SeiAttr);

Sets or reads a user-data SEI message (a 16-byte UUID and up to 128 bytes of data) that the encoder writes into the stream before intra pictures or before every picture.

Returns: 0 on success, -1 for an invalid or not created channel, a JPEG channel, a NULL pointer, or a missing UUID or data pointer when the mode is not NONE.

A userDataSize above 128 is cut to 128 in your structure (and logged). The mode ALL writes the SEI before every picture, INTRA and any other non-zero value before intra pictures only. OpenIMP copies the UUID and data, so your buffers can change afterwards. Get returns the stored attribute.

SoC: T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	🔧h	❌

Difference from the vendor library: On IDR pictures of T40 the SEI may be left out, because the header area holds the parameter sets twice.

IMP_Encoder_InsertUserData

int IMP_Encoder_InsertUserData(int encChn, void *data, uint32_t size);

Inserts user data into the stream before the next picture, as a user_data_unregistered SEI message (H.264 channels only).

Parameters

• data: Bytes to insert.
• size: Length in bytes.

Returns: 0 on success; -1 for a NULL pointer, a size of 0 or more than 1024 bytes, a channel that does not exist or is not H.264 (T20, T21, T23, T30).

The data goes into the channel's user-data cache (the number and size of the payloads come from userData.maxUserDataCnt / maxUserDataSize in the channel attribute, two payloads in the vendor library) and is written in front of the next picture; the application finds it in the next frames of the stream. Checked with the API test on T10, T20, T21 and T23.

SoC: T10, T20, T21, T23

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	·

IMP_Encoder_Get/Setframelossthd

int IMP_Encoder_Getframelossthd(int encChn, uint32_t *framelossthd);
int IMP_Encoder_Setframelossthd(int encChn, uint32_t framelossthd);

Reads or sets the frame loss threshold in bytes (T23). The value is kept for the getter.

Returns: 0 on success, -1 for an invalid or not created channel or a NULL pointer.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	⚠c	·	·	·	·

IMP_Encoder_SetMultiSectionMode

int IMP_Encoder_SetMultiSectionMode(int mode, int size, int cnt);

Splits the encoder memory into cnt sections of size KiB. Kept only on T23: the values are recorded, nothing is allocated differently.

Returns: 0 on success, -1 for mode 0, a size or count of 0 or less. Modes above 2 count as 1.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	⚠c	·	·	·	·

JPEG

IMP_Encoder_Get/SetJpegeQl

int IMP_Encoder_GetJpegeQl(int encChn, IMPEncoderJpegeQl *attr);
int IMP_Encoder_SetJpegeQl(int encChn, IMPEncoderJpegeQl *attr);

Sets or reads the user quantisation table level of a JPEG channel.

Returns: 0 on success, -1 for an invalid channel or a NULL pointer.

On T21, T23, T30 and T41 the setting is passed to the running JPEG encoder and also kept for channels created later; elsewhere it is only stored. Get returns the stored value.

SoC: not in the vendor API of T31, T40

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	·	·	✅

IMP_Encoder_SetAvpuJpegQp

int IMP_Encoder_SetAvpuJpegQp(int encChn, int jpegQp);

Sets the JPEG quality (0 to 100) of a JPEG channel from the next picture on (T41).

Returns: 0 on success. The vendor codes 0x80040001 (channel 8 or more), 0x80040002 (quality above 100, or the channel is not a JPEG channel) and 0x80040008 (channel not created).

SoC: T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	✅

IMP_Encoder_InputJpege

int IMP_Encoder_InputJpege(uint8_t *src, uint8_t *dst, int src_w, int src_h, int q, int *stream_length);

Encodes one NV12 picture to a baseline JPEG without an encoder channel. The chroma plane follows directly after the src_w * src_h luma bytes.

Parameters

• src: Source picture, NV12, luma plane followed by the interleaved chroma plane.
• dst: Output buffer. There is no capacity argument, so it must hold the worst case.
• src_w: Width. T41: multiple of 32. T23: even.
• src_h: Height. T41: multiple of 8. T23: even.
• q: Quality 1 to 100; any other value gives 75.
• stream_length: Receives the JPEG size in bytes (0 on failure).

Returns: 0 on success, -1 for a NULL pointer, a size outside the limits above, or an encoder failure.

On T41 the picture is coded by the software JPEG encoder; the vendor library ignores q there, OpenIMP honours it. On T23 the Helix hardware codes the picture, with the software encoder as a fallback, and the quality scales the quantisation tables.

SoC: T23, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	✅

Used by: timps.

IMP_Encoder_InputJpege_Ex

int IMP_Encoder_InputJpege_Ex(uint8_t *src, uint8_t *dst, int src_w, int src_h, int q, int *stream_length);

Same as InputJpege for the secondary-process interface of the vendor library. In OpenIMP it works only in the process that owns the encoder.

Returns: 0 on success, -1 on a height that is not a multiple of 16, in a process that does not own the encoder (errno ENOTSUP), and for the errors of InputJpege.

SoC: T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

Unbound encoding of own frames (YUV interface)

The encoder can be used without FrameSource: YuvInit creates an encoder context, YuvEncode encodes one frame you supply, YuvExit frees the context. The _Ex variants use an integer handle instead of a pointer.

IMP_Encoder_YuvInit

int IMP_Encoder_YuvInit(void **h, int inWidth, int inHeight, IMPEncoderYuvIn *encIn);

Creates an encoder context for frames supplied by the application, without a FrameSource channel.

Parameters

• h: Receives the context handle.
• inWidth: Frame width. T40/T41: multiple of 16. T23: even (the native T23 encoder also needs a multiple of 16).
• inHeight: Frame height. T40/T41: multiple of 8. T23: even.
• encIn: Codec type, rate control, frame rate and GOP length (IMPEncoderYuvIn). T23 accepts H.264 only.

Returns: 0 on success, -1 for a NULL argument, an unsupported size or type, no free context, or when the encoder cannot be created. T40/T41 provide a limited number of simultaneous contexts.

On T40 and T41 the context runs the same codec as a bound channel, so rate control and GOP behave the same. On T41 a user buffer given in encIn has to come from VbmAlloc.

SoC: T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

Difference from the vendor library: See Beyond the Vendor: Extensions an application can use or detect.

IMP_Encoder_YuvEncode

int IMP_Encoder_YuvEncode(void *h, IMPFrameInfo frame, IMPEncoderYuvOut *encOut);

Encodes one frame with the context and copies the finished stream into the caller's buffer.

Parameters

• h: Context from YuvInit.
• frame: Frame description with physical and virtual address of an NV12 picture (IMPFrameInfo, passed by value).
• encOut: Output buffer outAddr; on entry outLen is the capacity (0 = unchecked on T40/T41), on return the length of the access unit.

Returns: 0 on success, -1 for an invalid handle, a missing output buffer, a frame the encoder cannot use, an encode failure, no stream within 2 seconds (T40/T41), or a stream larger than the given capacity. outLen is 0 after a failure on T40/T41.

Use frame memory from VbmAlloc where possible. On T40/T41 a frame outside reserved memory, or whose chroma plane follows a luma plane of exactly width * height bytes, is copied into the layout the encoder reads. On T23 the frame size and dimensions must match the context, and outLen must be non-zero on entry.

SoC: T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

Difference from the vendor library: A picture that does not fit the output buffer fails with -1 and outLen 0, instead of writing past the buffer.

IMP_Encoder_YuvExit

int IMP_Encoder_YuvExit(void *h);

Destroys the context and frees its resources.

Returns: 0 on success, -1 for an invalid or NULL handle.

SoC: only in the vendor API of T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

IMP_Encoder_YuvRequestIDR

int IMP_Encoder_YuvRequestIDR(void *h);

Makes the next frame of the context a key frame.

Returns: 0 on success, -1 for a NULL handle or when the encoder refuses the request.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

Used by: timps.

IMP_Encoder_YuvGetCrop

int IMP_Encoder_YuvGetCrop(void *h, IMPEncoderCropCfg *cfg);

Reads the crop of a context (T23).

Returns: 0 on success, -1 for a NULL handle or pointer or when the crop cannot be read.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

IMP_Encoder_YuvSetCrop

int IMP_Encoder_YuvSetCrop(void *h, IMPEncoderCropCfg *cfg);

Sets a crop rectangle on a context (T23). All values must be even and the rectangle inside the picture; the margins between rectangle and the 16-aligned picture edge must stay below 510 pixels.

Returns: 0 on success, -1 for a NULL handle or pointer, an odd value, a rectangle outside the picture, a margin of 510 pixels or more, or when the encoder refuses it.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	·	·

IMP_Encoder_YuvInit_Ex

int IMP_Encoder_YuvInit_Ex(int *h, int inWidth, int inHeight, IMPEncoderYuvIn *encIn);

Same as YuvInit, but returns a small integer handle (0 to 7) instead of a pointer. In OpenIMP it works only in the process that owns the encoder.

Returns: 0 on success, -1 on the errors of YuvInit, when all 8 handles are in use, or in a process without the encoder (errno ENOTSUP).

SoC: only in the vendor API of T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_YuvEncode_Ex

int IMP_Encoder_YuvEncode_Ex(int h, IMPFrameInfo frame, IMPEncoderYuvOut *encOut);

Same as YuvEncode with an integer handle.

Returns: The result of YuvEncode; -1 for an unknown handle or in a process without the encoder (errno ENOTSUP).

SoC: only in the vendor API of T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_YuvExit_Ex

int IMP_Encoder_YuvExit_Ex(int h);

Same as YuvExit with an integer handle; the handle is free for reuse afterwards.

Returns: The result of YuvExit; -1 for an unknown handle or in a process without the encoder (errno ENOTSUP).

SoC: only in the vendor API of T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_VbmAlloc

void *IMP_Encoder_VbmAlloc(uint32_t size, uint32_t align);

Allocates a physically contiguous buffer from reserved memory that the YUV and JPEG interfaces can read.

Parameters

• size: Size in bytes.
• align: Alignment in bytes: 0 or a power of two up to 4096.

Returns: Pointer to the buffer, or NULL for a size of 0, a larger alignment, a non-power-of-two alignment, or when no memory is left.

SoC: only in the vendor API of T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

IMP_Encoder_VbmFree

void IMP_Encoder_VbmFree(void *vaddr);

Frees a buffer from VbmAlloc. A NULL pointer is ignored.

Returns: 0 on success, non-zero on error (mostly -1; T40 and T41 return their own error codes for some failures).

SoC: only in the vendor API of T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

IMP_Encoder_VbmV2P

intptr_t IMP_Encoder_VbmV2P(intptr_t vaddr);

Converts a virtual address of such a buffer to its physical address. Returns 0 for an address the allocator does not own.

Returns: 0 on success, non-zero on error (mostly -1; T40 and T41 return their own error codes for some failures).

SoC: only in the vendor API of T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

Used by: timps.

IMP_Encoder_VbmP2V

intptr_t IMP_Encoder_VbmP2V(intptr_t paddr);

Converts the physical address of a VbmAlloc buffer back to the virtual one. Returns 0 for a physical address of 0.

Returns: 0 on success, non-zero on error (mostly -1; T40 and T41 return their own error codes for some failures).

SoC: only in the vendor API of T23, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	·	✅	✅

IMP_Encoder_VbmAlloc_Ex

void *IMP_Encoder_VbmAlloc_Ex(uint32_t size, uint32_t align);

Allocation for the secondary-process interface. In OpenIMP the same as VbmAlloc, but only in the process that owns the encoder; elsewhere it returns NULL (errno ENOTSUP).

Returns: 0 on success, non-zero on error (mostly -1; T40 and T41 return their own error codes for some failures).

SoC: only in the vendor API of T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_VbmFree_Ex

void IMP_Encoder_VbmFree_Ex(void *vaddr);

Free for the secondary-process interface. In OpenIMP the same as VbmFree, but only in the process that owns the encoder; elsewhere it does nothing.

Returns: 0 on success, non-zero on error (mostly -1; T40 and T41 return their own error codes for some failures).

SoC: only in the vendor API of T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

Memory, buffer sharing and pools

IMP_Encoder_Get/SetMaxStreamCnt

int IMP_Encoder_GetMaxStreamCnt(int encChn, int *cnt);
int IMP_Encoder_SetMaxStreamCnt(int encChn, int cnt);

Sets or reads how many output streams a channel may hold.

Parameters

• channel: Channel number.
• count: 1 to 16.

Returns: -1 for an invalid channel or a count outside 1 to 16. On T31, T40 and T41 the setter also fails with -1 once the channel is created.

Call the setter before CreateChn on T31, T40 and T41.

T10	T20	T21	T23	T30	T31	T40	T41
✅	✅	✅	✅	?	✅	✅	✅

Used by: raptor.

IMP_Encoder_Get/SetStreamBufSize

int IMP_Encoder_GetStreamBufSize(int encChn, int *size);
int IMP_Encoder_SetStreamBufSize(int encChn, int size);

Sets or reads the size, in bytes, of the stream buffer of a channel.

Returns: -1 for an invalid channel, a size of 0 or less, or a channel that is already created.

Set it before CreateChn; it should hold several key frames at your bitrate.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

IMP_Encoder_SetbufshareChn

int IMP_Encoder_SetbufshareChn(int encChn, int shareChn);

Records which channel a JPEG channel should share its buffers with.

Parameters

• shareChn: The video channel to share with.

Returns: 0 on success; an error code for a channel or share channel number that is out of range.

In OpenIMP the value is only stored; a channel always has its own buffers. When the JPEG channel is created and the share channel does not hold a video encoder yet, OpenIMP logs a warning (the vendor library fails there) and goes on.

SoC: T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	✅	✅

Used by: prudynt, raptor.

IMP_Encoder_SetAvpuBsShare

int IMP_Encoder_SetAvpuBsShare(bool enAvpuBs, uint32_t avpuBsSize);

Switches one shared bitstream buffer for all H.264 and H.265 channels created while it is on, instead of a private stream buffer per channel.

Returns: 0, except an allocation failure (error code 0x80040100). A channel whose stream buffer does not fit in the shared one fails at CreateChn with 0x80048008.

Call it with enAvpuBs set before CreateChn; avpuBsSize is the buffer size in bytes (0 selects the default of about 2.3 MB). Turn it off after the channels are destroyed. While it is on, each channel keeps 2 streams by default and the pictures are handed out from heap copies (phyAddr is 0).

SoC: T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_SetRdBufShare

int IMP_Encoder_SetRdBufShare(int encChn, int enable);

Stores the flag for sharing the reference/reconstruction buffer ring of a channel (set before creating the channel).

Returns: 0 on success, -1 for an invalid channel or a channel that already exists.

Kept only: the T23 hardware encoder follows the environment variable OPENIMP_REF_SHARE (unset means on, the vendor default).

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	?	·	·	·	·

IMP_Encoder_SetIvpuBsSize

int IMP_Encoder_SetIvpuBsSize(uint32_t ivpuBsSize);

Sets the size of the bitstream buffer of the second hardware unit (T41). OpenIMP encodes JPEG on the CPU, so the value only limits the size of the JPEG that InputJpege returns.

Returns: 0 on success, 0x80040002 for a size of 0, 0x80040040 when called after the system was initialised (IMP_System_Init).

Call it before IMP_System_Init.

SoC: T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	·	·	🔧h

IMP_Encoder_SetPoolSize

int IMP_Encoder_SetPoolSize(int size);

Sets the size of the encoder bitstream pool. On T30 it sets the bitstream buffer (1920 * 1080 bytes unless set); on the other SoCs the value is only kept.

Returns: 0 on success, -1 for a size of 0 or less.

IMP_Encoder_Get/SetPool

int IMP_Encoder_GetPool(int encChn);
int IMP_Encoder_SetPool(int encChn, int poolId);

Records which memory pool the channel is bound to, or reads it back (-1 = none).

Parameters

• encChn: Channel number.
• poolId: Pool id, or -1 for none.

Returns: The setter returns 0, or -1 for an invalid channel or an id below -1; the getter returns the id, or -1 for an invalid channel.

SoC: T23, T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	✅	·	✅	✅	✅

Used by: raptor.

Difference from the vendor library: In OpenIMP a pool is a name only: every channel takes its buffers from the one common memory arena, so the id changes nothing about where buffers come from.

IMP_Encoder_ClearPoolId

int IMP_Encoder_ClearPoolId(int encChn);

Removes the pool binding (SetPool) from every encoder channel; the channel number argument is unused.

Returns: 0.

SoC: T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	?	·	·

Other

IMP_Encoder_Get/SetFisheyeEnableStatus

int IMP_Encoder_GetFisheyeEnableStatus(int encChn, int *enable);
int IMP_Encoder_SetFisheyeEnableStatus(int encChn, int enable);

Stores a fisheye flag for a channel and returns it. The fisheye processing itself is not provided; the flag only lets the application read back what it set.

Returns: 0 on success, -1 for an invalid channel, a NULL pointer (Get), or (Set) a channel that has already been created.

Set it before the channel is created.

T10	T20	T21	T23	T30	T31	T40	T41
⚠c	⚠c	⚠c	⚠c	⚠c	⚠c	⚠c	❌

IMP_Encoder_EnableAllNCUDenoise

int IMP_Encoder_EnableAllNCUDenoise(void);

NCU denoise exists on T30-class SoCs only; on T23 the call fails.

Returns: -1 on T23.

IMP_Encoder_DisableAllNCUDenoise

int IMP_Encoder_DisableAllNCUDenoise(void);

NCU denoise exists on T30-class SoCs only; on T23 the call fails.

Returns: -1 on T23.

IMP_Encoder_PadFrame

/* IMP_Encoder_PadFrame: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Vendor entry for feeding application frames into the encoder in place of captured ones. On T23 OpenIMP refuses every frame: it calls the release callback to give the frame back and returns -1.

Returns: -1 on T23.

Only the attribute side (SetPadFrameAttr) is stored.

SoC: not in the vendor API of T31, T40, T41

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	?	❌	·	·	·

IMP_Encoder_SetPadFrameAttr

/* IMP_Encoder_SetPadFrameAttr: exported by libimp; declared in the vendor SDK header, not in the OpenIMP include directory */

Stores the pad-frame attribute and enable flag for an H.264 channel. The attribute is only kept, because PadFrame is refused.

Returns: 0 on success for an H.264 channel, -1 for an invalid channel.

SoC: T23

T10	T20	T21	T23	T30	T31	T40	T41
❌	❌	❌	?	❌	·	·	·

IMP_Encoder_GetChnEvalInfo

int IMP_Encoder_GetChnEvalInfo(int encChn, void *info);

Reads the evaluation record of the most recent picture of an H.264 channel on T31: bytes of the picture, six hardware picture counters, then the slice QP and the lowest and highest QP used.

Parameters

• encChn: Channel number.
• info: Buffer of at least 36 bytes (8 for a JPEG channel); lay it over IMPEncoderStreamInfo (IMPEncoderJpegInfo for JPEG).

Returns: 0 on success, -1 for an invalid channel, a NULL pointer or a channel that was not created (errno ENOTSUP on the SoCs that do not have it). The record is 36 bytes (8 bytes for a JPEG channel) and is refreshed with every stream the encoder finishes.

Checked on a T31 camera with an AVC channel: iNumBytes 3993 for a 4003-byte access unit, QP 20/20/23; and a JPEG channel with 40209 bytes at quality 75.

SoC: T31

T10	T20	T21	T23	T30	T31	T40	T41
·	·	·	·	·	✅	·	·

Used by: raptor.

Difference from the vendor library: The record has the layout of IMPEncoderStreamInfo in the header: iNumBytes (entropy bytes of the picture) at offset 0, the six counters at 4 to 27, slice, minimum and maximum QP at 28, 30 and 32. The vendor 1.1.6 library copies the same data one 32-bit word later (no iNumBytes, every field 4 bytes earlier). This is a deliberate difference: do not apply a 4-byte compensation for the vendor shift with OpenIMP. A JPEG channel returns 8 bytes: iNumBytes (JPEG size) at 0 and the quality factor at 4.