1 /* 2 * Copyright 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <android/data_space.h> 20 #include <android/hardware_buffer.h> 21 #include <inttypes.h> 22 23 // TODO: the intention of these apis is to be stable - hence they are defined in 24 // an apex directory. But because they don't yet need to be stable, hold off on 25 // making them stable until a Mainline module needs them. 26 // __BEGIN_DECLS 27 28 namespace android { 29 30 /** 31 * Opaque handle for a native display 32 */ 33 typedef struct ADisplay ADisplay; 34 35 /** 36 * Enum describing the possible types of a display 37 */ 38 enum ADisplayType { 39 /** 40 * A display that is the internal, or "primary" display for a device. 41 */ 42 DISPLAY_TYPE_INTERNAL = 0, 43 44 /** 45 * A display that is externally connected for a device. 46 */ 47 DISPLAY_TYPE_EXTERNAL = 1, 48 }; 49 50 /** 51 * Opaque handle for display metadata 52 */ 53 typedef struct ADisplayConfig ADisplayConfig; 54 55 /** 56 * Acquires a list of display handles. Memory is allocated for the list and is 57 * owned by the caller. The caller is responsible for freeing this memory by 58 * calling ADisplayList_release. 59 * 60 * Returns the size of the returned list on success. 61 * Returns -errno on error. 62 */ 63 int ADisplay_acquirePhysicalDisplays(ADisplay*** outDisplays); 64 65 /** 66 * Releases a list of display handles created by 67 * ADisplayList_acquirePhysicalDisplays. 68 */ 69 void ADisplay_release(ADisplay** displays); 70 71 /** 72 * Queries the maximum supported fps for the given display. 73 */ 74 float ADisplay_getMaxSupportedFps(ADisplay* display); 75 76 /** 77 * Queries the display's type. 78 */ 79 ADisplayType ADisplay_getDisplayType(ADisplay* display); 80 81 /** 82 * Queries the display's preferred WCG format 83 */ 84 void ADisplay_getPreferredWideColorFormat(ADisplay* display, ADataSpace* outDataspace, 85 AHardwareBuffer_Format* outPixelFormat); 86 87 /** 88 * Gets the current display configuration for the given display. 89 * 90 * Memory is *not* allocated for the caller. As such, the returned output 91 * configuration's lifetime will not be longer than the ADisplay* passed to this 92 * function - if ADisplay_release is called destroying the ADisplay object then 93 * it is invalid to access the ADisplayConfig returned here. 94 * 95 * Note that the current display configuration can change. Listening to updates 96 * to the current display configuration should be done via Choreographer. If 97 * such an update is observed, then this method should be recalled to get the 98 * new current configuration. 99 * 100 * After a subsequent hotplug "connected" event the supported display configs 101 * may change. Then the preloaded display configs will be stale and the 102 * call for current config may return NAME_NOT_FOUND. In this case the client 103 * should release and re-acquire the display handle. 104 * 105 * Returns OK on success, -errno on failure. 106 */ 107 int ADisplay_getCurrentConfig(ADisplay* display, ADisplayConfig** outConfig); 108 109 /** 110 * Queries the width in pixels for a given display configuration. 111 */ 112 int32_t ADisplayConfig_getWidth(ADisplayConfig* config); 113 114 /** 115 * Queries the height in pixels for a given display configuration. 116 */ 117 int32_t ADisplayConfig_getHeight(ADisplayConfig* config); 118 119 /** 120 * Queries the display refresh rate for a given display configuration. 121 */ 122 float ADisplayConfig_getFps(ADisplayConfig* config); 123 124 /** 125 * Queries the vsync offset from which the system compositor is scheduled to 126 * run. If a vsync occurs at time T, and the compositor runs at time T + S, then 127 * this returns S in nanoseconds. 128 */ 129 int64_t ADisplayConfig_getCompositorOffsetNanos(ADisplayConfig* config); 130 131 /** 132 * Queries the vsync offset from which applications are scheduled to run. If a 133 * vsync occurs at time T, and applications run at time T + S, then this returns 134 * S in nanoseconds. 135 */ 136 int64_t ADisplayConfig_getAppVsyncOffsetNanos(ADisplayConfig* config); 137 138 } // namespace android 139 // __END_DECLS 140