API IVS

API reference: IVS

IVS runs an analysis algorithm on the video frames; the usual one is motion detection. An algorithm is an interface object (IMPIVSInterface): a set of callbacks plus a parameter block. The library ships two ready interfaces (CreateMoveInterface, CreateBaseMoveInterface), and an application can fill an interface of its own with custom callbacks (init, exit, preProcessSync, processAsync, getResult, releaseResult, getParam, setParam, flushFrame). A channel runs one interface in its own thread; a group ties channels to a frame source: bind the FrameSource channel to the IVS group with IMP_System_Bind, register the IVS channel in the group, then start it.

Typical call order: CreateMoveInterface, CreateGroup, CreateChn, RegisterChn, bind the FrameSource channel to the group, StartRecvPic, then loop on PollingResult, GetResult, ReleaseResult. Shut down with StopRecvPic, UnRegisterChn, DestroyChn, DestroyGroup, DestroyMoveInterface.

OpenIMP implements the framework once for T10 to T41. There are two groups (0 and 1) and up to 65 channels (0 to 64). Every frame of the bound FrameSource channel reaches each receiving IVS channel; a channel that is still busy with the previous frame drops the new one, so a slow algorithm never stalls the video path. Custom interfaces are supported: their preProcessSync sees the capture frame, and processAsync works on a private NV12 copy, since OpenIMP cannot hold a capture buffer for the algorithm. This was tested with a custom IMPIVSInterface. On errors the calls return -1 and set errno.

OpenIMP also offers OpenIMP_IVS_Move*Ex functions (a richer motion result with objects and a runtime configuration), see Beyond the Vendor.

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

Contents

• Ready-made interfaces (4)
• Groups and channels (6)
• Running and results (6)
• Parameters (1)

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)

Ready-made interfaces

Both create an interface object from a parameter block (NULL is refused with -1/EINVAL) and copy the block into it. The returned pointer goes to CreateChn; destroy the interface after the channel is gone.

IMP_IVS_CreateMoveInterface

IMPIVSInterface *IMP_IVS_CreateMoveInterface(IMP_IVS_MoveParam *param);

Creates the motion detection interface (frame-difference detector over up to 52 regions of interest with a sensitivity per region).

Parameters

• param: IMP_IVS_MoveParam: sensitivity per region, region rectangles and count, skipFrameCnt (frames skipped between comparisons) and the frame size.

Returns: The interface, or NULL when param is NULL (EINVAL) or memory runs out.

The result of the channel is an IMP_IVS_MoveOutput with one flag per region (retRoi), obtained with GetResult.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

See also: IMP_IVS_DestroyMoveInterface, IMP_IVS_CreateChn

IMP_IVS_DestroyMoveInterface

void IMP_IVS_DestroyMoveInterface(IMPIVSInterface *moveInterface);

Frees a motion interface. The channel using it has to be destroyed first.

Returns: no value.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

IMP_IVS_CreateBaseMoveInterface

IMPIVSInterface *IMP_IVS_CreateBaseMoveInterface(IMP_IVS_BaseMoveParam *param);

Creates the base motion interface, a block-based comparison against reference frames that returns a per-block result buffer instead of region flags.

Parameters

• param: IMP_IVS_BaseMoveParam: skipFrameCnt (0 or more), referenceNum (above 0), sadMode (0), sense and frameInfo with the frame size (1 to 8192 each).

Returns: The interface, or NULL when param is NULL (EINVAL) or memory runs out. The values in param are checked when the channel initialises the interface; an out-of-range value makes the channel creation fail.

The result is an IMP_IVS_BaseMoveOutput (ret, a data buffer and its length). The buffer holds one byte per 8x8 block, (width / 8) * (height / 8) bytes, and one result is produced for every frame. On T21, T23, T30, T40 and T41 the output also carries the frame timestamp. SetParam changes only sense; the other fields stay as created.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

IMP_IVS_DestroyBaseMoveInterface

void IMP_IVS_DestroyBaseMoveInterface(IMPIVSInterface *moveInterface);

Frees a base motion interface. The channel using it has to be destroyed first.

Returns: no value.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

Groups and channels

IMP_IVS_CreateGroup

int IMP_IVS_CreateGroup(int grpNum);

Creates an IVS group.

Parameters

• grpNum: Group number, 0 or 1.

Returns: 0 on success; -1 for a group number out of range.

Creating a group twice is not an error (it only logs), as in the vendor library.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_IVS_DestroyGroup

int IMP_IVS_DestroyGroup(int grpNum);

Removes a group.

Returns: 0 on success, also for a group that was never created (vendor behaviour). -1 for an invalid number or while a channel is still registered in the group.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

IMP_IVS_CreateChn

int IMP_IVS_CreateChn(int chnNum, IMPIVSInterface *handler);

Creates a channel for an interface and starts its processing thread. The interface's init callback is called.

Parameters

