i.MX - 6 - G2D - API - Users - Guide

Freescale Semiconductor Document Number: IMX6G2DAPIUG User’s Guide Rev. L3.10.17_1.0.0-ga, 05/2014

i.MX 6 G2D API User’s

? 2014 Freescale Semiconductor, Inc. All rights reserved.

Guide

1. Overview

G2D API (Application Programming Interface) is designed for the purposes of easy to understand and use 2D BLT function. It allows the user to implement the customized applications with the simple interfaces. It is hardware and platform independent for i.MX 6 2D Graphics. G2D API supports the following features but not limited: - Simple BLT operation from source to destination

- Alpha blend for source and destination with Porter-Duff rules - High performance memory copy from source to destination - Up-scaling and down-scaling from source to destination - 90/180/270 degree rotation from source to destination - Horizontal and vertical flip from source to destination - Enhanced visual quality with dither for pixel precision-loss - High performance memory clear for destination - Pixel-level cropping for source surface - Global alpha blend for source only - Asynchronous mode and sync - Contiguous memory allocator - Support VG engine

G2D API document include the detailed interface description, and sample code for reference. The API is designed with C-Style and can be used in both C and C++ application.

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

2

Contents

1.

Overview .............................................................................................................................................................2 2. Enumerations and Structures ...............................................................................................................................4 2.1 g2d_format enumeration ................................................................................................................................4 2.2 g2d_blend_func enumeration .........................................................................................................................4 2.3 g2d_cap_mode enumeration ..........................................................................................................................5 2.4 g2d_rotation enumeration ..............................................................................................................................5 2.5 g2d_cache_mode enumeration ......................................................................................................................5 2.6 g2d_hardware_type enumeration ..................................................................................................................5 2.7 g2d_surface structure......................................................................................................................................6 2.8 g2d_buf structure ............................................................................................................................................7 3. G2D Function Descriptions ...................................................................................................................................8 3.1 g2d_open ........................................................................................................................................................8 3.2 g2d_close ........................................................................................................................................................8 3.3 g2d_make_current .........................................................................................................................................9 3.4 g2d_clear ........................................................................................................................................................9 3.5 g2d_blit ........................................................................................................................................................ 10 3.6 g2d_copy ...................................................................................................................................................... 10 3.7 g2d_query_cap ............................................................................................................................................ 11 3.8 g2d_enable .................................................................................................................................................. 11 3.9 g2d_disable .................................................................................................................................................. 11 3.10 g2d_cache_op ............................................................................................................................................ 12 3.11 g2d_alloc .................................................................................................................................................... 12 3.12 g2d_free ..................................................................................................................................................... 12 3.13 g2d_flush ................................................................................................................................................... 13 3.14 g2d_finish .................................................................................................................................................. 13 4. Sample Codes for G2D API Usage ...................................................................................................................... 14 4.1 Color space conversion from YUV to RGB ..................................................................................................... 14 4.2 Alpha blend in Source Over mode ................................................................................................................. 15 4.3 Source cropping and destination rotation .................................................................................................... 16

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014 Freescale Semiconductor, Inc.

3

2. Enumerations and Structures

This chapter describes all Enumeration and Structure definition in G2D.

2.1 g2d_format enumeration

The Enumeration describes the pixel format for source and destination Name G2D_RGB565 G2D_RGBA8888 G2D_RGBX8888 G2D_BGRA8888 G2D_BGRX8888 G2D_BGR565 G2D_ARGBA8888 G2D_ABGR8888 G2D_XRGB8888 G2D_XBGR8888 G2D_NV12 G2D_I420 G2D_YV12 G2D_NV21 G2D_YUYV G2D_YVYU G2D_UYVY G2D_VYUY G2D_NV16 G2D_NV61 Numeric 0 1 2 3 4 5 6 7 8 9 20 21 22 23 24 25 26 27 28 29 Description RGB565 pixel format 32bit-RGBA pixel format 32bit-RGBX without alpha 32bit-BGRA pixel format 32bit-BGRX without alpha 16bit-BGR565 pixel format 32bit-ARGB pixel format 32bit-ABGR pixel format 32bit-XRGB without alpha 32bit-XBGR without alpha Y plane followed by interleaved U/V plane Y, U, V are within separate planes Y, V, U are within separate planes Y plane followed by interleaved V/U plane interleaved Y/U/Y/V plane interleaved Y/V/Y/U plane interleaved U/Y/V/Y plane interleaved V/Y/U/Y plane Y plane followed by interleaved U/V plane Y plane followed by interleaved V/U plane

2.2 g2d_blend_func enumeration

The Enumeration describes the blend factor for source and destination Name G2D_ZERO G2D_ONE G2D_SRC_ALPHA G2D_ONE_MINUS_SRC_ALPHA G2D_DST_ALPHA G2D_ONE_MINUS_DST_ALPHA Numeric 0 1 2 3 4 5 Description Blend factor with 0 Blend factor with 1 Blend factor with source alpha Blend factor with 1 - source alpha Blend factor with destination alpha Blend factor with 1 - destination alpha

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

4

2.3 g2d_cap_mode enumeration

The Enumeration describes the alternative capability in 2D BLT Name G2D_BLEND G2D_DITHER G2D_GLOBAL_ALPHA Numeric 0 1 2 Description Enable alpha blend in 2D BLT Enable dither in 2D BLT Enable global alpha in blend Note: G2D_GLOBAL_ALPHA is only valid when G2D_BLEND is enabled.

2.4 g2d_rotation enumeration

The Enumeration describes the rotation mode in 2D BLT Name G2D_ROTATION_0 G2D_ROTATION_90 G2D_ROTATION_180 G2D_ROTATION_270 G2D_FLIP_H G2D_FLIP_V Numeric 0 1 2 3 4 5 Description No rotation Rotation with 90 degree Rotation with 180 degree Rotation with 270 degree Horizontal flip Vertical flip

2.5 g2d_cache_mode enumeration

The Enumeration describes the cache operation mode Name G2D_CACHE_CLEAN G2D_CACHE_FLUSH G2D_GLOBAL_INVALIDATE Numeric 0 1 2 Description Clean the cacheable buffer Clean and invalidate cacheable buffer Invalidate the cacheable buffer

2.6 g2d_hardware_type enumeration

The Enumeration describes the supported hardware type Name G2D_HARDWARE_2D G2D_HARDWARE_VG Numeric Description 0 2D hardware type by default 1 VG hardware type

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

5

2.7 g2d_surface structure

The Structure describes the surface with operation attributes g2d_surface Members format planes[3] left top right bottom stride width height blendfunc global_alpha clrcolor rot Type g2d_format int int int int int int int int g2d_blend_func int int g2d_rotation Description Pixel format of surface buffer Physical addresses of surface buffer Left offset in blit rectangle Top offset in blit rectangle Right offset in blit rectangle Left offset in blit rectangle RGB/Y stride of surface buffer Surface width in pixel unit Surface height in pixel unit Alpha blend mode Global alpha value 0~255 Clear color is 32bit RGBA Rotation mode Notes: 1. RGB and YUV formats can be set in source surface, but only RGB format can be set in destination surface.

2. RGB pixel buffer only uses planes [0], buffer address is with 16bytes alignment, NV12: Y in planes [0], UV in planes [1], with 64bytes alignment,

I420: Y in planes [0], U in planes [1], U in planes [2], with 64 bytes alignment

3. The cropped region in source surface is specified with left, top, right and bottom parameters. 4. RGB stride alignment is 16bytes for source and destination surface, NV12 stride alignment is 8bytes for source surface, UV stride = Y stride,

I420 stride alignment is 8bytes for source surface, U stride=V stride = ? Y stride.

5. G2D_ROTATION_0/G2D_FLIP_H/G2D_FLIP_V shall be set in source surface, and the clockwise rotation degree shall be set in destination surface.

6. Application should calculate the rotated position and set it for destination surface. 7. The geometry definition of surface structure is described as below:

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

6

stridePlanestopleftbottomheightrightwidth

