Pixel buffers

This chapter provides an overview of the pixel buffer alignment, cache, internal representation, enumerations, structures, and functions.

Pixel buffer alignment

The VGLite hardware requires the pixel buffer start address and stride to be properly byte-aligned to work correctly. The start address and stride alignment requirement for a pixel buffer depends on the specific pixel format, and gcFEATURE_VG_16PIXELS_ALIGNED value (0/1) in vg_lite_options.h file.

Parent topic:Pixel buffers

Pixel cache

The Vivante Imaging Engine (IM) includes two fully associative caches. Each cache has 8 lines. Each line has 64 bytes. In this case, one cache line can hold either a 4x4-pixel tile or a 16x1-pixel row.

Parent topic:Pixel buffers

Internal representation

For non-32-bit color formats, each pixel is extended to 32 bits as follows:

If the source and destination formats have the same color format, but differ in the number of bits per color channel, the source channel is multiplied by (2^d- 1)/(2^s– 1) and is rounded to the nearest integer, where:

• d is the number of bits in the destination channel

• s is the number of bits in the source channel

Example: a b11111 5-bit source channel gets converted to an 8-bit destination b11111000.

The YUV formats are internally converted to RGB. The pixel selection is unified for all formats by using the LSB of the coordinate.

Parent topic:Pixel buffers

Pixel buffer enumerations

This section provides an overview of the pixel buffer enumerations.

vg_lite_buffer_format_t enumeration

This enumeration specifies the color format to use for a buffer. This applies to both image and Render Target. Formats include supported swizzles for RGB. For YUV swizzles, use the related values and parameters in vg_lite_swizzle_t.

The application shall use the vg_lite_query_feature API to determine support for some hardware-specific formats. For example, related vg_lite_feature_t enum values include gcFEATURE_BIT_VG_RGBA2_FORMAT and gcFEATURE_BIT_VG_IM_INDEX_FORMAT.

(Alignment columns refined March and Sept 2023)

Used in structure: vg_lite_buffer_t.

See also vg_lite_blit, vg_lite_clear, vg_lite_draw.

Attention: OpenVG VGImageFormat Note: The bits for each color channel are stored within a machine word from MSB to LSB in the order indicated by the pixel format name. This is the opposite of the original VG_LITE_* formats that are ordered from LSB to MSB. The formats with the same organization are listed in the same row as their VG_Lite counterparts.

Attention: Original VGLite API Image Format Note: The bits for each color channel are stored within a machine word from LSB to MSB in the order indicated by the pixel format name. This is the opposite of the OPENVG VG_* formats that are ordered from MSB to LSB.

The following codes, as also used in OpenVG 1.1 Specification Table 11, are used for format description:

• A - Alpha channel

• B - Blue color channel

• G - Green color channel

• R - Red color channel

• X - Uninterpreted padding byte or bit

• L - Grayscale

• BW - 1-bit black and white

• l - Linear color space

• s - Non-linear (sRGB) color space

• PRE - Alpha values are premultiplied

