API FrameSource

API reference: FrameSource

A FrameSource channel is one video output of the ISP: it has a size, a pixel format, an optional crop and scaler stage and a frame rate. The usual SoCs offer three channels: 0 (main stream), 1 (sub stream) and 2 (third stream or an extension channel). A channel feeds other modules (encoder, OSD, IVS) through IMP_System_Bind, or hands raw frames to the application with IMP_FrameSource_GetFrame.

Typical call order: IMP_ISP_Open and sensor setup, then IMP_System_Init, then CreateChn, optional SetChnFifoAttr / SetMaxDelay / SetFrameDepth, bind the channel to its consumers, EnableChn. Shut down in the reverse order: DisableChn, unbind, DestroyChn.

OpenIMP also offers a fallback frame (a test image delivered while the sensor stalls); it is switched with the environment variable OPENIMP_FALLBACK_FRAME and the OpenIMP extension OpenIMP_FrameSource_SetFallback, 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

• Channel lifecycle (4)
• Channel attributes (2)
• Getting frames (7)
• Delay FIFO and timed frames (4)
• Rotate, flip and mirror (2)
• Buffer memory (2)
• External injection (T40 and T41) (6)
• Other (7)

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)

Channel lifecycle

A channel goes through the states closed, created and running. Size, format and rate can only be changed while it is created but not running.

IMP_FrameSource_CreateChn

int IMP_FrameSource_CreateChn(int chnNum, IMPFSChnAttr *chn_attr);

Creates a channel with the given attributes and registers it as a module that can be bound. The channel does not run yet.

Parameters

• chnNum: Channel number, normally 0 to 2.
• chn_attr: Size, pixel format, crop, scaler, frame rate and number of buffers of the channel.

Returns: 0 on success, -1 if the number or the attributes are invalid or the channel already exists.

The width must be a multiple of 16 unless the format is raw. The structure layout differs between SoC families (T40 and T41 put an I2D block in front, T23 and newer add a frame crop), so build against the header of the SoC you target. A frame rate of outFrmRateNum/outFrmRateDen below the sensor rate drops frames; it never raises the rate above the sensor rate.

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_EnableChn, IMP_FrameSource_DestroyChn

IMP_FrameSource_DestroyChn

int IMP_FrameSource_DestroyChn(int chnNum);

Releases a channel and its buffers. The channel has to be disabled and unbound first.

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

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_CreateChn

IMP_FrameSource_EnableChn

int IMP_FrameSource_EnableChn(int chnNum);

Starts the channel. The sensor stream starts with the first enabled channel, and the buffers are allocated here.

Returns: 0 on success, -1 on error (no sensor, size too large, not enough buffer memory).

Call it after all consumers are bound, so no frame is produced before somebody can take it. Enabling an already running channel is not an error.

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_DisableChn

IMP_FrameSource_DisableChn

int IMP_FrameSource_DisableChn(int chnNum);

Stops the channel. Frames that the application still holds stay valid until they are released.

Returns: 0 on success (also when the channel was not running), -1 for an invalid number.

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_EnableChn

Channel attributes

IMP_FrameSource_Get/SetChnAttr

int IMP_FrameSource_GetChnAttr(int chnNum, IMPFSChnAttr *chn_attr);
int IMP_FrameSource_SetChnAttr(int chnNum, IMPFSChnAttr *chn_attr);

Reads or changes the attributes of a channel. Setting is only allowed while the channel is created and not running.

Parameters

• chnNum: Channel number.
• chn_attr: Attribute structure to read into or to apply.

Returns: 0 on success, -1 on error.

A change of the picture size has to be followed by a matching change of the encoder channel. For a rotated or cropped stream see SetChnRotate, SetI2dAttr and the crop fields of the structure.

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_CreateChn

IMP_FrameSource_SetYuvAlign

int IMP_FrameSource_SetYuvAlign(int chnNum, IMPFrameAlign *param);

Asks for line padding of the YUV frames to a multiple of 8, 16 or 32 bytes.

Parameters

• chnNum: Channel number.
• param: Enable flag and alignment of width and height.

Returns: 0 when the channel size already satisfies the alignment, -1 (errno ENOTSUP) when padded frames would be needed.

SoC: T41

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

Difference from the vendor library: Refuses padding that the channel would need; the open frame channel cannot pad.

Getting frames

The encoder normally pulls its frames through the bind, so a plain streamer never calls these. Use them when the application needs raw NV12 frames (snapshots, motion detection of its own, analysis). Every frame obtained with GetFrame has to be given back with ReleaseFrame, otherwise the channel runs out of buffers.

IMP_FrameSource_Get/SetFrameDepth

int IMP_FrameSource_GetFrameDepth(int chnNum, int *depth);
int IMP_FrameSource_SetFrameDepth(int chnNum, int depth);

Sets or reads how many frames the channel keeps ready for GetFrame. Without a depth, GetFrame has nothing to return.

Parameters

• chnNum: Channel number.
• depth: Number of queued frames. 0 disables the queue and frees the frames in it.

Returns: 0 on success, -1 on error.

The queue is separate from what the encoder sees through the bind; a frame the application does not release is not available again for the queue. Use the smallest depth that works (1 or 2), since every frame is a full capture buffer.

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

Used by: prudynt, raptor, timps.

See also: IMP_FrameSource_GetFrame, IMP_FrameSource_ReleaseFrame

IMP_FrameSource_GetFrame

int IMP_FrameSource_GetFrame(int chnNum, void **frame);

Waits for the next frame of the channel and returns a pointer to its description (IMPFrameInfo). The pixel data stays in the capture buffer, nothing is copied.

Parameters

• chnNum: Channel number, which has to be running and have a frame depth.
• frame: Receives the frame pointer.

Returns: 0 on success, -1 on a bad argument or when no frame arrives within about 2 seconds.

Give the frame back with ReleaseFrame. Frame data is NV12 for the YUV formats; the stride can be larger than the width.

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

Used by: raptor, timps.

Difference from the vendor library: Waits up to 2 seconds like the vendor library; a non-blocking first call after a pause no longer fails on an empty queue.

See also: IMP_FrameSource_ReleaseFrame, IMP_FrameSource_Get/SetFrameDepth

IMP_FrameSource_ReleaseFrame

int IMP_FrameSource_ReleaseFrame(int chnNum, void *frame);

Returns a frame obtained with GetFrame to the channel.

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

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

Used by: raptor, timps.

See also: IMP_FrameSource_GetFrame

IMP_FrameSource_GetFrameEx

int IMP_FrameSource_GetFrameEx(int chnNum, IMPFrameInfo **frame);

Variant of GetFrame for T40 and T41 that returns the frame without the depth queue, straight from the channel.

Returns: 0 on success, -1 on error or timeout.

SoC: only in the vendor API of T40, T41

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

See also: IMP_FrameSource_ReleaseFrameEx

IMP_FrameSource_ReleaseFrameEx

int IMP_FrameSource_ReleaseFrameEx(int chnNum, IMPFrameInfo *pframe);

Gives back a frame obtained with GetFrameEx.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

See also: IMP_FrameSource_GetFrameEx

IMP_FrameSource_SnapFrame

int IMP_FrameSource_SnapFrame(int chnNum, IMPPixelFormat fmt, int width, int height, void *out_buffer, IMPFrameInfo *info);

Copies one frame into a buffer of the application, in the format and size of the channel, and fills a frame description. Meant for snapshots.

Parameters

• chnNum: Channel number, running.
• fmt: Pixel format, must be the format of the channel.
• width: Width, must be the channel width.
• height: Height, must be the channel height.
• out_buffer: Buffer of at least one packed frame (for NV12 width*height*3/2).
• info: Receives the frame description.

Returns: 0 on success, -1 when width, height or format differ from the channel or no frame arrives.

The channel needs no frame depth for this call. The output is packed NV12 without line padding.

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

Used by: raptor.

IMP_FrameSource_SetFrameDepthCopyType

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

Chooses whether frames of the depth queue are copies or are held in place (zero copy).

Parameters

• chnNum: Channel number.
• bNoCopy: Non-zero for zero copy.

Returns: 0 on success, -1 on error.

SoC: T31

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

Delay FIFO and timed frames

A channel can keep the last few frames in a FIFO so the application can ask for the frame that was captured a given time ago (for example to record a few seconds before a motion event).

IMP_FrameSource_Get/SetChnFifoAttr

int IMP_FrameSource_GetChnFifoAttr(int chnNum, IMPFSChnFifoAttr *attr);
int IMP_FrameSource_SetChnFifoAttr(int chnNum, IMPFSChnFifoAttr *attr);

Configures the frame FIFO of the channel. In OpenIMP this is the same as setting the maximum delay to maxdepth and the delay to the same value.

Parameters

• chnNum: Channel number.
• attr: maxdepth is the number of frames to keep (0 means no FIFO). type selects the FIFO behaviour.

Returns: 0 on success, -1 on error.

A maxdepth of 0 changes nothing and is accepted in every state, which is what streamers send. Only FIFO_CACHE_PRIORITY is supported when the FIFO is used.

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

Used by: prudynt, raptor.

Difference from the vendor library: FIFO_DATA_PRIORITY with a non-zero depth is refused with -1, because it needs capture buffers shared between readers that OpenIMP does not have.

See also: IMP_FrameSource_Get/SetMaxDelay, IMP_FrameSource_Get/SetDelay

IMP_FrameSource_Get/SetDelay

int IMP_FrameSource_GetDelay(int chnNum, int *delay_ms);
int IMP_FrameSource_SetDelay(int chnNum, int delay_ms);

Sets or reads the delay, in frames, of the channel's FIFO, that is how many of the newest frames are kept for GetTimedFrame.

Parameters

• chnNum: Channel number.
• delay: Number of frames, between 0 and the value set with SetMaxDelay.

Returns: -1 when the channel does not exist or the delay is larger than the maximum delay.

The delay can be changed while the channel is running. Each kept frame occupies one capture buffer, so the sum of nrVBs and the maximum delay has to fit the buffer budget (checked when the channel is enabled).

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

Used by: raptor.

See also: IMP_FrameSource_Get/SetMaxDelay, IMP_FrameSource_GetTimedFrame

IMP_FrameSource_Get/SetMaxDelay

int IMP_FrameSource_GetMaxDelay(int chnNum, int *max_delay_ms);
int IMP_FrameSource_SetMaxDelay(int chnNum, int max_delay_ms);

Sets or reads the upper limit of the delay FIFO and reserves the buffers for it.

Parameters

• chnNum: Channel number.
• max_delay: Maximum delay in frames, 0 to 100 in the API, in OpenIMP limited by the buffers that fit in memory.

Returns: -1 when the value is out of range or the channel is not in the created state.

Call it between CreateChn and EnableChn. The default is 0, which changes nothing.

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

Used by: raptor.

See also: IMP_FrameSource_Get/SetDelay

IMP_FrameSource_GetTimedFrame

int IMP_FrameSource_GetTimedFrame(int chnNum, void *framets, int block, void *framedata, void *frame);

Returns the buffered frame that is closest to a requested capture time, together with the frame data copy.

Parameters

• chnNum: Channel number.
• framets: Requested timestamp and the tolerance before and after it.
• block: Non-zero waits for a matching frame, zero returns at once.
• framedata: Buffer that receives the frame data.
• frame: Receives the frame description.

Returns: 0 on success, -1 when there is no delay FIFO (call SetMaxDelay before EnableChn) or no frame matches.

Used for pre-event recording. T40 and T41 keep the delay frames as copies, which costs one frame copy per GetFrame while the delay is above 0.

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

Used by: raptor.

See also: IMP_FrameSource_Get/SetMaxDelay

Rotate, flip and mirror

IMP_FrameSource_SetChnRotate

int IMP_FrameSource_SetChnRotate(int chnNum, int rotTo90, int width, int height);

Turns the channel picture by 90 or 180 degrees in software, before any consumer sees it.

Parameters

• chnNum: Channel number.
• rotTo90: 0 off, 1 90 degrees counterclockwise, 2 90 degrees clockwise, 3 180 degrees.
• width: Picture width before the rotation.
• height: Picture height before the rotation.

Returns: -1 for an unsupported size (odd, above 4096) or mode.

Create the encoder channel with the rotated size (width and height swapped for 90 degrees). The rotation costs CPU time on every frame; on T40 and T41 use the hardware I2D block instead.

SoC: T31 (software rotation). T40 and T41 use SetI2dAttr.

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

Used by: timps.

Difference from the vendor library: Mode 3 (180 degrees) is an OpenIMP addition; the vendor library only knows 0 to 2.

IMP_FrameSource_Get/SetI2dAttr

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

Rotates, flips or mirrors the output of the channel with the hardware I2D block.

Parameters

• chnNum: Channel number.
• attr: Enable flags for flip, mirror and rotate, and the angle.

Returns: 0 on success, -1 on error.

Changing it needs the channel to be stopped, and the encoder size has to follow a rotation by 90 degrees.

SoC: T40 and T41

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

Used by: raptor.

Buffer memory

IMP_FrameSource_Get/SetPool

int IMP_FrameSource_GetPool(int chnNum);
int IMP_FrameSource_SetPool(int chnNum, int poolId);

Binds the channel's buffers to a memory pool created with IMP_System_MemPoolRequest, or reads the pool id.

Parameters

• chnNum: Channel number.
• poolId: Id of the pool. Set it before EnableChn.

Returns: The getter returns the pool id; the setter returns 0 or -1.

SoC: T23, T31, T41

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

Used by: raptor.

Difference from the vendor library: Real pools on T23 and T31. On T41 the id is only recorded and the buffers still come from the normal memory.

IMP_FrameSource_ClearPoolId

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

Forgets the pool id of the channel, so the buffers come from the default memory again.

Returns: 0 on success, -1 on error.

SoC: T31

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

External injection (T40 and T41)

A channel that is filled by the application instead of the sensor, for example to run a recorded or generated NV12 image through the encoder.

IMP_FrameSource_DequeueBuffer

int IMP_FrameSource_DequeueBuffer(int chnNum, IMPFrameInfo **frame);

Takes an empty buffer of an injection channel, which the application then fills with an NV12 picture.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

See also: IMP_FrameSource_QueueBuffer

IMP_FrameSource_QueueBuffer

int IMP_FrameSource_QueueBuffer(int chnNum, const IMPFrameInfo *frame);

Hands a filled buffer of an injection channel to the consumers of the channel.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

See also: IMP_FrameSource_DequeueBuffer

IMP_FrameSource_ExternInject_CreateChn

int IMP_FrameSource_ExternInject_CreateChn(int chnNum, IMPFSChnAttr *chnAttr);

Creates an injection channel, a channel without sensor that is fed by the application.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

See also: IMP_FrameSource_DequeueBuffer

IMP_FrameSource_ExternInject_DestroyChn

int IMP_FrameSource_ExternInject_DestroyChn(int chnNum);

Destroys an injection channel.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

IMP_FrameSource_ExternInject_EnableChn

int IMP_FrameSource_ExternInject_EnableChn(int chnNum);

Starts the injection channel, so buffers can be dequeued.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

IMP_FrameSource_ExternInject_DisableChn

int IMP_FrameSource_ExternInject_DisableChn(int chnNum);

Stops the injection channel.

Returns: 0 on success, -1 on error.

SoC: only in the vendor API of T40, T41

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

Other

IMP_FrameSource_ChnStatQuery

int IMP_FrameSource_ChnStatQuery(int chnNum, void *stat);

Reads the state of a channel as a number.

Parameters

• chnNum: Channel number.
• stat: Pointer to a 32-bit integer that receives 0 (closed), 1 (created) or 2 (running).

Returns: 0 on success, -1 on error.

SoC: T31

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

IMP_FrameSource_Get/SetDirectModeAttr

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

Selects the direct (online) mode between ISP and encoder, in which frames are not routed through a memory buffer.

Returns: 0 on success, -1 on error.

SoC: T23

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

IMP_FrameSource_SetSource

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

Declares which physical channel an extension channel (FS_EXT_CHANNEL) is derived from.

Parameters

• extchnNum: Number of the extension channel.
• sourcechnNum: Number of the physical channel it is cut from, 0 to 2.

Returns: 0 on success, -1 on error.

SoC: T31

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

IMP_FrameSource_EnableChnUndistort

int IMP_FrameSource_EnableChnUndistort(int chnNum);

Switches the lens distortion correction of the channel on. Accepted, no effect in OpenIMP (the call returns 0).

Returns: 0 on success, -1 on error.

IMP_FrameSource_DisableChnUndistort

int IMP_FrameSource_DisableChnUndistort(int chnNum);

Switches the lens distortion correction of the channel off. Accepted, no effect in OpenIMP.

Returns: 0 on success, -1 on error.

IMP_FrameSource_SetFrameOffset

int IMP_FrameSource_SetFrameOffset(int chnNum, int offset);

Sets a frame offset for the channel. Accepted and ignored, returns 0.

Returns: 0 on success, -1 on error.

IMP_FrameSource_CloseNCUInfo

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

Turns off the per-frame NCU information of the buffer manager. Internal helper of the vendor library, kept for compatibility.

Returns: 0 on success, -1 on error.