Blits for compositing and blending

This part of the API performs the hardware accelerated blit operations.

Compositing rules describes how two areas are combined to form a single area. Blending rules describes how combining the colors of the overlapping areas are combined. VGLite supports two blending operations and a subset of the Porter-Duff operations [PD84]. The Porter-Duff operators assume that the pixels have the alpha associated (premultiplied), it means that the pixels are premultiplied prior to the blending operation. GC555, GC355, and some GCNanoUltraV hardware support alpha premultiply for RGB image, but GCNanoLiteV does not.

The source image is copied to the destination window with a specified matrix that can include translation, rotation, scaling, and perspective correction.

The blit function can be used with or without the blend mode.
The blit function can be used with or without specifying any color value.
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.

Blit enumerations

This section gives details on blit enumerations.

`vg_lite_blend_t` enumeration

This enumeration defines the blending modes supported by some VGLite API functions. S and D represent source and destination non-premultiplied RGB color channels. Sa and Da represent the source and destination alpha channels. SP and DP represent source and destination alpha-premultiplied RGB color channels (SP = S*Sa, DP = D*Da).

Note: VG_LITE_BLEND_*_LVGL modes are supported on all VG cores. On VG cores that do not support gcFEATURE_BIT_VG_LVGL_SUPPORT, the LVGL blend modes are supported by a combination of software and hardware operations. OPENVG_BLEND_* modes can only be supported on GC355 and GC555 cores.

Used in blit functions: vg_lite_blit, vg_lite_blit2, vg_lite_blit_rect.

Used in draw functions: vg_lite_draw, vg_lite_draw_grad, vg_lite_draw_radial_grad, vg_lite_draw_pattern.

vg_lite_blend_t String Values	Description
VG_LITE_BLEND_NONE	S, no blending Non-premultiplied
VG_LITE_BLEND_SRC_OVER	*S + D (1 - Sa)** Non-premultiplied
VG_LITE_BLEND_DST_OVER	*S (1 – Da) + D** Non-premultiplied
VG_LITE_BLEND_SRC_IN	*S Da** Non-premultiplied
VG_LITE_BLEND_DST_IN	*D Sa** Non-premultiplied
VG_LITE_BLEND_MULTIPLY	*S (1 - Da) + D * (1 - Sa) + S * D** Non-premultiplied
VG_LITE_BLEND_SCREEN	*S + D - S D** Non-premultiplied
VG_LITE_BLEND_DARKEN	min(SRC_OVER, DST_OVER) Non-premultiplied
VG_LITE_BLEND_LIGHTEN	max(SRC_OVER, DST_OVER) Non-premultiplied
VG_LITE_BLEND_ADDITIVE	S + D Non-premultiplied
VG_LITE_BLEND_SUBTRACT	*D (1 - Sa)** Non-premultiplied
VG_LITE_BLEND_NORMAL_LVGL	*S Sa + D * (1 - Sa)** Non-premultiplied (from March 2023)
VG_LITE_BLEND_ADDITIVE_LVGL	*(S + D) Sa + D * (1 - Sa)** Non-premultiplied (from March 2023)
VG_LITE_BLEND_SUBTRACT_LVGL	*(S - D) Sa + D * (1 - Sa)** Non-premultiplied (from March 2023)
VG_LITE_BLEND_MULTIPLY_LVGL	*(S D) * Sa + D * (1 - Sa)** Non-premultiplied (from March 2023)
OpenVG Porter-Duff Blend String Values	(from Aug 2023)
OPENVG_BLEND_NONE	SP, no blending Premultiplied
OPENVG_BLEND_SRC_OVER	*(SP + DP (1 - Sa)) / (Sa + Da * (1 - Sa))** Premultiplied
OPENVG_BLEND_DST_OVER	*(SP (1 - Da) + DP) / (Sa * (1 - Da) + Da)** Premultiplied
OPENVG_BLEND_SRC_IN	*(SP Da) / (Sa * Da)** Premultiplied
OPENVG_BLEND_DST_IN	*(DP Sa) / (Sa * Da)** Premultiplied
OPENVG_BLEND_MULTIPLY	*(SPDP + SP(1 - Da) + DP(1 - Sa)) / (Sa + Da(1 - Sa))* Premultiplied
OPENVG_BLEND_SCREEN	*(SP + DP - (SPDP)) / (Sa + Da(1 - Sa))* Premultiplied
OPENVG_BLEND_DARKEN	min(SRC_OVER, DST_OVER) Premultiplied
OPENVG_BLEND_LIGHTEN	max(SRC_OVER, DST_OVER) Premultiplied
OPENVG_BLEND_ADDITIVE	(SP + DP) / (Sa + Da) Premultiplied

Parent topic:Blit enumerations

`vg_lite_color_t` parameter

The common parameter vg_lite_color_t is described in Table 1.

Parent topic:Blit enumerations

`vg_lite_color_transform_t` structure

Specifies the pixel color_transform values for scale and bias.

Used in functions: vg_lite_set_color_transform.

vg_lite_color_transform_t members	Type	Description
`a_scale`	`vg_lite_float_t`	Scale value for alpha.
`a_bias`	`vg_lite_float_t`	Bias value for alpha.
`r_scale`	`vg_lite_float_t`	Scale value for red.
`r_bias`	`vg_lite_float_t`	Bias value for red.
`g_scale`	`vg_lite_float_t`	Scale value for green.
`g_bias`	`vg_lite_float_t`	Bias value for green.
`b_scale`	`vg_lite_float_t`	Scale value for blue.
`b_bias`	`vg_lite_float_t`	Bias value for blue.

Parent topic:Blit enumerations

`vg_lite_filter_t` enumeration

Specifies the sample-filtering mode in VGLite blit and draw APIs.

Used in blit functions: vg_lite_blit, vg_lite_blit_rect.

Used in draw functions: vg_lite_draw_radial_gradient, vg_lite_draw_pattern.

vg_lite_filter_t string values	Description
`VG_LITE_FILTER_POINT`	Fetch only the nearest image pixel
`VG_LITE_FILTER_LINEAR`	Use linear interpolation along a horizontal line
`VG_LITE_FILTER_BI_LINEAR`	Use a 2x2 box around the image pixel and perform an interpolation
`VG_LITE_FILTER_GAUSSIAN`	Perform 3x3 gaussian blur with the convolution for image pixel. (from March 2023)

Parent topic:Blit enumerations

`vg_lite_color_transform_t` structure

Specifies the pixel color_transform values for scale and bias.

Used in functions: vg_lite_set_color_transform.

vg_lite_color_transform_t members	Type	Description
`a_scale`	`vg_lite_float_t`	Scale value for alpha.
`a_bias`	`vg_lite_float_t`	Bias value for alpha.
`r_scale`	`vg_lite_float_t`	Scale value for red.
`r_bias`	`vg_lite_float_t`	Bias value for red.
`g_scale`	`vg_lite_float_t`	Scale value for green.
`g_bias`	`vg_lite_float_t`	Bias value for green.
`b_scale`	`vg_lite_float_t`	Scale value for blue.
`b_bias`	`vg_lite_float_t`	Bias value for blue.

Parent topic:Blit enumerations

`vg_lite_mask_operation_t` enumeration

Specifies the mask operation mode in VGLite blit APIs.

Used in functions: vg_lite_blend_masklayer, vg_lite_render_masklayer.

vg_lite_mask_operation_t string values	Description
`VG_LITE_CLEAR_MASK`	This operation sets all mask values in the region of interest to 0, ignoring the new mask layer.
`VG_LITE_FILL_MASK`	This operation sets all mask values in the region of interest to 1, ignoring the new mask layer.
`VG_LITE_SET_MASK`	This operation copies values in the region of interest from the new mask layer, overwriting the previous mask values.
`VG_LITE_UNION_MASK`	This operation replaces the previous mask in the region of interest by its union with the new mask layer. The resulting values are always greater than or equal to their previous value.
`VG_LITE_INTERSECT_MASK`	This operation replaces the previous mask in the region of interest by its intersection with the new mask layer. The resulting mask values are always less than or equal to their previous value.
`VG_LITE_SUBTRACT_MASK`	This operation subtracts the new mask from the previous mask and replaces the previous mask in the region of interest by the resulting mask. The resulting values are always less than or equal to their previous value.

Parent topic:Blit enumerations

`vg_lite_orientation_t` enumeration

Specifies the mirror orientation in VGLite blit APIs.

Used in functions: vg_lite_set_mirror.

vg_lite_orientation_t string values	Description
`VG_LITE_ORIENTATION_TOP_BOTTOM`	Target output orientation is from top to bottom (default).
`VG_LITE_ORIENTATION_BOTTOM_TOP`	Target output orientation is from bottom to top.

Parent topic:Blit enumerations

`vg_lite_param_type_t` enumeration

Specifies the parameter type in VGLite blit APIs.

Used in functions: vg_lite_get_parameter.

vg_lite_param_type_t string value	Description
`VG_LITE_GPU_IDLE_STATE`	The count must be 1 for GPU idle state TRUE or FALSE.
`VG_LITE_SCISSOR_RECT`	The count must be 4n for x, y, right, bottom.

Parent topic:Blit enumerations

Parent topic:Blits for compositing and blending

Blit structures

This section provides details about blit structures.

`vg_lite_buffer_t` structure

Defined under the “Pixel buffer structures” section (see vg_lite_buffer_t structure).

Parent topic:Blit structures

`vg_lite_color_key_t` structure

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

When the enable value 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 in 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.

Used in structure: vg_lite_color_key4_t

vg_lite_color_key_t members	Type	Description
`enable`	vg_lite_uint8_t	When set (true), this color key is enabled
`low_r`	vg_lite_uint8_t	The R channel of `low_rgb`
`low_g`	vg_lite_uint8_t	The G channel of `low_rgb`
`low_b`	vg_lite_uint8_t	The B channel of `low_rgb`
`alpha`	vg_lite_uint8_t	The alpha value to replace the destination pixel alpha channel value with
`high_r`	vg_lite_uint8_t	The R channel of `high_rgb`
`high g`	vg_lite_uint8_t	The G channel of `high_rgb`
`high_b`	vg_lite_uint8_t	The B channel of `high_rgb`

Parent topic:Blit structures

`vg_lite_color_key4_t` structure

The priority order is: color_key_0 > color_key_1 > color_key_2 > color_key_3. (from April 2022)

Used in blit function: vg_lite_set_color_key

vg_lite_color_key4_t members	Type	Description
`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

Parent topic:Blit structures

`vg_lite_matrix_t` structure

Defined under the “Matrix control structures” section (see vg_lite_matrix_t structure).

Parent topic:Blit structures

`vg_lite_path_t` structure

Defined under the “Vector path structures” section (see vg_lite_path_t structure).

Parent topic:Blit structures

`vg_lite_rectangle_t` structure

This structure defines a rectangle by using coordinates.

Used in blit function: vg_lite_clear.

vg_lite_rectangle_t member	Type	Description
`x`	vg_lite_int32_t	X origin of rectangle, left coordinate in pixels
`y`	vg_lite_int32_t	Y origin of rectangle, top coordinate in pixels
`width`	vg_lite_int32_t	X Width of rectangle in pixels
`height`	vg_lite_int32_t	Y Height of rectangle in pixels

Parent topic:Blit structures

`vg_lite_point_t` structure

This structure defines a 2D point (from March 2021).

Used in structure: vg_lite_point4_t.

vg_lite_point_t member	Type	Description
X	vg_lite_int32_t	X value of coordinate
Y	vg_lite_int32_t	Y value of coordinate

Parent topic:Blit structures

`vg_lite_point4_t` structure

This structure defines four 2D points that form a polygon. The points are defined by structure vg_lite_point_t. (from March 2021)

vg_lite_point4_t member	Type	Description
`vg_lite_point_t[4]`	vg_lite_int32_t each	a set of four points

Parent topic:Blit structures

`vg_lite_float_point_t` structure

This structure defines a 2D float point (from March 2024).

Used in structure: vg_lite_float_point4_t.

vg_lite_float_point_t members	Type	Description
x	vg_lite_float_t	X value of coordinate
y	vg_lite_float_t	Y value of coordinate

Parent topic:Blit structures

`vg_lite_float_point4_t` structure

This structure defines four 2D float points that form a polygon. The points are defined by structure vg_lite_float_point_t. (from March 2024)

Used in blit function: vg_lite_get_transform_matrix.

vg_lite_float_point4_t members	Type	Description
vg_lite_float_point[4]	vg_lite_float_t each	a set of four points

Parent topic:Blit structures

Parent topic:Blits for compositing and blending

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/Draw extended functions

The following BLIT or DRAW-related functions typically require GC355 or GC555 hardware and are not available for all Vivante Vector Graphics hardware configurations.

Applications can use the VGLite API vg_lite_query_feature to determine HW support for the related functionality.

`vg_lite_get_parameter` function

Description:

This function returns the selected VGLite / GPU states to the application.

(from Aug 2023)

Syntax:

vg_lite_error_t vg_lite_get_parameter (
    vg_lite_param_type_t          type,
    vg_lite_int32_t               count,
    vg_lite_pointer               params
);

Parameters:

Parameter	Description
`type`	The parameter type to be queried (`VG_LITE_GPU_IDLE_STATE, VG_LITE_SCISSOR_RECT`)
`count`	The number of returned parameters
`params`	The pointer to the array of returned parameters

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_enable_scissor` function

Description:

This function enables scissor rectangle operation for the rectangle regions defined by vg_lite_scissor_rects API. (from March 2020, modified August 2020, requires GC355 or GC555 hardware)

Applications can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_SCISSOR) to determine HW support for scissoring. Support is available with GC355 and GC555.

Syntax:

vg_lite_error_t vg_lite_enable_scissor (
    void
);

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_disable_scissor` function

Description:

This function disables scissor operation for the rectangle regions defined by the vg_lite_scissor_rects API. (from March 2020, modified August 2020, requires GC355 or GC555 hardware).

Syntax:

vg_lite_error_t vg_lite_disable_scissor (
    void
);

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_scissor_rects` function

Description:

This function defines scissor rectangle regions on the hardware mask layer. But the scissor function is enable/disabled by vg_lite_enable_scissor and vg_lite_disable_scissor APIs. (from August 2022, requires GC355 or GC555 hardware).

Syntax:

vg_lite_error_t vg_lite_scissor_rects (
    vg_lite_buffer_t              *target,
    vg_lite_uint32_t              nums,
    vg_lite_rectangle_t           rect[]
);

Parameters:

Parameter	Description
`target`	Target render buffer that has the scissor mask layer.
`nums`	Number of scissor rectangles.
`rect[]`	The scissor rectangle array.

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_set_scissor` function

Description:

This is a legacy scissor API function that can be used to set a single scissor rectangle for the render target. This scissor API is supported by a different hardware mechanism other than the mask layer and it has better performance than the mask layer scissor function.

This API is not enabled/disabled by vg_lite_enable_scissor and vg_lite_disable_scissor APIs. Instead, the vg_lite_set_scissor API calls with a valid scissor rectangle input (x, y, right, bottom) enables the scissor function by default. The vg_lite_set_scissor API call with input parameter (-1, -1, -1, -1) disables the scissor function. (requires GC355 or GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_set_scissor (
    vg_lite_int32_t               x,
    vg_lite_int32_t               y,
    vg_lite_int32_t               right,
    vg_lite_int32_t               bottom
);

Parameters:

Parameter	Description
`x`	X Origin of rectangle, left coordinate in pixels
`Y`	Y Origin of rectangle, top coordinate in pixels
`right`	X rightmost pixel of the rectangle
`bottom`	Y bottom pixel of the rectangle

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_disable_color_transform` function

Description:

This function is used to disable color transformation. By default, the color transform is turned off. (from Sept 2022, only for GC355 and GC555 hardware)

Applications can use the VGLite API vg_lite_query_feature(gcFEATURE_BIT_VG_COLOR_TRANSFORMATION)` to determine HW support for color transformation. Support is available with GC355 and GC555.

Syntax:

vg_lite_error_t vg_lite_disable_color_transform (
);

Parameters: None

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_enable_color_transform` function

Description:

This function is used to enable color transformation. By default, the color transform is turned off. (from Sept 2022, only for GC355 and GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_enable_color_transform (
);

Parameters: None

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_set_color_transform` function

Description:

This function is used to set pixel scale and bias values for color transformation for each pixel channel. (from August 2022, only for GC355 and GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_set_color_transform (
    vg_lite_color_transform_t     *values
);

Parameters:

Parameter	Description
`*values`	Pointer to the color transformation values to set. See enum `vg_lite_color_transform_t.`

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_enable_masklayer` function

Description:

This function controls the availability of mask functionality. The mask is turned off by default. (from August - Sept mber 2022, requires GC555 hardware)

Applications can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_MASK) to determine HW support for mask. The blit and draw mask functions below require GC555 hardware support. These functions were introduced in August 2022 and the syntax or name was further refined in September 2022.

Syntax:

vg_lite_error_t vg_lite_enable_masklayer (
    void
  );

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_disable_masklayer` function

Description:

This function controls the availability of mask functionality. The mask is turned off by default. (from August -September 2022, requires GC555 hardware, prior to Sept 2022 name was vg_lite_disable_mask_layer)

Syntax:

vg_lite_error_t vg_lite_disable_masklayer (
    void
);

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_create_masklayer` function

Description:

This function creates a mask layer with the specified width and height. The mask format defaults to A8 and the default mask value is 255. (from August 2022-September, requires GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_create_masklayer (
    vg_lite_buffer_t              *masklayer,
    vg_lite_uint32_t              width,
    vg_lite_uint32_t              height
);

Parameters:

Parameter	Description
`*masklayer`	Points to the address of the buffer of the mask layer to be created.
`width`	Mask layer width (in pixels).
`height`	Mask layer height (in pixels).

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_blend_masklayer` function

Description:

This function blends the specified area of the source mask layer with the destination mask layer according to an vg_lite_mask_operation_t enumeration value, to create a blended destination mask layer. (from August-September 2022, requires GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_blend_masklayer (
    vg_lite_buffer_t              *dst_masklayer,
    vg_lite_buffer_t              *src_masklayer,
    vg_lite_mask_operation        operation,
    vg_lite_rectangle_t           *rect,
);

Parameters:

Parameter	Description
`*dst_masklayer`	Points to the address of the buffer of the destination mask layer.
`*src_masklayer`	Points to the address of the buffer of the source mask layer.
`operation`	Blending mode to be applied to each image pixel, as defined by the enum vg_lite_mask_operation_t.
`*rect`	The rectangle area (x, y, width, height) of the blend operation.

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_set_masklayer` function

Description:

This function sets the given mask layer to the hardware. (from August-September 2022, requires GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_set_masklayer (
    vg_lite_buffer_t             *masklayer
);

Parameters:

Parameter	Description
`*masklayer`	Points to the address of the buffer of the mask layer to be set.

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_render_masklayer` function

Description:

This function draws the mask layer according to the specified path, color, and matrix information. (from August-September 2022, requires GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_render_masklayer (
    vg_lite_buffer_t              *masklayer,
    vg_lite_mask_operation        operation,
    vg_lite_path_t                *path,
    vg_lite_fill_t                fill_rule,
    vg_lite_color_t               color,
    vg_lite_matrix_t              *matrix
);

Parameters:

Parameter	Description
`*masklayer`	Points to the address of the buffer of the destination mask layer.
`operation`	Blending mode to be applied to each image pixel, as defined by the enum `vg_lite_mask_operation_t`
`*path`	Pointer to the vg_lite_path_t structure containing path data that describes the path to draw. Refer to Vector path opcodes for plotting paths in this document for opcode detail.
`fill_rule`	Specifies the vg_lite_fill_t enum value for the fill rule for the path.
`color`	Specifies the color vg_lite_color_t RGBA value to be applied to each pixel drawn by the path.
`*matrix`	Points to a vg_lite_matrix_t structure that defines the 3x3 transformation matrix of the path. If the matrix is NULL, an identity matrix is assumed, meaning the source is copied directly on the target at 0,0 location. which is usually a bad idea since the path can be anything.

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_destroy_masklayer` function

Description:

This function is used to free a mask layer. (from August-September 2022, requires GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_destroy_masklayer (
    vg_lite_buffer_t              masklayer
);

Parameters:

Parameter	Description
`*masklayer`	Points to the address of the buffer of the mask layer to be destroyed.

Returns:

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

Parent topic:Blit/Draw extended functions

`vg_lite_set_mirror` function

Description:

This function is used to control mirror functionality. By default, the mirror is turned off and the default output orientation is from top to bottom. (from August 2022, only for GC555 hardware)

Application can use VGLite API [vg\_lite\_query\_feature](vg_lite_query_feature_function.md) (gcFEATURE_BIT_VG_MIRROR) to determine HW support for mirror. Mirror functions require GC555 hardware.

Syntax:

vg_lite_error_t vg_lite_set_mirror (
    vg_lite_orientation_t         orientation
);

Parameters:

Parameter	Description
`orientation`	The orientation mode as defined by the enum vg_lite_orientation_t.`

Returns:

VG_LITE_SUCCESS or VG_LITE_NOT_SUPPORT if not supported.

Parent topic:Blit/Draw extended functions

`vg_lite_source_global_alpha` function

Description:

This function sets the image/source global alpha and return a status error code. (from June 2021, requires GCNanoUltraV or GC555 hardware)

Application can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_GLOBAL_ALPHA) to determine HW support for global alpha. The global alpha BLIT-related functions require GCNanoUltraV or GC555 hardware.

Syntax:

vg_lite_error_t vg_lite_source_global_alpha (
    vg_lite_global_alpha_t        alpha_mode,
    vg_lite_uint8_t               alpha_value
);

Parameters:

Parameter	Description
`alpha_mode`	Global alpha mode value. See enum vg_lite_global_alpha_t.
`alpha_value`	The image/source global alpha value to set.

Returns:

VG_LITE_SUCCESS or VG_LITE_NOT_SUPPORT if global alpha is not supported.

Parent topic:Blit/Draw extended functions

`vg_lite_dest_global_alpha` function

Description:

This function sets the destination global alpha and returns a status error code. (from June 2021, requires GCNanoUltraV or GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_dest_global_alpha (
    vg_lite_global_alpha_t        alpha_mode,
    vg_lite_uint8_t               alpha_value
);

Parameters:

Parameter	Description
`alpha_mode`	Global alpha mode value. See enum vg_lite_global_alpha_t.
`alpha_value`	The destination global alpha value to set.

Returns:

VG_LITE_SUCCESS or VG_LITE_NOT_SUPPORT if global alpha is not supported.

Parent topic:Blit/Draw extended functions

Parent topic:Blits for compositing and blending

Blits for compositing and blending

Blit enumerations

vg_lite_blend_t enumeration

vg_lite_color_t parameter

vg_lite_color_transform_t structure

vg_lite_filter_t enumeration

vg_lite_color_transform_t structure

vg_lite_mask_operation_t enumeration

vg_lite_orientation_t enumeration

vg_lite_param_type_t enumeration

Blit structures

vg_lite_buffer_t structure

vg_lite_color_key_t structure

vg_lite_color_key4_t structure

vg_lite_matrix_t structure

vg_lite_path_t structure

vg_lite_rectangle_t structure

vg_lite_point_t structure

vg_lite_point4_t structure

vg_lite_float_point_t structure

vg_lite_float_point4_t structure

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

Blit/Draw extended functions

vg_lite_get_parameter function

vg_lite_enable_scissor function

vg_lite_disable_scissor function

vg_lite_scissor_rects function

vg_lite_set_scissor function

vg_lite_disable_color_transform function

vg_lite_enable_color_transform function

vg_lite_set_color_transform function

vg_lite_enable_masklayer function

vg_lite_disable_masklayer function

vg_lite_create_masklayer function

vg_lite_blend_masklayer function

vg_lite_set_masklayer function

vg_lite_render_masklayer function

vg_lite_destroy_masklayer function

vg_lite_set_mirror function

vg_lite_source_global_alpha function

vg_lite_dest_global_alpha function

`vg_lite_blend_t` enumeration

`vg_lite_color_t` parameter

`vg_lite_color_transform_t` structure

`vg_lite_filter_t` enumeration

`vg_lite_color_transform_t` structure

`vg_lite_mask_operation_t` enumeration

`vg_lite_orientation_t` enumeration

`vg_lite_param_type_t` enumeration

`vg_lite_buffer_t` structure

`vg_lite_color_key_t` structure

`vg_lite_color_key4_t` structure

`vg_lite_matrix_t` structure

`vg_lite_path_t` structure

`vg_lite_rectangle_t` structure

`vg_lite_point_t` structure

`vg_lite_point4_t` structure

`vg_lite_float_point_t` structure

`vg_lite_float_point4_t` structure

`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_get_parameter` function

`vg_lite_enable_scissor` function

`vg_lite_disable_scissor` function

`vg_lite_scissor_rects` function

`vg_lite_set_scissor` function

`vg_lite_disable_color_transform` function

`vg_lite_enable_color_transform` function

`vg_lite_set_color_transform` function

`vg_lite_enable_masklayer` function

`vg_lite_disable_masklayer` function

`vg_lite_create_masklayer` function

`vg_lite_blend_masklayer` function

`vg_lite_set_masklayer` function

`vg_lite_render_masklayer` function

`vg_lite_destroy_masklayer` function

`vg_lite_set_mirror` function

`vg_lite_source_global_alpha` function

`vg_lite_dest_global_alpha` function