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 |
(SP*DP + SP*(1 - Da) + DP*(1 - Sa)) / (Sa + Da*(1 - Sa)) Premultiplied |
OPENVG_BLEND_SCREEN |
(SP + DP - (SP*DP)) / (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 |
---|---|---|
|
|
Scale value for alpha. |
|
|
Bias value for alpha. |
|
|
Scale value for red. |
|
|
Bias value for red. |
|
|
Scale value for green. |
|
|
Bias value for green. |
|
|
Scale value for blue. |
|
|
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 |
---|---|
|
Fetch only the nearest image pixel |
|
Use linear interpolation along a horizontal line |
|
Use a 2x2 box around the image pixel and perform an interpolation |
|
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 |
---|---|---|
|
|
Scale value for alpha. |
|
|
Bias value for alpha. |
|
|
Scale value for red. |
|
|
Bias value for red. |
|
|
Scale value for green. |
|
|
Bias value for green. |
|
|
Scale value for blue. |
|
|
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 |
---|---|
|
This operation sets all mask values in the region of interest to 0, ignoring the new mask layer. |
|
This operation sets all mask values in the region of interest to 1, ignoring the new mask layer. |
|
This operation copies values in the region of interest from the new mask layer, overwriting the previous mask values. |
|
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. |
|
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. |
|
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 |
---|---|
|
Target output orientation is from top to bottom (default). |
|
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 |
---|---|
|
The count must be 1 for GPU idle state TRUE or FALSE. |
|
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 |
---|---|---|
|
vg_lite_uint8_t |
When set (true), this color key is enabled |
|
vg_lite_uint8_t |
The R channel of |
|
vg_lite_uint8_t |
The G channel of |
|
vg_lite_uint8_t |
The B channel of |
|
vg_lite_uint8_t |
The alpha value to replace the destination pixel alpha channel value with |
|
vg_lite_uint8_t |
The R channel of |
|
vg_lite_uint8_t |
The G channel of |
|
vg_lite_uint8_t |
The B channel of |
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 |
---|---|---|
|
high_rgb_0, low_rgb_0, alpha_0, enable_0 |
|
|
high_rgb_1, low_rgb_1, alpha_1, enable_1 |
|
|
high_rgb_2, low_rgb_2, alpha_2, enable_2 |
|
|
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 |
---|---|---|
|
vg_lite_int32_t |
X origin of rectangle, left coordinate in pixels |
|
vg_lite_int32_t |
Y origin of rectangle, top coordinate in pixels |
|
vg_lite_int32_t |
X Width of rectangle in pixels |
|
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_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 |
---|---|
|
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. |
|
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. |
|
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. |
|
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 |
|
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 |
|
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 |
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 |
---|---|
|
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 |
|
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. |
|
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). |
|
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 |
|
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 |
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_rec
t 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 |
---|---|
|
Points to the vg_lite_buffer_t structure that defines the destination buffer. |
|
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. |
|
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. |
|
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. |
|
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 |
|
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 |
|
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 |
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 |
---|---|
|
Points to the vg_lite_buffer_t structure that defines the destination buffer. |
|
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. |
|
Pixel coordinates of the lower-left corner of a pixel rectangle within the source buffer. |
|
Pixel coordinates of the lower-left corner of a pixel rectangle within the target buffer. |
|
Width of the copied pixel rectangle. |
|
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 |
---|---|
|
Pointer to the four 2D points that form a source polygon |
|
Pointer to the four 2D points that form a destination polygon |
|
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 |
---|---|
|
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. |
|
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. |
|
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 |
---|---|
|
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 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 |
---|---|
|
The parameter type to be queried ( |
|
The number of returned parameters |
|
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 render buffer that has the scissor mask layer. |
|
Number of scissor rectangles. |
|
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 Origin of rectangle, left coordinate in pixels |
|
Y Origin of rectangle, top coordinate in pixels |
|
X rightmost pixel of the rectangle |
|
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 |
---|---|
|
Pointer to the color transformation values to set. See enum |
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 |
---|---|
|
Points to the address of the buffer of the mask layer to be created. |
|
Mask layer width (in pixels). |
|
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 |
---|---|
|
Points to the address of the buffer of the destination mask layer. |
|
Points to the address of the buffer of the source mask layer. |
|
Blending mode to be applied to each image pixel, as defined by the enum vg_lite_mask_operation_t. |
|
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 |
---|---|
|
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 |
---|---|
|
Points to the address of the buffer of the destination mask layer. |
|
Blending mode to be applied to each image pixel, as defined by the enum |
|
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. |
|
Specifies the vg_lite_fill_t enum value for the fill rule for the path. |
|
Specifies the color vg_lite_color_t RGBA value to be applied to each pixel drawn by the path. |
|
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 |
---|---|
|
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 |
---|---|
|
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 |
---|---|
|
Global alpha mode value. See enum vg_lite_global_alpha_t. |
|
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 |
---|---|
|
Global alpha mode value. See enum vg_lite_global_alpha_t. |
|
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