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

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_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