CMDLIST Functions and Parameters

You are not advised to use the CMDLIST function, which will be removed in later versions. The VPC and CMDLIST functions in the earlier version have been combined into the VPC function. For details, see VPC Parameters.

The CMDLIST is an extended function of the VPC. It combines functions that need to start the VPC for multiple times into one startup-complete-interrupt-return process. CMDLIST applies to scenarios that do not require low latency and process a large number of low-resolution images.

Input Parameter

The CMDLIST input is a structure. For details about the parameters, see Figure 1 and Table 1.

Figure 1 CMDLIST structures

For details about the description and value ranges, see Table 1.

**Table 1** Structure description
Member Variable	Description	Value Range
unsigned int format	Input image type	typedef enum { yuv420_semi_plannar =0,//0 yuv422_semi_plannar,//1 yuv444_semi_plannar,//2 yuv422_packed,//3 yuv444_packed,//4 rgb888_packed,//5 xrgb8888_packed,//6 yuv400_semi_plannar,//7 invalid_image_type,//20 }Imge_Type;
unsigned int rank	Output image format (NV12 or NV21)	For details, see Table 1.
unsigned int bitwidth	Bit depth, which is usually 8 bits. The 10-bit depth is used only when the image format is YUV/YVU420 Semi-Planar and HFBC compression is used.	8: 8 bits 10: 10 bits
int is_hfbc_image	Input image channel. Generally, this parameter is set to 1 and the CVDR channel is used. The RDMA channel is used only when the HFBC data output by the VDEC is used as the input.	0: RDMA 1: CVDR
unsigned int in_width	Width of the input image, which must be 128-pixel aligned	128~4096
unsigned int in_height	Height of the input image, which must be 16-pixel aligned	16~4096
unsigned int width_step	Image stride	YUV400SP, YUV420SP, YUV422SP, and YUV444SP: Align the width to a 128-pixel boundary. YUV422 Packed: Align (width x 2) to a 128-pixel boundary. YUV444 Packed and RGB888: Align (width x 3) to a 128-pixel boundary. XRGB8888: Align (width x 4) to a 128-pixel boundary.
unsigned int need_debug	Reserved for internal debugging. Generally, this parameter is set to 0.	0: normal mode 1: debug mode
CMDLIST_IN_BUFFER in_buffer	Pointer to the address of the input image buffer, which is a union. For common uncompressed images, use bare_buffer, which must be 128-byte aligned. For HFBC-compressed images, use hfbc_buffer.	union CMDLIST_IN_BUFFER { char* bare_buffer; RDMACHANNEL* hfbc_buffer; }; RDMACHANNEL in this syntax is the same as that in vpc_in_msg. For details, see RDMACHANNEL Structure.
ROI_CONFIG roi_config	Structure of output parameter configuration	For details, see ROI_CONFIG structure.
IMAGE_CONFIG* next	Pointer to the next IMAGE_CONFIG structure. Set this parameter when multiple images are used. Otherwise, set this parameter to NULL.	--

For details about the structure syntax, see include/inc/dvpp/dvpp_config.h in the DDK page.

Figure 2 shows the information about the input parameters

Figure 2 Example of input parameters

This figure shows the normalization of the cropping and resizing operations.

When only cropping is performed, the resizing coefficient is 1.
When only resizing is performed, the cropping size is the original image.

The width of the input image is 128-pixel aligned, the height of the input image is 16-pixel aligned, and the maximum resolution of the input image and that of the output image are both 4 KB.

The following interfaces are required for buffer address alignment:
The buffer addresses of the input and output images must be both 128-byte aligned. The addresses must be in the same 4 GB space. HIAI_DVPP_DMalloc is required for applying for huge page memory.

The memory application API is HIAI_DVPP_DMalloc(size)

The resizing ratio calculated based on the output image size and the input image size must be within the range of [0.03125, 4].
The output buffer size must be calculated based on the output image resolution after the width is 128-pixel aligned and the height is 16-pixel aligned.
The CMDLIST API supports a maximum of 32 images and each image supports a maximum of 256 ROIs.

Output Parameter

None. The output image is in out_buffer of sum_out. You can obtain the image by reading the buffer.

Table 1 shows the rank configuration table of the input and output image formats.

Calling Example

/************************************************************************************************/
/***** Example description: **********************************************************************************
This example uses a 1920 x 1088 YUV420 NV12 image as the input.
File name of the input image: "file1_1920x1088_nv12.yuv"
Operations on the input image: Crop five sub-images and resize them to 224 x 224.
 ************************************************************************************************
 ************************************************************************************************/
int main()
{
    int ret = 0;
   // Reads the input file.
    char image_file[128] = "file1_1920x1088_nv12.yuv";
    ifstream in_stream(image_file);
    if (!in_stream.is_open()) {
        printf("can not open %s.\n", image_file);
        return -1;
    }
    in_stream.seekg(0, ios::end);
    int file_len = in_stream.tellg();
    char* in_buffer = (char *)HIAI_DVPP_DMalloc(file_len);
    in_stream.seekg(0, ios::beg);
    in_stream.read(in_buffer, file_len);
    in_stream.close();
    // Starts to add the configuration of the first image.
    IMAGE_CONFIG* image_config = (IMAGE_CONFIG*)malloc(sizeof(IMAGE_CONFIG));
    image_config->in_buffer.bare_buffer = in_buffer; // Currently, all used images are uncompressed.
    image_config->format = 0;
    image_config->rank = 1;// When the input is in NV12 format, the output is also in NV12 format. Set rank to 1.
    image_config->bitwidth = 8;// Currently, only 8-bit units are used.
    image_config->in_width = 1920;
    image_config->in_height = 1088;
    image_config->width_step = 1920;// The value is the same as the width.
    // Start to add the configuration of the first cropped image. In this example, the cropped area is enclosed by (0,0) and (511,511).
    ROI_CONFIG* roi_config = &image_config->roi_config;
  // Starts to configure the cropping parameters.
    roi_config->crop_config.enable = 1; // Note: If only resizing is required, set this parameter to 0.
    roi_config->crop_config.hmin = 0; 
    roi_config->crop_config.hmax = 511; 
    roi_config->crop_config.vmin = 0; 
    roi_config->crop_config.vmax = 511; 
   // Starts to configure output channel parameters.
    roi_config->sum_out.enable = 1; // Enables the output of the first channel.
    roi_config->sum_out.out_width = 224;
    roi_config->sum_out.out_height = 224;
    int out_buffer_size = AlignUp(224,128)*AlignUp(224,16)*3/2;
    roi_config->sum_out.out_buffer = (char*)HIAI_DVPP_DMalloc(out_buffer_size);
    ROI_CONFIG* last_roi = roi_config;
   // Starts to add the configurations of the second to fifth cropped images.
    for (int i = 0 ; i < 4; i++) {
        ROI_CONFIG* roi_config = (ROI_CONFIG*)malloc(sizeof(ROI_CONFIG));
        // Starts to configure the cropping parameters.
        roi_config->crop_config.enable = 1; 
        roi_config->crop_config.hmin = 100*i; 
        roi_config->crop_config.hmax = 299 + 100*i; 
        roi_config->crop_config.vmin = 100*i; 
        roi_config->crop_config.vmax = 299 + 100*i; 
        // Starts to configure output channel parameters.
        roi_config->sum_out.enable = 1; 
        roi_config->sum_out.out_width = 224;
        roi_config->sum_out.out_height = 224;
        out_buffer_size = AlignUp(224,128)*AlignUp(224,16)*3/2;
        roi_config->sum_out.out_buffer = (char*)HIAI_DVPP_DMalloc(out_buffer_size);
        roi_config->next = nullptr;
        last_roi->next = roi_config;
        last_roi = roi_config;
    }
    // Starts to call the CMDLIST API of the DVPP.
    IDVPPAPI *pidvppapi = NULL;
    // Calls the createdvppapi API only once, regardless of the subsequent callings.
    ret = CreateDvppApi(pidvppapi);
    if (ret != 0) {
        printf("creat dvpp api faild!\n");
        return -1;
    }
    dvppapi_ctl_msg dvppApiCtlMsg;
    dvppApiCtlMsg.in = (void *)(image_config);
    dvppApiCtlMsg.in_size = sizeof(IMAGE_CONFIG);
    ret = DvppCtl(pidvppapi, DVPP_CTL_CMDLIST_PROC, &dvppApiCtlMsg);
    if (0 != ret) {
        printf("call cmdlist dvppctl process faild!\n");
    } else {
        printf("cmdlist success.\n");
    }
    ret += DestroyDvppApi(pidvppapi);    
    roi_config = image_config->roi_config.next;
    while (roi_config != nullptr) {
        ROI_CONFIG* next_roi = roi_config->next;
        UNMAP(roi_config->sum_out.out_buffer, out_buffer_size);
        free(roi_config);
        roi_config = next_roi;
    }
    UNMAP(image_config->roi_config.sum_out.out_buffer, out_buffer_size);
    free(image_config);
    UNMAP(in_buffer, file_len);
    return ret;    
}

Parent topic: Compatibility with the Functions of Earlier Versions

Previous topic: VPC Functions and Parameters

Next topic: VENC Functions and Parameters