Warp Initializer IP Descriptor Structure - 1.1 English

Video Warp Processor LogiCORE IP Product Guide (PG396)

Document ID
PG396
Release Date
2022-05-11
Version
1.1 English

The Warp Initizalier IP descriptor should be placed in external memory in the below format. The address of this descriptor is provided to the IP through the Descriptor Address Register and the IP reads the descriptor from this address. The descriptor is a tightly packed structure of size 144 bytes in memory.

typedef struct {
U16	width;
U16	height;
S16    bytes_per_pixel;
U64	filter_table_addr_0; 
U64	filter_table_addr_1;
int    width_Q4;
int    height_Q4;
S16	k_pre;
S16	k_post;
U16    k0_pre;
U16    k1_pre;
U16    k0_post;
U16    k1_post;
U32	Q_fact_pre;
U32	Q_fact_post;
S8     k0_pre_Q_bits;
S8     k0_post_Q_bits;
S8     k1_pre_Q_bits;
S8     k1_post_Q_bits;
S16	h[6];
S32    h_trans[3];
U8     h_Qbits[6];
U32	normfactor;
U16	cenX;
U16	cenY;
int    num_ctrl_pts;
U64    src_ctrl_x_pts;
U64    src_ctrl_y_pts;
U64    src_tangents_x;
U64    src_tangents_y;
U64    interm_x;
U64    interm_y;
U8     warp_type;
U8     dummy[3];
U32    valid_segs;
U32    lblk_count;
U32    line_num_seg;
} xinitvector_hw;
S8 : Signed 8 bit
S16: Signed 16 bit
U8 : Unsigned 8 bit
U16: Unsigned 16 bit
U32: Unsigned 32 bit
U64: Unsigned 64 bit

The fields in the descriptor are explained in the following table:

Table 1. Warp Initializer Descriptor Fields
Field Explanation
Height Height of the input source image. Supported values are between 240 and the value provided in the Maximum Number of Rows field in the Vivado Integrated Design Environment (IDE).
Width Width of the input source image. Supported values are between 320 and the value provided in the Maximum Number of Columns field in the Vivado IDE.
k_pre Lens distortion value applied on the image before applying any other distortions. The user provided value is converted into a fixed format by the driver. Supported range without any other distortions is -5.0 to 5.0. The range will vary if other distortions are applied on images.
k_post Lens distortion value applied on the image after applying all other distortions. The user provided value is converted into a fixed format by the driver. Supported range without any other distortions is -5.0 to 5.0. The range will vary if other distortions are applied on images.
k0_pre Fixed point parameter estimated by the driver in onetime_calcs_warp() function. Its value depends on the k_pre.
K1_pre Fixed point parameter estimated by the driver in onetime_calcs_warp() function. Its value depends on the k_pre.
k0_post Fixed point parameter estimated by the driver in onetime_calcs_warp() function. Its value depends on the k_post.
K1_post Fixed point parameter estimated by the driver in onetime_calcs_warp() function. Its value depends on the k_post.
Q_fact_pre Fixed point format used for k_pre. This parameter is estimated by the driver in onetime_calcs_warp() function.
Q_fact_post Fixed point format used for k_post. This parameter is estimated by the driver in onetime_calcs_warp() function.
k0_pre_Q_bits Fixed point format used for k0_pre. This parameter is estimated by the driver in onetime_calcs_warp() function.
k0_post_Q_bits Fixed point format used for k0_post. This parameter is estimated by the driver in onetime_calcs_warp() function.
k1_pre_Q_bits Fixed point format used for k1_pre. This parameter is estimated by the driver in onetime_calcs_warp() function.
k1_post_Q_bits Fixed point format used for k1_post. This parameter is estimated by the driver in onetime_calcs_warp() function.
h[6] Homography matrix estimated based on the inputs of the rotation, scale, transition and keystone distortion values. h[6] represents the first two columns of homography 3x3 matrix in fixed point format.
h_trans [3] Represents the last column of homography 3x3 matrix in fixed point format.
h_Qbits[6] Fixed point format used for each element of the h[6]. These parameters are estimated by the driver in onetime_calcs_warp() function.
filter_table_addr_0 Memory address of warp filter table0.
filter_table_addr_1 Memory address of warp filter table1.
normfactor Fixed point value estimated by the driver in onetime_calcs_warp() function based on image width and height.
cenX Center column position of the image estimated based on width.
cenY Center row position of the image estimated based on height.
width_Q4 Width of the image in Q4 fixed point format.
Height_Q4 Height of the image in Q4 fixed point format.
bytes_per_pixel Number of bytes per pixel.
warp_type Type of warp. 0 for regular and 1 for arbitrary distortion.
num_ctrl_pts Number of control point used in arbitrary distortion. This parameter is required for arbitrary warp.
src_ctrl_x_pts Memory address of the column locations of source control points. These parameters are input from user for arbitrary warp.
src_ctrl_y_pts Memory address of the row locations of source control points. These parameters are input from user for arbitrary warp.
src_tangents_x Memory address of the column direction tangents estimated by the driver in onetime_calcs_warp() function based on source and destination control points.
src_tangents_y Memory address of the row direction tangents estimated by the driver in onetime_calcs_warp() function based on source and destination control points.
interm_x Memory address for storing intermediate information during warp filter parameters estimation block by block.
interm_y Memory address for storing intermediate information during warp filter parameters estimation block by block.
Valid_seg

