Blit functions

This section provides an overview on blit functions.

`vg_lite_blit` function

Description:

This is the blit function. The blit operation is performed using a source and a destination buffer. The source and destination buffer structures are defined using the vg_lite_buffer_t structure. Blit copies a source image to the destination window with a specified matrix that can include translation, rotation, scaling, and perspective correction. Note that vg_lite_buffer_t does not support coverage sample anti-aliasing so the destination buffer edge may not be smooth, especially with a rotation matrix. VGLite path rendering can be used to achieve high-quality coverage sample anti-aliasing (16X, 8X, 4X) rendering effect.

Note:

The blit function can be used with or without the blend function (vg_lite_blend_t)
The blit function can be used with or without specifying a foreground color value (vg_lite_color_t)
The blit function can be used for color conversion with an identity matrix and appropriate formats specified for the source and the destination buffers. In this case, do not specify blend mode and color value.

Syntax:

vg_lite_error_t vg_lite_blit (
       vg_lite_buffer_t        *target,
       vg_lite_buffer_t        *source,
       vg_lite_matrix_t        *matrix,
       vg_lite_blend_t         blend,
       vg_lite_color_t         color,
       vg_lite_filter_t        filter
);

Parameters:

Name	Description
`*target`	Points to the vg_lite_buffer_t structure, which defines the destination buffer. See Image Source Alignment Requirement for valid destination color formats for the blit functions.
`*source`	Points to the vg_lite_buffer_t structure for the source buffer. All color formats available in the vg_lite_buffer_format_t enum are valid source formats for the blit function.
`*matrix`	Points to a vg_lite_matrix_t structure that defines the transformation matrix of source pixels into the target. If the matrix is NULL, then an identity matrix is assumed, which means that the source is copied directly at 0,0 location on the target.
`blend`	Specifies one of the enum vg_lite_blend_t values for hardware-supported blend modes to be applied to each image pixel. If no blending is required, set this value to `VG_LITE_BLEND_NONE` (0). Note: If the `matrix` parameter is specified with rotation or perspective, and the `blend` parameter is specified as `VG_LITE_BLEND_NONE`, `VG_LITE_BLEND_SRC_IN`, or `VG_LITE_BLEND_DST_IN`; then, the VGLite driver overwrites the application setting for the blit operation as follows: - If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is supported, then Transparency mode is always set to `TRANSPARENT`- If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is not supported, then Blend mode is always set to `VG_LITE_BLEND_SRC_OVER`. It happens due to some limitations in the VGLite hardware.
`color`	If non-zero, this color value is used as a mix color. The mixed color gets multiplied with each source pixel before blending happens. If you don’t need a mix color, set the color parameter to 0.Note: this parameter has no effect if the source `vg_lite_buffer_t` structure member `image_mode` is set to `VG_LITE_ZERO` or `VG_LITE_NORMAL_IMAGE_MODE`.
`filter`	Specifies the filter type. All formats available in the vg_lite_filter_t enum are valid formats for this function. A value of zero (0) indicates `VG_LITE_FILTER_POINT`.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_blit2` function

Description:

This is the blit function for use with two sources. The blit2 operation is performed using two source buffers and one destination buffer. The source and destination buffer structures are defined using the vg_lite_buffer_t structure. Source0 and Source1 are first blended according to the blend mode with a specific transformation matrix for each image. Source1 is used as the source while Source0 is used as the dest and is directly output to the render target buffer.

The specified matrices can include translation, rotation, scaling, and perspective correction. Note that vg_lite_buffer_t does not support coverage sample anti-aliasing so the destination buffer edge may not be smooth, especially with a rotation matrix. VGLite path rendering can be used to achieve high-quality coverage sample anti-aliasing (16X, 8X, 4X) rendering effect.

Application can use VGLite API vg_lite_query_feature(gcFEATURE_BIT_VG_DOUBLE_IMAGE) to determine HW support for double image.

Note:

The vg_lite_blit function can be used for color conversion for Source0 or Source1 before merging sources with vg_lite_blit2.

Syntax:

vg_lite_error_t vg_lite_blit2 (
    vg_lite_buffer_t              *target,
    vg_lite_buffer_t              *source0,
    vg_lite_buffer_t              *source1,
    vg_lite_matrix_t              *matrix0,
    vg_lite_matrix_t              *matrix1,
    vg_lite_blend_t               blend,
    vg_lite_filter_t              filter
);

Parameters:

Name	Description
`*target`	Points to the vg_lite_buffer_t structure, which defines the destination buffer. See Alignment notes for valid destination color formats for the blit functions
`source0, source1`	Points to the vg_lite_buffer_t structure for the source0 and source1 buffers. All color formats available in the vg_lite_buffer_format_t` enum are valid source formats for the blit functions.
`matrix0, matrix1`	Points to a vg_lite_matrix_t structure that defines the 3x3 transformation matrix0 for the source0 pixels and matrix1 for the source1 pixels. If matrix0 and matrix1 are both NULL, the identity matrix is assumed, meaning the blending result of Source0 and Source1 is copied directly on the target at location(0,0).
`blend`	Specifies one of the enum vg_lite_blend_t values for hardware-supported blend modes to be applied to each image pixel. If no blending is required, set this value to `VG_LITE_BLEND_NONE (0).` Note: If the “matrix” parameter is specified with rotation or perspective, and the “blend” parameter is specified as `VG_LITE_BLEND_NONE, VG_LITE_BLEND_SRC_IN,` or `VG_LITE_BLEND_DST_IN`, the VGLite driver overwrites the application’s setting for the BLIT operation as follows: - If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is supported, the transparency mode will always be set to TRANSPARENT. - If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is not supported, the blend mode will always be set to `VG_LITE_BLEND_SRC_OVER`. This is due to some limitations in the VGLite hardware.
`filter`	Specifies the filter type. All formats available in the vg_lite_filter_t enum are valid formats for this function. A value of zero (0) indicates `VG_LITE_FILTER_POINT`.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_blit_rect` function

Description:

This is the blit rectangle function. The blit operation is performed using a source and a destination buffer. The source and destination buffer structures are defined using the vg_lite_buffer_t structure. Blit copies a source image to the destination window with a specified matrix that can include translation, rotation, scaling, and perspective correction. Note that vg_lite_buffer_t does not support coverage sample anti-aliasing so the destination buffer edge may not be smooth, especially with a rotation matrix. VGLite path rendering can be used to achieve high-quality coverage sample anti-aliasing (16X, 8X, 4X) rendering effect.

Note:

The blit_rect function can be used with or without the blend function (vg_lite_blend_t).
The blit_rect function can be used with or without specifying any color value (vg_lite_color_t).
The blit_rect function can be used for color conversion with an identity matrix and appropriate formats specified for the source and destination buffers. In this case, do not specify blend mode and color value.
The vg_lite_blit_rect rectangle start origin point is always (0,0) for hardware versions prior to GCNanoLiteV 1311p that do not support a non-zero rectangle origin.

Syntax:

vg_lite_error_t vg_lite_blit_rect (
    vg_lite_buffer_t              *target,
    vg_lite_buffer_t              *source,
    vg_lite_rectangle_t           *rect,
    vg_lite_matrix_t              *matrix,
    vg_lite_blend_t               blend,
    vg_lite_color_t               color,
    vg_lite_filter_t              filter
);

Parameters:

Name	Description
`*target`	Points to the vg_lite_buffer_t structure that defines the destination buffer.
`*source`	Points to the vg_lite_buffer_t structure for the source buffer. All color formats available in the vg_lite_buffer_format_t enum are valid source formats for the blit_rect function.
`*rect`	Specifies the rectangle area of the source image to blit. rect[0]/[1]/[2]/[3] are x, y, width, and height of the source rectangle respectively. Note: Non-zero source origins are supported.
`*matrix`	Points to a vg_lite_matrix_t structure that defines the 3x3 transformation matrix of source pixels into the target. If the matrix is NULL, then an identity matrix is assumed, which means that the source is copied directly at 0,0 location on the target.
`blend`	Specifies one of the enum vg_lite_blend_t values for hardware-supported blend modes to be applied to each image pixel. If no blending is required, set this value to `VG_LITE_BLEND_NONE` (0). Note: If the `matrix` parameter is specified with rotation or perspective, and the `blend` parameter is specified as `VG_LITE_BLEND_NONE`, `VG_LITE_BLEND_SRC_IN`, or `VG_LITE_BLEND_DST_IN`; then, the VGLite driver overwrites the application setting for the blit operation as follows: - If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is supported, then Transparency mode is always set to `TRANSPARENT` - If `gcFEATURE_BIT_VG_BORDER_CULLING` (vg_lite_feature_t) is not supported, then Blend mode is always set to `VG_LITE_BLEND_SRC_OVER`. It happens due to some limitations in the VGLite hardware.
`color`	If non-zero, this color value is used as a mix color. The mixed color gets multiplied with each source pixel before blending happens. If you do not need a mix color, then set the color parameter to 0. Note: This parameter has no effect if the source `vg_lite_buffer_t` structure member `image_mode` is set to `VG_LITE_ZERO` or `VG_LITE_NORMAL_IMAGE_MODE`.
`filter`	Specifies the filter type. All formats available in the vg_lite_filter_t enum are valid formats for this function. A value of zero (0) indicates `VG_LITE_FILTER_POINT`.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_copy_image` function

