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