2 * Copyright 2015 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef ANDROID_HARDWARE_HWCOMPOSER2_H
18 #define ANDROID_HARDWARE_HWCOMPOSER2_H
20 #include <hardware/hardware.h>
22 #include "hwcomposer_defs.h"
29 * For most of these enums, there is an invalid value defined to be 0. This is
30 * an attempt to catch uninitialized fields, and these values should not be
34 /* Display attributes queryable through getDisplayAttribute */
36 HWC2_ATTRIBUTE_INVALID = 0,
38 /* Dimensions in pixels */
39 HWC2_ATTRIBUTE_WIDTH = 1,
40 HWC2_ATTRIBUTE_HEIGHT = 2,
42 /* Vsync period in nanoseconds */
43 HWC2_ATTRIBUTE_VSYNC_PERIOD = 3,
45 /* Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these
46 * numbers to be stored in an int32_t without losing too much precision. If
47 * the DPI for a configuration is unavailable or is considered unreliable,
48 * the device may return -1 instead */
49 HWC2_ATTRIBUTE_DPI_X = 4,
50 HWC2_ATTRIBUTE_DPI_Y = 5,
53 /* Blend modes, settable per layer */
55 HWC2_BLEND_MODE_INVALID = 0,
57 /* colorOut = colorSrc */
58 HWC2_BLEND_MODE_NONE = 1,
60 /* colorOut = colorSrc + colorDst * (1 - alphaSrc) */
61 HWC2_BLEND_MODE_PREMULTIPLIED = 2,
63 /* colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */
64 HWC2_BLEND_MODE_COVERAGE = 3,
67 /* See the 'Callbacks' section for more detailed descriptions of what these
70 HWC2_CALLBACK_INVALID = 0,
71 HWC2_CALLBACK_HOTPLUG = 1,
72 HWC2_CALLBACK_REFRESH = 2,
73 HWC2_CALLBACK_VSYNC = 3,
74 } hwc2_callback_descriptor_t;
76 /* Optional capabilities which may be supported by some devices. The particular
77 * set of supported capabilities for a given device may be retrieved using
80 HWC2_CAPABILITY_INVALID = 0,
82 /* Specifies that the device supports sideband stream layers, for which
83 * buffer content updates and other synchronization will not be provided
84 * through the usual validate/present cycle and must be handled by an
85 * external implementation-defined mechanism. Only changes to layer state
86 * (such as position, size, etc.) need to be performed through the
87 * validate/present cycle. */
88 HWC2_CAPABILITY_SIDEBAND_STREAM = 1,
91 /* Possible composition types for a given layer */
93 HWC2_COMPOSITION_INVALID = 0,
95 /* The client will composite this layer into the client target buffer
96 * (provided to the device through setClientTarget).
98 * The device must not request any composition type changes for layers of
100 HWC2_COMPOSITION_CLIENT = 1,
102 /* The device will handle the composition of this layer through a hardware
103 * overlay or other similar means.
105 * Upon validateDisplay, the device may request a change from this type to
106 * HWC2_COMPOSITION_CLIENT. */
107 HWC2_COMPOSITION_DEVICE = 2,
109 /* The device will render this layer using the color set through
110 * setLayerColor. If this functionality is not supported on a layer that the
111 * client sets to HWC2_COMPOSITION_SOLID_COLOR, the device must request that
112 * the composition type of that layer is changed to HWC2_COMPOSITION_CLIENT
113 * upon the next call to validateDisplay.
115 * Upon validateDisplay, the device may request a change from this type to
116 * HWC2_COMPOSITION_CLIENT. */
117 HWC2_COMPOSITION_SOLID_COLOR = 3,
119 /* Similar to DEVICE, but the position of this layer may also be set
120 * asynchronously through setCursorPosition. If this functionality is not
121 * supported on a layer that the client sets to HWC2_COMPOSITION_CURSOR, the
122 * device must request that the composition type of that layer is changed to
123 * HWC2_COMPOSITION_CLIENT upon the next call to validateDisplay.
125 * Upon validateDisplay, the device may request a change from this type to
126 * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT. Changing to
127 * HWC2_COMPOSITION_DEVICE will prevent the use of setCursorPosition but
128 * still permit the device to composite the layer. */
129 HWC2_COMPOSITION_CURSOR = 4,
131 /* The device will handle the composition of this layer, as well as its
132 * buffer updates and content synchronization. Only supported on devices
133 * which provide HWC2_CAPABILITY_SIDEBAND_STREAM.
135 * Upon validateDisplay, the device may request a change from this type to
136 * either HWC2_COMPOSITION_DEVICE or HWC2_COMPOSITION_CLIENT, but it is
137 * unlikely that content will display correctly in these cases. */
138 HWC2_COMPOSITION_SIDEBAND = 5,
139 } hwc2_composition_t;
141 /* Possible connection options from the hotplug callback */
143 HWC2_CONNECTION_INVALID = 0,
145 /* The display has been connected */
146 HWC2_CONNECTION_CONNECTED = 1,
148 /* The display has been disconnected */
149 HWC2_CONNECTION_DISCONNECTED = 2,
152 /* Display requests returned by getDisplayRequests */
154 /* Instructs the client to provide a new client target buffer, even if no
155 * layers are marked for client composition. */
156 HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET = 1 << 0,
158 /* Instructs the client to write the result of client composition directly
159 * into the virtual display output buffer. If any of the layers are not
160 * marked as HWC2_COMPOSITION_CLIENT or the given display is not a virtual
161 * display, this request has no effect. */
162 HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1,
163 } hwc2_display_request_t;
165 /* Display types returned by getDisplayType */
167 HWC2_DISPLAY_TYPE_INVALID = 0,
169 /* All physical displays, including both internal displays and hotpluggable
170 * external displays */
171 HWC2_DISPLAY_TYPE_PHYSICAL = 1,
173 /* Virtual displays created by createVirtualDisplay */
174 HWC2_DISPLAY_TYPE_VIRTUAL = 2,
175 } hwc2_display_type_t;
177 /* Return codes from all functions */
180 HWC2_ERROR_BAD_CONFIG,
181 HWC2_ERROR_BAD_DISPLAY,
182 HWC2_ERROR_BAD_LAYER,
183 HWC2_ERROR_BAD_PARAMETER,
184 HWC2_ERROR_HAS_CHANGES,
185 HWC2_ERROR_NO_RESOURCES,
186 HWC2_ERROR_NOT_VALIDATED,
187 HWC2_ERROR_UNSUPPORTED,
190 /* Function descriptors for use with getFunction */
192 HWC2_FUNCTION_INVALID = 0,
193 HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES,
194 HWC2_FUNCTION_CREATE_LAYER,
195 HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY,
196 HWC2_FUNCTION_DESTROY_LAYER,
197 HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY,
199 HWC2_FUNCTION_GET_ACTIVE_CONFIG,
200 HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES,
201 HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT,
202 HWC2_FUNCTION_GET_COLOR_MODES,
203 HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE,
204 HWC2_FUNCTION_GET_DISPLAY_CONFIGS,
205 HWC2_FUNCTION_GET_DISPLAY_NAME,
206 HWC2_FUNCTION_GET_DISPLAY_REQUESTS,
207 HWC2_FUNCTION_GET_DISPLAY_TYPE,
208 HWC2_FUNCTION_GET_DOZE_SUPPORT,
209 HWC2_FUNCTION_GET_HDR_CAPABILITIES,
210 HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT,
211 HWC2_FUNCTION_GET_RELEASE_FENCES,
212 HWC2_FUNCTION_PRESENT_DISPLAY,
213 HWC2_FUNCTION_REGISTER_CALLBACK,
214 HWC2_FUNCTION_SET_ACTIVE_CONFIG,
215 HWC2_FUNCTION_SET_CLIENT_TARGET,
216 HWC2_FUNCTION_SET_COLOR_MODE,
217 HWC2_FUNCTION_SET_COLOR_TRANSFORM,
218 HWC2_FUNCTION_SET_CURSOR_POSITION,
219 HWC2_FUNCTION_SET_LAYER_BLEND_MODE,
220 HWC2_FUNCTION_SET_LAYER_BUFFER,
221 HWC2_FUNCTION_SET_LAYER_COLOR,
222 HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE,
223 HWC2_FUNCTION_SET_LAYER_DATASPACE,
224 HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME,
225 HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA,
226 HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM,
227 HWC2_FUNCTION_SET_LAYER_SOURCE_CROP,
228 HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE,
229 HWC2_FUNCTION_SET_LAYER_TRANSFORM,
230 HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION,
231 HWC2_FUNCTION_SET_LAYER_Z_ORDER,
232 HWC2_FUNCTION_SET_OUTPUT_BUFFER,
233 HWC2_FUNCTION_SET_POWER_MODE,
234 HWC2_FUNCTION_SET_VSYNC_ENABLED,
235 HWC2_FUNCTION_VALIDATE_DISPLAY,
236 } hwc2_function_descriptor_t;
238 /* Layer requests returned from getDisplayRequests */
240 /* The client should clear its target with transparent pixels where this
241 * layer would be. The client may ignore this request if the layer must be
243 HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET = 1 << 0,
244 } hwc2_layer_request_t;
246 /* Power modes for use with setPowerMode */
248 /* The display is fully off (blanked) */
249 HWC2_POWER_MODE_OFF = 0,
251 /* These are optional low power modes. getDozeSupport may be called to
252 * determine whether a given display supports these modes. */
254 /* The display is turned on and configured in a low power state that is
255 * suitable for presenting ambient information to the user, possibly with
256 * lower fidelity than HWC2_POWER_MODE_ON, but with greater efficiency. */
257 HWC2_POWER_MODE_DOZE = 1,
259 /* The display is configured as in HWC2_POWER_MODE_DOZE but may stop
260 * applying display updates from the client. This is effectively a hint to
261 * the device that drawing to the display has been suspended and that the
262 * the device should remain on in a low power state and continue displaying
263 * its current contents indefinitely until the power mode changes.
265 * This mode may also be used as a signal to enable hardware-based doze
266 * functionality. In this case, the device is free to take over the display
267 * and manage it autonomously to implement a low power always-on display. */
268 HWC2_POWER_MODE_DOZE_SUSPEND = 3,
270 /* The display is fully on */
271 HWC2_POWER_MODE_ON = 2,
274 /* Vsync values passed to setVsyncEnabled */
276 HWC2_VSYNC_INVALID = 0,
279 HWC2_VSYNC_ENABLE = 1,
282 HWC2_VSYNC_DISABLE = 2,
286 * Stringification Functions
289 #ifdef HWC2_INCLUDE_STRINGIFICATION
291 static inline const char* getAttributeName(hwc2_attribute_t attribute) {
293 case HWC2_ATTRIBUTE_INVALID: return "Invalid";
294 case HWC2_ATTRIBUTE_WIDTH: return "Width";
295 case HWC2_ATTRIBUTE_HEIGHT: return "Height";
296 case HWC2_ATTRIBUTE_VSYNC_PERIOD: return "VsyncPeriod";
297 case HWC2_ATTRIBUTE_DPI_X: return "DpiX";
298 case HWC2_ATTRIBUTE_DPI_Y: return "DpiY";
299 default: return "Unknown";
303 static inline const char* getBlendModeName(hwc2_blend_mode_t mode) {
305 case HWC2_BLEND_MODE_INVALID: return "Invalid";
306 case HWC2_BLEND_MODE_NONE: return "None";
307 case HWC2_BLEND_MODE_PREMULTIPLIED: return "Premultiplied";
308 case HWC2_BLEND_MODE_COVERAGE: return "Coverage";
309 default: return "Unknown";
313 static inline const char* getCallbackDescriptorName(
314 hwc2_callback_descriptor_t desc) {
316 case HWC2_CALLBACK_INVALID: return "Invalid";
317 case HWC2_CALLBACK_HOTPLUG: return "Hotplug";
318 case HWC2_CALLBACK_REFRESH: return "Refresh";
319 case HWC2_CALLBACK_VSYNC: return "Vsync";
320 default: return "Unknown";
324 static inline const char* getCapabilityName(hwc2_capability_t capability) {
325 switch (capability) {
326 case HWC2_CAPABILITY_INVALID: return "Invalid";
327 case HWC2_CAPABILITY_SIDEBAND_STREAM: return "SidebandStream";
328 default: return "Unknown";
332 static inline const char* getCompositionName(hwc2_composition_t composition) {
333 switch (composition) {
334 case HWC2_COMPOSITION_INVALID: return "Invalid";
335 case HWC2_COMPOSITION_CLIENT: return "Client";
336 case HWC2_COMPOSITION_DEVICE: return "Device";
337 case HWC2_COMPOSITION_SOLID_COLOR: return "SolidColor";
338 case HWC2_COMPOSITION_CURSOR: return "Cursor";
339 case HWC2_COMPOSITION_SIDEBAND: return "Sideband";
340 default: return "Unknown";
344 static inline const char* getConnectionName(hwc2_connection_t connection) {
345 switch (connection) {
346 case HWC2_CONNECTION_INVALID: return "Invalid";
347 case HWC2_CONNECTION_CONNECTED: return "Connected";
348 case HWC2_CONNECTION_DISCONNECTED: return "Disconnected";
349 default: return "Unknown";
353 static inline const char* getDisplayRequestName(
354 hwc2_display_request_t request) {
356 case 0: return "None";
357 case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET: return "FlipClientTarget";
358 case HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT:
359 return "WriteClientTargetToOutput";
360 case HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET |
361 HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT:
362 return "FlipClientTarget|WriteClientTargetToOutput";
363 default: return "Unknown";
367 static inline const char* getDisplayTypeName(hwc2_display_type_t type) {
369 case HWC2_DISPLAY_TYPE_INVALID: return "Invalid";
370 case HWC2_DISPLAY_TYPE_PHYSICAL: return "Physical";
371 case HWC2_DISPLAY_TYPE_VIRTUAL: return "Virtual";
372 default: return "Unknown";
376 static inline const char* getErrorName(hwc2_error_t error) {
378 case HWC2_ERROR_NONE: return "None";
379 case HWC2_ERROR_BAD_CONFIG: return "BadConfig";
380 case HWC2_ERROR_BAD_DISPLAY: return "BadDisplay";
381 case HWC2_ERROR_BAD_LAYER: return "BadLayer";
382 case HWC2_ERROR_BAD_PARAMETER: return "BadParameter";
383 case HWC2_ERROR_HAS_CHANGES: return "HasChanges";
384 case HWC2_ERROR_NO_RESOURCES: return "NoResources";
385 case HWC2_ERROR_NOT_VALIDATED: return "NotValidated";
386 case HWC2_ERROR_UNSUPPORTED: return "Unsupported";
387 default: return "Unknown";
391 static inline const char* getFunctionDescriptorName(
392 hwc2_function_descriptor_t desc) {
394 case HWC2_FUNCTION_INVALID: return "Invalid";
395 case HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES:
396 return "AcceptDisplayChanges";
397 case HWC2_FUNCTION_CREATE_LAYER: return "CreateLayer";
398 case HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY:
399 return "CreateVirtualDisplay";
400 case HWC2_FUNCTION_DESTROY_LAYER: return "DestroyLayer";
401 case HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY:
402 return "DestroyVirtualDisplay";
403 case HWC2_FUNCTION_DUMP: return "Dump";
404 case HWC2_FUNCTION_GET_ACTIVE_CONFIG: return "GetActiveConfig";
405 case HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES:
406 return "GetChangedCompositionTypes";
407 case HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT:
408 return "GetClientTargetSupport";
409 case HWC2_FUNCTION_GET_COLOR_MODES: return "GetColorModes";
410 case HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE: return "GetDisplayAttribute";
411 case HWC2_FUNCTION_GET_DISPLAY_CONFIGS: return "GetDisplayConfigs";
412 case HWC2_FUNCTION_GET_DISPLAY_NAME: return "GetDisplayName";
413 case HWC2_FUNCTION_GET_DISPLAY_REQUESTS: return "GetDisplayRequests";
414 case HWC2_FUNCTION_GET_DISPLAY_TYPE: return "GetDisplayType";
415 case HWC2_FUNCTION_GET_DOZE_SUPPORT: return "GetDozeSupport";
416 case HWC2_FUNCTION_GET_HDR_CAPABILITIES: return "GetHdrCapabilities";
417 case HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT:
418 return "GetMaxVirtualDisplayCount";
419 case HWC2_FUNCTION_GET_RELEASE_FENCES: return "GetReleaseFences";
420 case HWC2_FUNCTION_PRESENT_DISPLAY: return "PresentDisplay";
421 case HWC2_FUNCTION_REGISTER_CALLBACK: return "RegisterCallback";
422 case HWC2_FUNCTION_SET_ACTIVE_CONFIG: return "SetActiveConfig";
423 case HWC2_FUNCTION_SET_CLIENT_TARGET: return "SetClientTarget";
424 case HWC2_FUNCTION_SET_COLOR_MODE: return "SetColorMode";
425 case HWC2_FUNCTION_SET_COLOR_TRANSFORM: return "SetColorTransform";
426 case HWC2_FUNCTION_SET_CURSOR_POSITION: return "SetCursorPosition";
427 case HWC2_FUNCTION_SET_LAYER_BLEND_MODE: return "SetLayerBlendMode";
428 case HWC2_FUNCTION_SET_LAYER_BUFFER: return "SetLayerBuffer";
429 case HWC2_FUNCTION_SET_LAYER_COLOR: return "SetLayerColor";
430 case HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE:
431 return "SetLayerCompositionType";
432 case HWC2_FUNCTION_SET_LAYER_DATASPACE: return "SetLayerDataspace";
433 case HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME:
434 return "SetLayerDisplayFrame";
435 case HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA: return "SetLayerPlaneAlpha";
436 case HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM:
437 return "SetLayerSidebandStream";
438 case HWC2_FUNCTION_SET_LAYER_SOURCE_CROP: return "SetLayerSourceCrop";
439 case HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE:
440 return "SetLayerSurfaceDamage";
441 case HWC2_FUNCTION_SET_LAYER_TRANSFORM: return "SetLayerTransform";
442 case HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION:
443 return "SetLayerVisibleRegion";
444 case HWC2_FUNCTION_SET_LAYER_Z_ORDER: return "SetLayerZOrder";
445 case HWC2_FUNCTION_SET_OUTPUT_BUFFER: return "SetOutputBuffer";
446 case HWC2_FUNCTION_SET_POWER_MODE: return "SetPowerMode";
447 case HWC2_FUNCTION_SET_VSYNC_ENABLED: return "SetVsyncEnabled";
448 case HWC2_FUNCTION_VALIDATE_DISPLAY: return "ValidateDisplay";
449 default: return "Unknown";
453 static inline const char* getLayerRequestName(hwc2_layer_request_t request) {
455 case 0: return "None";
456 case HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET: return "ClearClientTarget";
457 default: return "Unknown";
461 static inline const char* getPowerModeName(hwc2_power_mode_t mode) {
463 case HWC2_POWER_MODE_OFF: return "Off";
464 case HWC2_POWER_MODE_DOZE_SUSPEND: return "DozeSuspend";
465 case HWC2_POWER_MODE_DOZE: return "Doze";
466 case HWC2_POWER_MODE_ON: return "On";
467 default: return "Unknown";
471 static inline const char* getTransformName(hwc_transform_t transform) {
473 case 0: return "None";
474 case HWC_TRANSFORM_FLIP_H: return "FlipH";
475 case HWC_TRANSFORM_FLIP_V: return "FlipV";
476 case HWC_TRANSFORM_ROT_90: return "Rotate90";
477 case HWC_TRANSFORM_ROT_180: return "Rotate180";
478 case HWC_TRANSFORM_ROT_270: return "Rotate270";
479 case HWC_TRANSFORM_FLIP_H_ROT_90: return "FlipHRotate90";
480 case HWC_TRANSFORM_FLIP_V_ROT_90: return "FlipVRotate90";
481 default: return "Unknown";
485 static inline const char* getVsyncName(hwc2_vsync_t vsync) {
487 case HWC2_VSYNC_INVALID: return "Invalid";
488 case HWC2_VSYNC_ENABLE: return "Enable";
489 case HWC2_VSYNC_DISABLE: return "Disable";
490 default: return "Unknown";
494 #define TO_STRING(E, T, printer) \
495 inline std::string to_string(E value) { return printer(value); } \
496 inline std::string to_string(T value) { return to_string(static_cast<E>(value)); }
497 #else // !HWC2_INCLUDE_STRINGIFICATION
498 #define TO_STRING(name, printer)
499 #endif // HWC2_INCLUDE_STRINGIFICATION
505 #ifdef HWC2_USE_CPP11
508 #ifdef HWC2_INCLUDE_STRINGIFICATION
514 enum class Attribute : int32_t {
515 Invalid = HWC2_ATTRIBUTE_INVALID,
516 Width = HWC2_ATTRIBUTE_WIDTH,
517 Height = HWC2_ATTRIBUTE_HEIGHT,
518 VsyncPeriod = HWC2_ATTRIBUTE_VSYNC_PERIOD,
519 DpiX = HWC2_ATTRIBUTE_DPI_X,
520 DpiY = HWC2_ATTRIBUTE_DPI_Y,
522 TO_STRING(hwc2_attribute_t, Attribute, getAttributeName)
524 enum class BlendMode : int32_t {
525 Invalid = HWC2_BLEND_MODE_INVALID,
526 None = HWC2_BLEND_MODE_NONE,
527 Premultiplied = HWC2_BLEND_MODE_PREMULTIPLIED,
528 Coverage = HWC2_BLEND_MODE_COVERAGE,
530 TO_STRING(hwc2_blend_mode_t, BlendMode, getBlendModeName)
532 enum class Callback : int32_t {
533 Invalid = HWC2_CALLBACK_INVALID,
534 Hotplug = HWC2_CALLBACK_HOTPLUG,
535 Refresh = HWC2_CALLBACK_REFRESH,
536 Vsync = HWC2_CALLBACK_VSYNC,
538 TO_STRING(hwc2_callback_descriptor_t, Callback, getCallbackDescriptorName)
540 enum class Capability : int32_t {
541 Invalid = HWC2_CAPABILITY_INVALID,
542 SidebandStream = HWC2_CAPABILITY_SIDEBAND_STREAM,
544 TO_STRING(hwc2_capability_t, Capability, getCapabilityName)
546 enum class Composition : int32_t {
547 Invalid = HWC2_COMPOSITION_INVALID,
548 Client = HWC2_COMPOSITION_CLIENT,
549 Device = HWC2_COMPOSITION_DEVICE,
550 SolidColor = HWC2_COMPOSITION_SOLID_COLOR,
551 Cursor = HWC2_COMPOSITION_CURSOR,
552 Sideband = HWC2_COMPOSITION_SIDEBAND,
554 TO_STRING(hwc2_composition_t, Composition, getCompositionName)
556 enum class Connection : int32_t {
557 Invalid = HWC2_CONNECTION_INVALID,
558 Connected = HWC2_CONNECTION_CONNECTED,
559 Disconnected = HWC2_CONNECTION_DISCONNECTED,
561 TO_STRING(hwc2_connection_t, Connection, getConnectionName)
563 enum class DisplayRequest : int32_t {
564 FlipClientTarget = HWC2_DISPLAY_REQUEST_FLIP_CLIENT_TARGET,
565 WriteClientTargetToOutput =
566 HWC2_DISPLAY_REQUEST_WRITE_CLIENT_TARGET_TO_OUTPUT,
568 TO_STRING(hwc2_display_request_t, DisplayRequest, getDisplayRequestName)
570 enum class DisplayType : int32_t {
571 Invalid = HWC2_DISPLAY_TYPE_INVALID,
572 Physical = HWC2_DISPLAY_TYPE_PHYSICAL,
573 Virtual = HWC2_DISPLAY_TYPE_VIRTUAL,
575 TO_STRING(hwc2_display_type_t, DisplayType, getDisplayTypeName)
577 enum class Error : int32_t {
578 None = HWC2_ERROR_NONE,
579 BadConfig = HWC2_ERROR_BAD_CONFIG,
580 BadDisplay = HWC2_ERROR_BAD_DISPLAY,
581 BadLayer = HWC2_ERROR_BAD_LAYER,
582 BadParameter = HWC2_ERROR_BAD_PARAMETER,
583 HasChanges = HWC2_ERROR_HAS_CHANGES,
584 NoResources = HWC2_ERROR_NO_RESOURCES,
585 NotValidated = HWC2_ERROR_NOT_VALIDATED,
586 Unsupported = HWC2_ERROR_UNSUPPORTED,
588 TO_STRING(hwc2_error_t, Error, getErrorName)
590 enum class FunctionDescriptor : int32_t {
591 Invalid = HWC2_FUNCTION_INVALID,
592 AcceptDisplayChanges = HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES,
593 CreateLayer = HWC2_FUNCTION_CREATE_LAYER,
594 CreateVirtualDisplay = HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY,
595 DestroyLayer = HWC2_FUNCTION_DESTROY_LAYER,
596 DestroyVirtualDisplay = HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY,
597 Dump = HWC2_FUNCTION_DUMP,
598 GetActiveConfig = HWC2_FUNCTION_GET_ACTIVE_CONFIG,
599 GetChangedCompositionTypes = HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES,
600 GetClientTargetSupport = HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT,
601 GetColorModes = HWC2_FUNCTION_GET_COLOR_MODES,
602 GetDisplayAttribute = HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE,
603 GetDisplayConfigs = HWC2_FUNCTION_GET_DISPLAY_CONFIGS,
604 GetDisplayName = HWC2_FUNCTION_GET_DISPLAY_NAME,
605 GetDisplayRequests = HWC2_FUNCTION_GET_DISPLAY_REQUESTS,
606 GetDisplayType = HWC2_FUNCTION_GET_DISPLAY_TYPE,
607 GetDozeSupport = HWC2_FUNCTION_GET_DOZE_SUPPORT,
608 GetHdrCapabilities = HWC2_FUNCTION_GET_HDR_CAPABILITIES,
609 GetMaxVirtualDisplayCount = HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT,
610 GetReleaseFences = HWC2_FUNCTION_GET_RELEASE_FENCES,
611 PresentDisplay = HWC2_FUNCTION_PRESENT_DISPLAY,
612 RegisterCallback = HWC2_FUNCTION_REGISTER_CALLBACK,
613 SetActiveConfig = HWC2_FUNCTION_SET_ACTIVE_CONFIG,
614 SetClientTarget = HWC2_FUNCTION_SET_CLIENT_TARGET,
615 SetColorMode = HWC2_FUNCTION_SET_COLOR_MODE,
616 SetColorTransform = HWC2_FUNCTION_SET_COLOR_TRANSFORM,
617 SetCursorPosition = HWC2_FUNCTION_SET_CURSOR_POSITION,
618 SetLayerBlendMode = HWC2_FUNCTION_SET_LAYER_BLEND_MODE,
619 SetLayerBuffer = HWC2_FUNCTION_SET_LAYER_BUFFER,
620 SetLayerColor = HWC2_FUNCTION_SET_LAYER_COLOR,
621 SetLayerCompositionType = HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE,
622 SetLayerDataspace = HWC2_FUNCTION_SET_LAYER_DATASPACE,
623 SetLayerDisplayFrame = HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME,
624 SetLayerPlaneAlpha = HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA,
625 SetLayerSidebandStream = HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM,
626 SetLayerSourceCrop = HWC2_FUNCTION_SET_LAYER_SOURCE_CROP,
627 SetLayerSurfaceDamage = HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE,
628 SetLayerTransform = HWC2_FUNCTION_SET_LAYER_TRANSFORM,
629 SetLayerVisibleRegion = HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION,
630 SetLayerZOrder = HWC2_FUNCTION_SET_LAYER_Z_ORDER,
631 SetOutputBuffer = HWC2_FUNCTION_SET_OUTPUT_BUFFER,
632 SetPowerMode = HWC2_FUNCTION_SET_POWER_MODE,
633 SetVsyncEnabled = HWC2_FUNCTION_SET_VSYNC_ENABLED,
634 ValidateDisplay = HWC2_FUNCTION_VALIDATE_DISPLAY,
636 TO_STRING(hwc2_function_descriptor_t, FunctionDescriptor,
637 getFunctionDescriptorName)
639 enum class LayerRequest : int32_t {
640 ClearClientTarget = HWC2_LAYER_REQUEST_CLEAR_CLIENT_TARGET,
642 TO_STRING(hwc2_layer_request_t, LayerRequest, getLayerRequestName)
644 enum class PowerMode : int32_t {
645 Off = HWC2_POWER_MODE_OFF,
646 DozeSuspend = HWC2_POWER_MODE_DOZE_SUSPEND,
647 Doze = HWC2_POWER_MODE_DOZE,
648 On = HWC2_POWER_MODE_ON,
650 TO_STRING(hwc2_power_mode_t, PowerMode, getPowerModeName)
652 enum class Transform : int32_t {
654 FlipH = HWC_TRANSFORM_FLIP_H,
655 FlipV = HWC_TRANSFORM_FLIP_V,
656 Rotate90 = HWC_TRANSFORM_ROT_90,
657 Rotate180 = HWC_TRANSFORM_ROT_180,
658 Rotate270 = HWC_TRANSFORM_ROT_270,
659 FlipHRotate90 = HWC_TRANSFORM_FLIP_H_ROT_90,
660 FlipVRotate90 = HWC_TRANSFORM_FLIP_V_ROT_90,
662 TO_STRING(hwc_transform_t, Transform, getTransformName)
664 enum class Vsync : int32_t {
665 Invalid = HWC2_VSYNC_INVALID,
666 Enable = HWC2_VSYNC_ENABLE,
667 Disable = HWC2_VSYNC_DISABLE,
669 TO_STRING(hwc2_vsync_t, Vsync, getVsyncName)
674 #endif // HWC2_USE_CPP11
680 typedef void (*hwc2_function_pointer_t)();
682 typedef void* hwc2_callback_data_t;
683 typedef uint32_t hwc2_config_t;
684 typedef uint64_t hwc2_display_t;
685 typedef uint64_t hwc2_layer_t;
691 typedef struct hwc2_device {
692 /* Must be the first member of this struct, since a pointer to this struct
693 * will be generated by casting from a hw_device_t* */
694 struct hw_device_t common;
696 /* getCapabilities(..., outCount, outCapabilities)
698 * Provides a list of capabilities (described in the definition of
699 * hwc2_capability_t above) supported by this device. This list must
700 * not change after the device has been loaded.
703 * outCount - if outCapabilities was NULL, the number of capabilities
704 * which would have been returned; if outCapabilities was not NULL,
705 * the number of capabilities returned, which must not exceed the
706 * value stored in outCount prior to the call
707 * outCapabilities - a list of capabilities supported by this device; may
708 * be NULL, in which case this function must write into outCount the
709 * number of capabilities which would have been written into
712 void (*getCapabilities)(struct hwc2_device* device, uint32_t* outCount,
713 int32_t* /*hwc2_capability_t*/ outCapabilities);
715 /* getFunction(..., descriptor)
717 * Returns a function pointer which implements the requested description.
720 * descriptor - the function to return
722 * Returns either a function pointer implementing the requested descriptor
723 * or NULL if the described function is not supported by this device.
725 hwc2_function_pointer_t (*getFunction)(struct hwc2_device* device,
726 int32_t /*hwc2_function_descriptor_t*/ descriptor);
729 static inline int hwc2_open(const struct hw_module_t* module,
730 hwc2_device_t** device) {
731 return module->methods->open(module, HWC_HARDWARE_COMPOSER,
732 (struct hw_device_t**) device);
735 static inline int hwc2_close(hwc2_device_t* device) {
736 return device->common.close(&device->common);
742 * All of these callbacks take as their first parameter the callbackData which
743 * was provided at the time of callback registration, so this parameter is
744 * omitted from the described parameter lists.
747 /* hotplug(..., display, connected)
748 * Descriptor: HWC2_CALLBACK_HOTPLUG
749 * Will be provided to all HWC2 devices
751 * Notifies the client that the given display has either been connected or
752 * disconnected. Every active display (even a built-in physical display) must
753 * trigger at least one hotplug notification, even if it only occurs immediately
754 * after callback registration.
756 * The client may call back into the device on the same thread to query display
757 * properties (such as width, height, and vsync period), and other threads may
758 * call into the device while the callback is in progress. The device must
759 * serialize calls to this callback such that only one thread is calling it at a
762 * Displays which have been connected are assumed to be in HWC2_POWER_MODE_OFF,
763 * and the vsync callback should not be called for a display until vsync has
764 * been enabled with setVsyncEnabled.
767 * display - the display which has been hotplugged
768 * connected - whether the display has been connected or disconnected
770 typedef void (*HWC2_PFN_HOTPLUG)(hwc2_callback_data_t callbackData,
771 hwc2_display_t display, int32_t /*hwc2_connection_t*/ connected);
773 /* refresh(..., display)
774 * Descriptor: HWC2_CALLBACK_REFRESH
775 * Will be provided to all HWC2 devices
777 * Notifies the client to trigger a screen refresh. This forces all layer state
778 * for this display to be resent, and the display to be validated and presented,
779 * even if there have been no changes.
781 * This refresh will occur some time after the callback is initiated, but not
782 * necessarily before it returns. This thread, however, is guaranteed not to
783 * call back into the device, thus it is safe to trigger this callback from
784 * other functions which call into the device.
787 * display - the display to refresh
789 typedef void (*HWC2_PFN_REFRESH)(hwc2_callback_data_t callbackData,
790 hwc2_display_t display);
792 /* vsync(..., display, timestamp)
793 * Descriptor: HWC2_CALLBACK_VSYNC
794 * Will be provided to all HWC2 devices
796 * Notifies the client that a vsync event has occurred. This callback must
797 * only be triggered when vsync is enabled for this display (through
800 * This callback should be triggered from a thread of at least
801 * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, typically
802 * less than 0.5 ms. This thread is guaranteed not to call back into the device.
805 * display - the display which has received a vsync event
806 * timestamp - the CLOCK_MONOTONIC time at which the vsync event occurred, in
809 typedef void (*HWC2_PFN_VSYNC)(hwc2_callback_data_t callbackData,
810 hwc2_display_t display, int64_t timestamp);
815 * All of these functions take as their first parameter a device pointer, so
816 * this parameter is omitted from the described parameter lists.
819 /* createVirtualDisplay(..., width, height, format, outDisplay)
820 * Descriptor: HWC2_FUNCTION_CREATE_VIRTUAL_DISPLAY
821 * Must be provided by all HWC2 devices
823 * Creates a new virtual display with the given width and height. The format
824 * passed into this function is the default format requested by the consumer of
825 * the virtual display output buffers. If a different format will be returned by
826 * the device, it should be returned in this parameter so it can be set properly
827 * when handing the buffers to the consumer.
829 * The display will be assumed to be on from the time the first frame is
830 * presented until the display is destroyed.
833 * width - width in pixels
834 * height - height in pixels
835 * format - prior to the call, the default output buffer format selected by
836 * the consumer; after the call, the format the device will produce
837 * outDisplay - the newly-created virtual display; pointer will be non-NULL
839 * Returns HWC2_ERROR_NONE or one of the following errors:
840 * HWC2_ERROR_UNSUPPORTED - the width or height is too large for the device to
841 * be able to create a virtual display
842 * HWC2_ERROR_NO_RESOURCES - the device is unable to create a new virtual
843 * display at this time
845 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_VIRTUAL_DISPLAY)(
846 hwc2_device_t* device, uint32_t width, uint32_t height,
847 int32_t* /*android_pixel_format_t*/ format, hwc2_display_t* outDisplay);
849 /* destroyVirtualDisplay(..., display)
850 * Descriptor: HWC2_FUNCTION_DESTROY_VIRTUAL_DISPLAY
851 * Must be provided by all HWC2 devices
853 * Destroys a virtual display. After this call all resources consumed by this
854 * display may be freed by the device and any operations performed on this
855 * display should fail.
858 * display - the virtual display to destroy
860 * Returns HWC2_ERROR_NONE or one of the following errors:
861 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
862 * HWC2_ERROR_BAD_PARAMETER - the display handle which was passed in does not
863 * refer to a virtual display
865 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_VIRTUAL_DISPLAY)(
866 hwc2_device_t* device, hwc2_display_t display);
868 /* dump(..., outSize, outBuffer)
869 * Descriptor: HWC2_FUNCTION_DUMP
870 * Must be provided by all HWC2 devices
872 * Retrieves implementation-defined debug information, which will be displayed
873 * during, for example, `dumpsys SurfaceFlinger`.
875 * If called with outBuffer == NULL, the device should store a copy of the
876 * desired output and return its length in bytes in outSize. If the device
877 * already has a stored copy, that copy should be purged and replaced with a
880 * If called with outBuffer != NULL, the device should copy its stored version
881 * of the output into outBuffer and store how many bytes of data it copied into
882 * outSize. Prior to this call, the client will have populated outSize with the
883 * maximum number of bytes outBuffer can hold. The device must not write more
884 * than this amount into outBuffer. If the device does not currently have a
885 * stored copy, then it should return 0 in outSize.
887 * Any data written into outBuffer need not be null-terminated.
890 * outSize - if outBuffer was NULL, the number of bytes needed to copy the
891 * device's stored output; if outBuffer was not NULL, the number of bytes
892 * written into it, which must not exceed the value stored in outSize
893 * prior to the call; pointer will be non-NULL
894 * outBuffer - the buffer to write the dump output into; may be NULL as
895 * described above; data written into this buffer need not be
898 typedef void (*HWC2_PFN_DUMP)(hwc2_device_t* device, uint32_t* outSize,
901 /* getMaxVirtualDisplayCount(...)
902 * Descriptor: HWC2_FUNCTION_GET_MAX_VIRTUAL_DISPLAY_COUNT
903 * Must be provided by all HWC2 devices
905 * Returns the maximum number of virtual displays supported by this device
906 * (which may be 0). The client will not attempt to create more than this many
907 * virtual displays on this device. This number must not change for the lifetime
910 typedef uint32_t (*HWC2_PFN_GET_MAX_VIRTUAL_DISPLAY_COUNT)(
911 hwc2_device_t* device);
913 /* registerCallback(..., descriptor, callbackData, pointer)
914 * Descriptor: HWC2_FUNCTION_REGISTER_CALLBACK
915 * Must be provided by all HWC2 devices
917 * Provides a callback for the device to call. All callbacks take a callbackData
918 * item as the first parameter, so this value should be stored with the callback
919 * for later use. The callbackData may differ from one callback to another. If
920 * this function is called multiple times with the same descriptor, later
921 * callbacks replace earlier ones.
924 * descriptor - which callback should be set
925 * callBackdata - opaque data which must be passed back through the callback
926 * pointer - a non-NULL function pointer corresponding to the descriptor
928 * Returns HWC2_ERROR_NONE or one of the following errors:
929 * HWC2_ERROR_BAD_PARAMETER - descriptor was invalid
931 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_REGISTER_CALLBACK)(
932 hwc2_device_t* device,
933 int32_t /*hwc2_callback_descriptor_t*/ descriptor,
934 hwc2_callback_data_t callbackData, hwc2_function_pointer_t pointer);
939 * All of these functions take as their first two parameters a device pointer
940 * and a display handle, so these parameters are omitted from the described
944 /* acceptDisplayChanges(...)
945 * Descriptor: HWC2_FUNCTION_ACCEPT_DISPLAY_CHANGES
946 * Must be provided by all HWC2 devices
948 * Accepts the changes required by the device from the previous validateDisplay
949 * call (which may be queried using getChangedCompositionTypes) and revalidates
950 * the display. This function is equivalent to requesting the changed types from
951 * getChangedCompositionTypes, setting those types on the corresponding layers,
952 * and then calling validateDisplay again.
954 * After this call it must be valid to present this display. Calling this after
955 * validateDisplay returns 0 changes must succeed with HWC2_ERROR_NONE, but
956 * should have no other effect.
958 * Returns HWC2_ERROR_NONE or one of the following errors:
959 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
960 * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called
962 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_ACCEPT_DISPLAY_CHANGES)(
963 hwc2_device_t* device, hwc2_display_t display);
965 /* createLayer(..., outLayer)
966 * Descriptor: HWC2_FUNCTION_CREATE_LAYER
967 * Must be provided by all HWC2 devices
969 * Creates a new layer on the given display.
972 * outLayer - the handle of the new layer; pointer will be non-NULL
974 * Returns HWC2_ERROR_NONE or one of the following errors:
975 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
976 * HWC2_ERROR_NO_RESOURCES - the device was unable to create this layer
978 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_CREATE_LAYER)(hwc2_device_t* device,
979 hwc2_display_t display, hwc2_layer_t* outLayer);
981 /* destroyLayer(..., layer)
982 * Descriptor: HWC2_FUNCTION_DESTROY_LAYER
983 * Must be provided by all HWC2 devices
985 * Destroys the given layer.
988 * layer - the handle of the layer to destroy
990 * Returns HWC2_ERROR_NONE or one of the following errors:
991 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
992 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
994 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_DESTROY_LAYER)(
995 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer);
997 /* getActiveConfig(..., outConfig)
998 * Descriptor: HWC2_FUNCTION_GET_ACTIVE_CONFIG
999 * Must be provided by all HWC2 devices
1001 * Retrieves which display configuration is currently active.
1003 * If no display configuration is currently active, this function must return
1004 * HWC2_ERROR_BAD_CONFIG and place no configuration handle in outConfig. It is
1005 * the responsibility of the client to call setActiveConfig with a valid
1006 * configuration before attempting to present anything on the display.
1009 * outConfig - the currently active display configuration; pointer will be
1012 * Returns HWC2_ERROR_NONE or one of the following errors:
1013 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1014 * HWC2_ERROR_BAD_CONFIG - no configuration is currently active
1016 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_ACTIVE_CONFIG)(
1017 hwc2_device_t* device, hwc2_display_t display,
1018 hwc2_config_t* outConfig);
1020 /* getChangedCompositionTypes(..., outNumElements, outLayers, outTypes)
1021 * Descriptor: HWC2_FUNCTION_GET_CHANGED_COMPOSITION_TYPES
1022 * Must be provided by all HWC2 devices
1024 * Retrieves the layers for which the device requires a different composition
1025 * type than had been set prior to the last call to validateDisplay. The client
1026 * will either update its state with these types and call acceptDisplayChanges,
1027 * or will set new types and attempt to validate the display again.
1029 * outLayers and outTypes may be NULL to retrieve the number of elements which
1030 * will be returned. The number of elements returned must be the same as the
1031 * value returned in outNumTypes from the last call to validateDisplay.
1034 * outNumElements - if outLayers or outTypes were NULL, the number of layers
1035 * and types which would have been returned; if both were non-NULL, the
1036 * number of elements returned in outLayers and outTypes, which must not
1037 * exceed the value stored in outNumElements prior to the call; pointer
1039 * outLayers - an array of layer handles
1040 * outTypes - an array of composition types, each corresponding to an element
1043 * Returns HWC2_ERROR_NONE or one of the following errors:
1044 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1045 * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this
1048 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CHANGED_COMPOSITION_TYPES)(
1049 hwc2_device_t* device, hwc2_display_t display,
1050 uint32_t* outNumElements, hwc2_layer_t* outLayers,
1051 int32_t* /*hwc2_composition_t*/ outTypes);
1053 /* getClientTargetSupport(..., width, height, format, dataspace)
1054 * Descriptor: HWC2_FUNCTION_GET_CLIENT_TARGET_SUPPORT
1055 * Must be provided by all HWC2 devices
1057 * Returns whether a client target with the given properties can be handled by
1060 * The valid formats can be found in android_pixel_format_t in
1061 * <system/graphics.h>.
1063 * For more about dataspaces, see setLayerDataspace.
1065 * This function must return true for a client target with width and height
1066 * equal to the active display configuration dimensions,
1067 * HAL_PIXEL_FORMAT_RGBA_8888, and HAL_DATASPACE_UNKNOWN. It is not required to
1068 * return true for any other configuration.
1071 * width - client target width in pixels
1072 * height - client target height in pixels
1073 * format - client target format
1074 * dataspace - client target dataspace, as described in setLayerDataspace
1076 * Returns HWC2_ERROR_NONE if the given configuration is supported or one of the
1078 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1079 * HWC2_ERROR_UNSUPPORTED - the given configuration is not supported
1081 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_CLIENT_TARGET_SUPPORT)(
1082 hwc2_device_t* device, hwc2_display_t display, uint32_t width,
1083 uint32_t height, int32_t /*android_pixel_format_t*/ format,
1084 int32_t /*android_dataspace_t*/ dataspace);
1086 /* getColorModes(..., outNumModes, outModes)
1087 * Descriptor: HWC2_FUNCTION_GET_COLOR_MODES
1088 * Must be provided by all HWC2 devices
1090 * Returns the color modes supported on this display.
1092 * The valid color modes can be found in android_color_mode_t in
1093 * <system/graphics.h>. All HWC2 devices must support at least
1094 * HAL_COLOR_MODE_NATIVE.
1096 * outNumModes may be NULL to retrieve the number of modes which will be
1100 * outNumModes - if outModes was NULL, the number of modes which would have
1101 * been returned; if outModes was not NULL, the number of modes returned,
1102 * which must not exceed the value stored in outNumModes prior to the
1103 * call; pointer will be non-NULL
1104 * outModes - an array of color modes
1106 * Returns HWC2_ERROR_NONE or one of the following errors:
1107 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1109 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_COLOR_MODES)(
1110 hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumModes,
1111 int32_t* /*android_color_mode_t*/ outModes);
1113 /* getDisplayAttribute(..., config, attribute, outValue)
1114 * Descriptor: HWC2_FUNCTION_GET_DISPLAY_ATTRIBUTE
1115 * Must be provided by all HWC2 devices
1117 * Returns a display attribute value for a particular display configuration.
1119 * Any attribute which is not supported or for which the value is unknown by the
1120 * device must return a value of -1.
1123 * config - the display configuration for which to return attribute values
1124 * attribute - the attribute to query
1125 * outValue - the value of the attribute; the pointer will be non-NULL
1127 * Returns HWC2_ERROR_NONE or one of the following errors:
1128 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1129 * HWC2_ERROR_BAD_CONFIG - config does not name a valid configuration for this
1132 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_ATTRIBUTE)(
1133 hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config,
1134 int32_t /*hwc2_attribute_t*/ attribute, int32_t* outValue);
1136 /* getDisplayConfigs(..., outNumConfigs, outConfigs)
1137 * Descriptor: HWC2_FUNCTION_GET_DISPLAY_CONFIGS
1138 * Must be provided by all HWC2 devices
1140 * Returns handles for all of the valid display configurations on this display.
1142 * outConfigs may be NULL to retrieve the number of elements which will be
1146 * outNumConfigs - if outConfigs was NULL, the number of configurations which
1147 * would have been returned; if outConfigs was not NULL, the number of
1148 * configurations returned, which must not exceed the value stored in
1149 * outNumConfigs prior to the call; pointer will be non-NULL
1150 * outConfigs - an array of configuration handles
1152 * Returns HWC2_ERROR_NONE or one of the following errors:
1153 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1155 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_CONFIGS)(
1156 hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumConfigs,
1157 hwc2_config_t* outConfigs);
1159 /* getDisplayName(..., outSize, outName)
1160 * Descriptor: HWC2_FUNCTION_GET_DISPLAY_NAME
1161 * Must be provided by all HWC2 devices
1163 * Returns a human-readable version of the display's name.
1165 * outName may be NULL to retrieve the length of the name.
1168 * outSize - if outName was NULL, the number of bytes needed to return the
1169 * name if outName was not NULL, the number of bytes written into it,
1170 * which must not exceed the value stored in outSize prior to the call;
1171 * pointer will be non-NULL
1172 * outName - the display's name
1174 * Returns HWC2_ERROR_NONE or one of the following errors:
1175 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1177 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_NAME)(
1178 hwc2_device_t* device, hwc2_display_t display, uint32_t* outSize,
1181 /* getDisplayRequests(..., outDisplayRequests, outNumElements, outLayers,
1183 * Descriptor: HWC2_FUNCTION_GET_DISPLAY_REQUESTS
1184 * Must be provided by all HWC2 devices
1186 * Returns the display requests and the layer requests required for the last
1187 * validated configuration.
1189 * Display requests provide information about how the client should handle the
1190 * client target. Layer requests provide information about how the client
1191 * should handle an individual layer.
1193 * If outLayers or outLayerRequests is NULL, the required number of layers and
1194 * requests must be returned in outNumElements, but this number may also be
1195 * obtained from validateDisplay as outNumRequests (outNumElements must be equal
1196 * to the value returned in outNumRequests from the last call to
1200 * outDisplayRequests - the display requests for the current validated state
1201 * outNumElements - if outLayers or outLayerRequests were NULL, the number of
1202 * elements which would have been returned, which must be equal to the
1203 * value returned in outNumRequests from the last validateDisplay call on
1204 * this display; if both were not NULL, the number of elements in
1205 * outLayers and outLayerRequests, which must not exceed the value stored
1206 * in outNumElements prior to the call; pointer will be non-NULL
1207 * outLayers - an array of layers which all have at least one request
1208 * outLayerRequests - the requests corresponding to each element of outLayers
1210 * Returns HWC2_ERROR_NONE or one of the following errors:
1211 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1212 * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not been called for this
1215 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_REQUESTS)(
1216 hwc2_device_t* device, hwc2_display_t display,
1217 int32_t* /*hwc2_display_request_t*/ outDisplayRequests,
1218 uint32_t* outNumElements, hwc2_layer_t* outLayers,
1219 int32_t* /*hwc2_layer_request_t*/ outLayerRequests);
1221 /* getDisplayType(..., outType)
1222 * Descriptor: HWC2_FUNCTION_GET_DISPLAY_TYPE
1223 * Must be provided by all HWC2 devices
1225 * Returns whether the given display is a physical or virtual display.
1228 * outType - the type of the display; pointer will be non-NULL
1230 * Returns HWC2_ERROR_NONE or one of the following errors:
1231 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1233 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DISPLAY_TYPE)(
1234 hwc2_device_t* device, hwc2_display_t display,
1235 int32_t* /*hwc2_display_type_t*/ outType);
1237 /* getDozeSupport(..., outSupport)
1238 * Descriptor: HWC2_FUNCTION_GET_DOZE_SUPPORT
1239 * Must be provided by all HWC2 devices
1241 * Returns whether the given display supports HWC2_POWER_MODE_DOZE and
1242 * HWC2_POWER_MODE_DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit over
1243 * DOZE (see the definition of hwc2_power_mode_t for more information), but if
1244 * both DOZE and DOZE_SUSPEND are no different from HWC2_POWER_MODE_ON, the
1245 * device should not claim support.
1248 * outSupport - whether the display supports doze modes (1 for yes, 0 for no);
1249 * pointer will be non-NULL
1251 * Returns HWC2_ERROR_NONE or one of the following errors:
1252 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1254 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_DOZE_SUPPORT)(
1255 hwc2_device_t* device, hwc2_display_t display, int32_t* outSupport);
1257 /* getHdrCapabilities(..., outNumTypes, outTypes, outMaxLuminance,
1258 * outMaxAverageLuminance, outMinLuminance)
1259 * Descriptor: HWC2_FUNCTION_GET_HDR_CAPABILITIES
1260 * Must be provided by all HWC2 devices
1262 * Returns the high dynamic range (HDR) capabilities of the given display, which
1263 * are invariant with regard to the active configuration.
1265 * Displays which are not HDR-capable must return no types in outTypes and set
1268 * If outTypes is NULL, the required number of HDR types must be returned in
1272 * outNumTypes - if outTypes was NULL, the number of types which would have
1273 * been returned; if it was not NULL, the number of types stored in
1274 * outTypes, which must not exceed the value stored in outNumTypes prior
1275 * to the call; pointer will be non-NULL
1276 * outTypes - an array of HDR types, may have 0 elements if the display is not
1278 * outMaxLuminance - the desired content maximum luminance for this display in
1279 * cd/m^2; pointer will be non-NULL
1280 * outMaxAverageLuminance - the desired content maximum frame-average
1281 * luminance for this display in cd/m^2; pointer will be non-NULL
1282 * outMinLuminance - the desired content minimum luminance for this display in
1283 * cd/m^2; pointer will be non-NULL
1285 * Returns HWC2_ERROR_NONE or one of the following errors:
1286 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1288 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_HDR_CAPABILITIES)(
1289 hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumTypes,
1290 int32_t* /*android_hdr_t*/ outTypes, float* outMaxLuminance,
1291 float* outMaxAverageLuminance, float* outMinLuminance);
1293 /* getReleaseFences(..., outNumElements, outLayers, outFences)
1294 * Descriptor: HWC2_FUNCTION_GET_RELEASE_FENCES
1295 * Must be provided by all HWC2 devices
1297 * Retrieves the release fences for device layers on this display which will
1298 * receive new buffer contents this frame.
1300 * A release fence is a file descriptor referring to a sync fence object which
1301 * will be signaled after the device has finished reading from the buffer
1302 * presented in the prior frame. This indicates that it is safe to start writing
1303 * to the buffer again. If a given layer's fence is not returned from this
1304 * function, it will be assumed that the buffer presented on the previous frame
1305 * is ready to be written.
1307 * The fences returned by this function should be unique for each layer (even if
1308 * they point to the same underlying sync object), and ownership of the fences
1309 * is transferred to the client, which is responsible for closing them.
1311 * If outLayers or outFences is NULL, the required number of layers and fences
1312 * must be returned in outNumElements.
1315 * outNumElements - if outLayers or outFences were NULL, the number of
1316 * elements which would have been returned; if both were not NULL, the
1317 * number of elements in outLayers and outFences, which must not exceed
1318 * the value stored in outNumElements prior to the call; pointer will be
1320 * outLayers - an array of layer handles
1321 * outFences - an array of sync fence file descriptors as described above,
1322 * each corresponding to an element of outLayers
1324 * Returns HWC2_ERROR_NONE or one of the following errors:
1325 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1327 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_GET_RELEASE_FENCES)(
1328 hwc2_device_t* device, hwc2_display_t display, uint32_t* outNumElements,
1329 hwc2_layer_t* outLayers, int32_t* outFences);
1331 /* presentDisplay(..., outPresentFence)
1332 * Descriptor: HWC2_FUNCTION_PRESENT_DISPLAY
1333 * Must be provided by all HWC2 devices
1335 * Presents the current display contents on the screen (or in the case of
1336 * virtual displays, into the output buffer).
1338 * Prior to calling this function, the display must be successfully validated
1339 * with validateDisplay. Note that setLayerBuffer and setLayerSurfaceDamage
1340 * specifically do not count as layer state, so if there are no other changes
1341 * to the layer state (or to the buffer's properties as described in
1342 * setLayerBuffer), then it is safe to call this function without first
1343 * validating the display.
1345 * If this call succeeds, outPresentFence will be populated with a file
1346 * descriptor referring to a present sync fence object. For physical displays,
1347 * this fence will be signaled at the vsync when the result of composition of
1348 * this frame starts to appear (for video-mode panels) or starts to transfer to
1349 * panel memory (for command-mode panels). For virtual displays, this fence will
1350 * be signaled when writes to the output buffer have completed and it is safe to
1354 * outPresentFence - a sync fence file descriptor as described above; pointer
1357 * Returns HWC2_ERROR_NONE or one of the following errors:
1358 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1359 * HWC2_ERROR_NO_RESOURCES - no valid output buffer has been set for a virtual
1361 * HWC2_ERROR_NOT_VALIDATED - validateDisplay has not successfully been called
1364 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_PRESENT_DISPLAY)(
1365 hwc2_device_t* device, hwc2_display_t display,
1366 int32_t* outPresentFence);
1368 /* setActiveConfig(..., config)
1369 * Descriptor: HWC2_FUNCTION_SET_ACTIVE_CONFIG
1370 * Must be provided by all HWC2 devices
1372 * Sets the active configuration for this display. Upon returning, the given
1373 * display configuration should be active and remain so until either this
1374 * function is called again or the display is disconnected.
1377 * config - the new display configuration
1379 * Returns HWC2_ERROR_NONE or one of the following errors:
1380 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1381 * HWC2_ERROR_BAD_CONFIG - the configuration handle passed in is not valid for
1384 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_ACTIVE_CONFIG)(
1385 hwc2_device_t* device, hwc2_display_t display, hwc2_config_t config);
1387 /* setClientTarget(..., target, acquireFence, dataspace, damage)
1388 * Descriptor: HWC2_FUNCTION_SET_CLIENT_TARGET
1389 * Must be provided by all HWC2 devices
1391 * Sets the buffer handle which will receive the output of client composition.
1392 * Layers marked as HWC2_COMPOSITION_CLIENT will be composited into this buffer
1393 * prior to the call to presentDisplay, and layers not marked as
1394 * HWC2_COMPOSITION_CLIENT should be composited with this buffer by the device.
1396 * The buffer handle provided may be null if no layers are being composited by
1397 * the client. This must not result in an error (unless an invalid display
1398 * handle is also provided).
1400 * Also provides a file descriptor referring to an acquire sync fence object,
1401 * which will be signaled when it is safe to read from the client target buffer.
1402 * If it is already safe to read from this buffer, -1 may be passed instead.
1403 * The device must ensure that it is safe for the client to close this file
1404 * descriptor at any point after this function is called.
1406 * For more about dataspaces, see setLayerDataspace.
1408 * The damage parameter describes a surface damage region as defined in the
1409 * description of setLayerSurfaceDamage.
1411 * Will be called before presentDisplay if any of the layers are marked as
1412 * HWC2_COMPOSITION_CLIENT. If no layers are so marked, then it is not
1413 * necessary to call this function. It is not necessary to call validateDisplay
1414 * after changing the target through this function.
1417 * target - the new target buffer
1418 * acquireFence - a sync fence file descriptor as described above
1419 * dataspace - the dataspace of the buffer, as described in setLayerDataspace
1420 * damage - the surface damage region
1422 * Returns HWC2_ERROR_NONE or one of the following errors:
1423 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1424 * HWC2_ERROR_BAD_PARAMETER - the new target handle was invalid
1426 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CLIENT_TARGET)(
1427 hwc2_device_t* device, hwc2_display_t display, buffer_handle_t target,
1428 int32_t acquireFence, int32_t /*android_dataspace_t*/ dataspace,
1429 hwc_region_t damage);
1431 /* setColorMode(..., mode)
1432 * Descriptor: HWC2_FUNCTION_SET_COLOR_MODE
1433 * Must be provided by all HWC2 devices
1435 * Sets the color mode of the given display.
1437 * Upon returning from this function, the color mode change must have fully
1440 * The valid color modes can be found in android_color_mode_t in
1441 * <system/graphics.h>. All HWC2 devices must support at least
1442 * HAL_COLOR_MODE_NATIVE, and displays are assumed to be in this mode upon
1446 * mode - the mode to set
1448 * Returns HWC2_ERROR_NONE or one of the following errors:
1449 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1450 * HWC2_ERROR_BAD_PARAMETER - mode is not a valid color mode
1451 * HWC2_ERROR_UNSUPPORTED - mode is not supported on this display
1453 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_MODE)(
1454 hwc2_device_t* device, hwc2_display_t display,
1455 int32_t /*android_color_mode_t*/ mode);
1457 /* setColorTransform(..., matrix, hint)
1458 * Descriptor: HWC2_FUNCTION_SET_COLOR_TRANSFORM
1459 * Must be provided by all HWC2 devices
1461 * Sets a color transform which will be applied after composition.
1463 * If hint is not HAL_COLOR_TRANSFORM_ARBITRARY, then the device may use the
1464 * hint to apply the desired color transform instead of using the color matrix
1467 * If the device is not capable of either using the hint or the matrix to apply
1468 * the desired color transform, it should force all layers to client composition
1469 * during validateDisplay.
1471 * The matrix provided is an affine color transformation of the following form:
1478 * This matrix will be provided in row-major form: {r.r, r.g, r.b, 0, g.r, ...}.
1480 * Given a matrix of this form and an input color [R_in, G_in, B_in], the output
1481 * color [R_out, G_out, B_out] will be:
1483 * R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr
1484 * G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg
1485 * B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb
1488 * matrix - a 4x4 transform matrix (16 floats) as described above
1489 * hint - a hint value which may be used instead of the given matrix unless it
1490 * is HAL_COLOR_TRANSFORM_ARBITRARY
1492 * Returns HWC2_ERROR_NONE or one of the following errors:
1493 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1494 * HWC2_ERROR_BAD_PARAMETER - hint is not a valid color transform hint
1496 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_COLOR_TRANSFORM)(
1497 hwc2_device_t* device, hwc2_display_t display, const float* matrix,
1498 int32_t /*android_color_transform_t*/ hint);
1500 /* setOutputBuffer(..., buffer, releaseFence)
1501 * Descriptor: HWC2_FUNCTION_SET_OUTPUT_BUFFER
1502 * Must be provided by all HWC2 devices
1504 * Sets the output buffer for a virtual display. That is, the buffer to which
1505 * the composition result will be written.
1507 * Also provides a file descriptor referring to a release sync fence object,
1508 * which will be signaled when it is safe to write to the output buffer. If it
1509 * is already safe to write to the output buffer, -1 may be passed instead. The
1510 * device must ensure that it is safe for the client to close this file
1511 * descriptor at any point after this function is called.
1513 * Must be called at least once before presentDisplay, but does not have any
1514 * interaction with layer state or display validation.
1517 * buffer - the new output buffer
1518 * releaseFence - a sync fence file descriptor as described above
1520 * Returns HWC2_ERROR_NONE or one of the following errors:
1521 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1522 * HWC2_ERROR_BAD_PARAMETER - the new output buffer handle was invalid
1523 * HWC2_ERROR_UNSUPPORTED - display does not refer to a virtual display
1525 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_OUTPUT_BUFFER)(
1526 hwc2_device_t* device, hwc2_display_t display, buffer_handle_t buffer,
1527 int32_t releaseFence);
1529 /* setPowerMode(..., mode)
1530 * Descriptor: HWC2_FUNCTION_SET_POWER_MODE
1531 * Must be provided by all HWC2 devices
1533 * Sets the power mode of the given display. The transition must be complete
1534 * when this function returns. It is valid to call this function multiple times
1535 * with the same power mode.
1537 * All displays must support HWC2_POWER_MODE_ON and HWC2_POWER_MODE_OFF. Whether
1538 * a display supports HWC2_POWER_MODE_DOZE or HWC2_POWER_MODE_DOZE_SUSPEND may
1539 * be queried using getDozeSupport.
1542 * mode - the new power mode
1544 * Returns HWC2_ERROR_NONE or one of the following errors:
1545 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1546 * HWC2_ERROR_BAD_PARAMETER - mode was not a valid power mode
1547 * HWC2_ERROR_UNSUPPORTED - mode was a valid power mode, but is not supported
1550 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_POWER_MODE)(
1551 hwc2_device_t* device, hwc2_display_t display,
1552 int32_t /*hwc2_power_mode_t*/ mode);
1554 /* setVsyncEnabled(..., enabled)
1555 * Descriptor: HWC2_FUNCTION_SET_VSYNC_ENABLED
1556 * Must be provided by all HWC2 devices
1558 * Enables or disables the vsync signal for the given display. Virtual displays
1559 * never generate vsync callbacks, and any attempt to enable vsync for a virtual
1560 * display though this function must return HWC2_ERROR_NONE and have no other
1564 * enabled - whether to enable or disable vsync
1566 * Returns HWC2_ERROR_NONE or one of the following errors:
1567 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1568 * HWC2_ERROR_BAD_PARAMETER - enabled was an invalid value
1570 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_VSYNC_ENABLED)(
1571 hwc2_device_t* device, hwc2_display_t display,
1572 int32_t /*hwc2_vsync_t*/ enabled);
1574 /* validateDisplay(..., outNumTypes, outNumRequests)
1575 * Descriptor: HWC2_FUNCTION_VALIDATE_DISPLAY
1576 * Must be provided by all HWC2 devices
1578 * Instructs the device to inspect all of the layer state and determine if
1579 * there are any composition type changes necessary before presenting the
1580 * display. Permitted changes are described in the definition of
1581 * hwc2_composition_t above.
1583 * Also returns the number of layer requests required
1584 * by the given layer configuration.
1587 * outNumTypes - the number of composition type changes required by the
1588 * device; if greater than 0, the client must either set and validate new
1589 * types, or call acceptDisplayChanges to accept the changes returned by
1590 * getChangedCompositionTypes; must be the same as the number of changes
1591 * returned by getChangedCompositionTypes (see the declaration of that
1592 * function for more information); pointer will be non-NULL
1593 * outNumRequests - the number of layer requests required by this layer
1594 * configuration; must be equal to the number of layer requests returned
1595 * by getDisplayRequests (see the declaration of that function for
1596 * more information); pointer will be non-NULL
1598 * Returns HWC2_ERROR_NONE if no changes are necessary and it is safe to present
1599 * the display using the current layer state. Otherwise returns one of the
1601 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1602 * HWC2_ERROR_HAS_CHANGES - outNumTypes was greater than 0 (see parameter list
1603 * for more information)
1605 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_VALIDATE_DISPLAY)(
1606 hwc2_device_t* device, hwc2_display_t display,
1607 uint32_t* outNumTypes, uint32_t* outNumRequests);
1612 * These are functions which operate on layers, but which do not modify state
1613 * that must be validated before use. See also 'Layer State Functions' below.
1615 * All of these functions take as their first three parameters a device pointer,
1616 * a display handle for the display which contains the layer, and a layer
1617 * handle, so these parameters are omitted from the described parameter lists.
1620 /* setCursorPosition(..., x, y)
1621 * Descriptor: HWC2_FUNCTION_SET_CURSOR_POSITION
1622 * Must be provided by all HWC2 devices
1624 * Asynchonously sets the position of a cursor layer.
1626 * Prior to validateDisplay, a layer may be marked as HWC2_COMPOSITION_CURSOR.
1627 * If validation succeeds (i.e., the device does not request a composition
1628 * change for that layer), then once a buffer has been set for the layer and it
1629 * has been presented, its position may be set by this function at any time
1630 * between presentDisplay and any subsequent validateDisplay calls for this
1633 * Once validateDisplay is called, this function will not be called again until
1634 * the validate/present sequence is completed.
1636 * May be called from any thread so long as it is not interleaved with the
1637 * validate/present sequence as described above.
1640 * x - the new x coordinate (in pixels from the left of the screen)
1641 * y - the new y coordinate (in pixels from the top of the screen)
1643 * Returns HWC2_ERROR_NONE or one of the following errors:
1644 * HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
1645 * HWC2_ERROR_BAD_LAYER - the layer is invalid or is not currently marked as
1646 * HWC2_COMPOSITION_CURSOR
1647 * HWC2_ERROR_NOT_VALIDATED - the device is currently in the middle of the
1648 * validate/present sequence
1650 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_CURSOR_POSITION)(
1651 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1652 int32_t x, int32_t y);
1654 /* setLayerBuffer(..., buffer, acquireFence)
1655 * Descriptor: HWC2_FUNCTION_SET_LAYER_BUFFER
1656 * Must be provided by all HWC2 devices
1658 * Sets the buffer handle to be displayed for this layer. If the buffer
1659 * properties set at allocation time (width, height, format, and usage) have not
1660 * changed since the previous frame, it is not necessary to call validateDisplay
1661 * before calling presentDisplay unless new state needs to be validated in the
1664 * Also provides a file descriptor referring to an acquire sync fence object,
1665 * which will be signaled when it is safe to read from the given buffer. If it
1666 * is already safe to read from the buffer, -1 may be passed instead. The
1667 * device must ensure that it is safe for the client to close this file
1668 * descriptor at any point after this function is called.
1670 * This function must return HWC2_ERROR_NONE and have no other effect if called
1671 * for a layer with a composition type of HWC2_COMPOSITION_SOLID_COLOR (because
1672 * it has no buffer) or HWC2_COMPOSITION_SIDEBAND or HWC2_COMPOSITION_CLIENT
1673 * (because synchronization and buffer updates for these layers are handled
1677 * buffer - the buffer handle to set
1678 * acquireFence - a sync fence file descriptor as described above
1680 * Returns HWC2_ERROR_NONE or one of the following errors:
1681 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1682 * HWC2_ERROR_BAD_PARAMETER - the buffer handle passed in was invalid
1684 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BUFFER)(
1685 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1686 buffer_handle_t buffer, int32_t acquireFence);
1688 /* setLayerSurfaceDamage(..., damage)
1689 * Descriptor: HWC2_FUNCTION_SET_LAYER_SURFACE_DAMAGE
1690 * Must be provided by all HWC2 devices
1692 * Provides the region of the source buffer which has been modified since the
1693 * last frame. This region does not need to be validated before calling
1696 * Once set through this function, the damage region remains the same until a
1697 * subsequent call to this function.
1699 * If damage.numRects > 0, then it may be assumed that any portion of the source
1700 * buffer not covered by one of the rects has not been modified this frame. If
1701 * damage.numRects == 0, then the whole source buffer must be treated as if it
1702 * has been modified.
1704 * If the layer's contents are not modified relative to the prior frame, damage
1705 * will contain exactly one empty rect([0, 0, 0, 0]).
1707 * The damage rects are relative to the pre-transformed buffer, and their origin
1708 * is the top-left corner. They will not exceed the dimensions of the latched
1712 * damage - the new surface damage region
1714 * Returns HWC2_ERROR_NONE or one of the following errors:
1715 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1717 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SURFACE_DAMAGE)(
1718 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1719 hwc_region_t damage);
1722 * Layer State Functions
1724 * These functions modify the state of a given layer. They do not take effect
1725 * until the display configuration is successfully validated with
1726 * validateDisplay and the display contents are presented with presentDisplay.
1728 * All of these functions take as their first three parameters a device pointer,
1729 * a display handle for the display which contains the layer, and a layer
1730 * handle, so these parameters are omitted from the described parameter lists.
1733 /* setLayerBlendMode(..., mode)
1734 * Descriptor: HWC2_FUNCTION_SET_LAYER_BLEND_MODE
1735 * Must be provided by all HWC2 devices
1737 * Sets the blend mode of the given layer.
1740 * mode - the new blend mode
1742 * Returns HWC2_ERROR_NONE or one of the following errors:
1743 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1744 * HWC2_ERROR_BAD_PARAMETER - an invalid blend mode was passed in
1746 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_BLEND_MODE)(
1747 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1748 int32_t /*hwc2_blend_mode_t*/ mode);
1750 /* setLayerColor(..., color)
1751 * Descriptor: HWC2_FUNCTION_SET_LAYER_COLOR
1752 * Must be provided by all HWC2 devices
1754 * Sets the color of the given layer. If the composition type of the layer is
1755 * not HWC2_COMPOSITION_SOLID_COLOR, this call must return HWC2_ERROR_NONE and
1756 * have no other effect.
1759 * color - the new color
1761 * Returns HWC2_ERROR_NONE or one of the following errors:
1762 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1764 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COLOR)(
1765 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1768 /* setLayerCompositionType(..., type)
1769 * Descriptor: HWC2_FUNCTION_SET_LAYER_COMPOSITION_TYPE
1770 * Must be provided by all HWC2 devices
1772 * Sets the desired composition type of the given layer. During validateDisplay,
1773 * the device may request changes to the composition types of any of the layers
1774 * as described in the definition of hwc2_composition_t above.
1777 * type - the new composition type
1779 * Returns HWC2_ERROR_NONE or one of the following errors:
1780 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1781 * HWC2_ERROR_BAD_PARAMETER - an invalid composition type was passed in
1782 * HWC2_ERROR_UNSUPPORTED - a valid composition type was passed in, but it is
1783 * not supported by this device
1785 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_COMPOSITION_TYPE)(
1786 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1787 int32_t /*hwc2_composition_t*/ type);
1789 /* setLayerDataspace(..., dataspace)
1790 * Descriptor: HWC2_FUNCTION_SET_LAYER_DATASPACE
1791 * Must be provided by all HWC2 devices
1793 * Sets the dataspace that the current buffer on this layer is in.
1795 * The dataspace provides more information about how to interpret the buffer
1796 * contents, such as the encoding standard and color transform.
1798 * See the values of android_dataspace_t in <system/graphics.h> for more
1802 * dataspace - the new dataspace
1804 * Returns HWC2_ERROR_NONE or one of the following errors:
1805 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1807 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DATASPACE)(
1808 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1809 int32_t /*android_dataspace_t*/ dataspace);
1811 /* setLayerDisplayFrame(..., frame)
1812 * Descriptor: HWC2_FUNCTION_SET_LAYER_DISPLAY_FRAME
1813 * Must be provided by all HWC2 devices
1815 * Sets the display frame (the portion of the display covered by a layer) of the
1816 * given layer. This frame will not exceed the display dimensions.
1819 * frame - the new display frame
1821 * Returns HWC2_ERROR_NONE or one of the following errors:
1822 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1824 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_DISPLAY_FRAME)(
1825 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1828 /* setLayerPlaneAlpha(..., alpha)
1829 * Descriptor: HWC2_FUNCTION_SET_LAYER_PLANE_ALPHA
1830 * Must be provided by all HWC2 devices
1832 * Sets an alpha value (a floating point value in the range [0.0, 1.0]) which
1833 * will be applied to the whole layer. It can be conceptualized as a
1834 * preprocessing step which applies the following function:
1835 * if (blendMode == HWC2_BLEND_MODE_PREMULTIPLIED)
1836 * out.rgb = in.rgb * planeAlpha
1837 * out.a = in.a * planeAlpha
1839 * If the device does not support this operation on a layer which is marked
1840 * HWC2_COMPOSITION_DEVICE, it must request a composition type change to
1841 * HWC2_COMPOSITION_CLIENT upon the next validateDisplay call.
1844 * alpha - the plane alpha value to apply
1846 * Returns HWC2_ERROR_NONE or one of the following errors:
1847 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1849 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_PLANE_ALPHA)(
1850 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1853 /* setLayerSidebandStream(..., stream)
1854 * Descriptor: HWC2_FUNCTION_SET_LAYER_SIDEBAND_STREAM
1855 * Provided by HWC2 devices which support HWC2_CAPABILITY_SIDEBAND_STREAM
1857 * Sets the sideband stream for this layer. If the composition type of the given
1858 * layer is not HWC2_COMPOSITION_SIDEBAND, this call must return HWC2_ERROR_NONE
1859 * and have no other effect.
1862 * stream - the new sideband stream
1864 * Returns HWC2_ERROR_NONE or one of the following errors:
1865 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1866 * HWC2_ERROR_BAD_PARAMETER - an invalid sideband stream was passed in
1868 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SIDEBAND_STREAM)(
1869 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1870 const native_handle_t* stream);
1872 /* setLayerSourceCrop(..., crop)
1873 * Descriptor: HWC2_FUNCTION_SET_LAYER_SOURCE_CROP
1874 * Must be provided by all HWC2 devices
1876 * Sets the source crop (the portion of the source buffer which will fill the
1877 * display frame) of the given layer. This crop rectangle will not exceed the
1878 * dimensions of the latched buffer.
1880 * If the device is not capable of supporting a true float source crop (i.e., it
1881 * will truncate or round the floats to integers), it should set this layer to
1882 * HWC2_COMPOSITION_CLIENT when crop is non-integral for the most accurate
1885 * If the device cannot support float source crops, but still wants to handle
1886 * the layer, it should use the following code (or similar) to convert to
1888 * intCrop.left = (int) ceilf(crop.left);
1889 * intCrop.top = (int) ceilf(crop.top);
1890 * intCrop.right = (int) floorf(crop.right);
1891 * intCrop.bottom = (int) floorf(crop.bottom);
1894 * crop - the new source crop
1896 * Returns HWC2_ERROR_NONE or one of the following errors:
1897 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1899 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_SOURCE_CROP)(
1900 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1903 /* setLayerTransform(..., transform)
1904 * Descriptor: HWC2_FUNCTION_SET_LAYER_TRANSFORM
1905 * Must be provided by all HWC2 devices
1907 * Sets the transform (rotation/flip) of the given layer.
1910 * transform - the new transform
1912 * Returns HWC2_ERROR_NONE or one of the following errors:
1913 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1914 * HWC2_ERROR_BAD_PARAMETER - an invalid transform was passed in
1916 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_TRANSFORM)(
1917 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1918 int32_t /*hwc_transform_t*/ transform);
1920 /* setLayerVisibleRegion(..., visible)
1921 * Descriptor: HWC2_FUNCTION_SET_LAYER_VISIBLE_REGION
1922 * Must be provided by all HWC2 devices
1924 * Specifies the portion of the layer that is visible, including portions under
1925 * translucent areas of other layers. The region is in screen space, and will
1926 * not exceed the dimensions of the screen.
1929 * visible - the new visible region, in screen space
1931 * Returns HWC2_ERROR_NONE or one of the following errors:
1932 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1934 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_VISIBLE_REGION)(
1935 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,
1936 hwc_region_t visible);
1938 /* setLayerZOrder(..., z)
1939 * Descriptor: HWC2_FUNCTION_SET_LAYER_Z_ORDER
1940 * Must be provided by all HWC2 devices
1942 * Sets the desired Z order (height) of the given layer. A layer with a greater
1943 * Z value occludes a layer with a lesser Z value.
1946 * z - the new Z order
1948 * Returns HWC2_ERROR_NONE or one of the following errors:
1949 * HWC2_ERROR_BAD_LAYER - an invalid layer handle was passed in
1951 typedef int32_t /*hwc2_error_t*/ (*HWC2_PFN_SET_LAYER_Z_ORDER)(
1952 hwc2_device_t* device, hwc2_display_t display, hwc2_layer_t layer,