Description:

This API copied a pixel rectangle with dimension (width, height) from source buffer to destination buffer. The source image pixel (sx *+ i,*sy + j) is copied to the destination image pixel (dx *+ i,*dy + j), for *0 ≤ i <*width and *0 ≤ j <*height. Pixels whose source or destination lie outside the bounds of the respective image are ignored. Pixel format conversion is applied as needed.

No pre-multiply, transformation, blending, filtering operations are applied to the pixel copy.

Syntax:

vg_lite_error_t vg_lite_copy_image (
    vg_lite_buffer_t              *target,
    vg_lite_buffer_t              *source,
    vg_lite_int32_t               sx,
    vg_lite_int32_t               sy,
    vg_lite_int32_t               dx,
    vg_lite_int32_t               dy,
    vg_lite_int32_t               width,
    vg_lite_int32_t               height
);

Parameters:

Name	Description
`*target`	Points to the vg_lite_buffer_t structure that defines the destination buffer.
`*source`	Points to the vg_lite_buffer_t structure for the source buffer. All color formats available in the vg_lite_buffer_format_t enum are valid source formats for the blit function.
`sx, sy`	Pixel coordinates of the lower-left corner of a pixel rectangle within the source buffer.
`dx, dy`	Pixel coordinates of the lower-left corner of a pixel rectangle within the target buffer.
`width`	Width of the copied pixel rectangle.
`height`	Height of the copied pixel rectangle.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_get_transform_matrix` function

Description:

This function generates a 3x3 homogenous transform matrix from 4 float point source coordinates and 4 float point target coordinates. (from March 2021)

Syntax:

vg_lite_error_t vg_lite_get_transform_matrix (
    vg_lite_float_point4_t       src,
    vg_lite_float_point4_t       dst,
    vg_lite_matrix_t             *mat
);

Parameters:

Name	Description
`src`	Pointer to the four 2D points that form a source polygon
`dst`	Pointer to the four 2D points that form a destination polygon
`mat`	Output parameter, pointer to a 3x3 homogenous matrix that transforms the source polygon to a destination polygon.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_clear` function

