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

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