gralloc.h revision 33c0fe022e166007547d9c7390e7e6dbba5122e7
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18#ifndef ANDROID_GRALLOC_INTERFACE_H 19#define ANDROID_GRALLOC_INTERFACE_H 20 21#include <system/window.h> 22#include <hardware/hardware.h> 23 24#include <stdint.h> 25#include <sys/cdefs.h> 26#include <sys/types.h> 27 28__BEGIN_DECLS 29 30#define GRALLOC_API_VERSION 1 31 32/** 33 * The id of this module 34 */ 35#define GRALLOC_HARDWARE_MODULE_ID "gralloc" 36 37/** 38 * Name of the graphics device to open 39 */ 40 41#define GRALLOC_HARDWARE_FB0 "fb0" 42#define GRALLOC_HARDWARE_GPU0 "gpu0" 43 44enum { 45 /* buffer is never read in software */ 46 GRALLOC_USAGE_SW_READ_NEVER = 0x00000000, 47 /* buffer is rarely read in software */ 48 GRALLOC_USAGE_SW_READ_RARELY = 0x00000002, 49 /* buffer is often read in software */ 50 GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003, 51 /* mask for the software read values */ 52 GRALLOC_USAGE_SW_READ_MASK = 0x0000000F, 53 54 /* buffer is never written in software */ 55 GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000, 56 /* buffer is never written in software */ 57 GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020, 58 /* buffer is never written in software */ 59 GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030, 60 /* mask for the software write values */ 61 GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0, 62 63 /* buffer will be used as an OpenGL ES texture */ 64 GRALLOC_USAGE_HW_TEXTURE = 0x00000100, 65 /* buffer will be used as an OpenGL ES render target */ 66 GRALLOC_USAGE_HW_RENDER = 0x00000200, 67 /* buffer will be used by the 2D hardware blitter */ 68 GRALLOC_USAGE_HW_2D = 0x00000400, 69 /* buffer will be used with the framebuffer device */ 70 GRALLOC_USAGE_HW_FB = 0x00001000, 71 /* mask for the software usage bit-mask */ 72 GRALLOC_USAGE_HW_MASK = 0x00001F00, 73 74 /* buffer should be displayed full-screen on an external display when 75 * possible 76 */ 77 GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000, 78 79 /* Must have a hardware-protected path to external display sink for 80 * this buffer. If a hardware-protected path is not available, then 81 * either don't composite only this buffer (preferred) to the 82 * external sink, or (less desirable) do not route the entire 83 * composition to the external sink. 84 */ 85 GRALLOC_USAGE_PROTECTED = 0x00004000, 86 87 /* implementation-specific private usage flags */ 88 GRALLOC_USAGE_PRIVATE_0 = 0x10000000, 89 GRALLOC_USAGE_PRIVATE_1 = 0x20000000, 90 GRALLOC_USAGE_PRIVATE_2 = 0x40000000, 91 GRALLOC_USAGE_PRIVATE_3 = 0x80000000, 92 GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000, 93}; 94 95/*****************************************************************************/ 96 97/** 98 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 99 * and the fields of this data structure must begin with hw_module_t 100 * followed by module specific information. 101 */ 102typedef struct gralloc_module_t { 103 struct hw_module_t common; 104 105 /* 106 * (*registerBuffer)() must be called before a buffer_handle_t that has not 107 * been created with (*alloc_device_t::alloc)() can be used. 108 * 109 * This is intended to be used with buffer_handle_t's that have been 110 * received in this process through IPC. 111 * 112 * This function checks that the handle is indeed a valid one and prepares 113 * it for use with (*lock)() and (*unlock)(). 114 * 115 * It is not necessary to call (*registerBuffer)() on a handle created 116 * with (*alloc_device_t::alloc)(). 117 * 118 * returns an error if this buffer_handle_t is not valid. 119 */ 120 int (*registerBuffer)(struct gralloc_module_t const* module, 121 buffer_handle_t handle); 122 123 /* 124 * (*unregisterBuffer)() is called once this handle is no longer needed in 125 * this process. After this call, it is an error to call (*lock)(), 126 * (*unlock)(), or (*registerBuffer)(). 127 * 128 * This function doesn't close or free the handle itself; this is done 129 * by other means, usually through libcutils's native_handle_close() and 130 * native_handle_free(). 131 * 132 * It is an error to call (*unregisterBuffer)() on a buffer that wasn't 133 * explicitly registered first. 134 */ 135 int (*unregisterBuffer)(struct gralloc_module_t const* module, 136 buffer_handle_t handle); 137 138 /* 139 * The (*lock)() method is called before a buffer is accessed for the 140 * specified usage. This call may block, for instance if the h/w needs 141 * to finish rendering or if CPU caches need to be synchronized. 142 * 143 * The caller promises to modify only pixels in the area specified 144 * by (l,t,w,h). 145 * 146 * The content of the buffer outside of the specified area is NOT modified 147 * by this call. 148 * 149 * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address 150 * of the buffer in virtual memory. 151 * 152 * THREADING CONSIDERATIONS: 153 * 154 * It is legal for several different threads to lock a buffer from 155 * read access, none of the threads are blocked. 156 * 157 * However, locking a buffer simultaneously for write or read/write is 158 * undefined, but: 159 * - shall not result in termination of the process 160 * - shall not block the caller 161 * It is acceptable to return an error or to leave the buffer's content 162 * into an indeterminate state. 163 * 164 * If the buffer was created with a usage mask incompatible with the 165 * requested usage flags here, -EINVAL is returned. 166 * 167 */ 168 169 int (*lock)(struct gralloc_module_t const* module, 170 buffer_handle_t handle, int usage, 171 int l, int t, int w, int h, 172 void** vaddr); 173 174 175 /* 176 * The (*unlock)() method must be called after all changes to the buffer 177 * are completed. 178 */ 179 180 int (*unlock)(struct gralloc_module_t const* module, 181 buffer_handle_t handle); 182 183 184 /* reserved for future use */ 185 int (*perform)(struct gralloc_module_t const* module, 186 int operation, ... ); 187 188 /* reserved for future use */ 189 void* reserved_proc[7]; 190} gralloc_module_t; 191 192/*****************************************************************************/ 193 194/** 195 * Every device data structure must begin with hw_device_t 196 * followed by module specific public methods and attributes. 197 */ 198 199typedef struct alloc_device_t { 200 struct hw_device_t common; 201 202 /* 203 * (*alloc)() Allocates a buffer in graphic memory with the requested 204 * parameters and returns a buffer_handle_t and the stride in pixels to 205 * allow the implementation to satisfy hardware constraints on the width 206 * of a pixmap (eg: it may have to be multiple of 8 pixels). 207 * The CALLER TAKES OWNERSHIP of the buffer_handle_t. 208 * 209 * Returns 0 on success or -errno on error. 210 */ 211 212 int (*alloc)(struct alloc_device_t* dev, 213 int w, int h, int format, int usage, 214 buffer_handle_t* handle, int* stride); 215 216 /* 217 * (*free)() Frees a previously allocated buffer. 218 * Behavior is undefined if the buffer is still mapped in any process, 219 * but shall not result in termination of the program or security breaches 220 * (allowing a process to get access to another process' buffers). 221 * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes 222 * invalid after the call. 223 * 224 * Returns 0 on success or -errno on error. 225 */ 226 int (*free)(struct alloc_device_t* dev, 227 buffer_handle_t handle); 228 229 /* This hook is OPTIONAL. 230 * 231 * If non NULL it will be caused by SurfaceFlinger on dumpsys 232 */ 233 void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len); 234 235 void* reserved_proc[7]; 236} alloc_device_t; 237 238 239typedef struct framebuffer_device_t { 240 struct hw_device_t common; 241 242 /* flags describing some attributes of the framebuffer */ 243 const uint32_t flags; 244 245 /* dimensions of the framebuffer in pixels */ 246 const uint32_t width; 247 const uint32_t height; 248 249 /* frambuffer stride in pixels */ 250 const int stride; 251 252 /* framebuffer pixel format */ 253 const int format; 254 255 /* resolution of the framebuffer's display panel in pixel per inch*/ 256 const float xdpi; 257 const float ydpi; 258 259 /* framebuffer's display panel refresh rate in frames per second */ 260 const float fps; 261 262 /* min swap interval supported by this framebuffer */ 263 const int minSwapInterval; 264 265 /* max swap interval supported by this framebuffer */ 266 const int maxSwapInterval; 267 268 int reserved[8]; 269 270 /* 271 * requests a specific swap-interval (same definition than EGL) 272 * 273 * Returns 0 on success or -errno on error. 274 */ 275 int (*setSwapInterval)(struct framebuffer_device_t* window, 276 int interval); 277 278 /* 279 * This hook is OPTIONAL. 280 * 281 * It is non NULL If the framebuffer driver supports "update-on-demand" 282 * and the given rectangle is the area of the screen that gets 283 * updated during (*post)(). 284 * 285 * This is useful on devices that are able to DMA only a portion of 286 * the screen to the display panel, upon demand -- as opposed to 287 * constantly refreshing the panel 60 times per second, for instance. 288 * 289 * Only the area defined by this rectangle is guaranteed to be valid, that 290 * is, the driver is not allowed to post anything outside of this 291 * rectangle. 292 * 293 * The rectangle evaluated during (*post)() and specifies which area 294 * of the buffer passed in (*post)() shall to be posted. 295 * 296 * return -EINVAL if width or height <=0, or if left or top < 0 297 */ 298 int (*setUpdateRect)(struct framebuffer_device_t* window, 299 int left, int top, int width, int height); 300 301 /* 302 * Post <buffer> to the display (display it on the screen) 303 * The buffer must have been allocated with the 304 * GRALLOC_USAGE_HW_FB usage flag. 305 * buffer must be the same width and height as the display and must NOT 306 * be locked. 307 * 308 * The buffer is shown during the next VSYNC. 309 * 310 * If the same buffer is posted again (possibly after some other buffer), 311 * post() will block until the the first post is completed. 312 * 313 * Internally, post() is expected to lock the buffer so that a 314 * subsequent call to gralloc_module_t::(*lock)() with USAGE_RENDER or 315 * USAGE_*_WRITE will block until it is safe; that is typically once this 316 * buffer is shown and another buffer has been posted. 317 * 318 * Returns 0 on success or -errno on error. 319 */ 320 int (*post)(struct framebuffer_device_t* dev, buffer_handle_t buffer); 321 322 323 /* 324 * The (*compositionComplete)() method must be called after the 325 * compositor has finished issuing GL commands for client buffers. 326 */ 327 328 int (*compositionComplete)(struct framebuffer_device_t* dev); 329 330 /* 331 * This hook is OPTIONAL. 332 * 333 * If non NULL it will be caused by SurfaceFlinger on dumpsys 334 */ 335 void (*dump)(struct framebuffer_device_t* dev, char *buff, int buff_len); 336 337 /* 338 * (*enableScreen)() is used to either blank (enable=0) or 339 * unblank (enable=1) the screen this framebuffer is attached to. 340 * 341 * Returns 0 on success or -errno on error. 342 */ 343 int (*enableScreen)(struct framebuffer_device_t* dev, int enable); 344 345 void* reserved_proc[6]; 346 347} framebuffer_device_t; 348 349 350/** convenience API for opening and closing a supported device */ 351 352static inline int gralloc_open(const struct hw_module_t* module, 353 struct alloc_device_t** device) { 354 return module->methods->open(module, 355 GRALLOC_HARDWARE_GPU0, (struct hw_device_t**)device); 356} 357 358static inline int gralloc_close(struct alloc_device_t* device) { 359 return device->common.close(&device->common); 360} 361 362 363static inline int framebuffer_open(const struct hw_module_t* module, 364 struct framebuffer_device_t** device) { 365 return module->methods->open(module, 366 GRALLOC_HARDWARE_FB0, (struct hw_device_t**)device); 367} 368 369static inline int framebuffer_close(struct framebuffer_device_t* device) { 370 return device->common.close(&device->common); 371} 372 373 374__END_DECLS 375 376#endif // ANDROID_ALLOC_INTERFACE_H 377