Description:

This function performs the clear operation, clearing/filling the specified buffer (entire buffer or partial rectangle in a buffer) with an explicit color.

Syntax:

vg_lite_error_t vg_lite_clear (
    vg_lite_buffer_t              *target,
    vg_lite_rectangle_t           *rect,
    vg_lite_color_t               color
);

Parameters:

Name	Description
`*target`	Pointer to the vg_lite_buffer_t structure for the destination buffer. All color formats available in the vg_lite_buffer_format_t enum are valid destination formats for the clear function.
`*rect`	Pointer to the vg_lite_rectangle_tstructure that specifies the area to be filled. If the rectangle is NULL, the entire target buffer is filled with the specified color.
`color`	Clear color, as specified in the vg_lite_color_t enum that is the color value to use for filling the buffer. If the buffer is in L8 format, the RGBA color is converted into a luminance value.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enum for other return codes.

Parent topic:Blit functions

`vg_lite_set_color_key` function

Description:

This function sets a color key. Color key can be used for blit or for draw pattern operations. (from April 2022)

A “color key” have two sections, where each section contains R,G,B channels which are noted as high_rgb and low_rgb respectively.

When the vg_lite_color_key_t structure value enable is true, the color key specified is effective and the alpha value is used to replace the alpha channel of the destination pixel when its RGB channels are within range [low_rgb, high_rgb]. After the color key is used in the current frame, if the color key is not needed for the next frame, it should be disabled before the next frame.

Hardware support for color key is not available for GCNanoLiteV. Application can use VGLite API vg_lite_query_feature(gcFEATURE_BIT_VG_COLOR_KEY) to determine HW support for color key.

Syntax:

vg_lite_error_t vg_lite_set_color_key (
    vg_lite_color_key4_t          colorkey
);

Parameters:

Parameter	Description
`colorkey`	Color keying parameters as defined by vg_lite_color_key4_t.

Here are 4 groups of color key states:

color_key_0, high_rgb_0, low_rgb_0, alpha_0, enable_0
color_key_1, high_rgb_1, low_rgb_1, alpha_1, enable_1
color_key_2, high_rgb_2, low_rgb_2, alpha_2, enable_2
color_key_3, high_rgb_3, low_rgb_3, alpha_3, enable_3

The priority order of these states is:

color_key_0 > color_key_1 > color_key_2 > color_key_3.

Returns:

VG_LITE_SUCCESS if successful. VG_LITE_NOT_SUPPORT if color key is not supported in hardware.

Parent topic:Blit functions

`vg_lite_gaussian_filter` function

Description:

This function sets 3x3 gaussian blur weighted values to filter an image pixel. (from March 2023)

The parameters w0, w1, w2 define a 3x3 gaussian blur weight matrix as:

The sum of the 9 kernel weights must be 1.0 to avoid convolution overflow ( w0 + 4*w1 + 4*w2 = 1.0 ).

The 3x3 weight matrix applies to a 3x3 pixel block:

With the following dot product equation:

Applications can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_GAUSSIAN_BLUR) to determine HW support for gaussian blur.

Syntax:

vg_lite_error_t vg_lite_gaussian_filter (
    vg_lite_float_t               w0
    vg_lite_float_t               w1
    vg_lite_float_t               w2
);

Parameters:

Parameter	Description
`w0, w1, w2`	w0, w1, w2 define a 3x3 gaussian blur weighted matrix as:

Returns:

VG_LITE_SUCCESS if successful. Otherwise, VG_LITE_NOT_SUPPORT if gaussian blur is not supported in hardware.

Parent topic:Blit functions

Parent topic:Blits for compositing and blending

Blit functions

vg_lite_blit function

vg_lite_blit2 function

vg_lite_blit_rect function

vg_lite_copy_image function

vg_lite_get_transform_matrix function

vg_lite_clear function

vg_lite_set_color_key function

vg_lite_gaussian_filter function

`vg_lite_blit` function

`vg_lite_blit2` function

`vg_lite_blit_rect` function

`vg_lite_copy_image` function

`vg_lite_get_transform_matrix` function

`vg_lite_clear` function

`vg_lite_set_color_key` function

`vg_lite_gaussian_filter` function