Number of valid blocks that the Warp Filter needs to reconstruct. This value must be read from the valid_segs field of the Warp Initializer descriptor.

Lblock_count

For faster processing, the Warp Filter runs two cores parallely. The total number of valid blocks are divided between the two cores. The number of blocks that need to be processed by the first core comes from lblock_count. This value must be read from the lblock_count field of the Warp Initializer descriptor.

Line_num

The line number from which the second core in the Warp Filter starts reading the source image. This value must be read from the line_num field of the Warp Initializer descriptor.

This descriptor is filled in the driver based on the user input configuration. The user should provide the following input configuration structure to the driver.

typedef struct {
	            int frame_width;
	            int frame_height;
	            int warp_type;
	            float pre_fisheye;
	            float post_fisheye;
	            int left_top_x;
	            int left_top_y;
	            int right_top_x;
	            int right_top_y;
	            int left_bottom_x;
	            int left_bottom_y;
	            int right_bottom_x;
	            int right_bottom_y;
	            float scale_x;
	            float scale_y;
	            float rotation;
	            float trans_x;
	            float trans_y;
	            float zoom;
	            int num_ctrl_pts;
	            XVWarpInit_ArbParam_MeshInfo *ctrl_pts;
} WARP_CFG;
The supported range for each parameter is given in the following table.
Table 2. Warp Configuration Parameters
Warp Configuration Parameter Range
frame_width

320 to 3840

frame_height

240 to 2160

warp_type

0(fixed), 1(arbitrary)

pre_fisheye

-5.0 to 5.0

post_fisheye

-5.0 to 5.0

left_top_x

0 to width

left_top_y

0 to height

right_top_x

0 to width

right_top_y

0 to height

left_bottom_x

0 to width

left_bottom_y

0 to height

right_bottom_x

0 to width

right_bottom_y

0 to height

scale_x

0.5 to 2.0

scale_y

0.5 to 2.0

rotation

-90 to 90

trans_x

-width to width

trans_y

-height to height

zoom

0.5 to 2

num_ctrl_pts

4, 8, 16, 32

The following figures show the effect of these values on a 3840x2160 image.

Figure 1. post_fisheye = -2.0, scale_x = 0.75, scale_y = 0.75

Figure 2. left_top_x = 400, left_top_y = 0, right_top_x = 1600, right_top_y = 0, left_bottom_x = 0, left_bottom_y = 2160, right_bottom_x = 3840, right_bottom_y = 2160