# K230 nonai 2D API reference

## Overview

### Overview

nonai 2D hardware can implement OSD, picture frame and CSC functions. This article only describes the CSC function. The OSD and picture frame functions have not yet been implemented in the API of this article. They can be added in the future if there is demand.

The VENC module uses nonai 2D hardware to superimpose OSD and picture frames on encoded images. It is limited to encoded images and cannot be used alone. See chapters 1.2.1.4 and 2.1.14 ~ 2.1.29 of "K230_Video Codec_API Reference".

### Functional Description

Realizes the mutual conversion between RGB and YUV. As a module of mpp, it can participate in the system binding function and can perform single frame processing without binding.

Supports mutual conversion of the following image formats:

PIXEL_FORMAT_YUV_SEMIPLANAR_420

PIXEL_FORMAT_YVU_PLANAR_420

PIXEL_FORMAT_YUV_PACKAGE_444

PIXEL_FORMAT_YVU_PLANAR_444

PIXEL_FORMAT_RGB_565

PIXEL_FORMAT_RGB_888

PIXEL_FORMAT_RGB_888_PLANAR

Code example:

```c
k_nonai_2d_chn_attr attr_2d;
k_video_frame_info input;
k_video_frame_info output;
int ch = 0;

attr_2d.mode = K_NONAI_2D_CALC_MODE_CSC;
attr_2d.dst_fmt = PIXEL_FORMAT_YUV_SEMIPLANAR_420;
kd_mpi_nonai_2d_create_chn(ch, &attr_2d);
kd_mpi_nonai_2d_start_chn(ch);

input.v_frame.pixel_format = PIXEL_FORMAT_RGB_888;
kd_mpi_nonai_2d_send_frame(ch, &input, 1000);
kd_mpi_nonai_2d_get_frame(ch, &output, 1000);

kd_mpi_nonai_2d_stop_chn(ch);
kd_mpi_nonai_2d_destroy_chn(ch);
```

## API Reference