2.8 g2d_buf structure

The Structure describes the buffer used as g2d interfaces. g2d_buf Members buf_handle buf_vaddr buf_paddr buf_size Type void * void * int int Description The handle associated with buffer Virtual address of the buffer Physical address of the buffer The actual size of the buffer

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

7

3. G2D Function Descriptions

3.1 g2d_open

Description:

Open g2d device and return a handle.

Syntax:

int g2d_open(void **handle);

Parameters:

handle Pointer to receive g2d device handle

Returns:

Success with 0, fail with -1

3.2 g2d_close

Description:

Close g2d device with the handle.

Syntax:

int g2d_close(void *handle);

Parameters:

handle g2d device handle

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

8

3.3 g2d_make_current

Description:

Set the specific hardware type for current context, default is G2D_HARDWARE_2D

Syntax:

int g2d_make_current(void *handle, enum g2d_hardware_type type);

Parameters:

handle g2d device handle type g2d hardware type

Returns:

Success with 0, fail with -1

3.4 g2d_clear

Description:

Clear a specific area

Syntax:

int g2d_clear(void *handle, struct g2d_surface *area);

Parameters:

handle g2d device handle area the area to be cleared

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

9

3.5 g2d_blit

Description:

G2d blit from source to destination with alternative operation (Blend, Dither, etc)

Syntax:

int g2d_blit(void *handle, struct g2d_surface *src, struct g2d_surface *dst);

Parameters:

handle g2d device handle src source surface dst destination surface

Returns:

Success with 0, fail with -1

3.6 g2d_copy

Description:

G2d copy with specified size

Syntax:

int g2d_copy(void *handle, struct g2d_buf *d, struct g2d_buf* s, int size);

Parameters:

handle g2d device handle d destination buffer s source buffer size copy bytes

Limitations:

If the destination buffer is cacheable, it must be invalidated before g2d_copy due to the alignment limitation of g2d driver.

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

10

3.7 g2d_query_cap

Description:

Query the alternative capability enablement

Syntax:

int g2d_query_cap(void *handle, enum g2d_cap_mode cap, int *enable);

Parameters:

handle g2d device handle cap g2d capability to query

enable Pointer to receive g2d capability enablement

Returns: Success with 0, fail with -1

3.8 g2d_enable

Description:

Enable g2d capability with the specific mode

Syntax:

int g2d_enable(void *handle, enum g2d_cap_mode cap);

Parameters:

handle g2d device handle

cap g2d capability to enable

Returns:

Success with 0, fail with -1

3.9 g2d_disable

Description:

Enable g2d capability with the specific mode

Syntax:

int g2d_disable (void *handle, enum g2d_cap_mode cap);

Parameters:

handle g2d device handle

cap g2d capability to disable

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

11

3.10 g2d_cache_op

Description:

Perform cache operations for the cacheable buffer allocated through g2d driver

Syntax:

int g2d_cache_op (struct g2d_buf *buf, enum g2d_cache_mode op);

Parameters:

buf the buffer to be handled with cache operations op cache operation type

Returns:

Success with 0, fail with -1

3.11 g2d_alloc

Description:

Allocate a buffer through g2d device

Syntax:

struct g2d_buf *g2d_alloc(int size, int cacheable);

Parameters:

size allocated bytes

cacheable 0, non-cacheable, 1, cacheable attribute defined by system

Returns:

Success with valid g2d buffer pointer, fail with 0

3.12 g2d_free

Description:

Free the buffer through g2d device

Syntax:

int g2d_free(struct g2d_buf *buf);

Parameters:

buf g2d buffer to free

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

12

3.13 g2d_flush

Description:

Flush g2d command and return without completing pipeline.

Syntax:

int g2d_flush (void *handle);

Parameters:

handle g2d device handle

Returns:

Success with 0, fail with -1

3.14 g2d_finish

Description:

Flush g2d command and then return when pipeline is finished

Syntax:

int g2d_finish (void *handle);

Parameters:

handle g2d device handle

Returns:

Success with 0, fail with -1

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

13

