5.9. Region Processing - OSD
5.9.1. Module Description
The OSD (On-Screen Display) module is an important image processing tool that configures operation regions (Region) and overlays them onto images with operations such as color filling, drawing, and mosaic. Its main application scenarios include:
Video/image enhancement: overlay annotations or information display on real-time video or static images.
Privacy protection: Blur or cover specific areas by overlaying mosaics or occlusion areas to protect sensitive information.
Since OSD is an auxiliary function of VSE, it cannot be used independently. It must be attached to a VSE output channel by calling the hbn_rgn_attach_to_chn interface.
5.9.1.1. Basic Specifications
OSD supports color filling, point/line/text drawing, mosaic, and other functions.
Text drawing supports the 16x16 dot matrix HZK16 Chinese font library and the 16x8 dot matrix ASC16 English font library.
The width of overlaid Region in OSD must be a multiple of 32, height must be even, and minimum size is 32x2.
Supports overlay region data format VGA_8, with colormap supporting up to 16 colors.
Each OSD supports 8 histogram statistic regions with area size ranging from 2x2 to 256x256.
VSE hardware supports OSD functionality; all channels except channel 4 support hardware OSD with maximum of 4 regions per channel. Software OSD supports up to 255 regions.
When using OSD, it must be bound to a VSE output channel. The OSD support status for each VSE output channel is as follows:
| VSE Output Channel ID | Hardware OSD Overlay Function | Software OSD Overlay Function |
|---|---|---|
| 0 | Supported | Supported |
| 1 | Supported | Supported |
| 2 | Supported | Supported |
| 3 | Supported | Supported |
| 4 | Not supported | Supported |
| 5 | Supported | Supported |
Note: VSE channel 4 uses software implementation with NEON instruction set for OSD overlay functionality by default.
The input channel (Ichn0) of VSE receives data from two sources: one via VFLOW, and the other through recirculation.
The region buffer is created via
hbn_rgn_create, and then attached to a specified VSE channel usinghbn_rgn_attach_to_chn.After binding the OSD to a specific VSE output channel (Ochnx), the OSD hardware automatically overlays the region buffer data onto the video frames processed by VSE.
VSE output channel 4 (Ochn4) does not support hardware OSD and defaults to NEON-based software implementation for OSD overlay.
When more than 4 regions are used on a VSE output channel, the extra regions beyond 4 are processed using software with NEON instructions.
5.9.1.2. Notes
Region Limitations: Each VSE channel supports up to 4 non-overlapping OSD regions in hardware (i.e., the 4 Regions must not overlap vertically). Below are example diagrams:
The left image shows supported OSD region overlay methods; the right image shows unsupported methods.
OSD Supported Overlay Types:
OVERLAY: Overlay region, allows user-defined content filling within a rectangular area, such as writing text or drawing lines.
COVER: Covered area, solid color block, supports rectangles and polygons, but not circles.
MOSAIC: Mosaic region, applies mosaic effect to a rectangular area for obscuring.
5.9.2. Reference Examples
Refer to the sample_osd section for sample code related to OSD.
5.9.3. API Reference
| API Interface | Function Description |
|---|---|
| hbn_rgn_create | Create region |
| hbn_rgn_destroy | Destroy region |
| hbn_rgn_getattr | Get region attributes |
| hbn_rgn_setattr | Set region attributes |
| hbn_rgn_setbitmap | Set region buffer |
| hbn_rgn_attach_to_chn | Attach region to channel |
| hbn_rgn_detach_from_chn | Detach region from channel |
| hbn_rgn_set_displayattr | Set display attributes |
| hbn_rgn_get_displayattr | Get display attributes |
| hbn_rgn_draw_word | Write string into buffer |
| hbn_rgn_draw_line | Draw line in buffer |
| hbn_rgn_set_colormap | Set OSD color index mapping table |
| hbn_rgn_get_sta | Get brightness statistic region |
| hbn_rgn_set_sta | Set brightness statistic region |
5.9.3.1. hbn_rgn_create()
【Function Declaration】
int32_t hbn_rgn_create(hbn_rgn_handle_t handle, const hbn_rgn_attr_t *region)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_rgn_attr_t region: region attribute.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Used to create a region.
【Notes】
None
5.9.3.2. hbn_rgn_destroy
【Function Declaration】
int32_t hbn_rgn_destroy(hbn_rgn_handle_t handle)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Used to destroy a region.
【Notes】
None
5.9.3.3. hbn_rgn_getattr
【Function Declaration】
int32_t hbn_rgn_getattr(hbn_rgn_handle_t handle, hbn_rgn_attr_t *region)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_rgn_attr_t *region: region attributes.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
After creating a region, this function retrieves its attributes.
【Notes】
None
5.9.3.4. hbn_rgn_setattr
【Function Declaration】
int32_t hbn_rgn_setattr(hbn_rgn_handle_t handle, const hbn_rgn_attr_t *region)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_rgn_attr_t *region: region attributes.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
After creating a region, this function sets its attributes.
【Notes】
None
5.9.3.5. hbn_rgn_setbitmap
【Function Declaration】
int32_t hbn_rgn_setbitmap(hbn_rgn_handle_t handle, const hbn_rgn_bitmap_t *bitmap_attr)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_rgn_bitmap_t *bitmap_attr: buffer attributes for the region.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
After creating a region, users can allocate a buffer for drawing and set it as the buffer for this region.
【Notes】
None
5.9.3.6. hbn_rgn_attach_to_chn
【Function Declaration】
int32_t hbn_rgn_attach_to_chn(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_vnode_handle_t vnode_fd: target VSE handle to bind to, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: target VSE channel ID.
[IN] hbn_rgn_chn_attr_t *rgn_chn: display attributes of the region when overlaid on the channel.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Used to attach a created region to a specific VSE channel.
【Notes】
VSE channel 4 lacks hardware OSD capability and uses software processing. Other channels support up to 4 hardware OSD regions, which must not overlap vertically. Any additional regions are handled by software.
5.9.3.7. hbn_rgn_detach_from_chn
【Function Declaration】
int32_t hbn_rgn_detach_from_chn(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_vnode_handle_t vnode_fd: VSE handle to detach from, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: VSE channel ID to detach from.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Used to detach a created region from a specific VSE channel.
【Notes】
None
5.9.3.8. hbn_rgn_set_displayattr
【Function Declaration】
int32_t hbn_rgn_set_displayattr(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_vnode_handle_t vnode_fd: target VSE handle to operate on, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: target VSE channel ID.
[IN] hbn_rgn_chn_attr_t *rgn_chn: display attributes of the region when overlaid on the channel.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
After binding a region to a channel, this function modifies the binding attributes.
【Notes】
None
5.9.3.9. hbn_rgn_get_displayattr
【Function Declaration】
int32_t hbn_rgn_get_displayattr(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)
【Parameter Description】
[IN] hbn_rgn_handle_t handle: region handle, unique identifier for the region, maximum value cannot exceed 255.
[IN] hbn_vnode_handle_t vnode_fd: target VSE handle to operate on, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: target VSE channel ID.
[IN] hbn_rgn_chn_attr_t *rgn_chn: display attributes of the region when overlaid on the channel.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
After binding a region to a channel, this function retrieves the binding attributes.
【Notes】
None
5.9.3.10. hbn_rgn_draw_word
【Function Declaration】
int32_t hbn_rgn_draw_word(const hbn_rgn_draw_word_t *draw_word)
【Parameter Description】
[IN] hbn_rgn_draw_word_t *draw_word: attributes for drawing text.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Draw text on a user-allocated buffer. Combined with the hbn_rgn_setbitmap() function, this buffer can be assigned to a specific region.
【Notes】
None
5.9.3.11. hbn_rgn_draw_line
【Function Declaration】
int32_t hbn_rgn_draw_line(const hbn_rgn_draw_line_t *draw_line)
【Parameter Description】
[IN] hbn_rgn_draw_line_t *draw_line: attributes for drawing lines.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Draw lines on a user-allocated buffer. Combined with the hbn_rgn_setbitmap() function, this buffer can be assigned to a specific region.
【Notes】
None
5.9.3.12. hbn_rgn_set_colormap
【Function Declaration】
int32_t hbn_rgn_set_colormap(uint32_t color_map[16])
【Parameter Description】
[IN] uint32_t color_map[16]: new color_map to set.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Set a new global color_map. The color_map must follow this rule: R component in bits 16–23, G component in bits 8–15, B component in bits 0–7.
【Notes】
The newly set color_map remains effective until system reboot.
5.9.3.13. hbn_rgn_set_sta
【Function Declaration】
int32_t hbn_rgn_set_sta(hbn_vnode_handle_t vnode_fd, int32_t chnid, uint8_t sta_level[3], hbn_rgn_sta_t sta_attr[8]);
【Parameter Description】
[IN] hbn_vnode_handle_t vnode_fd: target VSE handle, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: target VSE channel ID.
[IN] uint8_t sta_level[3]: threshold values for statistics, must be configured in ascending order, range from 1 to 254.
[IN] hbn_rgn_sta_t sta_attr[8]: attributes of statistic regions, including positional information.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Set 3 threshold values and position information for up to 8 statistic regions. These regions are independent of regular regions and should be used in conjunction with hbn_rgn_get_sta().
【Notes】
This function must be called each time before retrieving statistical data to reconfigure.
5.9.3.14. hbn_rgn_get_sta
【Function Declaration】
int32_t hbn_rgn_get_sta(hbn_vnode_handle_t vnode_fd, int32_t chnid, uint16_t sta_value[8][4])
【Parameter Description】
[IN] hbn_vnode_handle_t vnode_fd: target VSE handle, obtained via hbn_vflow_get_vnode_handle().
[IN] int32_t chnid: target VSE channel ID.
[OUT] uint16_t sta_value[8][4]: statistical data, retrieves pixel counts in 4 intervals based on brightness histogram and configured thresholds.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Function Description】
Retrieve statistical data from up to 8 regions, output in the form of brightness histograms. With 3 configured thresholds, returns pixel counts in 4 intervals.
【Notes】
None.
5.9.4. Parameter Description
typedef enum hbn_rgn_type_e hbn_rgn_type_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| OVERLAY_RGN | - | - | - | - | Overlay type: overlays an image onto the channel | - |
| COVER_RGN | - | - | - | - | Covered type: covers the channel with a solid color | - |
| MOSAIC_RGN | - | - | - | - | Mosaic type: converts a region into mosaic (currently unsupported) | - |
| RGN_TYPE_MAX | - | - | - | - | Maximum number of supported types | - |
typedef enum hbn_rgn_font_size_e hbn_rgn_font_size_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| FONT_SIZE_SMALL | - | - | - | - | Small font size | - |
| FONT_SIZE_MEDIUM | - | - | - | - | Medium font size | - |
| FONT_SIZE_LARGE | - | - | - | - | Large font size | - |
| FONT_SIZE_EXTRA_LARGE | - | - | - | - | Extra Large Font Size | - |
typedef enum hbn_rgn_font_color_e hbn_rgn_font_color_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| FONT_COLOR_WHITE | - | - | - | - | White | - |
| FONT_COLOR_BLACK | - | - | - | - | Black | - |
| FONT_COLOR_GREY | - | - | - | - | Grey | - |
| FONT_COLOR_BLUE | - | - | - | - | Blue | - |
| FONT_COLOR_GREEN | - | - | - | - | Green | - |
| FONT_COLOR_RED | - | - | - | - | Red | - |
| FONT_COLOR_CYAN | - | - | - | - | Cyan | - |
| FONT_COLOR_PURPLE | - | - | - | - | Purple | - |
| FONT_COLOR_YELLOW | - | - | - | - | Yellow | - |
| FONT_COLOR_ORANGE | - | - | - | - | Orange | - |
| FONT_COLOR_BROWN | - | - | - | - | Brown | - |
| FONT_COLOR_PINK | - | - | - | - | Pink | - |
| FONT_COLOR_DARKBLUE | - | - | - | - | Dark Blue | - |
| FONT_COLOR_DARKGREEN | - | - | - | - | Dark Green | - |
| FONT_COLOR_DARKRED | - | - | - | - | Dark Red | - |
| FONT_COLOR_DARKGRAY | - | - | - | - | Dark Grey | - |
| FONT_KEY_COLOR_NUM | - | - | - | - | Number of Colors | - |
typedef enum hbn_rgn_pixel_format_e hbn_rgn_pixel_format_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| PIXEL_FORMAT_VGA_8 | - | - | - | - | 8-bit color/alpha data format | - |
| PIXEL_FORMAT_YUV420SP | - | - | - | - | YUV420SP data format (not supported yet) | - |
typedef enum hbn_rgn_cover_type_e hbn_rgn_cover_type_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| COVER_RECT | - | - | - | - | Rectangle | - |
| COVER_POLYGON | - | - | - | - | Polygon | - |
typedef struct hbn_rgn_size_s hbn_rgn_size_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| width | uint32_t | - | - | - | Width | - |
| height | uint32_t | - | - | - | Height | - |
struct hbn_rgn_point_s hbn_rgn_point
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| x | uint32_t | - | - | - | X coordinate | - |
| y | uint32_t | - | - | - | Y coordinate | - |
typedef struct hbn_ren_overlay_s hbn_rgn_overlay_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| pixel_fmt | hbn_rgn_pixel_format_t | - | - | - | Data format type | Yes |
| size | hbn_rgn_size_t | - | - | - | Size, width must be multiple of 32, | Yes |
| height must be multiple of 2 |
struct hbn_rgn_polygon_s hbn_rgn_polygon
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| side_num | hbn_rgn_pixel_format_t | 0 | POLYGON_MAX_SIDE | - | Number of polygon vertices | Yes |
| vertex[POLYGON_MAX_SIDE] | hbn_rgn_point_t | - | - | - | Coordinates of polygon vertices, inner polygons not supported | Yes |
struct hbn_rgn_cover_attr_s hbn_rgn_cover
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| cover_type | hbn_rgn_cover_type_t | - | - | - | Cover type | Yes |
| - | union (size, polygon) | - | - | - | Size information for rectangle or coordinate data for polygon | Yes |
| For rectangle: width must be multiple of 32, height must be multiple of 2 | Yes |
struct hbn_rgn_mosaic_attr_s hbn_rgn_mosaic
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| size | hbn_rgn_size_t | - | - | - | Must satisfy width multiple of 16, height multiple of 2 | Yes |
| pixel_block | uint32_t | - | - | - | Currently unused | No |
struct hbn_rgn_attr_s hbn_rgn_attr
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| type | hbn_rgn_type_t | OVERLAY_RGN | MOSAIC_RGN | - | Region type | Yes |
| alpha | uint32_t | 0 | 15 | - | Alpha blending coefficient | No |
| color | hbn_rgn_font_color_t | FONT_COLOR_WHITE | FONT_COLOR_DARKGRAY | - | Color | Yes |
| overlay_attr | hbn_rgn_overlay_t | - | - | - | Overlay attribute | Yes |
| cover_attr | hbn_rgn_cover_t | - | - | - | Cover attribute | Yes |
| mosaic_chn | hbn_rgn_mosaic_t | - | - | - | Mosaic attribute | No |
struct hbn_rgn_chn_attr_s hbn_rgn_chn_attr
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| show | bool | - | - | - | Whether to display | Yes |
| invert_en | bool | - | - | - | Whether to invert color (not supported yet) | No |
| display_level | uint32_t | 0 | 3 | 0 | Display level: must be 0 for hardware OSD, 1–3 for software; currently used to distinguish hardware/software, display level not supported yet | Yes |
| point | hbn_rgn_point_t | - | - | - | Coordinate information | Yes |
struct hbn_rgn_bitmap_attr_s hbn_rgn_bitmap
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| pixel_fmt | hbn_rgn_pixel_format_t | - | - | - | Data format type | Yes |
| size | hbn_rgn_size_t | - | - | - | Size information | Yes |
| *paddr | void | - | - | - | Input buffer address | Yes |
struct hbn_rgn_draw_word_param_s hbn_rgn_draw_word
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| *paddr | void | - | - | - | Canvas buffer address | Yes |
| size | hbn_rgn_size_t | - | - | - | Canvas size | Yes |
| *draw_string | uint8_t | - | - | - | String address for drawing text, must end with "\0"; supports simplified Chinese and English characters; note that Chinese characters must be encoded in GBK | Yes |
| font_color | hbn_rgn_font_color_t | 0 | FONT_COLOR_DARKGRAY | - | Font color | Yes |
| bg_color | uint32_t | 0 | FONT_COLOR_DARKGRAY | - | Background color | Yes |
| alpha | uint32_t | 0 | 15 | - | Alpha blending index: 0 = fully transparent, 15 = fully opaque; currently only hardware supports this | Yes |
| font_size | hbn_rgn_font_size_t | - | - | - | Font size | Yes |
| flush_en | bool | - | - | - | Whether to refresh canvas | Yes |
typedef struct hbn_rgn_draw_line_param_s hbn_rgn_draw_line_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| *paddr | void | - | - | - | Buffer address for drawing line | Yes |
| size | hbn_rgn_size_t | - | - | - | Canvas size | Yes |
| start_point | hbn_rgn_point_t | - | - | - | Start coordinate of line | Yes |
| end_point | hbn_rgn_point_t | - | - | - | End coordinate of line | Yes |
| thick | uint32_t | - | - | - | Line thickness | Yes |
| color | hbn_rgn_font_color_t | FONT_COLOR_WHITE | FONT_COLOR_DARKGRAY | - | Line color | Yes |
| bg_color | uint32_t | FONT_COLOR_WHITE | FONT_COLOR_DARKGRAY | - | Background color | Yes |
| alpha | uint32_t | 0 | 15 | - | Background transparency; line opacity is fixed at 15; hardware supports semi-transparent background, software currently only supports fully transparent background | Yes |
| flush_en | bool | - | - | - | Whether to refresh canvas | Yes |
typedef struct hbn_rgn_sta_attr_s hbn_rgn_sta_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| sta_en | uint8_t | - | - | - | Whether to enable this region | Yes |
| start_x | uint16_t | - | - | - | Starting X coordinate | Yes |
| start_y | uint16_t | - | - | - | Starting Y coordinate | Yes |
| width | uint16_t | 2 | 255 | - | Width of statistics region | Yes |
| height | uint16_t | 2 | 255 | - | Height of statistics region | Yes |