- [kd_mpi_nonai_2d_request_chn](#kd_mpi_nonai_2d_request_chn)
- [kd_mpi_nonai_2d_release_chn](#kd_mpi_nonai_2d_release_chn)
- [kd_mpi_nonai_2d_attach_vb_pool](#kd_mpi_nonai_2d_attach_vb_pool)
- [kd_mpi_nonai_2d_detach_vb_pool](#kd_mpi_nonai_2d_detach_vb_pool)
- [kd_mpi_nonai_2d_create_chn](#kd_mpi_nonai_2d_create_chn)
- [kd_mpi_nonai_2d_destroy_chn](#kd_mpi_nonai_2d_destroy_chn)
- [kd_mpi_nonai_2d_start_chn](#kd_mpi_nonai_2d_start_chn)
- [kd_mpi_nonai_2d_stop_chn](#kd_mpi_nonai_2d_stop_chn)
- [kd_mpi_nonai_2d_get_frame](#kd_mpi_nonai_2d_get_frame)
- [kd_mpi_nonai_2d_release_frame](#kd_mpi_nonai_2d_release_frame)
- [kd_mpi_nonai_2d_send_frame](#kd_mpi_nonai_2d_send_frame)

### kd_mpi_nonai_2d_request_chn

Description

Apply for free 2D channels.

Syntax

```c
k_s32 kd_mpi_nonai_2d_request_chn(k_u32* chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Output the requested idle channel number, value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Output |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If chn_num is a null pointer, K_ERR_NONAI_2D_NULL_PTR is returned.
- If there is no free channel, K_ERR_NONAI_2D_NOBUF or the corresponding no resource error code is returned.
- The applied channel needs to be initialized through kd_mpi_nonai_2d_create_chn before it can be used.

Example

None.

Related Topics

kd_mpi_nonai_2d_release_chn、kd_mpi_nonai_2d_create_chn

### kd_mpi_nonai_2d_release_chn

Description

Release the applied 2D channel.

Syntax

```c
k_s32 kd_mpi_nonai_2d_release_chn(k_u32 chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number to be released, value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If the channel number exceeds the legal range, K_ERR_NONAI_2D_INVALID_CHNID is returned.
- If the channel has not been applied for or has been released, K_ERR_NONAI_2D_UNEXIST is returned.
- Before releasing the channel, make sure that the channel has been stopped (kd_mpi_nonai_2d_stop_chn) and destroyed (kd_mpi_nonai_2d_destroy_chn), otherwise the return operation does not allow errors.

Example

None.

Related Topics

kd_mpi_nonai_2d_request_chn、kd_mpi_nonai_2d_destroy_chn

### kd_mpi_nonai_2d_attach_vb_pool

Description

Bind the VB (Video Buffer) pool to the specified 2D channel.

Syntax

```c
k_s32 kd_mpi_nonai_2d_attach_vb_pool(k_u32 chn_num, k_u32 pool_id);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |
| pool_id | VB pool ID. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- It can be set on the fly
- If the channel number is illegal, K_ERR_NONAI_2D_INVALID_CHNID is returned.
- If the channel is not created, K_ERR_NONAI_2D_UNEXIST is returned.
- If the VB pool ID is invalid, K_ERR_NONAI_2D_ILLEGAL_PARAM is returned.
- A channel can only be bound to one VB pool at the same time, and repeated binding will overwrite the original binding relationship.

Example

None.

Related Topics

kd_mpi_nonai_2d_detach_vb_pool

### kd_mpi_nonai_2d_detach_vb_pool

Description

Unbind the specified 2D channel from the VB pool.

Syntax

```c
k_s32 kd_mpi_nonai_2d_detach_vb_pool(k_u32 chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- It can be set on the fly
- If the channel number is illegal, K_ERR_NONAI_2D_INVALID_CHNID is returned.
- If the channel is not created, K_ERR_NONAI_2D_UNEXIST is returned.
- If the channel is not bound to any VB pool, success is still returned (no error).

Example

None.

Related Topics

kd_mpi_nonai_2d_attach_vb_pool

### kd_mpi_nonai_2d_create_chn

Description

Create channel.

Syntax

```c
k_s32 kd_mpi_nonai_2d_create_chn(k_u32 chn_num, const k_nonai_2d_chn_attr *attr);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |
| attr | Channel attribute pointer. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

None.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_destroy_chn

Description

Destroy the channel.

Syntax

```c
k_s32 kd_mpi_nonai_2d_destroy_chn(k_u32 chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- You must call kd_mpi_nonai_2d_stop_chn to stop receiving images before destruction, otherwise failure will be returned.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_start_chn

Description

Enables receiving input images.

Syntax

```c
k_s32 kd_mpi_nonai_2d_start_chn(k_u32 chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |

Return Value

| Return Value | Description |
|--------|-------------------------------|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If the channel is not created, failure K_ERR_NONAI_2D_UNEXIST is returned.
- If the channel has started to receive images and calls this interface again to specify the number of frames to receive before stopping receiving images, the return operation is not allowed.
- Frame processing begins only after reception is turned on.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_stop_chn

Description

Stop receiving input images.

Syntax

```c
k_s32 kd_mpi_nonai_2d_stop_chn(k_u32 chn_num);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |

Return Value

| Return Value | Description |
|--------|-------------------------------|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If the channel is not created, failure is returned.
- This interface does not determine whether to stop receiving currently, that is, it allows repeated stopping of reception without returning an error.
- This interface is used to stop receiving images, which must be stopped before the channel is destroyed or reset.
- Calling this interface only stops receiving raw data, and the frame buffer will not be cleared.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_get_frame

Description

Get the processed image.

Syntax

```c
k_s32 kd_mpi_nonai_2d_get_frame(k_u32 chn_num, k_video_frame_info *frame, k_s32 milli_sec);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |
| frame | Image structure pointer. | Output |
| milli_sec | Get image timeout. Value range: [-1, +∞] -1: blocking. 0: Non-blocking. Greater than 0: timeout period | Input |

Return Value

| Return Value | Description |
|--------|-------------------------------|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If the channel is not created, failure is returned.
- If the frame is empty, K_ERR_NONAI_2D_NULL_PTR is returned.
- If milli_sec is less than -1, return K_ERR_NONAI_2D_ILLEGAL_PARAM.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_release_frame

Description

Release the image cache.

Syntax

```c
k_s32 kd_mpi_nonai_2d_release_frame(k_u32 chn_num, k_video_frame_info *frame);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |
| frame | Image structure pointer. | Output |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- If the channel is not created, error code K_ERR_NONAI_2D_UNEXIST is returned.
- If the frame is empty, error code K_ERR_NONAI_2D_NULL_PTR is returned.

Example

None.

Related Topics

None.

### kd_mpi_nonai_2d_send_frame

Description

Support users to send original images for 2D operations.

Syntax

```c
k_s32 kd_mpi_nonai_2d_send_frame(k_u32 chn_num, k_video_frame_info *frame, k_s32 milli_sec);
```

Parameters

| Parameter Name | Description | Input/Output |
|---|---|---|
| chn_num | Channel number. Value range: [0, K_NONAI_2D_MAX_CHN_NUMS]. | Input |
| frame | For the original image information structure pointer, refer to "K230 System Control API Reference". | Input |
| milli_sec | Timeout for sending images. Value range: [-1,+∞] -1: blocking. 0: Non-blocking. > 0: timeout period. | Input |

Return Value

| Return Value | Description |
|---|---|
| 0 | success. |
| non-0 | Failure, see [error code](#error-code). |

Chip differences

None.

Requirements

- Header File: mpi_nonai_2d_api.h，k_type.h，k_module.h，k_sys_comm.h，k_nonai_2d_comm.h
- Library File: libvenc.a

Notes

- This interface enables users to send images to channels.
- If milli_sec is less than -1, return K_ERR_NONAI_2D_ILLEGAL_PARAM.
- To call this interface to send images, the user needs to ensure that the channel has been created and enabled to receive input images.

Example

None.

Related Topics

None.

## data type

The relevant data types of this function module are defined as follows:

### K_NONAI_2D_MAX_CHN_NUMS

Description

Define the maximum number of channels.

definition

```c
#define K_NONAI_2D_MAX_CHN_NUMS  24
```

Notes

None.

Related Data Types and Interfaces

None.

### k_nonai_2d_calc_mode

Description

Define the 2D operation mode.

definition

```text
typedef enum
{
​     K_NONAI_2D_CALC_MODE_CSC = 0,    /* Color space conversion */
​     K_NONAI_2D_CALC_MODE_OSD,      /* On Screen Display */
​     K_NONAI_2D_CALC_MODE_BORDER,     /* Draw border */
​     K_NONAI_2D_CALC_MODE_OSD_BORDER,   /* OSD first, then draw border */
​     K_NONAI_2D_CALC_MODE_BUTT
} k_nonai_2d_calc_mode;
```

member

| member name | Description |
| -------- | --------------------- |
| mode | 2D calculation mode |

Notes

Currently, only CSC mode is supported, and other modes have not yet been implemented.

Related Data Types and Interfaces

None.

### k_nonai_2d_chn_attr

Description

Define channel properties.

definition

```text
typedef struct
{
​      k_pixel_format dst_fmt;     /* Format of output image */
​      k_nonai_2d_calc_mode mode;
} k_nonai_2d_chn_attr;
```

member

| member name | Description |
| -------- | --------------------- |
| dst_fmt | For the format of the output image, see Chapter 1.2 |
| mode | 2D calculation mode, see Chapter 3.2 |

Notes

Related Data Types and Interfaces

None.

### k_nonai_2d_color_gamut

Description

Define the color type of CSC. The default is BT601.

definition

```text
typedef enum
{
​     NONAI_2D_COLOR_GAMUT_BT601 = 0,
​     NONAI_2D_COLOR_GAMUT_BT709,
​     NONAI_2D_COLOR_GAMUT_BT2020,
​     NONAI_2D_COLOR_GAMUT_BUTT
} k_nonai_2d_color_gamut;
```

Notes

None.

Related Data Types and Interfaces

None.

## error code

Table 41 API error codes
| error code | Macro definition | Description |
| ---------- | ---------------------------- | -------------------------------------------- |
| 0xa0188001 | K_ERR_NONAI_2D_INVALID_DEVID | Device ID is outside the legal range |
| 0xa0188002 | K_ERR_NONAI_2D_INVALID_CHNID | Channel ID is outside the legal range |
| 0xa0188003 | K_ERR_NONAI_2D_ILLEGAL_PARAM | Parameter exceeds legal range |
| 0xa0188004 | K_ERR_NONAI_2D_EXIST | Trying to apply for or create an existing device, channel or resource |
| 0xa0188005 | K_ERR_NONAI_2D_UNEXIST | Attempting to use or destroy a non-existent device, channel or resource |
| 0xa0188006 | K_ERR_NONAI_2D_NULL_PTR | There is a null pointer in the function parameter |
| 0xa0188007 | K_ERR_NONAI_2D_NOT_CONFIG | Not configured before use |
| 0xa0188008 | K_ERR_NONAI_2D_NOT_SUPPORT | Unsupported parameters or functions |
| 0xa0188009 | K_ERR_NONAI_2D_NOT_PERM | This operation is not allowed, such as trying to modify static configuration parameters |
| 0xa018800c | K_ERR_NONAI_2D_NOMEM | Failed to allocate memory, such as insufficient system memory |
| 0xa018800d | K_ERR_NONAI_2D_NOBUF | Failed to allocate cache, such as the requested data buffer is too large |
| 0xa018800e | K_ERR_NONAI_2D_BUF_EMPTY | No data in buffer |
| 0xa018800f | K_ERR_NONAI_2D_BUF_FULL | The buffer is full of data |
| 0xa0188010 | K_ERR_NONAI_2D_NOTREADY | The system is not initialized or the corresponding module is not loaded. |
| 0xa0188011 | K_ERR_NONAI_2D_BADADDR | The address is outside the legal range |
| 0xa0188012 | K_ERR_NONAI_2D_BUSY | NONAI_2D system busy |