API OSD

API reference: OSD

OSD puts overlays (text bitmaps, pictures, lines, rectangles, solid covers, mosaics) on the video. The model is: a group is an overlay stage that sits in a frame path (usually between FrameSource and Encoder); a region is one overlay object with a handle. A region exists on its own (CreateRgn), becomes visible in a group after RegisterRgn and ShowRgn, and has two attribute sets: the region attribute (type, geometry, picture data) and the group-region attribute (position and visibility inside one group).

Typical call order: CreateGroup, CreateRgn, SetRgnAttr, RegisterRgn, SetGrpRgnAttr, AttachToGroup (or a bind that contains the OSD cell), Start, ShowRgn. Change the picture of a running region with UpdateRgnAttrData.

Where the overlay is drawn depends on the SoC. On T10 to T31 the group draws into the NV12 frame in software: lines, rectangles and bitmaps by the CPU, pictures and covers through the IPU where the build has the IPU backend (switch off with OPENIMP_T31_OSD=0). T23, T40 and T41 use the same CPU drawing for lines and mosaics and the IPU for pictures and covers (OPENIMP_T23_OSD=0 disables drawing, the state is still kept). On T23, T40 and T41 there is in addition an ISP-drawn OSD: pictures that the ISP blends into the stream after the scaler, with the _ISP / _PicISP calls below (also reachable as IMP_ISP_Tuning_*OsdRgn).

Limits in OpenIMP: T10 to T31 accept groups 0 to 3 and 64 regions; T23, T40 and T41 accept groups 0 to 8 and 512 regions.

Error values: on T10 to T31 a failing call returns -1 and sets errno. T23, T40 and T41 return the OSD error codes of that SDK generation instead (for example 0x80020001 for a bad group, 0x80020002 for a bad parameter, 0x80020008 for a region that does not exist, 0x80020010 for a NULL pointer). Test for "not 0", not for -1, in code that runs on both families. The _ISP calls always return -1.

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

Contents

• Groups (6)
• Regions (8)
• Registering and showing (4)
• ISP-drawn OSD (T23, T40, T41) (10)
• Helpers (3)

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

IMP_OSD_CreateGroup

int IMP_OSD_CreateGroup(int grpNum);

Creates an OSD group so regions can be registered in it.

Parameters

• grpNum: Group index, 0 to 3 on T10 to T31, 0 to 8 on T23, T40 and T41.

Returns: 0 on success, an error value for a group number out of range.

Creating a group that already exists succeeds and keeps it as it is.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_DestroyGroup, IMP_OSD_RegisterRgn

IMP_OSD_DestroyGroup

int IMP_OSD_DestroyGroup(int grpNum);

Removes a group.

Returns: 0 on success, an error value for an invalid index or a group that was not created. On T10 to T31 also an error while a region is still registered in the group; T23, T40 and T41 instead drop the registrations and succeed.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_CreateGroup, IMP_OSD_UnRegisterRgn

IMP_OSD_AttachToGroup

int IMP_OSD_AttachToGroup(IMPCell *from, IMPCell *to);

Splices the OSD cell from into the existing bind that feeds the cell to, so the path source -> to becomes source -> OSD -> to.

Parameters

• from: The OSD cell (device DEV_ID_OSD, group number).
• to: The cell whose input is redirected, normally an encoder channel.

Returns: 0 on success, non-zero when to has no bind to splice into or one of the new binds fails; the original bind is restored in that case.

Do it before the encoder channel starts, since the encoder looks its OSD group up when the channel is registered or started. The call is a wrapper around IMP_System_GetBindbyDest, IMP_System_UnBind and IMP_System_Bind.

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

See also: IMP_System_Bind, IMP_OSD_Start

IMP_OSD_Start

int IMP_OSD_Start(int grpNum);

Lets the group draw on every frame that passes it.

Returns: 0 on success, an error value for an invalid index; on T10 to T31 also when the group was not created.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_Stop

IMP_OSD_Stop

int IMP_OSD_Stop(int grpNum);

Stops drawing; frames pass the group unchanged. Region state is kept.

Returns: 0 on success, an error value for an invalid index; on T10 to T31 also when the group was not created.

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

Used by: raptor.

IMP_OSD_SetGroupCallback

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

Installs a function that is called with every frame after the group has drawn into it (T40 and T41). NULL removes it.

Parameters

• grpNum: Group created with CreateGroup; below 6 on T40, below 4 on T41.
• callback: int cb(int group_index, IMPFrameInfo *frame); its return value is ignored.

Returns: 0 on success, an error value for an invalid or not created group.

Set it after CreateGroup and before the frame source is enabled. The callback runs outside the OSD lock, so it may call other OSD functions. The frame may be modified in place.

SoC: Only in the vendor API of T40 and T41.

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

Regions

A region exists independently of any group. Types are line, rectangle, bitmap, cover and picture (OSD_REG_*), plus the ISP types on T23, T40 and T41.

IMP_OSD_CreateRgn

IMPRgnHandle IMP_OSD_CreateRgn(IMPOSDRgnAttr *prAttr);

Allocates a region and returns its handle. With an attribute it is also loaded straight away.

Parameters

• attr: Region attribute, or NULL to set it later with SetRgnAttr.

Returns: The handle (0 or more), or a negative error value when all regions are in use (64 on T10 to T31, 512 on T23, T40 and T41) or memory runs out.

A destroyed handle is reused. A bitmap or picture is converted and kept in rmem when the attribute is set, so the source buffer may be released afterwards.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_DestroyRgn, IMP_OSD_SetRgnAttr

IMP_OSD_DestroyRgn

int IMP_OSD_DestroyRgn(IMPRgnHandle handle);

Frees a region and its picture memory.

Returns: 0 on success, an error value for an invalid or unused handle. On T10 to T31 also an error while the region is still registered in a group.

Call UnRegisterRgn first. On T23, T40 and T41 the call does not check this.

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

Used by: prudynt, raptor, timps.

IMP_OSD_Get/SetRgnAttr

int IMP_OSD_GetRgnAttr(IMPRgnHandle handle, IMPOSDRgnAttr *prAttr);
int IMP_OSD_SetRgnAttr(IMPRgnHandle handle, IMPOSDRgnAttr *prAttr);

Writes or reads the region attribute (type, geometry, colours, picture data pointer).

Parameters

• handle: Region handle from CreateRgn.
• attr: Region attribute.

Returns: an error value for an invalid or unused handle or a NULL attribute.

Setting reloads the picture or bitmap, so it is slower than UpdateRgnAttrData when only the picture bytes change. The change is visible from the next frame on. On T40 and T41 an attribute from an older SDK layout is accepted, the missing part is zeroed.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_UpdateRgnAttrData

IMP_OSD_SetRgnAttrWithTimestamp

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

Same as SetRgnAttr, with a timestamp argument that is accepted but not used.

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

OpenIMP does not track a frame time window, the attribute applies from the next frame. On T23, T40 and T41 a NULL timestamp is refused.

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

Used by: raptor.

IMP_OSD_UpdateRgnAttrData

int IMP_OSD_UpdateRgnAttrData(IMPRgnHandle handle, IMPOSDRgnAttrData *prAttrData);

Replaces only the data part of the region attribute (the picture or bitmap pointer) and reloads the overlay. Use it to refresh a clock or text bitmap.

Returns: an error value for an invalid or unused handle or NULL data.

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

Used by: prudynt, raptor.

IMP_OSD_RgnCreate_Query

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

Tells whether a region handle is in use.

Parameters

• stat: Receives status 1 when the region exists, else 0.

Returns: an error value for a NULL pointer or a handle out of range.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_RgnRegister_Query

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

Tells whether a region is registered in a group.

Parameters

• stat: Receives status 1 when registered in that group, else 0.

Returns: an error value for a NULL pointer, a handle out of range or an invalid group.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_SetPoolSize

int IMP_OSD_SetPoolSize(int size);

Records the size of the OSD picture pool.

Parameters

• size: Bytes, must be above 0.

Returns: an error value for a size of 0 or less.

OpenIMP allocates each picture separately from rmem, so the value is only stored; the call is kept for programs that set it before IMP_System_Init.

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

Used by: prudynt, raptor, timps.

Difference from the vendor library: The vendor reserves a pool of this size. OpenIMP never runs out because of the pool size.

Registering and showing

IMP_OSD_RegisterRgn

int IMP_OSD_RegisterRgn(IMPRgnHandle handle, int grpNum, IMPOSDGrpRgnAttr *pgrAttr);

Puts a region into a group. The optional group-region attribute gives position and visibility there.

Parameters

• handle: Region handle.
• grpNum: Group created with CreateGroup.
• attr: Group-region attribute (show, offPos, scaling, layer, alpha), or NULL for all zero (not shown).

Returns: an error value for an invalid handle or group, a region or group that does not exist, or (T10 to T31) a region that is already registered in another group.

