Android Hardware Abstraction Layer
hwcomposer.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2010 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 #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H
18 #define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H
19 
20 #include <stdint.h>
21 #include <sys/cdefs.h>
22 
23 #include <hardware/gralloc.h>
24 #include <hardware/hardware.h>
25 #include <cutils/native_handle.h>
26 
28 
29 __BEGIN_DECLS
30 
31 /*****************************************************************************/
32 
33 /* for compatibility */
34 #define HWC_MODULE_API_VERSION HWC_MODULE_API_VERSION_0_1
35 #define HWC_DEVICE_API_VERSION HWC_DEVICE_API_VERSION_0_1
36 #define HWC_API_VERSION HWC_DEVICE_API_VERSION
37 
38 /*****************************************************************************/
39 
40 /**
41  * The id of this module
42  */
43 #define HWC_HARDWARE_MODULE_ID "hwcomposer"
44 
45 /**
46  * Name of the sensors device to open
47  */
48 #define HWC_HARDWARE_COMPOSER "composer"
49 
50 typedef struct hwc_rect {
51  int left;
52  int top;
53  int right;
54  int bottom;
55 } hwc_rect_t;
56 
57 typedef struct hwc_frect {
58  float left;
59  float top;
60  float right;
61  float bottom;
62 } hwc_frect_t;
63 
64 typedef struct hwc_region {
65  size_t numRects;
66  hwc_rect_t const* rects;
67 } hwc_region_t;
68 
69 typedef struct hwc_color {
70  uint8_t r;
71  uint8_t g;
72  uint8_t b;
73  uint8_t a;
74 } hwc_color_t;
75 
76 typedef struct hwc_layer_1 {
77  /*
78  * compositionType is used to specify this layer's type and is set by either
79  * the hardware composer implementation, or by the caller (see below).
80  *
81  * This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER
82  * before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is
83  * also set, otherwise, this field is preserved between (*prepare)()
84  * calls.
85  *
86  * HWC_BACKGROUND
87  * Always set by the caller before calling (*prepare)(), this value
88  * indicates this is a special "background" layer. The only valid field
89  * is backgroundColor.
90  * The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT
91  * handle the background color.
92  *
93  *
94  * HWC_FRAMEBUFFER_TARGET
95  * Always set by the caller before calling (*prepare)(), this value
96  * indicates this layer is the framebuffer surface used as the target of
97  * OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY
98  * or HWC_BACKGROUND, then no OpenGL ES composition will be done, and
99  * this layer should be ignored during set().
100  *
101  * This flag (and the framebuffer surface layer) will only be used if the
102  * HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions,
103  * the OpenGL ES target surface is communicated by the (dpy, sur) fields
104  * in hwc_compositor_device_1_t.
105  *
106  * This value cannot be set by the HWC implementation.
107  *
108  *
109  * HWC_FRAMEBUFFER
110  * Set by the caller before calling (*prepare)() ONLY when the
111  * HWC_GEOMETRY_CHANGED flag is also set.
112  *
113  * Set by the HWC implementation during (*prepare)(), this indicates
114  * that the layer will be drawn into the framebuffer using OpenGL ES.
115  * The HWC can toggle this value to HWC_OVERLAY to indicate it will
116  * handle the layer.
117  *
118  *
119  * HWC_OVERLAY
120  * Set by the HWC implementation during (*prepare)(), this indicates
121  * that the layer will be handled by the HWC (ie: it must not be
122  * composited with OpenGL ES).
123  *
124  */
126 
127  /*
128  * hints is bit mask set by the HWC implementation during (*prepare)().
129  * It is preserved between (*prepare)() calls, unless the
130  * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0.
131  *
132  * see hwc_layer_t::hints
133  */
134  uint32_t hints;
135 
136  /* see hwc_layer_t::flags */
137  uint32_t flags;
138 
139  union {
140  /* color of the background. hwc_color_t.a is ignored */
142 
143  struct {
144  /* handle of buffer to compose. This handle is guaranteed to have been
145  * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If
146  * the layer's handle is unchanged across two consecutive prepare calls and
147  * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the
148  * HWComposer implementation may assume that the contents of the buffer have
149  * not changed. */
150  buffer_handle_t handle;
151 
152  /* transformation to apply to the buffer during composition */
153  uint32_t transform;
154 
155  /* blending to apply during composition */
156  int32_t blending;
157 
158  /* area of the source to consider, the origin is the top-left corner of
159  * the buffer. As of HWC_DEVICE_API_VERSION_1_3, sourceRect uses floats.
160  * If the h/w can't support a non-integer source crop rectangle, it should
161  * punt to OpenGL ES composition.
162  */
163  union {
164  // crop rectangle in integer (pre HWC_DEVICE_API_VERSION_1_3)
166  hwc_rect_t sourceCrop; // just for source compatibility
167  // crop rectangle in floats (as of HWC_DEVICE_API_VERSION_1_3)
169  };
170 
171  /* where to composite the sourceCrop onto the display. The sourceCrop
172  * is scaled using linear filtering to the displayFrame. The origin is the
173  * top-left corner of the screen.
174  */
176 
177  /* visible region in screen space. The origin is the
178  * top-left corner of the screen.
179  * The visible region INCLUDES areas overlapped by a translucent layer.
180  */
182 
183  /* Sync fence object that will be signaled when the buffer's
184  * contents are available. May be -1 if the contents are already
185  * available. This field is only valid during set(), and should be
186  * ignored during prepare(). The set() call must not wait for the
187  * fence to be signaled before returning, but the HWC must wait for
188  * all buffers to be signaled before reading from them.
189  *
190  * HWC_FRAMEBUFFER layers will never have an acquire fence, since
191  * reads from them are complete before the framebuffer is ready for
192  * display.
193  *
194  * The HWC takes ownership of the acquireFenceFd and is responsible
195  * for closing it when no longer needed.
196  */
198 
199  /* During set() the HWC must set this field to a file descriptor for
200  * a sync fence object that will signal after the HWC has finished
201  * reading from the buffer. The field is ignored by prepare(). Each
202  * layer should have a unique file descriptor, even if more than one
203  * refer to the same underlying fence object; this allows each to be
204  * closed independently.
205  *
206  * If buffer reads can complete at significantly different times,
207  * then using independent fences is preferred. For example, if the
208  * HWC handles some layers with a blit engine and others with
209  * overlays, then the blit layers can be reused immediately after
210  * the blit completes, but the overlay layers can't be reused until
211  * a subsequent frame has been displayed.
212  *
213  * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't
214  * produce a release fence for them. The releaseFenceFd will be -1
215  * for these layers when set() is called.
216  *
217  * The HWC client taks ownership of the releaseFenceFd and is
218  * responsible for closing it when no longer needed.
219  */
221 
222  /*
223  * Availability: HWC_DEVICE_API_VERSION_1_2
224  *
225  * Alpha value applied to the whole layer. The effective
226  * value of each pixel is computed as:
227  *
228  * if (blending == HWC_BLENDING_PREMULT)
229  * pixel.rgb = pixel.rgb * planeAlpha / 255
230  * pixel.a = pixel.a * planeAlpha / 255
231  *
232  * Then blending proceeds as usual according to the "blending"
233  * field above.
234  *
235  * NOTE: planeAlpha applies to YUV layers as well:
236  *
237  * pixel.rgb = yuv_to_rgb(pixel.yuv)
238  * if (blending == HWC_BLENDING_PREMULT)
239  * pixel.rgb = pixel.rgb * planeAlpha / 255
240  * pixel.a = planeAlpha
241  *
242  *
243  * IMPLEMENTATION NOTE:
244  *
245  * If the source image doesn't have an alpha channel, then
246  * the h/w can use the HWC_BLENDING_COVERAGE equations instead of
247  * HWC_BLENDING_PREMULT and simply set the alpha channel to
248  * planeAlpha.
249  *
250  * e.g.:
251  *
252  * if (blending == HWC_BLENDING_PREMULT)
253  * blending = HWC_BLENDING_COVERAGE;
254  * pixel.a = planeAlpha;
255  *
256  */
257  uint8_t planeAlpha;
258 
259  /* reserved for future use */
260  uint8_t _pad[3];
261  };
262  };
263 
264  /* Allow for expansion w/o breaking binary compatibility.
265  * Pad layer to 96 bytes, assuming 32-bit pointers.
266  */
267  int32_t reserved[24 - 19];
268 
269 } hwc_layer_1_t;
270 
271 /* This represents a display, typically an EGLDisplay object */
272 typedef void* hwc_display_t;
273 
274 /* This represents a surface, typically an EGLSurface object */
275 typedef void* hwc_surface_t;
276 
277 /*
278  * hwc_display_contents_1_t::flags values
279  */
280 enum {
281  /*
282  * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
283  * passed to (*prepare)() has changed by more than just the buffer handles
284  * and acquire fences.
285  */
286  HWC_GEOMETRY_CHANGED = 0x00000001,
287 };
288 
289 /*
290  * Description of the contents to output on a display.
291  *
292  * This is the top-level structure passed to the prepare and set calls to
293  * negotiate and commit the composition of a display image.
294  */
295 typedef struct hwc_display_contents_1 {
296  /* File descriptor referring to a Sync HAL fence object which will signal
297  * when this composition is retired. For a physical display, a composition
298  * is retired when it has been replaced on-screen by a subsequent set. For
299  * a virtual display, the composition is retired when the writes to
300  * outputBuffer are complete and can be read. The fence object is created
301  * and returned by the set call; this field will be -1 on entry to prepare
302  * and set. SurfaceFlinger will close the returned file descriptor.
303  */
305 
306  union {
307  /* Fields only relevant for HWC_DEVICE_VERSION_1_0. */
308  struct {
309  /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES
310  * composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to
311  * prepare. The set call should commit this surface atomically to
312  * the display along with any overlay layers.
313  */
316  };
317 
318  /* WARNING: These fields are for experimental virtual display support,
319  * and are not currently used. */
320  struct {
321  /* outbuf is the buffer that receives the composed image for
322  * virtual displays. Writes to the outbuf must wait until
323  * outbufAcquireFenceFd signals. A fence that will signal when
324  * writes to outbuf are complete should be returned in
325  * retireFenceFd.
326  *
327  * This field will not be updated until after prepare(). If
328  * prepare() sets all non-FB layers to OVERLAY or sets all non-FB
329  * layers to FRAMEBUFFER, then the FRAMEBUFFER_TARGET buffer and
330  * the output buffer may be the same. In mixed OVERLAY/FRAMEBUFFER
331  * configurations they will have different buffers so the
332  * h/w composer does not have to read and write the same buffer.
333  *
334  * For physical displays, outbuf will be NULL.
335  */
336  buffer_handle_t outbuf;
337 
338  /* File descriptor for a fence that will signal when outbuf is
339  * ready to be written. The h/w composer is responsible for closing
340  * this when no longer needed.
341  *
342  * Will be -1 whenever outbuf is NULL, or when the outbuf can be
343  * written immediately.
344  */
346  };
347  };
348 
349  /* List of layers that will be composed on the display. The buffer handles
350  * in the list will be unique. If numHwLayers is 0, all composition will be
351  * performed by SurfaceFlinger.
352  */
353  uint32_t flags;
354  size_t numHwLayers;
356 
358 
359 /* see hwc_composer_device::registerProcs()
360  * All of the callbacks are required and non-NULL unless otherwise noted.
361  */
362 typedef struct hwc_procs {
363  /*
364  * (*invalidate)() triggers a screen refresh, in particular prepare and set
365  * will be called shortly after this call is made. Note that there is
366  * NO GUARANTEE that the screen refresh will happen after invalidate()
367  * returns (in particular, it could happen before).
368  * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and
369  * it is safe to call invalidate() from any of hwc_composer_device
370  * hooks, unless noted otherwise.
371  */
372  void (*invalidate)(const struct hwc_procs* procs);
373 
374  /*
375  * (*vsync)() is called by the h/w composer HAL when a vsync event is
376  * received and HWC_EVENT_VSYNC is enabled on a display
377  * (see: hwc_event_control).
378  *
379  * the "disp" parameter indicates which display the vsync event is for.
380  * the "timestamp" parameter is the system monotonic clock timestamp in
381  * nanosecond of when the vsync event happened.
382  *
383  * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL.
384  *
385  * It is expected that vsync() is called from a thread of at least
386  * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible,
387  * typically less than 0.5 ms.
388  *
389  * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling
390  * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation
391  * can either stop or continue to process VSYNC events, but must not
392  * crash or cause other problems.
393  */
394  void (*vsync)(const struct hwc_procs* procs, int disp, int64_t timestamp);
395 
396  /*
397  * (*hotplug)() is called by the h/w composer HAL when a display is
398  * connected or disconnected. The PRIMARY display is always connected and
399  * the hotplug callback should not be called for it.
400  *
401  * The disp parameter indicates which display type this event is for.
402  * The connected parameter indicates whether the display has just been
403  * connected (1) or disconnected (0).
404  *
405  * The hotplug() callback may call back into the h/w composer on the same
406  * thread to query refresh rate and dpi for the display. Additionally,
407  * other threads may be calling into the h/w composer while the callback
408  * is in progress.
409  *
410  * The h/w composer must serialize calls to the hotplug callback; only
411  * one thread may call it at a time.
412  *
413  * This callback will be NULL if the h/w composer is using
414  * HWC_DEVICE_API_VERSION_1_0.
415  */
416  void (*hotplug)(const struct hwc_procs* procs, int disp, int connected);
417 
418 } hwc_procs_t;
419 
420 
421 /*****************************************************************************/
422 
423 typedef struct hwc_module {
425 } hwc_module_t;
426 
427 typedef struct hwc_composer_device_1 {
429 
430  /*
431  * (*prepare)() is called for each frame before composition and is used by
432  * SurfaceFlinger to determine what composition steps the HWC can handle.
433  *
434  * (*prepare)() can be called more than once, the last call prevails.
435  *
436  * The HWC responds by setting the compositionType field in each layer to
437  * either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the
438  * composition for the layer is handled by SurfaceFlinger with OpenGL ES,
439  * in the later case, the HWC will have to handle the layer's composition.
440  * compositionType and hints are preserved between (*prepare)() calles
441  * unless the HWC_GEOMETRY_CHANGED flag is set.
442  *
443  * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
444  * list's geometry has changed, that is, when more than just the buffer's
445  * handles have been updated. Typically this happens (but is not limited to)
446  * when a window is added, removed, resized or moved. In this case
447  * compositionType and hints are reset to their default value.
448  *
449  * For HWC 1.0, numDisplays will always be one, and displays[0] will be
450  * non-NULL.
451  *
452  * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES.
453  * Entries for unsupported or disabled/disconnected display types will be
454  * NULL.
455  *
456  * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra
457  * entries correspond to enabled virtual displays, and will be non-NULL.
458  *
459  * returns: 0 on success. An negative error code on error. If an error is
460  * returned, SurfaceFlinger will assume that none of the layer will be
461  * handled by the HWC.
462  */
463  int (*prepare)(struct hwc_composer_device_1 *dev,
464  size_t numDisplays, hwc_display_contents_1_t** displays);
465 
466  /*
467  * (*set)() is used in place of eglSwapBuffers(), and assumes the same
468  * functionality, except it also commits the work list atomically with
469  * the actual eglSwapBuffers().
470  *
471  * The layer lists are guaranteed to be the same as the ones returned from
472  * the last call to (*prepare)().
473  *
474  * When this call returns the caller assumes that the displays will be
475  * updated in the near future with the content of their work lists, without
476  * artifacts during the transition from the previous frame.
477  *
478  * A display with zero layers indicates that the entire composition has
479  * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)()
480  * behaves just like eglSwapBuffers().
481  *
482  * For HWC 1.0, numDisplays will always be one, and displays[0] will be
483  * non-NULL.
484  *
485  * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES.
486  * Entries for unsupported or disabled/disconnected display types will be
487  * NULL.
488  *
489  * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra
490  * entries correspond to enabled virtual displays, and will be non-NULL.
491  *
492  * IMPORTANT NOTE: There is an implicit layer containing opaque black
493  * pixels behind all the layers in the list. It is the responsibility of
494  * the hwcomposer module to make sure black pixels are output (or blended
495  * from).
496  *
497  * IMPORTANT NOTE: In the event of an error this call *MUST* still cause
498  * any fences returned in the previous call to set to eventually become
499  * signaled. The caller may have already issued wait commands on these
500  * fences, and having set return without causing those fences to signal
501  * will likely result in a deadlock.
502  *
503  * returns: 0 on success. A negative error code on error:
504  * HWC_EGL_ERROR: eglGetError() will provide the proper error code (only
505  * allowed prior to HWComposer 1.1)
506  * Another code for non EGL errors.
507  */
508  int (*set)(struct hwc_composer_device_1 *dev,
509  size_t numDisplays, hwc_display_contents_1_t** displays);
510 
511  /*
512  * eventControl(..., event, enabled)
513  * Enables or disables h/w composer events for a display.
514  *
515  * eventControl can be called from any thread and takes effect
516  * immediately.
517  *
518  * Supported events are:
519  * HWC_EVENT_VSYNC
520  *
521  * returns -EINVAL if the "event" parameter is not one of the value above
522  * or if the "enabled" parameter is not 0 or 1.
523  */
524  int (*eventControl)(struct hwc_composer_device_1* dev, int disp,
525  int event, int enabled);
526 
527  /*
528  * blank(..., blank)
529  * Blanks or unblanks a display's screen.
530  *
531  * Turns the screen off when blank is nonzero, on when blank is zero.
532  * Multiple sequential calls with the same blank value must be supported.
533  * The screen state transition must be be complete when the function
534  * returns.
535  *
536  * returns 0 on success, negative on error.
537  */
538  int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank);
539 
540  /*
541  * Used to retrieve information about the h/w composer
542  *
543  * Returns 0 on success or -errno on error.
544  */
545  int (*query)(struct hwc_composer_device_1* dev, int what, int* value);
546 
547  /*
548  * (*registerProcs)() registers callbacks that the h/w composer HAL can
549  * later use. It will be called immediately after the composer device is
550  * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks
551  * from within registerProcs(). registerProcs() must save the hwc_procs_t
552  * pointer which is needed when calling a registered callback.
553  */
555  hwc_procs_t const* procs);
556 
557  /*
558  * This field is OPTIONAL and can be NULL.
559  *
560  * If non NULL it will be called by SurfaceFlinger on dumpsys
561  */
562  void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len);
563 
564  /*
565  * (*getDisplayConfigs)() returns handles for the configurations available
566  * on the connected display. These handles must remain valid as long as the
567  * display is connected.
568  *
569  * Configuration handles are written to configs. The number of entries
570  * allocated by the caller is passed in *numConfigs; getDisplayConfigs must
571  * not try to write more than this number of config handles. On return, the
572  * total number of configurations available for the display is returned in
573  * *numConfigs. If *numConfigs is zero on entry, then configs may be NULL.
574  *
575  * HWC_DEVICE_API_VERSION_1_1 does not provide a way to choose a config.
576  * For displays that support multiple configurations, the h/w composer
577  * implementation should choose one and report it as the first config in
578  * the list. Reporting the not-chosen configs is not required.
579  *
580  * Returns 0 on success or -errno on error. If disp is a hotpluggable
581  * display type and no display is connected, an error should be returned.
582  *
583  * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
584  * It should be NULL for previous versions.
585  */
586  int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp,
587  uint32_t* configs, size_t* numConfigs);
588 
589  /*
590  * (*getDisplayAttributes)() returns attributes for a specific config of a
591  * connected display. The config parameter is one of the config handles
592  * returned by getDisplayConfigs.
593  *
594  * The list of attributes to return is provided in the attributes
595  * parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each
596  * requested attribute is written in order to the values array. The
597  * HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values
598  * array will have one less value than the attributes array.
599  *
600  * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
601  * It should be NULL for previous versions.
602  *
603  * If disp is a hotpluggable display type and no display is connected,
604  * or if config is not a valid configuration for the display, a negative
605  * value should be returned.
606  */
607  int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp,
608  uint32_t config, const uint32_t* attributes, int32_t* values);
609 
610  /*
611  * Reserved for future use. Must be NULL.
612  */
613  void* reserved_proc[4];
614 
616 
617 /** convenience API for opening and closing a device */
618 
619 static inline int hwc_open_1(const struct hw_module_t* module,
620  hwc_composer_device_1_t** device) {
621  return module->methods->open(module,
622  HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device);
623 }
624 
625 static inline int hwc_close_1(hwc_composer_device_1_t* device) {
626  return device->common.close(&device->common);
627 }
628 
629 /*****************************************************************************/
630 
631 __END_DECLS
632 
633 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */