41
60
#define HWC_HARDWARE_COMPOSER "composer"
45
/* hwc_composer_device_t::set failed in EGL */
50
* hwc_layer_t::hints values
51
* Hints are set by the HAL and read by SurfaceFlinger
55
* HWC can set the HWC_HINT_TRIPLE_BUFFER hint to indicate to SurfaceFlinger
56
* that it should triple buffer this layer. Typically HWC does this when
57
* the layer will be unavailable for use for an extended period of time,
58
* e.g. if the display will be fetching data directly from the layer and
59
* the layer can not be modified until after the next set().
61
HWC_HINT_TRIPLE_BUFFER = 0x00000001,
64
* HWC sets HWC_HINT_CLEAR_FB to tell SurfaceFlinger that it should clear the
65
* framebuffer with transparent pixels where this layer would be.
66
* SurfaceFlinger will only honor this flag when the layer has no blending
69
HWC_HINT_CLEAR_FB = 0x00000002
73
* hwc_layer_t::flags values
74
* Flags are set by SurfaceFlinger and read by the HAL
78
* HWC_SKIP_LAYER is set by SurfaceFlnger to indicate that the HAL
79
* shall not consider this layer for composition as it will be handled
80
* by SurfaceFlinger (just as if compositionType was set to HWC_OVERLAY).
82
HWC_SKIP_LAYER = 0x00000001,
86
* hwc_layer_t::compositionType values
89
/* this layer is to be drawn into the framebuffer by SurfaceFlinger */
92
/* this layer will be handled in the HWC */
97
* hwc_layer_t::blending values
101
HWC_BLENDING_NONE = 0x0100,
103
/* ONE / ONE_MINUS_SRC_ALPHA */
104
HWC_BLENDING_PREMULT = 0x0105,
106
/* SRC_ALPHA / ONE_MINUS_SRC_ALPHA */
107
HWC_BLENDING_COVERAGE = 0x0405
111
* hwc_layer_t::transform values
114
/* flip source image horizontally */
115
HWC_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H,
116
/* flip source image vertically */
117
HWC_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V,
118
/* rotate source image 90 degrees clock-wise */
119
HWC_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90,
120
/* rotate source image 180 degrees */
121
HWC_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180,
122
/* rotate source image 270 degrees clock-wise */
123
HWC_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270,
126
62
typedef struct hwc_rect {
135
71
hwc_rect_t const* rects;
138
typedef struct hwc_layer {
74
typedef struct hwc_color {
81
typedef struct hwc_layer_1 {
140
* initially set to HWC_FRAMEBUFFER, indicates the layer will
141
* be drawn into the framebuffer using OpenGL ES.
142
* The HWC can toggle this value to HWC_OVERLAY, to indicate
143
* it will handle the layer.
83
* compositionType is used to specify this layer's type and is set by either
84
* the hardware composer implementation, or by the caller (see below).
86
* This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER
87
* before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is
88
* also set, otherwise, this field is preserved between (*prepare)()
92
* Always set by the caller before calling (*prepare)(), this value
93
* indicates this is a special "background" layer. The only valid field
95
* The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT
96
* handle the background color.
99
* HWC_FRAMEBUFFER_TARGET
100
* Always set by the caller before calling (*prepare)(), this value
101
* indicates this layer is the framebuffer surface used as the target of
102
* OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY
103
* or HWC_BACKGROUND, then no OpenGL ES composition will be done, and
104
* this layer should be ignored during set().
106
* This flag (and the framebuffer surface layer) will only be used if the
107
* HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions,
108
* the OpenGL ES target surface is communicated by the (dpy, sur) fields
109
* in hwc_compositor_device_1_t.
111
* This value cannot be set by the HWC implementation.
115
* Set by the caller before calling (*prepare)() ONLY when the
116
* HWC_GEOMETRY_CHANGED flag is also set.
118
* Set by the HWC implementation during (*prepare)(), this indicates
119
* that the layer will be drawn into the framebuffer using OpenGL ES.
120
* The HWC can toggle this value to HWC_OVERLAY to indicate it will
125
* Set by the HWC implementation during (*prepare)(), this indicates
126
* that the layer will be handled by the HWC (ie: it must not be
127
* composited with OpenGL ES).
145
130
int32_t compositionType;
147
/* see hwc_layer_t::hints above */
133
* hints is bit mask set by the HWC implementation during (*prepare)().
134
* It is preserved between (*prepare)() calls, unless the
135
* HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0.
137
* see hwc_layer_t::hints
150
/* see hwc_layer_t::flags above */
153
/* handle of buffer to compose. this handle is guaranteed to have been
154
* allocated with gralloc */
155
buffer_handle_t handle;
157
/* transformation to apply to the buffer during composition */
160
/* blending to apply during composition */
163
/* area of the source to consider, the origin is the top-left corner of
165
hwc_rect_t sourceCrop;
167
/* where to composite the sourceCrop onto the display. The sourceCrop
168
* is scaled using linear filtering to the displayFrame. The origin is the
169
* top-left corner of the screen.
171
hwc_rect_t displayFrame;
173
/* visible region in screen space. The origin is the
174
* top-left corner of the screen.
175
* The visible region INCLUDES areas overlapped by a translucent layer.
177
hwc_region_t visibleRegionScreen;
182
* hwc_layer_list_t::flags values
186
* HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
187
* passed to (*prepare)() has changed by more than just the buffer handles.
189
HWC_GEOMETRY_CHANGED = 0x00000001,
194
* The handle members of hwLayers elements must be unique.
196
typedef struct hwc_layer_list {
199
hwc_layer_t hwLayers[0];
141
/* see hwc_layer_t::flags */
145
/* color of the background. hwc_color_t.a is ignored */
146
hwc_color_t backgroundColor;
149
/* handle of buffer to compose. This handle is guaranteed to have been
150
* allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If
151
* the layer's handle is unchanged across two consecutive prepare calls and
152
* the HWC_GEOMETRY_CHANGED flag is not set for the second call then the
153
* HWComposer implementation may assume that the contents of the buffer have
155
buffer_handle_t handle;
157
/* transformation to apply to the buffer during composition */
161
/* source transform of the buffer */
162
uint32_t sourceTransform;
165
/* blending to apply during composition */
168
/* area of the source to consider, the origin is the top-left corner of
170
hwc_rect_t sourceCrop;
172
/* where to composite the sourceCrop onto the display. The sourceCrop
173
* is scaled using linear filtering to the displayFrame. The origin is the
174
* top-left corner of the screen.
176
hwc_rect_t displayFrame;
178
/* visible region in screen space. The origin is the
179
* top-left corner of the screen.
180
* The visible region INCLUDES areas overlapped by a translucent layer.
182
hwc_region_t visibleRegionScreen;
184
/* Sync fence object that will be signaled when the buffer's
185
* contents are available. May be -1 if the contents are already
186
* available. This field is only valid during set(), and should be
187
* ignored during prepare(). The set() call must not wait for the
188
* fence to be signaled before returning, but the HWC must wait for
189
* all buffers to be signaled before reading from them.
191
* HWC_FRAMEBUFFER layers will never have an acquire fence, since
192
* reads from them are complete before the framebuffer is ready for
195
* The HWC takes ownership of the acquireFenceFd and is responsible
196
* for closing it when no longer needed.
200
/* During set() the HWC must set this field to a file descriptor for
201
* a sync fence object that will signal after the HWC has finished
202
* reading from the buffer. The field is ignored by prepare(). Each
203
* layer should have a unique file descriptor, even if more than one
204
* refer to the same underlying fence object; this allows each to be
205
* closed independently.
207
* If buffer reads can complete at significantly different times,
208
* then using independent fences is preferred. For example, if the
209
* HWC handles some layers with a blit engine and others with
210
* overlays, then the blit layers can be reused immediately after
211
* the blit completes, but the overlay layers can't be reused until
212
* a subsequent frame has been displayed.
214
* Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't
215
* produce a release fence for them. The releaseFenceFd will be -1
216
* for these layers when set() is called.
218
* The HWC client taks ownership of the releaseFenceFd and is
219
* responsible for closing it when no longer needed.
225
/* Allow for expansion w/o breaking binary compatibility.
226
* Pad layer to 96 bytes, assuming 32-bit pointers.
228
int32_t reserved[24 - 18];
202
232
/* This represents a display, typically an EGLDisplay object */
203
233
typedef void* hwc_display_t;
205
235
/* This represents a surface, typically an EGLSurface object */
206
236
typedef void* hwc_surface_t;
239
* hwc_display_contents_1_t::flags values
243
* HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
244
* passed to (*prepare)() has changed by more than just the buffer handles
245
* and acquire fences.
247
HWC_GEOMETRY_CHANGED = 0x00000001,
251
* Description of the contents to output on a display.
253
* This is the top-level structure passed to the prepare and set calls to
254
* negotiate and commit the composition of a display image.
256
typedef struct hwc_display_contents_1 {
257
/* File descriptor referring to a Sync HAL fence object which will signal
258
* when this composition is retired. For a physical display, a composition
259
* is retired when it has been replaced on-screen by a subsequent set. For
260
* a virtual display, the composition is retired when the writes to
261
* outputBuffer are complete and can be read. The fence object is created
262
* and returned by the set call; this field will be -1 on entry to prepare
263
* and set. SurfaceFlinger will close the returned file descriptor.
268
/* Fields only relevant for HWC_DEVICE_VERSION_1_0. */
270
/* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES
271
* composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to
272
* prepare. The set call should commit this surface atomically to
273
* the display along with any overlay layers.
279
/* Fields only relevant for HWC_DEVICE_VERSION_1_2 and later. */
281
/* outbuf is the buffer that receives the composed image for
282
* virtual displays. Writes to the outbuf must wait until
283
* outbufAcquireFenceFd signals. A fence that will signal when
284
* writes to outbuf are complete should be returned in
287
* For physical displays, outbuf will be NULL.
289
buffer_handle_t outbuf;
291
/* File descriptor for a fence that will signal when outbuf is
292
* ready to be written. The h/w composer is responsible for closing
293
* this when no longer needed.
295
* Will be -1 whenever outbuf is NULL, or when the outbuf can be
296
* written immediately.
298
int outbufAcquireFenceFd;
302
/* List of layers that will be composed on the display. The buffer handles
303
* in the list will be unique. If numHwLayers is 0, all composition will be
304
* performed by SurfaceFlinger.
308
hwc_layer_1_t hwLayers[0];
310
} hwc_display_contents_1_t;
209
312
/* see hwc_composer_device::registerProcs()
210
* Any of the callbacks can be NULL, in which case the corresponding
211
* functionality is not supported.
313
* All of the callbacks are required and non-NULL unless otherwise noted.
213
315
typedef struct hwc_procs {
241
387
* (*prepare)() can be called more than once, the last call prevails.
243
* The HWC responds by setting the compositionType field to either
244
* HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for
245
* this layer is handled by SurfaceFlinger with OpenGL ES, in the later
246
* case, the HWC will have to handle this layer's composition.
389
* The HWC responds by setting the compositionType field in each layer to
390
* either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the
391
* composition for the layer is handled by SurfaceFlinger with OpenGL ES,
392
* in the later case, the HWC will have to handle the layer's composition.
393
* compositionType and hints are preserved between (*prepare)() calles
394
* unless the HWC_GEOMETRY_CHANGED flag is set.
248
396
* (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
249
397
* list's geometry has changed, that is, when more than just the buffer's
250
398
* handles have been updated. Typically this happens (but is not limited to)
251
* when a window is added, removed, resized or moved.
253
* a NULL list parameter or a numHwLayers of zero indicates that the
254
* entire composition will be handled by SurfaceFlinger with OpenGL ES.
399
* when a window is added, removed, resized or moved. In this case
400
* compositionType and hints are reset to their default value.
402
* For HWC 1.0, numDisplays will always be one, and displays[0] will be
405
* For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries
406
* for unsupported or disabled/disconnected display types will be NULL.
408
* For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more.
409
* The extra entries correspond to enabled virtual displays, and will be
410
* non-NULL. In HWC 1.2, support for one virtual display is required, and
411
* no more than one will be used. Future HWC versions might require more.
256
413
* returns: 0 on success. An negative error code on error. If an error is
257
414
* returned, SurfaceFlinger will assume that none of the layer will be
258
415
* handled by the HWC.
260
int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list);
417
int (*prepare)(struct hwc_composer_device_1 *dev,
418
size_t numDisplays, hwc_display_contents_1_t** displays);
264
421
* (*set)() is used in place of eglSwapBuffers(), and assumes the same
265
422
* functionality, except it also commits the work list atomically with
266
423
* the actual eglSwapBuffers().
268
* The list parameter is guaranteed to be the same as the one returned
269
* from the last call to (*prepare)().
271
* When this call returns the caller assumes that:
273
* - the display will be updated in the near future with the content
274
* of the work list, without artifacts during the transition from the
277
* - all objects are available for immediate access or destruction, in
278
* particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer.
279
* Note that this means that immediately accessing (potentially from a
280
* different process) a buffer used in this call will not result in
281
* screen corruption, the driver must apply proper synchronization or
282
* scheduling (eg: block the caller, such as gralloc_module_t::lock(),
283
* OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work
284
* after the buffer is freed from the actual composition).
286
* a NULL list parameter or a numHwLayers of zero indicates that the
287
* entire composition has been handled by SurfaceFlinger with OpenGL ES.
288
* In this case, (*set)() behaves just like eglSwapBuffers().
290
* dpy, sur, and list are set to NULL to indicate that the screen is
291
* turning off. This happens WITHOUT prepare() being called first.
292
* This is a good time to free h/w resources and/or power
293
* the relevant h/w blocks down.
295
* IMPORTANT NOTE: there is an implicit layer containing opaque black
296
* pixels behind all the layers in the list.
297
* It is the responsibility of the hwcomposer module to make
298
* sure black pixels are output (or blended from).
300
* returns: 0 on success. An negative error code on error:
301
* HWC_EGL_ERROR: eglGetError() will provide the proper error code
425
* The layer lists are guaranteed to be the same as the ones returned from
426
* the last call to (*prepare)().
428
* When this call returns the caller assumes that the displays will be
429
* updated in the near future with the content of their work lists, without
430
* artifacts during the transition from the previous frame.
432
* A display with zero layers indicates that the entire composition has
433
* been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)()
434
* behaves just like eglSwapBuffers().
436
* For HWC 1.0, numDisplays will always be one, and displays[0] will be
439
* For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries
440
* for unsupported or disabled/disconnected display types will be NULL.
442
* For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more.
443
* The extra entries correspond to enabled virtual displays, and will be
444
* non-NULL. In HWC 1.2, support for one virtual display is required, and
445
* no more than one will be used. Future HWC versions might require more.
447
* IMPORTANT NOTE: There is an implicit layer containing opaque black
448
* pixels behind all the layers in the list. It is the responsibility of
449
* the hwcomposer module to make sure black pixels are output (or blended
452
* IMPORTANT NOTE: In the event of an error this call *MUST* still cause
453
* any fences returned in the previous call to set to eventually become
454
* signaled. The caller may have already issued wait commands on these
455
* fences, and having set return without causing those fences to signal
456
* will likely result in a deadlock.
458
* returns: 0 on success. A negative error code on error:
459
* HWC_EGL_ERROR: eglGetError() will provide the proper error code (only
460
* allowed prior to HWComposer 1.1)
302
461
* Another code for non EGL errors.
305
int (*set)(struct hwc_composer_device *dev,
308
hwc_layer_list_t* list);
310
* This hook is OPTIONAL.
463
int (*set)(struct hwc_composer_device_1 *dev,
464
size_t numDisplays, hwc_display_contents_1_t** displays);
467
* eventControl(..., event, enabled)
468
* Enables or disables h/w composer events for a display.
470
* eventControl can be called from any thread and takes effect
473
* Supported events are:
476
* returns -EINVAL if the "event" parameter is not one of the value above
477
* or if the "enabled" parameter is not 0 or 1.
479
int (*eventControl)(struct hwc_composer_device_1* dev, int disp,
480
int event, int enabled);
484
* Blanks or unblanks a display's screen.
486
* Turns the screen off when blank is nonzero, on when blank is zero.
487
* Multiple sequential calls with the same blank value must be supported.
488
* The screen state transition must be be complete when the function
491
* returns 0 on success, negative on error.
493
int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank);
496
* Used to retrieve information about the h/w composer
498
* Returns 0 on success or -errno on error.
500
int (*query)(struct hwc_composer_device_1* dev, int what, int* value);
503
* (*registerProcs)() registers callbacks that the h/w composer HAL can
504
* later use. It will be called immediately after the composer device is
505
* opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks
506
* from within registerProcs(). registerProcs() must save the hwc_procs_t
507
* pointer which is needed when calling a registered callback.
509
void (*registerProcs)(struct hwc_composer_device_1* dev,
510
hwc_procs_t const* procs);
513
* This field is OPTIONAL and can be NULL.
312
515
* If non NULL it will be called by SurfaceFlinger on dumpsys
314
void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len);
317
* This hook is OPTIONAL.
319
* (*registerProcs)() registers a set of callbacks the h/w composer HAL
320
* can later use. It is FORBIDDEN to call any of the callbacks from
321
* within registerProcs(). registerProcs() must save the hwc_procs_t pointer
322
* which is needed when calling a registered callback.
323
* Each call to registerProcs replaces the previous set of callbacks.
324
* registerProcs is called with NULL to unregister all callbacks.
326
* Any of the callbacks can be NULL, in which case the corresponding
327
* functionality is not supported.
329
void (*registerProcs)(struct hwc_composer_device* dev,
330
hwc_procs_t const* procs);
332
void* reserved_proc[6];
334
} hwc_composer_device_t;
517
void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len);
520
* (*getDisplayConfigs)() returns handles for the configurations available
521
* on the connected display. These handles must remain valid as long as the
522
* display is connected.
524
* Configuration handles are written to configs. The number of entries
525
* allocated by the caller is passed in *numConfigs; getDisplayConfigs must
526
* not try to write more than this number of config handles. On return, the
527
* total number of configurations available for the display is returned in
528
* *numConfigs. If *numConfigs is zero on entry, then configs may be NULL.
530
* HWC_DEVICE_API_VERSION_1_1 does not provide a way to choose a config.
531
* For displays that support multiple configurations, the h/w composer
532
* implementation should choose one and report it as the first config in
533
* the list. Reporting the not-chosen configs is not required.
535
* Returns 0 on success or -errno on error. If disp is a hotpluggable
536
* display type and no display is connected, an error should be returned.
538
* This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
539
* It should be NULL for previous versions.
541
int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp,
542
uint32_t* configs, size_t* numConfigs);
545
* (*getDisplayAttributes)() returns attributes for a specific config of a
546
* connected display. The config parameter is one of the config handles
547
* returned by getDisplayConfigs.
549
* The list of attributes to return is provided in the attributes
550
* parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each
551
* requested attribute is written in order to the values array. The
552
* HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values
553
* array will have one less value than the attributes array.
555
* This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
556
* It should be NULL for previous versions.
558
* If disp is a hotpluggable display type and no display is connected,
559
* or if config is not a valid configuration for the display, a negative
560
* value should be returned.
562
int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp,
563
uint32_t config, const uint32_t* attributes, int32_t* values);
566
* Reserved for future use. Must be NULL.
568
void* reserved_proc[4];
570
} hwc_composer_device_1_t;
337
572
/** convenience API for opening and closing a device */
339
static inline int hwc_open(const struct hw_module_t* module,
340
hwc_composer_device_t** device) {
574
static inline int hwc_open_1(const struct hw_module_t* module,
575
hwc_composer_device_1_t** device) {
341
576
return module->methods->open(module,
342
577
HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device);
345
static inline int hwc_close(hwc_composer_device_t* device) {
580
static inline int hwc_close_1(hwc_composer_device_1_t* device) {
346
581
return device->common.close(&device->common);
350
584
/*****************************************************************************/
586
#if !HWC_REMOVE_DEPRECATED_VERSIONS
587
#include <hardware/hwcomposer_v0.h>
354
592
#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */