API control

Before calling any VGLite API function, the application must initialize the VGLite implicit (global) context by calling vg_lite_init(), which will fill in a features table, reset the fast-clear buffer, reset the compositing target buffer and allocate the command and tessellation buffers.

The VGLite driver only supports one current context and one thread to issue commands to the Vivante Vector Graphics hardware. The VGLite driver does not support multiple concurrent contexts running simultaneously in multiple threads/processes, as the VGLite kernel driver does not support context switching. A VGLite application can only use a single context at any time to issue commands to the Vivante Vector Graphics hardware. If a VGLite application must switch contexts, vg_lite_close() must be called to close the current context in the current thread, then vg_lite_init() can be called to initialize a new context either in the current thread or from another thread/process.

Context initialization and control functions

This section provides an overview of the context initialization and control functions.

vg_lite_init

Description:

This function initializes the memory and data structures needed for VGLite draw/blit functions, by allocating memory for the command buffer and a tessellation buffer of the specified size.

GC555 has a newly designed hardware tessellation module that requires less memory for the tessellation buffer than GC355 and GNanoLite-V. Specifically, the GC555 required tessellation buffer size is “buffer_height * 128 byte”. vg_lite_init API can simply be called with the render buffer “width” and “height” as the input parameters for GC555. This results in the best path to tessellation performance.

GC355 and GCNanoLiteV hardware tessellation module requires a tessellation buffer with size “buffer_height * buffer_width * 8 byte”. If system memory is limited, the application can define a smaller tessellation window based on the amount of memory available. GPU hardware can process the entire render buffer path tessellation in multiple passes with the tessellation window sliding across the render buffer. The multi-pass path tessellation with the smaller tessellation window has a certain performance overhead.

The minimum tessellation window that can be used is 16x16. If tess_height or tess_width is less than 0 in vg_lite_init API, then no path tessellation buffer is created and path drawing APIs do not work, only blit APIs can be used after vg_lite_init.

If this would be the first context that accesses the hardware, the hardware is turned on and initialized. If a new context must be initialized, vg_lite_close must be called to close the current context. Otherwise, vg_lite_init will return an error.

Syntax:

vg_lite_error_t vg_lite_init (
    vg_lite_int32_t             tess_width,
    vg_lite_int32_t             tess_height

);

Parameters:

Name	Description
tess_width	Width of tessellation window. Maximum cannot be greater than render buffer width. If less than or equal to 0, then no tessellation buffer is created, in which case only blit APIs can be used afterward.
tess_height	Height of tessellation window. Maximum cannot be greater than render buffer height. If less than or equal to 0, then no tessellation buffer is created, in which case blit APIs can be used afterward.

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_close

Description:

This function deallocates all the resources and free up all the memory that was initialized earlier by the vg_lite_init function. It will also turn OFF the hardware automatically if this was the only active context.

Syntax:

vg_lite_error_t vg_lite_close (
    void
);

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_flush

Description:

This function explicitly submits the command buffer to the GPU without waiting for it to complete. (From Dec 2019, return type is vg_lite_error_t, previously was void.)

Syntax:

vg_lite_error_t vg_lite_flush (
    void
);

Returns:

Returns VG_LITE_SUCCESS if the flush is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_finish

Description:

This function explicitly submits the command buffer to the GPU and waits for it to complete.

Syntax:

vg_lite_error_t vg_lite_finish (
    void
);

Returns:

Returns VG_LITE_SUCCESS if the function is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_frame_delimiter

Description:

This function sets a flag for GPU to signal the completion of current frame. A vg_lite_finish is called by default within this API. The enum VG_LITE_FRAME_END_FLAG is the only value that can be set by flag parameter.

Syntax:

vg_lite_error_t vg_lite_frame_delimiter (
    vg_lite_frame_flag_t flag
);

Returns:

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

Parent topic:Context initialization and control functions

vg_lite_set_command_buffer_size

Description:

This function is optional. If used, call it before vg_lite_init if you want to change the command buffer size. (available from March 2020)

Syntax:

vg_lite_error_t vg_lite_set_command_buffer_size (
    vg_lite_uint32_t            size
);

Parameters:

Name	Description
size	Size of the VGLite Command buffer. Default is 64K.

Returns:

Returns VG_LITE_SUCCESS if the flush is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_set_command_buffer

Description:

This function sets a user-defined external memory buffer (physical, 64-byte aligned) as the VGLite command buffer. By default, the VGLite driver allocates a static command buffer internally. Thus, it is not necessary for an application to allocate and set the command buffer. This function is only used for devices where an application needs to allocate the command buffer dynamically. (from December 2021)

Syntax:

vg_lite_error_t vg_lite_set_command_buffer (
    vg_lite_uint32_t            physical,
    vg_lite_uint32_t            size
);

Parameters:

Name	Description
physical	The physical address of a memory buffer. The address must be 64-byte aligned.
size	The size of memory buffer. The size must be 128-byte aligned.

Returns:

Returns VG_LITE_SUCCESS if the command buffer set is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_set_tess_buffer

Description:

This function specifies a memory buffer from an application as the VGLite driver’s tessellation buffer. By default, the VGLite driver allocates a static tessellation buffer internally. Thus, it is not necessary for an application to allocate and set the tessellation buffer. This function is only used for devices where the application needs to allocate the tessellation buffer dynamically. (from December 2021)

Syntax:

vg_lite_error_t vg_lite_set_tess_buffer (
    vg_lite_uint32_t            physical,
    vg_lite_uint32_t            size
);

Parameters:

Name	Description
physical	The physical address of a tessellation buffer. The address must be 64-byte aligned.
size	The size of tessellation buffer. tessellation buffer size = target buffer’s height * 128B.

Returns:

Returns VG_LITE_SUCCESS if the tessellation buffer set is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

vg_lite_set_memory_pool

Description:

This function sets the specific memory pool from which certain type of buffers, VG_LITE_COMMAND_BUFFER, VG_LITE_TESSELLATION_BUFFER, or VG_LITE_RENDER_BUFFER, should be allocated. By default, all types of buffers are allocated from VG_LITE_MEMORY_POOL_1. This API must be called before vg_lite_init() for setting VG_LITE_COMMAND_BUFFER or VG_LITE_TESSELLATION_BUFFER memory pools. This API can be called anytime for VG_LITE_RENDER_BUFFER to affect the following vg_lite_allocate() calls.(from December 2023)

Syntax:

vg_lite_error_t vg_lite_set_memory_pool (
    vg_lite_buffer_type_t        type,
    vg_lite_memory_pool_t        pool
);

Parameters:

Name	Description
type	The buffer type (VG_LITE_COMMAND_BUFFER, VG_LITE_TESSELLATION_BUFFER, or VG_LITE_RENDER_BUFFER) to be allocated from memory pool.
pool	The memory pool (VG_LITE_MEMORY_POOL_1, VG_LITE_MEMORY_POOL_2) from which the buffer type should be allocated.

Returns:

Returns VG_LITE_SUCCESS if the memory pool set is successful. See vg_lite_error_t enumeration for other return codes.

Parent topic:Context initialization and control functions

Parent topic:API control