1/* 2 * Copyright (C) 2016 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 17package android.hardware.graphics.mapper@2.0; 18 19import android.hardware.graphics.common@1.0; 20 21interface IMapper { 22 struct BufferDescriptorInfo { 23 /** 24 * The width specifies how many columns of pixels must be in the 25 * allocated buffer, but does not necessarily represent the offset in 26 * columns between the same column in adjacent rows. The rows may be 27 * padded. 28 */ 29 uint32_t width; 30 31 /** 32 * The height specifies how many rows of pixels must be in the 33 * allocated buffer. 34 */ 35 uint32_t height; 36 37 /** 38 * The number of image layers that must be in the allocated buffer. 39 */ 40 uint32_t layerCount; 41 42 /** Buffer pixel format. */ 43 PixelFormat format; 44 45 /** 46 * Buffer usage mask; valid flags can be found in the definition of 47 * BufferUsage. 48 */ 49 bitfield<BufferUsage> usage; 50 }; 51 52 struct Rect { 53 int32_t left; 54 int32_t top; 55 int32_t width; 56 int32_t height; 57 }; 58 59 /** 60 * Creates a buffer descriptor. The descriptor can be used with IAllocator 61 * to allocate buffers. 62 * 63 * Since the buffer descriptor fully describes a buffer, any device 64 * dependent or device independent checks must be performed here whenever 65 * possible. Specifically, when layered buffers are not supported, this 66 * function must return UNSUPPORTED if layerCount is great than 1. 67 * 68 * @param descriptorInfo specifies the attributes of the descriptor. 69 * @return error is NONE upon success. Otherwise, 70 * BAD_VALUE when any of the specified attributes is 71 * invalid or conflicting. 72 * NO_RESOURCES when the creation cannot be fullfilled at 73 * this time. 74 * UNSUPPORTED when any of the specified attributes is 75 * not supported. 76 * @return descriptor is the newly created buffer descriptor. 77 */ 78 @entry 79 @callflow(next="*") 80 createDescriptor(BufferDescriptorInfo descriptorInfo) 81 generates (Error error, 82 BufferDescriptor descriptor); 83 84 /** 85 * Imports a raw buffer handle to create an imported buffer handle for use 86 * with the rest of the mapper or with other in-process libraries. 87 * 88 * A buffer handle is considered raw when it is cloned (e.g., with 89 * native_handle_clone) from another buffer handle locally, or when it is 90 * received from another HAL server/client or another process. A raw 91 * buffer handle must not be used to access the underlying graphics 92 * buffer. It must be imported to create an imported handle first. 93 * 94 * This function must at least validate the raw handle before creating the 95 * imported handle. It must also support importing the same raw handle 96 * multiple times to create multiple imported handles. The imported handle 97 * must be considered valid everywhere in the process, including in 98 * another instance of the mapper. 99 * 100 * Because of passthrough HALs, a raw buffer handle received from a HAL 101 * may actually have been imported in the process. importBuffer must treat 102 * such a handle as if it is raw and must not return BAD_BUFFER. The 103 * returned handle is independent from the input handle as usual, and 104 * freeBuffer must be called on it when it is no longer needed. 105 * 106 * @param rawHandle is the raw buffer handle to import. 107 * @return error is NONE upon success. Otherwise, 108 * BAD_BUFFER when the raw handle is invalid. 109 * NO_RESOURCES when the raw handle cannot be imported at 110 * this time. 111 * @return buffer is the imported buffer handle and has the type 112 * buffer_handle_t. 113 */ 114 @entry 115 @callflow(next="*") 116 importBuffer(handle rawHandle) generates (Error error, pointer buffer); 117 118 /** 119 * Frees a buffer handle. Buffer handles returned by importBuffer must be 120 * freed with this function when no longer needed. 121 * 122 * This function must free up all resources allocated by importBuffer for 123 * the imported handle. For example, if the imported handle was created 124 * with native_handle_create, this function must call native_handle_close 125 * and native_handle_delete. 126 * 127 * @return error is NONE upon success. Otherwise, 128 * BAD_BUFFER when the buffer is invalid. 129 */ 130 @exit 131 @callflow(next="*") 132 freeBuffer(pointer buffer) generates (Error error); 133 134 /** 135 * Locks the given buffer for the specified CPU usage. 136 * 137 * Locking the same buffer simultaneously from multiple threads is 138 * permitted, but if any of the threads attempt to lock the buffer for 139 * writing, the behavior is undefined, except that it must not cause 140 * process termination or block the client indefinitely. Leaving the 141 * buffer content in an indeterminate state or returning an error are both 142 * acceptable. 143 * 144 * The client must not modify the content of the buffer outside of 145 * accessRegion, and the device need not guarantee that content outside of 146 * accessRegion is valid for reading. The result of reading or writing 147 * outside of accessRegion is undefined, except that it must not cause 148 * process termination. 149 * 150 * data will be filled with a pointer to the locked buffer memory. This 151 * address will represent the top-left corner of the entire buffer, even 152 * if accessRegion does not begin at the top-left corner. 153 * 154 * @param buffer is the buffer to lock. 155 * @param cpuUsage specifies one or more CPU usage flags to request. 156 * @param accessRegion is the portion of the buffer that the client 157 * intends to access. 158 * @param acquireFence when non-empty, is a handle containing a file 159 * descriptor referring to a sync fence object, which will be 160 * signaled when it is safe for the mapper to lock the buffer. If 161 * it is already safe to lock, acquireFence is empty. 162 * @return error is NONE upon success. Otherwise, 163 * BAD_BUFFER when the buffer is invalid or is 164 * incompatible with this function. 165 * BAD_VALUE when cpuUsage is 0, contains non-CPU usage 166 * flags, or is incompatible with the buffer. 167 * NO_RESOURCES when the buffer cannot be locked at this 168 * time, but locking may succeed at a future 169 * time. 170 * @return data is a CPU-accessible pointer to the buffer data. 171 */ 172 @callflow(next="unlock") 173 lock(pointer buffer, 174 bitfield<BufferUsage> cpuUsage, 175 Rect accessRegion, 176 handle acquireFence) 177 generates (Error error, 178 pointer data); 179 180 /** 181 * This is largely the same as lock(), except that instead of returning a 182 * pointer directly to the buffer data, it returns an YCbCrLayout struct 183 * describing how to access the data planes. 184 * 185 * This function must work on buffers with PixelFormat::YCbCr_*_888 if 186 * supported by the device, as well as with any other formats requested by 187 * multimedia codecs when they are configured with a 188 * flexible-YUV-compatible color format. 189 * 190 * @param buffer is the buffer to lock. 191 * @param cpuUsage specifies one or more CPU usage flags to request. 192 * @param accessRegion is the portion of the buffer that the client 193 * intends to access. 194 * @param acquireFence when non-empty, is a handle containing a file 195 * descriptor referring to a sync fence object, which will be 196 * signaled when it is safe for the mapper to lock the buffer. If 197 * it is already safe to lock, acquireFence is empty. 198 * @return error is NONE upon success. Otherwise, 199 * BAD_BUFFER when the buffer is invalid or is 200 * incompatible with this function. 201 * BAD_VALUE when cpuUsage is 0, contains non-CPU usage 202 * flags, or is incompatible with the buffer. 203 * NO_RESOURCES when the buffer cannot be locked at this 204 * time, but locking may succeed at a future 205 * time. 206 * @return layout is the data layout of the buffer. 207 */ 208 @callflow(next="unlock") 209 lockYCbCr(pointer buffer, 210 bitfield<BufferUsage> cpuUsage, 211 Rect accessRegion, 212 handle acquireFence) 213 generates (Error error, 214 YCbCrLayout layout); 215 216 /** 217 * Unlocks a buffer to indicate all CPU accesses to the buffer have 218 * completed. 219 * 220 * @param buffer is the buffer to unlock. 221 * @return error is NONE upon success. Otherwise, 222 * BAD_BUFFER when the buffer is invalid or not locked. 223 * @return releaseFence, when non-empty, is a handle containing a file 224 * descriptor referring to a sync fence object. The sync fence 225 * object will be signaled when the mapper has completed any 226 * pending work. 227 */ 228 @callflow(next="*") 229 unlock(pointer buffer) 230 generates (Error error, 231 handle releaseFence); 232}; 233