vg_lite_buffer_format_t String Value	Description	Supported as source	Supported as destination	Start address/ Stride alignment: bytes
VG_LITE_ABGR8888 VG_sRGBA_8888 VG_sRGBA_8888_PRE VG_lRGBA_8888 VG_lRGBA_8888_PRE		Yes	Yes	Start 4B / Stride 64B
VG_LITE_ARGB8888 VG_sBGRA_8888 VG_sBGRA_8888_PRE VG_lBGRA_8888 VG_lBGRA_8888_PRE		Yes	Yes	Start 4B / Stride 64B
VG_LITE_BGRA8888 VG_sARGB_8888 VG_sARGB_8888_PRE VG_lARGB_8888 VG_lARGB_8888_PRE		Yes	Yes	Start 4B / Stride 64B
VG_LITE_RGBA8888 VG_sABGR_8888 VG_sABGR_8888_PRE VG_lABGR_8888 VG_lABGR_8888_PRE		Yes	Yes	Start 4B / Stride 64B
VG_LITE_BGRX8888 VG_sXRGB_8888 VG_lXRGB_8888		Yes	Yes	Start 4B / Stride 64B
VG_LITE_RGBX8888 VG_sXBGR_8888 VG_lXBGR_8888		Yes	Yes	Start 4B / Stride 64B
VG_LITE_XBGR8888 RGBX VG_sRGBX_8888 VG_lRGBX_8888		Yes	Yes	Start 4B / Stride 64B
VG_LITE_XRGB8888 VG_sBGRX_8888 VG_lBGRX_8888		Yes	Yes	Start 4B / Stride 64B
VG_LITE_ABGR1555 VG_sRGBA_5551		Yes	Yes	Start 4B / Stride 32B
VG_LITE_ARGB1555 VG_sBGRA_5551		Yes	Yes	Start 4B / Stride 32B
VG_LITE_BGRA5551 VG_sARGB_1555		Yes	Yes	Start 4B / Stride 32B
VG_LITE_RGBA5551 VG_sABGR_1555		Yes	Yes	Start 4B / Stride 32B
VG_LITE_BGR565 VG_sRGB_565		Yes	Yes	Start 4B / Stride 32B
VG_LITE_RGB565 VG_sBGR_565		Yes	Yes	Start 4B / Stride 32B
VG_LITE_ABGR4444 VG_sRGBA_4444		Yes	Yes	Start 4B / Stride 32B
VG_LITE_ARGB4444 VG_sBGRA_4444		Yes	Yes	Start 4B / Stride 32B
VG_LITE_BGRA4444 VG_sARGB_4444		Yes	Yes	Start 4B / Stride 32B
VG_LITE_RGBA4444 VG_sABGR_4444		Yes	Yes	Start 4B / Stride 32B
VG_LITE_YUY2 VG_LITE_YUYV		Yes	No	Start 4B / Stride 32B
VG_LITE_A4 VG_A_4		Yes	No	Start 4B / Stride 8B
VG_LITE_A8 VG_A_8		Yes	Yes	Start 4B / Stride 16B
VG_LITE_L8 VG_sL_8 VG_lL_8		Yes	Yes	Start 4B / Stride 16B

Hardware-dependent formats for vg_lite_buffer_format_t	Description	Supported as source	Supported as destination	Alignment (bytes)
VG_LITE_ABGR2222		Yes	Yes	Start 4B / Stride 16B
VG_LITE_ARGB2222		Yes	Yes	Start 4B / Stride 16B
VG_LITE_BGRA2222		Yes	Yes	Start 4B / Stride 16B
VG_LITE_RGBA2222		Yes	No	8B
VG_LITE_INDEX_1	1-bit index format	Yes	No	8B
VG_LITE_INDEX_2	2-bit index format	Yes	No	both 8B
VG_LITE_INDEX_4	4-bit index format	Yes	No	both 8B
VG_LITE_INDEX_8	8-bit index format	Yes	No	both 16B
VG_LITE_NV12_TILED		Yes	No	Y: both 16 Bytes UV: both 8 Bytes
VG_LITE_ANV12_TILED		Yes	No	A, Y: both 16 Bytes UV: both 8 Bytes
VG_LITE_AYUY2_TILED		Yes	No	both 32B
VG_LITE_RGB888		Yes	Yes	Start 4B / Stride 32B
VG_LITE_BGR888			Yes	Yes
VG_LITE_ARGB8565			Yes	Yes
VG_LITE_BGRA5658		Yes	Yes	Start 4B / Stride 32B
VG_LITE_ABGR8565		Yes	Yes	Start 4B / Stride 32B
VG_LITE_RGBA5658		Yes	Yes	Start 4B / Stride 32B

Parent topic:Pixel buffer enumerations

Image buffer alignment requirement

The image (or source) buffer alignment requirement depends on the specific pixel format, and some gcFEATURE_*_ALIGNED defines in the vg_lite_options.h file.

Image format	Bits per pixel	Source tile mode	Start address alignment requirement in bytes	Stride alignment requirement in bytes	Buffer height alignment requirement	Supported for destination
VG_LITE_INDEX1	1	linear	8B	2B	1
VG_LITE_INDEX1	1	tile	8B	1B	4
VG_LITE_INDEX2	2	linear	8B	4B	1
VG_LITE_INDEX2	2	tile	8B	1B	4
VG_LITE_INDEX4	4	linear	8B	8B	1
VG_LITE_INDEX4	4	tile	8B	2B	4
VG_LITE_INDEX8	8	linear	16B	16B	1
VG_LITE_INDEX8	8	tile	16B	4B	4
VG_LITE_A4	4	linear	8B	8B	1
VG_LITE_A4	4	tile	8B	2B	4
VG_LITE_A8	8	linear	16B	16B	1	Yes
VG_LITE_A8	8	tile	16B	4B	4	Yes
VG_LITE_L8	8	linear	16B	16B	1	Yes
VG_LITE_L8	8	tile	16B	4B	4	Yes
VG_LITE_ARGB2222	8	linear	16B	16B	1	Yes
VG_LITE_ARGB2222	8	tile	16B	4B	4	Yes
VG_LITE_RGB565	16	linear	32B	32B	1	Yes
VG_LITE_RGB565	16	tile	32B	8B	4	Yes
VG_LITE_ARGB1555	16	linear	32B	32B	1	Yes
VG_LITE_ARGB1555	16	tile	32B	8B	4	Yes
VG_LITE_ARGB4444	16	linear	32B	32B	1	Yes
VG_LITE_ARGB4444	16	tile	32B	8B	4	Yes
VG_LITE_ARGB8888	32	linear	64B	64B	1	Yes
VG_LITE_ARGB8888	32	tile	64B	16B	4	Yes
VG_LITE_XRGB8888	32	linear	64B	64B	1	Yes
VG_LITE_XRGB8888	32	tile	64B	16B	4	Yes
VG_LITE_ARGB8565	24	linear	64B	48B*	1	Yes
VG_LITE_ARGB8565	24	tile	64B	12B*	4	Yes
VG_LITE_RGB888	24	linear	64B	48B*	1	Yes
VG_LITE_RGB888	24	tile	64B	12B*	4	Yes
VG_LITE_YUY2/UYVY	16	linear	32B	32B	1
VG_LITE_YUY2/UYVY	16	tile	32B	8B	4
VG_LITE_NV12	12	linear	Y: 32B UV: 32B	Y: 32B UV: 32B	1
VG_LITE_YV12	12	linear	Y: 32B U: 16B V: 16B	Y: 32B U: 16B V: 16B	1
VG_LITE_NV16	16	linear	Y: 32B UV: 32B	Y: 32B UV: 32B	1
VG_LITE_YV16	16	linear	Y: 32B U: 16B V: 16B	Y: 32B U: 16B V: 16B	1
VG_LITE_YV24	24	linear	Y: 32B U: 32B V: 32B	Y: 32B U: 32B V: 32B	1
VG_LITE_ETC2	8	tile	16B	4B	4

Note:

1. The values in the table reflect the alignment requirements of the data in memory. The stride of ARGB8888 / ARGB8565 is seen as 4Byte per pixel when configuring the hardware.

2. For tile mode, the stride is still the byte size of a row of pixels in the buffer instead of 4 rows.

3. When DECNano function is enabled for the buffer, the total buffer size need align to 64Byte*compression rate for ARGB8888 or XRGB8888 format, align to 48Byte*compress rate for RGB888 format.

Additional Alignment Requirement

1. Buffer starting address must be 16 pixel-byte-size aligned, that is 8 bit-per-pixel format buffer must be 16 bytes aligned; 16 bit-per-pixel format buffer must be 32 bytes aligned; 24 and 32 bit-per-pixel format buffer must be 64 bytes aligned.

2. For linear mode buffer, the buffer stride must be 16 pixel-byte-size aligned.

3. For tile mode buffer, buffer width and height must be 4 pixel aligned so buffer width and height end at tile boundary.

Parent topic:Pixel buffer enumerations

Destination buffer alignment requirement

The destination (or render target) buffer alignment requirement depends on the specific pixel format, and some gcFEATURE_*_ALIGNED defines in the vg_lite_options.h file.

Target format	Bits per pixel	Target tile mode	VG tile mode	Start address alignment requirement in bytes	Stride alignment requirement in bytes	Buffer height alignment requirement
VG_LITE_A8	8	linear	linear	4B	1B	1
VG_LITE_A8	8	linear	tile	64B	64B	4
VG_LITE_A8	8	tile	linear	64B	64B	4
VG_LITE_A8	8	tile	tile	64B	16B	4
VG_LITE_L8	8	linear	linear	4B	1B	1
VG_LITE_L8	8	linear	tile	64B	64B	4
VG_LITE_L8	8	tile	linear	64B	64B	4
VG_LITE_L8	8	tile	tile	64B	16B	4
VG_LITE_ARGB2222	8	linear	linear	4B	1B	1
VG_LITE_ARGB2222	8	linear	tile	64B	64B	4
VG_LITE_ARGB2222	8	tile	linear	64B	64B	4
VG_LITE_ARGB2222	8	tile	tile	64B	16B	4
VG_LITE_RGB565	16	linear	linear	4B	2B	1
VG_LITE_RGB565	16	linear	tile	64B	64B	4
VG_LITE_RGB565	16	tile	linear	64B	64B	4
VG_LITE_RGB565	16	tile	tile	64B	16B	4
VG_LITE_ARGB1555	16	linear	linear	4B	2B	1
VG_LITE_ARGB1555	16	linear	tile	64B	64B	4
VG_LITE_ARGB1555	16	tile	linear	64B	64B	4
VG_LITE_ARGB1555	16	tile	tile	64B	16B	4
VG_LITE_ARGB4444	16	linear	linear	4B	2B	1
VG_LITE_ARGB4444	16	linear	tile	64B	64B	4
VG_LITE_ARGB4444	16	tile	linear	64B	64B	4
VG_LITE_ARGB4444	16	tile	tile	64B	16B	4
VG_LITE_ARGB8888	32	linear	linear	4B	4B	1
VG_LITE_ARGB8888	32	linear	tile	64B	64B	4
VG_LITE_ARGB8888	32	tile	linear	64B	64B	4
VG_LITE_ARGB8888	32	tile	tile	64B	16B	4
VG_LITE_XRGB8888	32	linear	linear	4B	4B	1
VG_LITE_XRGB8888	32	linear	tile	64B	64B	4
VG_LITE_XRGB8888	32	tile	linear	64B	64B	4
VG_LITE_XRGB8888	32	tile	tile	64B	16B	4
VG_LITE_ARGB8565	24	linear	linear	64B	3B*	1
VG_LITE_ARGB8565	24	linear	tile	64B	48B*	4
VG_LITE_ARGB8565	24	tile	linear	64B	48B*	4
VG_LITE_ARGB8565	24	tile	tile	64B	12B*	4
VG_LITE_RGB888	24	linear	linear	64B	3B*	1
VG_LITE_RGB888	24	linear	tile	64B	48B*	4
VG_LITE_RGB888	24	tile	linear	64B	48B*	4
VG_LITE_RGB888	24	tile	tile	64B	12B*	4

Note:

1. The values in the table reflect the alignment requirements of pixel data in memory. The stride of ARGB8888/ARGB8565 is seen as 4 Bytes per pixel when configuring the hardware.

2. For tile mode, the buffer stride is still the byte size of a row of pixels instead of 4 rows of pixels.

3. For PE clear function, the clear size must align to 48 Bytes for the RGB888 or ARGB8565 format.

4. For PE clear function with DECNano enabled, the clear size must align to 48 Bytes for RGB888, align to 64 Bytes for ARGB8888 or XRGB8888.

