K230 nonai 2D API reference#

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:

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);

kd_mpi_nonai_2d_request_chn#

Description

Apply for free 2D channels.

Syntax

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

#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

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

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

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

K230 nonai 2D API reference

Contents

K230 nonai 2D API reference#

Overview#

Overview#

Functional Description#

API Reference#

kd_mpi_nonai_2d_request_chn#

kd_mpi_nonai_2d_release_chn#

kd_mpi_nonai_2d_attach_vb_pool#

kd_mpi_nonai_2d_detach_vb_pool#

kd_mpi_nonai_2d_create_chn#

kd_mpi_nonai_2d_destroy_chn#

kd_mpi_nonai_2d_start_chn#

kd_mpi_nonai_2d_stop_chn#

kd_mpi_nonai_2d_get_frame#

kd_mpi_nonai_2d_release_frame#

kd_mpi_nonai_2d_send_frame#

data type#

K_NONAI_2D_MAX_CHN_NUMS#

k_nonai_2d_calc_mode#

k_nonai_2d_chn_attr#

k_nonai_2d_color_gamut#

error code#