Vector-dased draw operations

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

Draw and gradient enumerations

This section provides an overview of draw and gradient enumerations.

vg_lite_blend_t enumeration

This enumeration is defined under the “Blit enumerations” section (see vg_lite_blend_t enumeration).

Parent topic:Draw and gradient enumerations

vg_lite_color_t parameter

The common parameter vg_lite_color_t is described in Common parameter types.

Parent topic:Draw and gradient enumerations

vg_lite_fill_t enumeration

This enumeration is used to specify the fill rule to use. For drawing any path, the hardware supports both non-zero and odd-even fill rules.

To determine whether any point is contained inside an object, imagine drawing a line from that point out to infinity in any direction such that the line does not cross any vertex of the path. For each edge that is crossed by the line, add 1 to the counter if the edge is crossed from left to right, as seen by an observer walking across the line towards infinity, and subtract 1 if the edge crossed from right to left. In this way, each region of the plane will receive an integer value.

The non-zero fill rule says that a point is inside the shape if the resulting sum is not equal to zero. The even/odd rule says that a point is inside the shape if the resulting sum is odd, regardless of sign.

Used in function: vg_lite_render_masklayer.

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

vg_lite_fill_t string values

Description

VG_LITE_FILL_NON_ZERO

Non-zero fill rule. A pixel is drawn if it crosses at least one path pixel.

VG_LITE_FILL_EVEN_ODD

Even-odd fill rule. A pixel is drawn if it crosses an odd number of path pixels.

Parent topic:Draw and gradient enumerations

vg_lite_filter_t enumeration

This enum is defined under the “Blit enumerations” section (see vg_lite_filter_t enumeration).

Parent topic:Draw and gradient enumerations

vg_lite_gradient_spreadmode_t enumeration

vg_lite_gradient_spreadmode_t enum is defined to match OpenVG enum VGColorRampSpreadMode (from March 2023, replacesvg_lite_radial_gradient_spreadmode*, requires GC355/GC555 hardware)*

The application may only define stops with offsets between 0 and 1. Spread modes define how the given set of stops are repeated or extended in order to define interpolated color values for arbitrary input values outside the [0,1] range.

Used in structure: vg_lite_radial_gradient_t.

vg_lite_gradient_spreadmode_t String Values

Description

VG_LITE_GRADIENT_SPREAD_FILL

The current fill color is used for all stop values less than 0 or greater than 1 respectively.

VG_LITE_GRADIENT_SPREAD_PAD

Colors defined at 0 and 1 are used for all stop values less than 0 or greater than 1 respectively.

VG_LITE_GRADIENT_SPREAD_REPEAT

Color values defined between 0 and 1 are repeated indefinitely in both directions.

VG_LITE_GRADIENT_SPREAD_REFLECT

Color values defined between 0 and 1 are repeated indefinitely in both directions but with alternate copies of the range reversed.

Parent topic:Draw and gradient enumerations

vg_lite_pattern_mode_t enumeration

Defines how the region outside the image pattern is filled for the path.

Used in function: vg_lite_draw_gradient, vg_lite_draw_pattern.

vg_lite_pattern_mode_t string values

Description

VG_LITE_PATTERN_COLOR

Pixels outside the bounds of the source image should be taken as the color.

VG_LITE_PATTERN_PAD

Pixels outside the bounds of the source image should be taken as having the same color as the closest edge pixel. The color of the pattern border is expanded to fill the region outside the pattern.

VG_LITE_PATTERN_REPEAT

Pixels outside the bounds of the source image should be repeated indefinitely in all directions. (from March 2023)

VG_LITE_PATTERN_REFLECT

Pixels outside the bounds of the source image should be reflected indefinitely in all directions. (from March 2023)

Parent topic:Draw and gradient enumerations

vg_lite_radial_gradient_spreadmode_t enumeration

(Deprecated March 2023) use vg_lite_gradient_spreadmode_t. Defines the radial gradient padding mode. (from Nov 2020, requires GC355 hardware)

Used in structure: vg_lite_radial_gradient_t.

vg_lite_radial_gradient_spreadmode_t String Values

Description