5. If the DECNano function is enabled for the buffer, the target buffer start address needs to align to 64 Bytes.

6. If the DECNano function is enabled for the buffer, the total buffer size needs to align to a 64-byte compression rate for ARGB8888 or XRGB8888 format and align to a 48 Byte*compression rate for RGB888 format.

Additional Alignment Requirement

1. Buffer starting address must be at least 4-byte aligned. Buffer stride must be at least one pixel size aligned.

2. Buffer starting address must be 64-byte aligned for 24 bit-per-pixel format, or tile mode, or DECNano enabled.

3. Buffer height must be 4-pixel aligned for tile mode buffer.

4. For tile mode buffer, the buffer stride must be 16-byte aligned for non-24bit-per-pixel formats. So, 8 bits-per-pixel format buffer width must be 16-pixel aligned; 16 bits-per-pixel format buffer width must be 8-pixel aligned; 32 bit-per-pixel format buffer width must be 4 pixel aligned.

5. For tile mode buffer, the buffer stride must be 12-byte aligned for 24 bits-per-pixel formats, that is, the buffer width must be 4-pixel aligned.

6. For PE clear function, the clear size must align to 48 Bytes for 24-bits-per-pixel formats.

7. For PE clear function with DECNano enabled, the clear size must align to 48 Bytes for 24 bits-per-pixel formats and align to 64 Bytes for 32 bits-per-pixel formats.

8. If source buffer tile mode is different from destination buffer tile mode, buffer starting address must be 64 Byte aligned, buffer stride must be 64 Byte aligned for non-24 bits-per-pixel formats, buffer stride must be 48-Byte aligned for 24 bits-per-pixel formats.

VGLite hardware requires the raster image width to be a multiple of 16 pixels for linear gradient and radial gradient operations. This requirement applies to all image formats. Therefore, the user must pad an arbitrary image width to a multiple of 16 pixels for VGLite linear gradient and radial gradient APIs.

Parent topic:Pixel buffer enumerations

vg_lite_buffer_layout_t enumeration

Specifies the buffer data layout in memory.

Used in structure: vg_lite_buffer.

vg_lite_buffer_layout_t String Value	Description
VG_LITE_LINEAR	Linear (scanline) layout.
VG_LITE_TILED	Data is organized in 4x4 pixel tiles. Note: for this layout, the buffer start address and stride must be 64-byte aligned

Parent topic:Pixel buffer enumerations

vg_lite_compress_mode_t enumeration

Specifies the DECNano comprssion mode. (from March 2023)

Used in structure: vg_lite_buffer_t.

vg_lite_compress_mode_t string value	Description
VG_LITE_DEC_DISABLE	Disable compression.
VG_LITE_DEC_NON_SAMPLE	compression ratio is 1.6 for ARGB8888, 2.0 for XRGB8888
VG_LITE_DEC_HSAMPLE	compression ratio is 2.0 for ARGB8888, 2.6 for XRGB8888
VG_LITE_DEC_HV_SAMPLE	compression ratio is 2.6 for ARGB8888, 4.0 for XRGB8888

Parent topic:Pixel buffer enumerations

vg_lite_gamma_conversion_t enumeration

Specifies the gamma conversion mode (from Sept 2022)

Used in function: vg_lite_set_gamma.

vg_lite_gamma_conversion_t string value	Description
VG_LITE_GAMMA_NO_CONVERSION	Leave the color as it is.
VG_LITE_GAMMA_LINEAR	Convert from sRGB to linear.
VG_LITE_GAMMA_NON_LINEAR	Convert from linear to sRGB space.

Parent topic:Pixel buffer enumerations

vg_lite_index_endian_t enumeration

Specifies the endian order parsing mode for index formats (from March 2023).

Used in structure: vg_lite_buffer_t.

