README.txt
1# VendorGraphicBuffer
2
3libvendorgraphicbuffer abstracts away the gralloc version used by the system.
4So vendor modules that need to allocate/map buffers or look into a gralloc buffer's private_handle
5don't need to depend on a specific version of gralloc or allocator/mapper interfaces.
6
7
8To use libvendorgraphicbuffer add it as a shared library to your module and
9#include <VendorGraphicBuffer.h>
10
11Location of header:
12/hardware/google/gchips/libvendorgraphicbuffer/include
13
14Location of source code:
15/hardware/google/gchips/libvendorgraphicbuffer/gralloc3
16/hardware/google/gchips/libvendorgraphicbuffer/gralloc4
17
18
19
20### How to look at the buffer handle's metadata ###
21
22Standard metadata stored in the handle as value
23
24 VendorGraphicBufferMeta gmeta;
25 gmeta.init(dst_handle);
26
27 or
28
29 VendorGraphicBufferMeta gmeta(dst_handle);
30
31
32 gmeta.fd
33 gmeta.width
34 gmeta.format
35 .....
36 etc
37
38 Please refer to VendorGraphicBufferMeta class to which values are available.
39 Please contact the Pixel Graphics System Software team if you need access to
40 metadata not preset here!
41
42
43Dynamic metadata (stored as file descriptor)
44
45 Get them by calling static functions of VendorGraphicBufferMeta
46
47- AFBC:
48 static int is_afbc(buffer_handle_t);
49
50 Returns 1 if buffer is compressed with AFBC (AFBC 1.0)
51 Returns 0 if buffer is not compressed.
52
53 e.g:
54 VendorGraphicBufferMeta::is_afbc(handle);
55
56- Video MetaData:
57 static void* get_video_metadata(buffer_handle_t);
58
59 Returns the address of video metadata that must be type cast to video metadata struct by
60 the user.
61
62 Please DO NOT FREE this address!
63
64 e.g:
65 metaData = (ExynosVideoMeta*)VendorGraphicBufferMeta::get_video_metadata(bufferHandle);
66
67- Buffer align information (needed by HWC)
68
69 static int get_pad_align(buffer_handle_t, pad_align_t *pad_align);
70
71 pad_align_t struct is defined in VendorGraphicBuffer.h header
72 and gets filled with short int type.
73
74 pad_align->align.w
75 pad_align->align.h
76 pad_align->pad.w
77 pad_align->pad.h
78
79
80### How to lock/unlock buffers ###
81
821) Get a Singleton instance of VendorGraphicBufferMapper:
83
84 static VendorGraphicBufferMapper& gmapper(VendorGraphicBufferMapper::get());
85
862) Create Rect object that will be used as input to mapper function (and android_ycbcr object
87 if locking YUV buffers)
88
89 Android::Rect bounds(width, height);
90 android_ycbcr outLayout;
91
92
93 Android::Rect class is defined in /frameworks/native/libs/ui/include_vndk/ui/Rect.h
94 android_ycbcr struct is diefeind in /system/core/libsystem/include/system/graphics.h
95
96 Both headers should get included if you include VendorGraphicBuffer.h
97
983) lock the buffer:
99 To make sure you use 64-bit usages while locking the buffer:
100 status_t err = gmapper.lock64(bufferHandle, 64bit_usage, bounds, &vaddr);
101 status_t err = gmapper.lockYCbCr64(bufferHandle, 64_bit_usage, bounds, &outLayout);
102
103 You can still use the default mapper functions in the original GraphicBufferMapper class:
104 status_t err = gmapper.lock(....);
105
106 Refer to following header if you need to use more mapper functions:
107 /frameworks/native/libs/ui/include_vndk/ui/GraphicBufferMapper.h
108
1094) unlock the buffer:
110 gmapper.unlock(bufferHandle);
111
112
113### How to allocate buffers ###
114
1151) Get a Singleton instnace of VendorGraphicBufferAllocator:
116 VendorGraphicBufferAllocator& gAllocator(VendorGraphicBufferAllocator::get());
117
1182) Allocate buffer
119 status_t error = gAllocator.allocate(width, height, format, layer_count, allocUsage, &dstBuffer, &dstStride, "requestorName");
120
1213) To free the buffer
122 gAllocator.free(freeBuffer.bufferHandle);
123
124 You can still use the default allocator functions in the original GraphicBufferAllocator class:
125
126 Refer to following header if you need to use more mapper functions:
127 /frameworks/native/libs/ui/include_vndk/ui/GraphicBufferAllocator.h
128
129
130### New name for S.LSI specific USAGES ###
131
132New usages names can be accessed by adding the namespace containing them:
133using namespace vendor::graphics
134 or
135using vendor::graphics::BufferUsage
136using vendor::graphics::VendorGraphicBufferUsage
137 or directly by
138vendor::graphics::BufferUsage::<USAGE>
139vendor::graphics::VendorGraphicBufferUsage::<USAGE>
140
141
142*** gralloc1 default usages can still be used ***
143They remain so the users of libvendorgraphicbuffer don't have to change too much
144code when moving over to libvendorgraphicbuffer.
145But I recommend moving over the Usages declared in
146 /hardware/interfaces/graphics/common/1.0/types.hal
147
148 Instead of using GRALLOC1_PRODUCE_USAGE_VIDEO_DECORDER please consider using
149 BufferUsage::VIDEO_DECORDER
150
151
152*** But S.LSI specific usages have been RENAMED ***
153
154/* S.LSI specific usages */
155enum VendorGraphicBufferUsage {
156 NO_AFBC = 1ULL << 29,
157 NOZEROED = 1ULL << 58,
158 PRIVATE_NONSECURE = 1ULL << 59,
159 VIDEO_PRIVATE_DATA = 1ULL << 60,
160};
161
162 Instead of using GRALLOC1_PRODUCER_USAGE_NO_AFBC,
163 plese use VendorGraphicBufferUsage::NO_AFBC.
164
165This change was force to remove confusion between Android default and
166vendor-specific usages.
167