VG_LITE_RADIAL_GRADIENT_SPREAD_FILL = 0

The current fill color is used for all stop values less than 0 or greater than 1 respectively.

VG_LITE_RADIAL_GRADIENT_SPREAD_PAD

Colors defined at 0 and 1 are used for all stop values less than 0 or greater than 1 respectively.

VG_LITE_RADIAL_GRADIENT_SPREAD_REPEAT

Color values defined between 0 and 1 are repeated indefinitely in both directions.

VG_LITE_RADIAL_GRADIENT_SPREAD_REFLECT

Color values defined between 0 and 1 are repeated indefinitely in both directions but with alternate copies of the range reversed.

Parent topic:Draw and gradient enumerations

Parent topic:Vector-dased draw operations

Draw and gradient structures

This section provides an overview of the draw and gradient structures.

vg_lite_buffer_t structure

This structure is defined under the “Pixel buffer structures” section (see vg_lite_buffer_t structure).

Parent topic:Draw and gradient structures

vg_lite_color_ramp_t structure

This structure defines the stops for the radial gradient. The five parameters provide the offset and color for the stop. Each stop is defined by a set of floating point values which specify the offset and the sRGBA color and alpha values. Color channel values are in the form of a non-premultiplied (R, G, B, alpha) quad. All parameters are in the range of [0,1]. The red, green, blue, alpha value of [0, 1] is mapped to an 8-bit pixel value [0, 255].(from November 2020, requires GC355 hardware)

The define for the max number of radial gradient stops is #define MAX_COLOR_RAMP_STOPS256.

Used in radial gradient structure: vg_lite_radial_gradient_t.

vg_lite_color_ramp_t members

Type

Description

stop

vg_lite_float_t

Offset value for the color stop

red

vg_lite_float_t

Red color channel value for the color stop

green

vg_lite_float_t

Green color channel value for the color stop

blue

vg_lite_float_t

Blue color channel value for the color stop

alpha

vg_lite_float_t

Alpha color channel value for the color stop

Parent topic:Draw and gradient structures

vg_lite_linear_gradient_t structure

This structure defines the organization of a linear gradient in VGLite data. The linear gradient is applied to filling a path. It generates a 256x1 image according to the specified settings.

Used in init and draw functions: vg_lite_init_grad, vg_lite_set_grad, vg_lite_update_grad, vg_lite_get_grad_matrix, vg_lite_clear_grad, vg_lite_draw_grad.

vg_lite_linear_gradient_t constants

Type

Description

VLC_MAX_GRADIENT_STOPS

vg_lite_int32_t

Constant. Maximum number of gradient colors = 16.

vg_lite_linear_gradient_t members

colors [VLC_MAX_GRADIENT_STOPS]

vg_lite_uint32_t

Color array for the gradient

count

vg_lite_uint32_t

Number of colors

stops [VLC_MAX_GRADIENT_STOPS]

vg_lite_uint32_t

Number of color stops, from 0 to 255

matrix

vg_lite_matrix_t

Struct for the matrix to transform the gradient color ramp

image

vg_lite_buffer_t

Image object struct to represent the color ramp

Parent topic:Draw and gradient structures

vg_lite_ext_linear_gradient structure

This structure defines the organization of the extended parameters possible for a linear gradient (from April 2022).

Used in functions: vg_lite_draw_linear_grad.

vg_lite_ext_linear_gradient_t members

Type

Description

count

vg_lite_uint32_t

Count of colors, up to 256.

matrix

vg_lite_matrix_t

The matrix to transform the gradient.

image

vg_lite_buffer_t

The image for rendering as gradient pattern.

linear_grad

vg_lite_linear_gradient_parameter_t

Linear gradient parameters. Includes center point, focal point and radius.

ramp_length

vg_lite_uint32_t

Color ramp length for gradient paints provided to the driver.

color_ramp[VLC_MAX_COLOR_RAMP_STOPS]

vg_lite_color_ramp_t

Color ramp parameter for gradient paints provided to the driver.

converted_length

vg_lite_uint32_t

Converted internal color ramp length.

converted_ramp[VLC_MAX_COLOR_RAMP_STOPS+2]

vg_lite_color_ramp_t

Converted internal color ramp.

pre-multiplied

vg_lite_uint8_t

If this value is set to 1, the color value of color_ramp will be multiplied by the alpha value of color_ramp.

spread_mode

vg_lite_radial_gradient_spreadmode_t

The spread mode that is applied to the pixels out of the image after transformed.

|

Parent topic:Draw and gradient structures

vg_lite_linear_gradient_parameter structure

This structure defines a radial direction for a linear gradient. (from April 2022)

Line0 connects point (X0, Y0) to point (X1, Y1) and represents the radial direction of the linear gradient.

Line1 is a line perpendicular to line0 which passes through point (X0, Y0).

Line2 is a line perpendicular to line0 which passes through point (X1, Y1)

The linear gradient paint is applied at the intersection of the path fill area and the plane starting from line 1 and ending at line 2.

Used in structure: vg_lite_ext_linear_gradient.

Used in functions: vg_lite_set_linear_grad.

vg_lite_linear_gradient_parameter_t members

Type

Description

X0

vg_lite_float_t

X origin of linear gradient radial direction.

Y0

vg_lite_float_t

Y origin of linear gradient radial direction.

X1

vg_lite_float_t

X end point of linear gradient radial direction.

Y1

vg_lite_float_t

Y end point of linear gradient radial direction.

Parent topic:Draw and gradient structures

vg_lite_matrix_t structure

This structure is defined under the “Matrix control structures” section (see vg_lite_matrix_t structure).

Parent topic:Draw and gradient structures

vg_lite_path_t structure

This structure is defined under the “Vector path structures” section (see vg_lite_path_t structure).

Parent topic:Draw and gradient structures

vg_lite_radial_gradient_parameter_t structure

This structure defines the gradient radius and the X and Y coordinates for the center and focal points of the gradient (from November 2020, requires GC355 or GC555 hardware).

Used in radial gradient structure: vg_lite_radial_gradient_t.

vg_lite_radial_gradient_parameter_t member

Type

Description

cx

vg_lite_float_t

cy

vg_lite_float_t

r

vg_lite_float_t

fx

vg_lite_float_t

fy

vg_lite_float_t

Parent topic:Draw and gradient structures

vg_lite_radial_gradient_t structure

This structure defines the application of the radial gradient to fill a path. (from November 2020, requires GC355 or GC555 hardware).

Used in radial gradient functions: vg_lite_draw_grad, vg_lite_set_radial_grad, vg_lite_update_radial_grad, vg_lite_get_radial_grad, vg_lite_clear_radial_grad.

vg_lite_radial_gradient_t member

Type

Description

count

vg_lite_uint32_t

Count of colors, up to 256

matrix

vg_lite_matrix_t

Structure that specifies the transform matrix for the gradient

image

vg_lite_buffer_t

Structure that specifies the image for rendering as a gradient pattern

radial_grad

vg_lite_radial_gradient_parameter_t

Structure that specifies the location of the gradient’s center point (cx, cy), focal point(fx, fy) and radius(r)

ramp_length

vg_lite_uint32_t

Color ramp parameters for gradient paints provided to the driver

color_ramp[VLC_MAX_COLOR_RAMP_STOPS]

vg_lite_color_ramp_t

Structure that specifies the color ramp

converted_length

vg_lite_uint32_t

Converted internal color ramp.

converted_ramp[VLC_MAX_COLOR_RAMP_STOPS+2]

vg_lite_color_ramp_t

Structure that specifies the internal color ramp

pre_multiplied

vg_lite_uint32_t

If this value is set to 1, the color value of color_ramp will be multiplied by the alpha value of color_ramp.

spread_mode

vg_lite_radial_gradient_spreadmode_t

Enum that specifies the tiling mode, which is applied to the pixels out of the image after transformation

Parent topic:Draw and gradient structures

Parent topic:Vector-dased draw operations

Draw functions

This section provides an overview of the draw functions.

vg_lite_draw function

Description:

This function performs a hardware accelerated 2D vector draw operation.