vg_lite_index_endian_t string value	Description
VG_LITE_INDEX_ENDIAN_LITTLE_ENDIAN	Parse the index pixel from low to high, when using index1, the parsing order is bit0~bit7. when using index2, the parsing order is bit0:1,bit2:3,bit4:5.bit6:7. when using index4, the parsing order is bit0:3,bit4:7.
VG_LITE_INDEX_ENDIAN_BIG_ENDIAN	Parse the index pixel from low to high, when using index1, the parsing order is bit7~bit0. when using index2, the parsing order is bit7:6,bit5:4,bit3:2.bit1:0. when using index4, the parsing order is bit4:7,bit0:3.

Parent topic:Pixel buffer enumerations

vg_lite_image_mode_t enumeration

Specifies how an image is rendered onto a buffer (prior to Sept 2022 name was vg_lite_buffer_image_mode_t).

Used in structure: vg_lite_buffer_t.

vg_lite_image_mode_t string value	Description
VG_LITE_ZERO
VG_LITE_NORMAL_IMAGE_MODE	Image drawn with blending mode
VG_LITE_MULTIPLY_IMAGE_MODE	Image is multiplied with paint color
VG_LITE_STENCIL_MODE
VG_LITE_NONE_IMAGE_MODE	Image input is ignored.
VG_LITE_RECOLOR_MODE

Parent topic:Pixel buffer enumerations

vg_lite_map_flag_t enumeration

Specifies whether mapping is for user memory or the DMA buffer (from March 2023).

Used in function: vg_lite_map.

vg_lite_map_flag_t string value	Description
VG_LITE_MAP_USER_MEMORY	Mapping is for user memory.
VG_LITE_MAP_DMABUF	Mapping is for the DMA buffer.

Parent topic:Pixel buffer enumerations

vg_lite_paint_type_t enumeration

Specifies paint type (from May 2023).

Used in structure: vg_lite_buffer_t.

vg_lite_paint_type_t string value	Description
VG_LITE_PAINT_ZERO
VG_LITE_PAINT_COLOR	Color
VG_LITE_PAINT_LINEAR_GRADIENT	Linear Gradient
VG_LITE_PAINT_RADIAL_GRADIENT	Radial Gradient
VG_LITE_PAINT_PATTERN	Pattern

Parent topic:Pixel buffer enumerations

vg_lite_transparency_t enumeration

Specifies the transparency mode for a buffer (prior to Sept 2022 name was vg_lite_buffer_transparency_mode_t).

Used in structure:vg_lite_buffer.

vg_lite_transparency_t string value	Description
VG_LITE_IMAGE_OPAQUE	Opaque image: all image pixels are copied to the VG PE for rasterization
VG_LITE_IMAGE_TRANSPARENT	Transparent image: only the non-transparent image pixels are copied to the VG PE. Note: This mode is only valid when IMAGE_MODE (vg_lite_image_mode_t) is either VG_LITE_NORMAL_IMAGE_MODE or VG_LITE_MULTIPLY_IMAGE_MODE.

Parent topic:Pixel buffer enumerations

vg_lite_swizzle_t enumeration

This enumeration specifies the swizzle for the UV components of YUV data.

Used in structure: vg_lite_yuvinfo.

vg_lite_swizzle_t string value	Description
VG_LITE_SWIZZLE_UV	U in lower bits, V in upper bits
VG_LITE_SWIZZLE_VU	V in lower bits, U in upper bits

Parent topic:Pixel buffer enumerations

vg_lite_yuv2rgb_t enumeration

This enumeration specifies the standard for conversion of YUV data to RGB data.

Used in structure: vg_lite_yuvinfo.

vg_lite_yuv2rgb_t string value	Description
VG_LITE_YUV601	YUV Converting with ITC.BT-601 standard
VG_LITE_YUV709	YUV Converting with ITC.BT-709 standard

Parent topic:Pixel buffer enumerations

Parent topic:Pixel buffers

Pixel buffer structures

This section provides an overview on the pixel buffer structures.

vg_lite_buffer_t structure

This structure defines the buffer layout for a VGLite image or memory data.

Used in structures: vg_lite_linear_gradient_t, vg_lite_radial_gradient_t.