4. Sample Codes for G2D API Usage

This chapter provides the brief prototype codes with G2D API.

4.1 Color space conversion from YUV to RGB

g2d_open(&handle);

src.planes[0] = buf_y; src.planes[1] = buf_u; src.planes[2] = buf_v; src.left = crop.left; src.top = crop.top; src.right = crop.right; src.bottom = crop.bottom; src.stride = y_stride; src.width = y_width; src.height = y_height; src.rot = G2D_ROTATION_0; src.format = G2D_I420; dst.planes[0] = buf_rgba; dst.left = 0; dst.top = 0; dst.right = disp_width; dst.bottom = disp_height; dst.stride = disp_width; dst.width = disp_width; dst.height = disp_height; dst.rot = G2D_ROTATION_0; dst.format = G2D_RGBA8888; g2d_blit(handle, &src, &dst); g2d_finish(handle); g2d_close(handle);

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

14

4.2 Alpha blend in Source Over mode

g2d_open(&handle);

src.planes[0] = src_buf; src.left = 0; src.top = 0; src.right = test_width; src.bottom = test_height; src.stride = test_width; src.width = test_width; src.height = test_height; src.rot = G2D_ROTATION_0; src.format = G2D_RGBA8888; src.blendfunc = G2D_ONE; dst.planes[0] = dst_buf; dst.left = 0; dst.top = 0; dst.right = test_width; dst.bottom = test_height; dst.stride = test_width;

dst.width = test_width;

dst.height = test_height; dst.format = G2D_RGBA8888;

dst.rot = G2D_ROTATION_0;

dst.blendfunc = G2D_ONE_MINUS_SRC_ALPHA;

g2d_enable(handle,G2D_BLEND);

g2d_blit(handle, &src, &dst); g2d_finish(handle);

g2d_disable(handle,G2D_BLEND);

g2d_close(handle);

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

15

4.3 Source cropping and destination rotation

g2d_open(&handle);

src.planes[0] = src_buf; src.left = crop.left; src.top = crop.left; src.right = crop.right; src.bottom = crop.bottom; src.stride = src_stride; src.width = src_width; src.height = src_height; src.format = G2D_RGBA8888;

src.rot = G2D_ROTATION_0;//G2D_FLIP_H or G2D_FLIP_V

dst.planes[0] = dst_buf; dst.left = 0; dst.top = 0; dst.right = dst_width; dst.bottom = dst_height; dst.stride = dst_width; dst.width = dst_width; dst.height = dst_height;

dst.format = G2D_RGBA8888;

dst.rot = G2D_ROTATION_90; g2d_blit(handle, &src, &dst); g2d_finish(handle); g2d_close(handle);

i.MX 6 G2D API User’s Guide, Rev. L3.10.17_1.0.0-ga, 05/2014

Freescale Semiconductor, Inc.

16

How to Reach Us:

Home Page: freescale.com Web Support:

freescale.com/support

Document Number: IMX6G2DAPIUGRev. L3.10.17_1.0.0-ga05/2014

Information in this document is provided solely to enable system and software implementers to use Freescale products. There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits based on the information in this document.

Freescale reserves the right to make changes without further notice to any products herein. Freescale makes no warranty, representation, or guarantee regarding the suitability of its products for any particular purpose, nor does Freescale assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. “Typical” parameters that may be provided in Freescale data sheets and/or specifications can and do vary in different applications, and actual performance may vary over time. All operating parameters, including “typicals,” must be validated for each customer application by customer’s technical experts. Freescale does not convey any license under its patent rights nor the rights of others. Freescale sells products pursuant to standard terms and conditions of sale, which can be found at the following address: freescale.com/SalesTermsandConditions.

Freescale and the Freescale logo are trademarks of Freescale Semiconductor, Inc., Reg. U.S. Pat. & Tm. Off. All other product or service names are the property of their respective owners. ARM and ARM Cortex-A9 are registered trademarks of ARM Limited.

? 2014 Freescale Semiconductor, Inc.

本文来源：https://www.bwwdw.com/article/2qkt.html