• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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