Used in init functions: vg_lite_allocate, vg_lite_free, vg_lite_upload_buffer, vg_lite_map, vg_lite_unmap.

Used in blit functions:vg_lite_blit, vg_lite_blit_rect, vg_lite_clear, vg_lite_create_masklayer, vg_lite_fill_masklayer, vg_lite_blend_masklayer, vg_lite_set_masklayer, vg_lite_render_masklayer, vg_lite_destroy_masklayer

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

vg_lite_buffer_t member	Type	Description
width	vg_lite_int32_t	Width of buffer in pixels
height	vg_lite_int32_t	Height of buffer in pixels
stride	vg_lite_int32_t	Stride in bytes
tiled	vg_lite_buffer_layout_t	Linear or tiled format for buffer enum
format	vg_lite_buffer_format_t	color format enum
handle	vg_lite_pointer	memory handle
memory	vg_lite_pointer	pointer to the start address of the memory
address	vg_lite_uint32_t	GPU address
yuv	vg_lite_yuvinfo_t	YUV format info struct
image_mode	vg_lite_image_mode_t	Blit image mode enum
transparency_mode	vg_lite_transparency_t	Image transparency mode enum
fc_buffer[3]	vg_lite_fc_buffer_t	Three (3) fast clear buffers, reserved YUV format (from March 2023)
compress_mode	vg_lite_compress_mode	Compression mode (from March 2023)
index_endian	vg_lite_index_endian_t	Big/Little Endian setting for index formats (from March 2023)
paintType	vg_lite_paint_type_t	Paint type enum (from May 2023)
fc_enable	vg_lite_int8_t	Enable Image fast clear (moved from Aug 2023)
scissor_layer	vg_lite_int8_t	Get paintcolor from different paint types (from Aug 2023)
premulitplied	vg_lite_int8_t	The RGB pixel values are alpha-premultipled (from Aug 2023)

Parent topic:Pixel buffer structures

vg_lite_fc_buffer_t structure

This structure defines the organization of a fast clear buffer. (from March 2023)

Used in structure: vg_lite_buffer_t.

vg_lite_fc_buffer_t members	Type	Description
width	vg_lite_int32_t	Width of buffer in pixels
height	vg_lite_int32_t	Height of buffer in pixels
stride	vg_lite_int32_t	Stride in bytes
handle	vg_lite_pointer	memory handle as allocated by the VGLite kernel
memory	vg_lite_pointer	logical pointer to the start address of the memory for the CPU
address	vg_lite_uint32_t	address to the buffer’s memory for the GPU hardware
color	vg_lite_uint32_t	The fast clear color value

Parent topic:Pixel buffer structures

vg_lite_yuvinfo_t structure

This structure defines the organization of VGLite YUV data.

Used in structure: vg_lite_buffer_t.

vg_lite_yuvinfo_t member	Type	Description
swizzle	vg_lite_swizzle_t	UV swizzle enum
yuv2rgb	vg_lite_yuv2rgb_t	YUV conversion standard enum
`uv_planar	vg_lite_uint32_t	UV (U) planar address for GPU, generated by driver
v_planar	vg_lite_uint32_t	V planar address for GPU, generated by driver
`alpha_planar	vg_lite_uint32_t	Alpha planar address for GPU, generated by driver
`uv_stride	vg_lite_uint32_t	UV (U) stride in bytes
`v_stride	vg_lite_uint32_t	V planar stride in bytes
alpha_stride	vg_lite_uint32_t	Alpha stride in bytes
`uv_height	vg_lite_uint32_t	UV (U) height in pixels
`v_height	vg_lite_uint32_t	V stride in bytes
uv_memory	vg_lite_pointer	Logical pointer to the UV (U) planar memory
`v_memory	vg_lite_pointer	Logical pointer to the V planar memory
uv_handle	vg_lite_pointer	Memory handle of the UV (U) planar, generated by the driver
v_handle	vg_lite_pointer	Memory handle of the V planar, generated by the driver

Parent topic:Pixel buffer structures

Parent topic:Pixel buffers

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