Pixel buffer functions

This section provides an overview of the pixel buffer functions.

`vg_lite_allocate` function

Description:

This function is used to allocate a buffer before it is used in either blit or draw functions.

To allow the hardware to access some memory, such as a source image or target buffer, you must first allocate the memory. The supplied vg_lite_buffer_t structure must be initialized with the size (width and height) and format of the requested buffer. If the stride is set to zero, then this function fills it in. The only input parameter to this function is the pointer to the buffer structure. If the structure has all the information needed, then appropriate memory is allocated for the buffer.

This function calls the kernel to allocate the memory. The kernel fills in the memory handle, logical address, and hardware addresses in the vg_lite_buffer_t structure.

Alignment note:

Vivante GPUs have an alignment requirement of 64 bytes. However, to meet the alignment requirements of the Vivante display controller, the VGLite driver sets the render target buffer alignment to 128 bytes. For source image buffer alignment requirements, see the alignment notes available in Table 1.

The vg_lite_buffer_format_t value descriptions:

Syntax:

vg_lite_error_t vg_lite_allocate (
       vg_lite_buffer_t       *buffer
);

Parameters:

Name	Description
`buffer`	Pointer to the buffer that holds the size and format of the buffer being allocated. Either the memory or address field must be set to a non-zero value to map either a logical or physical address into hardware accessible memory.

Returns:

VG_LITE_SUCCESS if the contiguous buffer was allocated successfully.
VG_LITE_OUT_OF_RESOURCES if there is insufficient memory in the host OS heap for the buffer.
VG_LITE_OUT_OF_MEMORY if allocation of a contiguous buffer failed.

Parent topic:Pixel buffer functions

`vg_lite_free` function

Description:

This function is used to deallocate the buffer that was previously allocated. It frees up the memory for that buffer.

Syntax:

vg_lite_error_t vg_lite_free (
       vg_lite_buffer_t       *buffer
);

Parameters:

Name	Description
`buffer`	Pointer to a buffer structure that was filled in by calling the vg_lite_allocate() function.

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_upload_buffer` function

Description:

The function uploads the pixel data to a GPU memory buffer object. The format of the data (pixel) to be uploaded must match the format defined for the buffer object. The input data memory buffer should contain enough data to be uploaded to the GPU buffer pointed by the input parameter buffer.

Note: Vivante Vector Graphics IP only uses data[0] and stride[0] as it does not support planar YUV formats..

Syntax:

vg_lite_error_t vg_lite_upload_buffer (
    vg_lite_buffer_t           *buffer,
    vg_lite_uint8_t            *data[3],
    vg_lite_uint32_t           stride[3]
);

Parameters:

Name	Description
`buffer`	Pointer to a buffer structure that was filled in by calling the vg_lite_allocate() function
`data[3]`	Pointer to pixel data. For the YUV format, there may be up to 3 pointers.
`stride[3]`	Stride for the pixel data

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_map` function

Description:

This function is used to map the memory appropriately for a particular buffer. For some operating systems, it is used to get proper translation to the physical or logical address of the buffer needed by the GPU.

To use a frame buffer directly as a target buffer:

Wrap a vg_lite_buffer_t structure around the buffer
Call the kernel to map the supplied logical or physical address into hardware accessible memory

For example, if you know the logical address of the frame buffer, set the memory field of the vg_lite_buffer_t structure with that address and call this function. If you know the physical address, set the memory field to NULL and program the address field with the physical address.

Syntax:

vg_lite_error_t  vg_lite_map  (
    vg_lite_buffer_t           *buffer,
    vg_lite_map_flag_t         flag,
    int32_t                    fd
    );

Parameters:

Name	Description
`*buffer`	Pointer to a buffer structure that was filled in by calling the vg_lite_allocate() function
`flag`	Enumerate the `vg_lite_map_flag_t` value that specifies whether the mapping is for user memory or DMA buffer. (from March 2023)
`fd`	File descriptor for `dma_buf` if the flag is `VG_LITE_MAP_DMABUF`. Otherwise, this parameter is ignored. (from March 2023)

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_unmap` function

Description:

This function unmaps the buffer and frees any memory resources allocated by a previous call to the vg_lite_map() function.

Syntax:

vg_lite_error_t vg_lite_unmap (
       vg_lite_buffer_t        *buffer
);

Parameters:

Name	Description
`buffer`	Pointer to a buffer structure that was filled in by calling the vg_lite_map() function

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_flush_mapped_buffer` function

Description:

This function flushes the CPU cache for the mapped buffer to make sure the buffer contents are written to GPU memory.

Syntax:

vg_lite_error_t vg_lite_flush_mapped_buffer (
    vg_lite_buffer_t           *buffer
);

Parameters:

Name	Description
`*buffer`	Pointer to a buffer structure that was filled in by calling the vg_lite_map() function

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_set_CLUT` function

Description:

This function sets the Color Lookup Table (CLUT) in the context state for index color image. Once the CLUT is set (Not NULL), the image pixel color for index format image rendering is obtained from the Color Lookup Table (CLUT) according to the pixel’s color index value.

Note: Available only for IP with Indexed color support..

Syntax:

vg_lite_error_t vg_lite_set_CLUT (
  vg_lite_uint32_t                    count,
  vg_lite_uint32_t                    *colors
);

Parameters:

Name	Description
`count`	This is the count of the colors in the color look-up table: - For INDEX_1, there can be up to 2 colors in the table - For INDEX_2, there can be up to 4 colors in the table - For INDEX_4, there can be up to 16 colors in the table - For INDEX_8, there can be up to 256 colors in the table
`*colors`	The Color Lookup Table (CLUT) pointed by “colors” will be stored in the context and programmed to the command buffer when needed. The CLUT will not take effect until the command buffer is submitted to HW. The color is in ARGB format with A located in the upper bits. Note: The VGLite driver does not validate the CLUT contents from the application.

Returns:

VG_LITE_SUCCESS as no checking is done.

Parent topic:Pixel buffer functions

`vg_lite_enable_dither` function

Description:

This function is used to enable the dither function. Dither is turned off by default. The application can use the VGLite API vg_lite_query_feature (gcFEATURE_BIT_VG_DITHER) to determine HW support for dither.

Syntax:

vg_lite_error_t vg_lite_enable_dither (
);

Parameters: None

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_disable_dither` function

Description:

This function is used to disable the dither function. Dither is turned off by default.

Syntax:

vg_lite_error_t vg_lite_disable_dither (
);

Parameters: None

Returns:

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

Parent topic:Pixel buffer functions

`vg_lite_set_gamma` function

Description:

This function sets a gamma value.

Application can use the VGLite API vg_lite_query_feature(gcFEATURE_BIT_VG_GAMMA) to determine HW support for gamma.

Syntax:

vg_lite_error_t vg_lite_set_gamma (
    vg_lite_gamma_conversion_t    gamma_value
);

Parameters:

Name	Description
`gamma_value`	Sets a gamma value. See enum vg_lite_gamma_conversion_t.

Returns:

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

Parent topic:Pixel buffer functions

Parent topic:Pixel buffers

Pixel buffer functions

vg_lite_allocate function

vg_lite_free function

vg_lite_upload_buffer function

vg_lite_map function

vg_lite_unmap function

vg_lite_flush_mapped_buffer function

vg_lite_set_CLUT function

vg_lite_enable_dither function

vg_lite_disable_dither function

vg_lite_set_gamma function

`vg_lite_allocate` function

`vg_lite_free` function

`vg_lite_upload_buffer` function

`vg_lite_map` function

`vg_lite_unmap` function

`vg_lite_flush_mapped_buffer` function

`vg_lite_set_CLUT` function

`vg_lite_enable_dither` function

`vg_lite_disable_dither` function

`vg_lite_set_gamma` function