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 |
---|---|
|
High quality: 16x coverage sample anti-aliasing |
|
Upper quality: 8x coverage sample anti-aliasing. Use vg_lite_query_feature to determine availability of 8x CSAA (feature enum value |
|
Medium quality: 4x coverage sample anti-aliasing |
|
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 |
---|---|---|
|
|
GPU memory object handle |
|
|
Logical memory address |
|
|
GPU memory address |
|
|
Size of memory |
|
|
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 for path [0] left [1] top [2] right [3] bottom |
|
enum for quality hint for the path, anti-aliasing level |
|
|
enum for coordinate format |
|
|
struct with path data that has been uploaded into GPU addressable memory |
|
|
|
number of bytes in the path |
|
|
pointer to path data |
|
|
0: not changed; 1: changed. |
|
|
0: path data memory is allocated by application; 1: path data memory is allocated by driver. |
|
The draw path type as specified in enum vg_lite_path_type_t. (added for stroke control, from March 2022) |
|
|
|
As defined by structure vg_lite_stroke_t (added for stroke control, from March 2022) |
|
|
Pointer to the physical description of the stroke path. (added for stroke control, from March 2022) |
|
|
Number of bytes in the stroke path data. (added for stroke control, from March 2022) |
|
The stroke path fill color. (from Sept 2022) |
|
|
|
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 |
---|---|
|
Pointer to the opcode array to use to construct the path. (*opcode from March 2023) |
|
The opcode count |
|
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 |
---|---|
|
Pointer to the vg_lite_path_t structure with the path definition. |
|
Pointer to the opcode array to use to construct the path. (*opcode from March 2023) |
|
Pointer to the coordinate data array to use to construct the path |
|
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 |
---|---|
|
Pointer to the vg_lite_path_t structure for the path object to be initialized with the member values specified. |
|
The coordinate data format. All formats available in the vg_lite_format_t enum are valid formats for this function. |
|
The quality for the path object. All formats available in the vg_lite_quality_t enum are valid formats for this function. |
|
The length of the path data (in bytes) |
|
Pointer to path data |
|
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 |
---|---|
|
Pointer to the vg_lite_path_t structure for the path object to be initialized with the member values specified. |
|
The coordinate data format. The vg_lite_format_t enum value should be FP32. |
|
The quality for the path object. All formats available in the vg_lite_quality_t enum are valid formats for this function. |
|
The length of the path data (in bytes). |
|
Pointer to path data. |
|
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 |
---|---|
|
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 |
---|---|
|
Pointer to the |
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) |
Parent topic:Vector path control