Warp Initializer IP Descriptor Structure - 1.0 English

Video Warp Processor LogiCORE IP Product Guide (PG396)

Document ID
PG396
Release Date
2021-12-07
Version
1.0 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 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 k1_pre_Q_bits;
S8 k1_post_Q_bits;
S16 h[6];
S32 h_trans[3];
U8 h_Qbits[6];
U64 filter_table_addr_0;
U64 filter_table_addr_1;
U32 normfactor;
U16 cenX;
U16 cenY;
Int width_Q4;
int height_Q4;
S16 bytes_per_pixel;
U8 warp_type;
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;
} 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.

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