• chnNum: Channel number, 0 to 64.
• handler: Interface. It needs at least a preProcessSync or a processAsync; a param pointer must come with a positive paramSize and vice versa.

Returns: 0 on success. -1 for a bad number or interface, a channel that exists, an interface that already serves another channel, an init that fails or no thread.

One interface serves one channel. Create a second interface for a second channel.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

See also: IMP_IVS_DestroyChn, IMP_IVS_RegisterChn

IMP_IVS_DestroyChn

int IMP_IVS_DestroyChn(int chnNum);

Stops the channel if needed, unregisters it, ends its thread and calls the interface's exit callback.

Returns: 0 on success, -1 for an invalid number or a channel that does not exist.

It is safe to call while another thread waits in PollingResult; that call returns with a timeout error.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

IMP_IVS_RegisterChn

int IMP_IVS_RegisterChn(int grpNum, int chnNum);

Attaches a channel to a group so it receives the frames bound to that group.

Returns: 0 on success, -1 for invalid numbers, a group or channel that does not exist, or a channel that is already registered.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_IVS_UnRegisterChn

int IMP_IVS_UnRegisterChn(int chnNum);

Detaches a channel from its group.

Returns: 0 on success, -1 when the channel is not registered or is still receiving (call StopRecvPic first).

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

Running and results

IMP_IVS_StartRecvPic

int IMP_IVS_StartRecvPic(int chnNum);

Lets the channel receive and analyse frames.

Returns: 0 on success, -1 when the channel does not exist or is not registered in a group.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_IVS_StopRecvPic

int IMP_IVS_StopRecvPic(int chnNum);

Stops frame delivery. A frame in flight is given up to about one second to finish, then the interface's flushFrame is called.

Returns: 0 on success, -1 when the channel does not exist.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: prudynt, raptor, timps.

IMP_IVS_PollingResult

int IMP_IVS_PollingResult(int chnNum, int timeoutMs);

Waits until the channel has a new result.

Parameters

• chnNum: Channel.
• timeoutMs: Milliseconds; 0 only checks, a negative value (IMP_IVS_DEFAULT_TIMEOUTMS) waits up to 10 seconds.

Returns: 0 when a result is ready, -1 with ETIMEDOUT when none arrived in time or the channel was destroyed meanwhile, -1 for an invalid or missing channel.

Follow with GetResult and ReleaseResult.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_IVS_GetResult

int IMP_IVS_GetResult(int chnNum, void **result);

Hands out the pointer to the latest result (the interface's getResult callback).

Parameters

• chnNum: Channel.
• result: Receives the pointer to the result structure of the interface (for the motion interface an IMP_IVS_MoveOutput).

Returns: What the interface returns; -1 for invalid arguments or a channel without getResult.

For the two ready-made interfaces six results are kept in a ring, and the call does not check that a new result is pending. Always wait with PollingResult first.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

Difference from the vendor library: See Beyond the Vendor: IVS / motion.

See also: IMP_IVS_PollingResult, IMP_IVS_ReleaseResult

IMP_IVS_ReleaseResult

int IMP_IVS_ReleaseResult(int chnNum, void *result);

Gives a result back (the interface's releaseResult callback). For the ready-made interfaces this does nothing.

Returns: What the interface returns; -1 for invalid arguments or a missing channel.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.

IMP_IVS_ReleaseData

int IMP_IVS_ReleaseData(void *vaddr);

Releases frame data that a custom interface was handed. In OpenIMP the capture frames are never held for IVS, so this checks the pointer and returns.

Parameters

• vaddr: Address of the data, must not be NULL.

Returns: 0, or -1 for a NULL pointer.

Call it where the vendor documentation says to, so the program also works with the vendor library. Tested with a custom IMPIVSInterface.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor.

Parameters

IMP_IVS_Get/SetParam

int IMP_IVS_GetParam(int chnNum, void *param);
int IMP_IVS_SetParam(int chnNum, void *param);

Reads or writes the parameter block of the channel's interface.

Parameters

• chnNum: Channel.
• param: A block of the size the interface declared (paramSize); for the motion interface an IMP_IVS_MoveParam.

Returns: 0 on success, -1 for a NULL pointer, a missing channel, or an interface without parameter support. The motion interface refuses a sensitivity outside 0 to 8 and keeps the old parameters.

A new parameter set takes effect with the next accepted frame. GetParam returns the interface's current copy.

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

Tested (tool, date, camera, what was checked):

• T10: apitest rc3gaps2 2026-10-27 .31
• T20: apitest rc3gaps2 2026-10-27 .107
• T21: apitest rc3gaps2 2026-10-27 .24
• T23: apitest rc3gaps2 2026-10-27 .30
• T31: apitest rc3gaps2 2026-10-27 .26
• T40: apitest rc3gaps2 2026-10-27 .184
• T41: apitest rc3gaps2 2026-10-27 .34

Used by: raptor, timps.