Vector path control

This chapter provides an overview of the vector path enumerations, structures, functions, and opcodes for plotting paths.

Vector path enumerations

This section provides an overview of vector path enumerations.

`vg_lite_format_t` enumeration

Values for vg_lite_format_t enum are defined in Table 1.

If vg_lite_format_t	Path data alignment in the array should be:
VG_LITE_S8	8 bit
VG_LITE_S16	2 bytes
VG_LITE_S32	4 bytes

Parent topic:Vector path enumerations

`vg_lite_quality_t` enumeration

Specifies the level of hardware assisted anti-aliasing.

Used in structure: vg_lite_path_t.

Used in function: vg_lite_init_path, vg_lite_init_arc_path.

vg_lite_quality_t string values	Description
`VG_LITE_HIGH`	High quality: 16x coverage sample anti-aliasing
`VG_LITE_UPPER`	Upper quality: 8x coverage sample anti-aliasing. Use vg_lite_query_feature to determine availability of 8x CSAA (feature enum value `gcFEATURE_BIT_VG_QUALITY_8X`.(deprecated from June 2020, available with supported hardware from August 2022).
`VG_LITE_MEDIUM`	Medium quality: 4x coverage sample anti-aliasing
`VG_LITE_LOW`	Low quality: No anti-aliasing

Parent topic:Vector path enumerations

Parent topic:Vector path control

Vector path structures

This section provides an overview of vector path structures.

`vg_lite_hw_memory` structure

This structure gets the memory allocation information recorded by the kernel.

Used in structure: vg_lite_path_t.

vg_lite_hw_memory_t member	Type	Description
`handle`	`vg_lite_pointer`	GPU memory object handle
`memory`	`vg_lite_pointer`	Logical memory address
`address`	`vg_lite_uint32_t`	GPU memory address
`bytes`	`vg_lite_uint32_t`	Size of memory
`property`	`vg_lite_uint32_t`	Bit 0 is used for path upload: - 0: Disable path data uploading (always embedded into command buffer) - 1: Enable auto path data uploading

Parent topic:Vector path structures

`vg_lite_path_t` structure

This structure describes VGLite path data.

Path data is made of op codes and coordinates. The format for op codes is always VG_LITE_S8. For more details on opcodes, see Vector path opcodes for plotting paths.

Used in init functions: vg_lite_init_path, vg_lite_init_arc_path, vg_lite_upload_path, vg_lite_clear_path, vg_lite_append_path.

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

vg_lite_path_t members	Type	Description
`bounding_box[4]`	`vg_lite_float_t`	bounding box for path [0] left [1] top [2] right [3] bottom
`quality`	vg_lite_quality_t	enum for quality hint for the path, anti-aliasing level
`format`	vg_lite_format_t	enum for coordinate format
`uploaded`	vg_lite_hw_memory_t	struct with path data that has been uploaded into GPU addressable memory
`path_length`	`vg_lite_uint32_t`	number of bytes in the path
`path`	`vg_lite_pointer`	pointer to path data
`path_changed`	`vg_lite_int8_t`	0: not changed; 1: changed.
`pdata_internal`	`vg_lite_int8_t`	0: path data memory is allocated by application; 1: path data memory is allocated by driver.
`path_type`	vg_lite_path_type_t	The draw path type as specified in enum vg_lite_path_type_t. (added for stroke control, from March 2022)
`*stroke`	`vg_lite_stroke_t`	As defined by structure vg_lite_stroke_t (added for stroke control, from March 2022)
`stroke_path`	`vg_lite_pointer`	Pointer to the physical description of the stroke path. (added for stroke control, from March 2022)
`stroke_size`	`vg_lite_uint32_t`	Number of bytes in the stroke path data. (added for stroke control, from March 2022)
`stroke_color`	vg_lite_color_t	The stroke path fill color. (from Sept 2022)
`add_end`	`vg_lite_int8_t`	Flag that add end_path in driver (from March 2023)

Special notes for path objects:

Endianness has no impact, as it is aligned against the boundaries
Multiple contiguous opcodes should be packed by the size of the specified data format. For example, by 2 bytes for VG_LITE_S16 or by 4 bytes for VG_LITE_S32.

For example, because opcodes are 8-bit (1-byte), 16-bit (2-byte), or 32-bit (4-byte) data types:

…
<opcode1_that_needs_data>
<align_to_data_size>
<data_for_opcode1>
<opcode2_that_doesnt_need_data>
<align_to_data_size>
<opcode3_that_needs_data>
<align_to_data_size>
<data_for_opcode3>
…

Path data in the array should always be 1-, 2-, or 4-byte aligned, depending on the format:

For example, for 32-bit (4-byte) data types:

…
<opcode1_that_needs_data>
<pad to 4 bytes>
<4 byte data_for_opcode1>
<opcode2_that_doesnt_need_data>
<pad to 4 bytes>
<opcode3_that_needs_data>
<pad to 4 bytes>
<4 byte data_for_opcode3>
…

Parent topic:Vector path structures

Parent topic:Vector path control

Vector path functions

When using a small tessellation window and depending on a path’s size, a path might be uploaded to the hardware multiple times because the hardware scanline convert path with the provided tessellation window size, so VGLite path rendering performance might go down. That is why it is preferable to set the tessellation buffer size to the most common path size, for example if you only render 24-pt fonts, you can set the tessellation buffer to be 24x24.

All the RGBA color formats available in the vg_lite_buffer_format_t are supported as the destination buffer for the draw function.

`vg_lite_get_path_length` function

Description:

This function calculates the path command buffer length (in bytes).

The application is responsible for allocating a buffer according to the buffer length calculated with this function. Then, the buffer is used by the path as a command buffer. The VGLite driver does not allocate the path command buffer.

Syntax:

vg_lite_uint32_t vg_lite_get_path_length (
    vg_lite_uint8_t             *opcode,
    vg_lite_uint32_t            count,
    vg_lite_format_t            format
);

Parameters:

Parameter	Description
`*opcode`	Pointer to the opcode array to use to construct the path. (opcode from March 2023)*
`count`	The opcode count
`format`	The coordinate data format. All formats available in the vg_lite_format_t enum are valid formats for this function.

Returns:

Returns the command buffer length in bytes.

Parent topic:Vector path functions

`vg_lite_append_path` function

Description:

This function assembles the command buffer for the path. The command buffer is allocated by the application and assigned to the path. This function makes the final GPU command buffer for the path based on the input opcodes (cmd) and coordinates (data). The application is responsible for allocating a buffer large enough for the path*. (from Jan 2022, returns a vg_lite_error_t status code)*

Syntax:

vg_lite_error_t vg_lite_append_path (
    vg_lite_path_t              *path
    vg_lite_uint8_t             *opcode,
    vg_lite_pointer             data,
    vg_lite_uint32_t            seg_count
);

Parameters:

Parameter	Description
`*path`	Pointer to the vg_lite_path_t structure with the path definition.
`*opcode`	Pointer to the opcode array to use to construct the path. (opcode from March 2023)*
`data`	Pointer to the coordinate data array to use to construct the path
`seg_count`	The opcode count

Returns:

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

Parent topic:Vector path functions

vg_lite_init_path function

Description:

This function initializes a path definition with specified values. (From Dec 2019 returns vg_lite_error_t, previous was void.)

Syntax:

vg_lite_error_t vg_lite_init_path (
    vg_lite_path_t              *path,
    vg_lite_format_t            format,
    vg_lite_quality_t           quality,
    vg_lite_uint32_t            length,
    vg_lite_pointer             *data,
    vg_lite_float_t             min_x, 
    vg_lite_float_t             min_y,
    vg_lite_float_t             max_x, 
    vg_lite_float_t             max_y
);

Parameters:

Parameter	Description
`*path`	Pointer to the vg_lite_path_t structure for the path object to be initialized with the member values specified.
`format`	The coordinate data format. All formats available in the vg_lite_format_t enum are valid formats for this function.
`quality`	The quality for the path object. All formats available in the vg_lite_quality_t enum are valid formats for this function.
`length`	The length of the path data (in bytes)
`*data`	Pointer to path data
`min_x` `min_y` `max_x` `max_y`	Minimum and maximum x and y values specifying the bounding box of the path

Returns:

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

Parent topic:Vector path functions

`vg_lite_init_arc_path` function

Description:

This function initializes an arc path definition with specified values. (from February 2021)

Syntax:

vg_lite_error_t vg_lite_init_arc_path (
    vg_lite_path_t              *path,
    vg_lite_format_t            format,
    vg_lite_quality_t           quality,
    vg_lite_uint32_t            length,
    vg_lite_pointer             *data,
    vg_lite_float_t             min_x, 
    vg_lite_float_t             min_y,
    vg_lite_float_t             max_x, 
    vg_lite_float_t             max_y
);

Parameters:

Parameter	Function
`*path`	Pointer to the vg_lite_path_t structure for the path object to be initialized with the member values specified.
`format`	The coordinate data format. The vg_lite_format_t enum value should be FP32.
`quality`	The quality for the path object. All formats available in the vg_lite_quality_t enum are valid formats for this function.
`length`	The length of the path data (in bytes).
`*data`	Pointer to path data.
`min_x` `min_y` `max_x` `max_y`	Minimum and maximum x and y values specifying the bounding box of the path.

Returns:

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

Parent topic:Vector path functions

`vg_lite_upload_path` function

Description:

This function is used to upload a path to GPU memory.

In normal cases, the VGLite driver will copy any path data into a command buffer structure during runtime. This does take some time if there are many paths to be rendered. Also, in an embedded system the path data won’t change - so it makes sense to upload the path data into GPU memory in such a form that the GPU can directly access it. This function will signal the driver to allocate a buffer that will contain the path data and the required command buffer header and footer data for the GPU to access the data directly. Call vg_lite_clear_path to free this buffer after the path is used.

Syntax:

vg_lite_error_t vg_lite_upload_path (
    vg_lite_path_t              *path
);

Parameters:

Parameter	Description
`*path`	Pointer to a vg_lite_path_t structure that contains the path to be uploaded.

Returns:

VG_LITE_OUT_OF_MEMORY if not enough GPU memory is available for buffer allocation.

Parent topic:Vector path functions

`vg_lite_clear_path` function

Description:

This function will clear and reset path member values. If the path has been uploaded, it frees the GPU memory allocated when uploading the path. (From Dec 2019 returns vg_lite_error_t, previous was void.)

.

Syntax:

vg_lite_error_t vg_lite_clear_path (
    vg_lite_path_t              *path
);

Parameters:

Parameter	Description
`*path`	Pointer to the `vg_lite_path_t` path definition to be cleared.

Returns:

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

Parent topic:Vector path functions

Parent topic:Vector path control

Vector path opcodes for plotting paths

The following opcodes are path drawing commands available for vector path data.

A path operation is submitted to the GPU as [Opcode | Coordinates]. The operation code is stored as a VG_LITE_S8 while the coordinates are specified via vg_lite_format_t.

Opcode	Arguments	Description
0x00	None	VLC_OP_END. Finish tessellation. Close any open path.
0x01	None	VLC_OP_CLOSE. For VGLite driver internal use only. Application should not use this OP directly.
0x02	(x, y)
0x03	(∆x, ∆y)
0x04	(x, y)
0x05	(∆x, ∆y)
0x06	(cx, cy) (x, y)
0x07	(∆cx, ∆cy) (∆x, ∆y)
0x08	(cx-1, cy1) (cx2, cy2) (x, y)
0x09	(∆cx-1, ∆cy1) (∆cx2, ∆cy2) (∆x, ∆y)
0x0A	None	VLC_OP_BREAK. Indicates 64-bit path data (including the opcode) is a no-op.
0x0B	(x)
0x0C	(∆x)
0x0D	(y)
0x0E	(∆y)
0x0F	(x,y)
0x10	(∆x,∆y)
0x11	(cx2,cy2) (x,y)
0x12	(∆cx2,∆cy2) (∆x,∆y)
0x13	(rh,rv,rot,x,y)
0x14	(rh,rv,rot,x,y)
0x15	(rh,rv,rot,x,y)
0x16	(rh,rv,rot,x,y)
0x17	(rh,rv,rot,x,y)
0x18	(rh,rv,rot,x,y)
0x19	(rh,rv,rot,x,y)
0x1A	(rh,rv,rot,x,y)