On T10 to T31 a region belongs to one group, T23, T40 and T41 allow registering it in several. Registering a shown ISP line or cover region on T23 also hands it to the ISP.

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

Used by: prudynt, raptor, timps.

See also: IMP_OSD_ShowRgn, IMP_OSD_SetGrpRgnAttr

IMP_OSD_UnRegisterRgn

int IMP_OSD_UnRegisterRgn(IMPRgnHandle handle, int grpNum);

Takes a region out of a group.

Returns: an error value for an invalid handle or group or when the region is not registered in that group.

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

Used by: prudynt, raptor, timps.

IMP_OSD_Get/SetGrpRgnAttr

int IMP_OSD_GetGrpRgnAttr(IMPRgnHandle handle, int grpNum, IMPOSDGrpRgnAttr *pgrAttr);
int IMP_OSD_SetGrpRgnAttr(IMPRgnHandle handle, int grpNum, IMPOSDGrpRgnAttr *pgrAttr);

Writes or reads the per-group attribute of a registered region (visibility, offset, layer, alpha, scaling).

Returns: an error value for an invalid argument or when the region is not registered in the group.

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

Used by: prudynt, raptor, timps.

IMP_OSD_ShowRgn

int IMP_OSD_ShowRgn(IMPRgnHandle handle, int grpNum, int showFlag);

Shows or hides a registered region in a group without touching its other attributes.

Parameters

• show: Non-zero shows, 0 hides.

Returns: an error value for an invalid argument or when the region is not registered in the group.

For ISP line and cover regions on T23, T40 and T41 the call also switches the ISP overlay.

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

Used by: prudynt, raptor, timps.

ISP-drawn OSD (T23, T40, T41)

Pictures drawn by the ISP itself. The region is addressed by frame-source channel chn and a slot handle (8 slots per channel). The usual order is Init_ISP (done implicitly), SetPoolSize_ISP, CreateRgn_ISP, SetRgnAttr_PicISP, ShowRgn_ISP, and at the end DestroyRgn_ISP. A picture must lie inside the frame of the channel. The picture bytes are copied into rmem when the attribute is set, so the caller may free its buffer.

IMP_OSD_CreateRgn_ISP

IMPRgnHandle IMP_OSD_CreateRgn_ISP(int chn, IMPIspOsdAttrAsm *attr);

Reserves one of the 8 picture slots of a frame-source channel for an ISP-drawn picture and returns its handle.

Parameters

• chn: Frame-source channel (0 to 2 on T23, 0 to 5 on T40, 0 or 1 on T41).
• attr: Must be NULL; the picture is given with SetRgnAttr_PicISP.

Returns: The handle (0 to 7), or -1 for a bad channel, a non-NULL attribute or when all 8 slots are in use.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_SetRgnAttr_PicISP

int IMP_OSD_SetRgnAttr_PicISP(int chn, IMPRgnHandle handle, IMPIspOsdAttrAsm *attr);

Gives a slot its picture (position, size, stride, pixel data). The picture bytes are copied into rmem; the slot stays hidden until ShowRgn_ISP.

Parameters

• chn: Frame-source channel.
• handle: Slot from CreateRgn_ISP.
• attr: ISP picture attribute of type ISP_OSD_REG_PIC; the picture must lie inside the channel frame.

Returns: -1 for an invalid argument, a slot that was not created, another type, a picture outside the frame, stride times height of 0, or no rmem.

On T40 and T41 the picture size of a slot cannot change after the first set; destroy and recreate the slot instead. The memory is counted against the pool size.

SoC: Only on T23, T40 and T41.

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

Difference from the vendor library: On T23 an odd picture width is refused with -1 (the ISP stops on it; the vendor library accepts it). The vendor takes the picture as it is; OpenIMP copies it into rmem and flushes the cache before the driver sees it. See Beyond the Vendor: Behaviour that differs from the vendor (better or deviating on purpose).

IMP_OSD_UpdateRgnAttrData_ISP

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

Exchanges the picture bytes of a slot that already has a picture of the same size and resends it to the ISP.

Returns: -1 for an invalid argument, a slot without picture, a different size or a NULL picture pointer.

SoC: Only on T23 (T40 and T41 change a picture through SetRgnAttr_PicISP).

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

IMP_OSD_GetRgnAttr_ISPPic

int IMP_OSD_GetRgnAttr_ISPPic(int chn, IMPRgnHandle handle, IMPIspOsdAttrAsm *attr);

Reads back the stored attribute of a slot; osd_enable shows whether it is currently shown.

Returns: -1 for an invalid argument. T23 also returns -1 for a slot that was not created, T40 and T41 return the stored copy anyway.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_ShowRgn_ISP

int IMP_OSD_ShowRgn_ISP(int chn, IMPRgnHandle handle, int showFlag);

Shows or hides an ISP picture slot.

Returns: -1 for an invalid argument or a slot without picture (T23) or not created (T40, T41).

On T40 and T41 a shown region that overlaps an earlier shown one in the same channel is dropped from the ISP update.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_DestroyRgn_ISP

int IMP_OSD_DestroyRgn_ISP(int chn, IMPRgnHandle handle);

Hides the slot if needed, releases its picture memory and frees the slot.

Returns: -1 for an invalid argument or (T23) a slot that was not created.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_SetPoolSize_ISP

int IMP_OSD_SetPoolSize_ISP(int size);

Sets the budget for ISP OSD pictures.

Parameters

• size: Bytes, above 0.

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

On T40 and T41 the sum of all slot pictures is checked against this size and SetRgnAttr_PicISP fails when it is exceeded; the value may be set after IMP_System_Init. Call it before creating the pictures.

SoC: Only on T23, T40 and T41.

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

Difference from the vendor library: The vendor allocates the pool at IMP_System_Init; OpenIMP counts the slot sizes against the latest value instead.

IMP_OSD_Init_ISP

int IMP_OSD_Init_ISP(void);

Prepares the ISP OSD. Calling it is optional on T40 and T41, which prepare themselves on the first region call.

Returns: 0.

T23 clears its picture slots; the pictures get their own rmem buffers, so SetPoolSize_ISP has no memory effect there.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_Exit_ISP

void IMP_OSD_Exit_ISP(void);

Destroys every ISP picture slot that is still in use.

Returns: no value.

T23 first hides the slots that are shown, then frees their pictures. T40 and T41 destroy every region that was created.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_Get/SetRgnAttr_ISP

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

Sets or reads an ISP line, rectangle or cover region (the ISP draws boxes and masks, not pictures). The region attribute carries the draw block or the mask block.

Parameters

• show: Remembered and returned by Get; the enable field inside the ISP block decides whether the region is drawn.

Returns: 0 on success; -1 on error. On T23 a type outside the three ISP types gives the OSD not-supported error and a NULL attribute the parameter error.

T23 takes (attr, show) with _Sec for the second sensor and MultiCamera_ variants with a sensor number; the line/rectangle type goes to Tuning_SetDrawBlock, the cover type to Tuning_SetMaskBlock, a picture type is refused (use SetRgnAttr_PicISP); Get reads the OSD attributes and the mask block. RegisterRgn, SetRgnAttr and ShowRgn call it for you for ISP line and cover regions. T40 takes (sensor, attr, show): sensor below 2, region type 10 to 12 only; the line/rectangle type goes to IMP_ISP_SetDrawAttr, the cover type to IMP_ISP_Tuning_SetMask, a picture type is refused; Get reads the draw attributes, the OSD attributes and the mask.

SoC: T23 and T40; not exported on T41.

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

Multi-sensor variants (T23): _Sec suffix (second sensor) and ISP_MultiCamera_ prefix.

Helpers

IMP_OSD_SetMosaic

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

Pixelates a rectangle of an NV12 frame in place (luma only).

Parameters

• frame_virAddr: Virtual address of the frame; its luma plane is modified.
• attr: Rectangle (x, y, size), frame size and mosaic cell size.

Returns: 0 on success, non-zero for a NULL argument, odd coordinates or sizes, a rectangle outside the frame or a cell size of 0 or less.

Every pixel of a cell takes the value of the cell's top-left pixel; chroma stays untouched.

SoC: Only on T23, T40 and T41.

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

IMP_OSD_Alloc

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

Copies a picture into rmem and returns its physical address, for use as data of an OSD_REG_PIC_RMEM region (undocumented vendor helper).

Parameters

• phys_out: Receives the physical address.
• data: Picture bytes, or NULL to leave the memory uninitialised.
• size: Bytes, above 0.

Returns: 0 on success, -1 for a NULL output, a size of 0 or less, or no memory.

SoC: Implemented by OpenIMP on T23.

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

IMP_ISPOSD_Alloc

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

Allocates an uninitialised rmem buffer for an ISP OSD picture and returns its virtual address (undocumented vendor helper).

Parameters

• size: Bytes, above 0.

Returns: The address, or NULL on failure.

SoC: Implemented by OpenIMP on T23.

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