The size of the tessellation buffer can be specified at initialization and it is aligned with the minimum hardware alignment requirements of the kernel. Specifying a smaller size for tessellation buffer allocates less memory but reduces performance. Because the hardware walks the target with the provided tessellation window size, a path may be sent to the hardware multiple times. It is a good practice to set the tessellation buffer size to the most common path size. For example, if all you do is render up to 24-point fonts, you can set the tessellation buffer to 24x24.

Note:

  • All the color formats available in the vg_lite_buffer_format_t enum are supported as the destination buffer for the draw function

  • The hardware does not support strokes; they must be converted to paths before you use them in the draw API

Syntax:

vg_lite_error_t vg_lite_draw (
       vg_lite_buffer_t         *target,
       vg_lite_path_t           *path,
       vg_lite_fill_t           fill_rule,
       vg_lite_matrix_t         *matrix,
       vg_lite_blend_t          blend,
       vg_lite_color_t          color
);

Parameters:

Parameter

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 draw function.

*path

Pointer to the vg_lite_path_t structure containing path data that describes the path to draw. See opcode details in Vector path opcodes for plotting paths.

fill_rule

Specifies the vg_lite_fill_t enum value for the fill rule for the path

*matrix

Pointer to a vg_lite_matrix_t structure that defines the affine transformation matrix of the path. If the matrix is NULL, an identity matrix is assumed. Note: Non-affine transformations are not supported by vg_lite_draw; therefore, a perspective transformation matrix might have unexpected effects on path rendering.

blend

Select one of the hardware-supported blend modes in the vg_lite_blend_t enum to be applied to each drawn pixel. If no blending is required, set this value to VG_LITE_BLEND_NONE (0).

color

The color applied to each pixel drawn by the path.

Returns:

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

Parent topic:Draw functions

vg_lite_draw_grad function

Description:

This function is used to fill a path with a linear gradient according to the specified fill rules. The specified path is transformed according to the selected matrix and is filled with the specified color gradient.

Syntax:

vg_lite_error_t vg_lite_draw_grad (
    vg_lite_buffer_t            *target,
    vg_lite_path_t              *path, 
    vg_lite_fill_t              fill_rule, 
    vg_lite_matrix_t            *matrix, 
    vg_lite_linear_gradient_t   *grad, 
    vg_lite_blend_t             blend
);  

Parameters:

Parameter

Description

*target

Pointer to the vg_lite_buffer_t structure containing data describing the target path.

*path

Pointer to the vg_lite_path_t structure containing path data that describes the path to draw and fill with the linear gradient. See opcode details in Vector path opcodes for plotting paths.

fill_rule

Specifies the vg_lite_fill_t enum value for the fill rule for the path

*matrix

Pointer to the vg_lite_matrix_t structure that defines the 3x3 transformation matrix of the path. If the matrix is NULL, an identity matrix is assumed; however, this option is not preferable.

*grad

Pointer to the vg_lite_linear_gradient_t structure that contains the values to be used to fill the path.

blend

Specifies the blend mode in the vg_lite_blend_t enum to be applied to each drawn pixel. If no blending is required, set this value to VG_LITE_BLEND_NONE (0).

Returns:

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

Parent topic:Draw functions

vg_lite_draw_radial_grad function

Description:

This function is used to fill a path with a radial gradient according to the specified fill rules. The specified path is transformed according to the selected matrix and is filled with the radial color gradient. The application can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_RADIAL_GRADIENT) to determine HW support for radial gradient.

Syntax:

vg_lite_error_t vg_lite_draw_radial_grad (
    vg_lite_buffer_t            *target,
    vg_lite_path_t              *path, 
    vg_lite_fill_t              fill_rule, 
    vg_lite_matrix_t            *path_matrix, 
    vg_lite_radial_gradient_t   *grad,
    vg_lite_color_t             paint_color,
    vg_lite_blend_t             blend,
    vg_lite_filter_t            filter
);  

Parameters:

Parameter

Description

*target

Pointer to the vg_lite_buffer_t structure containing data describing the target path.

*path

Pointer to the vg_lite_path_t structure containing path data that describes the path to draw for and fill with the radial gradient. See opcode details in Vector path opcodes for plotting paths.

fill_rule

Specifies the vg_lite_fill_t enum value for the fill rule for the path

*path_matrix

Pointer 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; however, his option is not preferable.

*grad

Pointer to the vg_lite_radial_gradient_t structure that contains the values to be used to fill the path. Note: grad->image.image_mode does not support VG_LITE_MULTIPLY_IMAGE_MODE .

paint_color

Specifies the paint color vg_lite_color_t RGBA value to be applied by VG_LITE_RADIAL_GRADIENT_SPREAD_FILL set by the function vg_lite_set_radial_grad. When pixels are out of the image after transformation, paint_color is applied to them. For details, see vg_lite_radial_gradient_spreadmode_t.

blend

Specifies the blend mode in the vg_lite_blend_t enum to be applied to each drawn pixel. If no blending is required, set this value to VG_LITE_BLEND_NONE (0).

filter

Specified the filter mode vg_lite_filter_t enum value to be applied to each drawn pixel. If no filtering is required, set this value to VG_LITE_BLEND_POINT (0).

Returns:

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

Parent topic:Draw functions

vg_lite_draw_pattern function

Description:

This function fills a path with an image pattern. The path is transformed according to the specified matrix and is filled with the transformed image pattern.

Syntax:

vg_lite_error_t vg_lite_draw_pattern (
    vg_lite_buffer_t            *target,
    vg_lite_path_t              *path,
    vg_lite_fill_t              fill_rule,
    vg_lite_matrix_t            *path_matrix,
    vg_lite_buffer_t            *pattern_image,
    vg_lite_matrix_t            *pattern_matrix,
    vg_lite_blend_t             blend,
    vg_lite_pattern_mode_t      pattern_mode,
    vg_lite_color_t             pattern_color,
    vg_lite_color_t             color,
    vg_lite_filter_t            filter
);

Parameters:

Parameter

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 this draw function.

*path

Pointer to the vg_lite_path_t structure containing path data that describes the path to draw. See opcode details in Vector path opcodes for plotting paths

fill_rule

Specifies the vg_lite_fill_t enum value for the fill rule for the path.

*path_matrix

Pointer to the vg_lite_matrix_t structure that defines the 3x3 transformation matrix of the source pixels into the target. If the matrix is NULL, an identity matrix is assumed, meaning the source is copied directly onto the target at 0,0 location.

*pattern_image

Pointer 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.

*pattern_matrix

Pointer to the vg_lite_buffer_t structure that describes the source of the image pattern

Pointer to a vg_lite_matrix_t structure that defines the 3x3 transformation matrix of the source pixels into the target. If the matrix is NULL, 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 vg_lite_blend_t enum values for hardware-supported blend modes to be applied to each drawn pixel in the image. If no blending is required, set this value to VG_LITE_BLEND_NONE (0).

pattern_mode

Specifies the vg_lite_pattern_mode_t value that defines how the region outside the image pattern is to be filled.

pattern_color

Specifies a 32bpp ARGB color (vg_lite_color_t) to be applied to the fill outside the image pattern area when the pattern_mode value is VG_LITE_PATTERN_COLOR. (from Dec 2019, type now vg_lite_color_t, previously was uint32_t)

color

Specifies a 32bpp ARGB color (vg_lite_color_t) to be applied as a mix color. If non-zero, the mix color value gets multiplied with each source pixel before blending happens. If a mix color is not needed, set the color parameter to 0 (from May 2023). Note: This parameter has no effect if the pattern image 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 successful. See vg_lite_error_t enum for other return codes.

Parent topic:Draw functions

Parent topic:Vector-dased draw operations

Linear gradient initialization and control functions

This part of the API performs linear gradient operations.

A color gradient (color progression, color ramp) is a smooth transition between a set of colors (color stops) that is done along a line (linear, or axial color gradient) or radially, along concentric circles (radial color gradient). The color transition is done by linear interpolation between two consecutive color stops.

Note: VGLite supports linear color gradients for GCNanoLiteV and GCNanoUltraV. Both linear and radial gradients are supported with GC355 and GC555.

vg_lite_init_grad function

Description:

This function initializes the internal buffer for the linear gradient object with default settings for rendering.

Syntax:

vg_lite_error_t vg_lite_init_grad (
       vg_lite_linear_gradient_t *grad
);

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_t structure, which defines the gradient to be initialized. Default values are used.

Returns:

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

Parent topic:Linear gradient initialization and control functions

vg_lite_clear_grad function

Description:

This function is used to clear the values of a linear gradient object and free up the memory of the image buffer.

Syntax:

vg_lite_error_t vg_lite_clear_grad (
       vg_lite_linear_gradient_t        *grad
);

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_t structure that is to be cleared

Returns:

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

Parent topic:Linear gradient initialization and control functions

vg_lite_set_grad function

Description:

This function is used to set values for the members of the vg_lite_linear_gradient_t structure.

Note: The vg_lite_set_grad API adopts the following rules to set the default gradient colors if the input parameters are incomplete or invalid:

  • If no valid stops have been specified (for example, due to an empty input array, out-of-range or out-of-order stops), a stop at 0 with (R, G, B, A) color (0.0, 0.0, 0.0, 1.0) (opaque black) and a stop at 1 with color (1.0, 1.0, 1.0, 1.0) (opaque white) are implicitly defined

  • If at least one valid stop has been specified, but none has been defined with an offset of 0, then an implicit stop is added with an offset of 0 and the same color as the first user-defined stop

  • If at least one valid stop has been specified, but none has been defined with an offset of 1, then an implicit stop is added with an offset of 1 and the same color as the last user-defined stop

Syntax:

vg_lite_error_t vg_lite_set_grad (
       vg_lite_linear_gradient_t       *grad,
       uint32_t                        count,
       uint32_t                        *colors,
       uint32_t                        *stops
      );

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_t structure to be set

count

The number of colors in the linear gradient. The maximum color stop count is defined by VLC_MAX_GRAD which is 16.

*colors

Specifies the color array for the gradient stops. The color is in ARGB8888 format with alpha in the upper byte.

*stops

Pointer to the gradient stop offset

Returns:

Always returns VG_LITE_SUCCESS.

Parent topic:Linear gradient initialization and control functions

vg_lite_get_grad_matrix function

Description:

This function is used to get a pointer to the transformation matrix of the gradient object. It allows an application to manipulate the matrix to facilitate correct rendering of the gradient path.

Syntax:

vg_lite_error_t vg_lite_get_grad_matrix (
       vg_lite_linear_gradient_t         *grad
);

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_t structure, which contains the matrix to be retrieved

Returns:

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

Parent topic:Linear gradient initialization and control functions

vg_lite_update_grad function

Description:

This function is used to update or generate values for an image object that is going to be rendered. The vg_lite_linear_gradient_t object has an image buffer, which is used to render the gradient pattern. The image buffer is created or updated with the corresponding gradient parameters.

Syntax:

vg_lite_error_t vg_lite_update_grad (
       vg_lite_linear_gradient_t     *grad
);

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_t structure, which contains the update values to be used for the object to be rendered

Returns:

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

Parent topic:Linear gradient initialization and control functions

Parent topic:Vector-dased draw operations

Linear gradient extended functions

The following functions are available only with IP that includes hardware support for extended linear gradient capabilities, such as GC355 and GC555. These functions are not available with GCNanoLiteV, GCNanoUltraV, or GCNanoV. Applications can use VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_LINEAR_GRADIENT_EXT) to determine HW support for linear gradient.

vg_lite_set_linear_grad function

Description:

This function is used to set the values that define the linear gradient. (from April 2022)

Syntax:

vg_lite_error_t vg_lite_set_linear_grad (
    vg_lite_ext_linear_gradient_t          *grad,
    vg_lite_uint32_t                       count,
    vg_lite_color_ramp_t                   *color_ramp,
    vg_lite_linear_gradient_parameter_t    grad_param,
    vg_lite_radial_gradient_spreadmode_t   spread_mode,
    vg_lite_uint8_t                        pre_mult
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_ext_linear_gradient_t structure that is to be set.

count

Count of the colors in the gradient. The maximum color stop count is defined by MAX_COLOR_RAMP_STOPS, which is set to 256.

*color_ramp

It is the array of stops for the linear gradient. The number of parameters for each stop is 5, and gives the offset and color of the stop. Each stop is defined by a floating-point offset value and four floating-point values containing the sRGBA color and alpha value associated with each stop, in the form of a non-premultiplied (R, G, B, alpha) quad. The range of all parameters is [0,1].

grad_param

Gradient parameters as specified in the structure vg_lite_linear_gradient_parameter_t.

spread_mode

The fill mode is applied to the pixels out of the paint after transformation. Uses the same spread mode enumeration types as radial gradient. For details, see vg_lite_radial_gradient_spreadmode_t enum.

pre_mult

This parameter controls whether color and alpha values are interpolated in premultiplied or non-premultiplied form.

Returns:

Returns VG_LITE_INVALID_ARGUMENTS to indicate the parameters are wrong.

Parent topic:Linear gradient extended functions

vg_lite_get_linear_grad_matrix function

Description:

This function returns a pointer to an extended linear gradient object’s matrix.(from March 2023).

Syntax:

vg_lite_matrix_t* vg_lite_get_linear_grad_matrix (
    vg_lite_ext_linear_gradient_t   *grad,
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_ext_linear_gradient_t structure.

Returns:

Returns a pointer to vg_lite_matrix_t for the specified extended linear gradient.

Parent topic:Linear gradient extended functions

vg_lite_draw_linear_grad function

Description:

This function returns a pointer to an extended linear gradient object’s matrix.(from March 2023).

Syntax:

vg_lite_error_t vg_lite_draw_linear_grad (
    vg_lite_buffer_t                *target,
    vg_lite_path_t                  *path, 
    vg_lite_fill_t                  fill_rule, 
    vg_lite_matrix_t                *path_matrix, 
    vg_lite_ext_linear_gradient_t   *grad, 
    vg_lite_color_t                 paint_color,
    vg_lite_blend_t                 blend,
    vg_lite_filter_t                filter
); 

Parameters:

Parameter

Description

*target

Pointer to the vg_lite_buffer_t structure containing data describing the target path.

*path

Pointer to the vg_lite_path_t structure containing path data that describes the path to draw for the linear gradient. 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.

*path_matrix

Pointer 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; however, this option is not preferable.

*grad

Pointer to the vg_lite_ext_linear_gradient_t structure that contains the values to be used to fill the path. Note: grad->image.image_mode does not support VG_LITE_MULTIPLY_IMAGE_MODE.

paint_color

Specifies the paint color vg_lite_color_t RGBA value to be applied by VG_LITE_RADIAL_GRADIENT_SPREAD_FILL, set by function vg_lite_set_linear_grad. When pixels are out of the image after transformation, this paint_color is applied to them. For details, see enum vg_lite_radial_gradient_spreadmode_t.

blend

Specifies blend mode in the vg_lite_blend_t enum to be applied to each drawn pixel. If no blending is required, set this value to VG_LITE_BLEND_NONE (0).

filter

Specified the filter mode vg_lite_filter_t enum value to be applied to each drawn pixel. If no filtering is required, set this value to VG_LITE_BLEND_POINT (0).

Returns:

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

Parent topic:Linear gradient extended functions

vg_lite_update_linear_grad function

Description:

This function is used to update or generate the corresponding image object to render (from April 2022).

The vg_lite_ext_linear_gradient_t object has an image buffer that is used to render the linear gradient paint. The image buffer is created/updated according to the specified grad parameters.

Syntax:

vg_lite_error_t vg_lite_update_linear_grad (
    vg_lite_ext_linear_gradient_t   *grad,
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_ext_t structure that is to be updated or created.

Returns:

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

Parent topic:Linear gradient extended functions

vg_lite_clear_linear_grad function

Description:

This function is used to clear the linear gradient object. This resets the grad members and free the image buffer’s memory (from April 2022).

Syntax:

vg_lite_error_t vg_lite_clear_linear_grad (
    vg_lite_ext_linear_gradient_t    *grad,
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_linear_gradient_ext_t structure that is to be cleared.

Returns:

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

Parent topic:Linear gradient extended functions

Parent topic:Vector-dased draw operations

Radial gradient functions initialization and control functions

The following functions are available only with IP that supports radial gradients, such as GC355 and GC555. These functions are not available with GCNanoLiteV, or GCNanoUltraV or GCNanoV.

Note: There is no init function required for radial gradients. Buffer initialization is done through the vg_lite_update_radial_grad function. (from Nov 2020, requires GC355 or GC555 hardware)

vg_lite_set_radial_grad function

Description:

This function is used to set the values for the radial linear gradient definition. (from November 2020, requires GC355 or GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_set_radial_grad (
    vg_lite_radial_gradient_t              *grad,
    vg_lite_uint32_t                       count,
    vg_lite_color_ramp_t                   *color_ramp,
    vg_lite_radial_gradient_parameter_t    grad_param,
    vg_lite_radial_gradient_spreadmode_t   spread_mode,
    vg_lite_uint8_t                        pre_mult
); 

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_radial_gradient_t structure for the radial gradient that has to be set

count

The number of color stops in the gradient. The maximum color stop count is defined by MAX_COLOR_RAMP_STOPS, which is currently 256.

*color_ramp

Pointer to the vg_lite_color_ramp_t structure that defines the stops for the radial gradient. The five parameters provide the offset and color for each stop. Each stop is defined by a set of floating point values that specify the offset and the sRGBA color and alpha values. Color channel values are in the form of a non-premultiplied (R, G, B, alpha) quad. All parameters are in the range of [0,1]. The red, green, blue, alpha value of [0, 1] is mapped to an 8-bit pixel value [0, 255].

grad_param

The radial gradient parameters are supplied as a vector of 5 floats. Parameters (cx, cy) specify the center point, parameters (fx, fy) specify the focal point, and r specifies the radius. See structure vg_lite_radial_gradient_parameter_t.

spread_mode

The tiling mode that is applied to pixels out of the paint after transformation. See enum vg_lite_radial_gradient_spreadmode_t.

pre_mult

Controls whether color and alpha values are interpolated in premultiplied or non-premultiplied form. If this value is set to 1, the color value of vgColorRamp is multipled by the alpha value of vgColorRamp.

Returns:

Returns VG_LITE_INVALID_ARGUMENTS to indicate that the parameters are wrong.

Parent topic:Radial gradient functions initialization and control functions

vg_lite_update_radial_grad function

Description:

This function is used to update or generate values for an image object that is going to be rendered. The vg_lite_radial_gradient_t object has an image buffer that is used to render the gradient pattern. The image buffer will be created or updated with the corresponding gradient parameters. (from November 2020, requires GC355 or GC555 hardware)

Syntax:

vg_lite_error_t vg_lite_update_radial_grad (
    vg_lite_radial_gradient_t   *grad, 
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_radial_gradient_t structure, which contains the updated values to be used for the object to be rendered

Returns:

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

Parent topic:Radial gradient functions initialization and control functions

vg_lite_get_radial_grad_matrix function

Description:

This function is used to get a pointer to the radial gradient object’s transformation matrix. This allows an application to manipulate the matrix to facilitate correct rendering of the gradient path*. (from Nov 2020, requires GC355 or GC555 hardware).*

Syntax:

vg_lite_error_t vg_lite_get_radial_grad_matrix (
    vg_lite_radial_gradient_t    *grad, 
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_radial_gradient_t structure, which contains the matrix to be retrieved

Returns:

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

Parent topic:Radial gradient functions initialization and control functions

vg_lite_clear_rad_grad function

Description:

This function is used to clear the values of a radial gradient object and free the image buffer’s memory*. (from Nov 2020, requires GC355 or GC555 hardware)*

Syntax:

vg_lite_error_t vg_lite_clear_radial_grad (
    vg_lite_radial_gradient_t   *grad, 
);  

Parameters:

Parameter

Description

*grad

Pointer to the vg_lite_radial_gradient_t structure which is to be cleared

Returns:

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

Parent topic:Radial gradient functions initialization and control functions

Parent topic:Vector-dased draw operations