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 * An accessRegion of all-zeros means the entire buffer. That is, it is 151 * equivalent to '(0,0)-(buffer width, buffer height)'. 152 * 153 * data will be filled with a pointer to the locked buffer memory. This 154 * address will represent the top-left corner of the entire buffer, even 155 * if accessRegion does not begin at the top-left corner. 156 * 157 * @param buffer is the buffer to lock. 158 * @param cpuUsage specifies one or more CPU usage flags to request. 159 * @param accessRegion is the portion of the buffer that the client 160 * intends to access. 161 * @param acquireFence when non-empty, is a handle containing a file 162 * descriptor referring to a sync fence object, which will be 163 * signaled when it is safe for the mapper to lock the buffer. If 164 * it is already safe to lock, acquireFence is empty. 165 * @return error is NONE upon success. Otherwise, 166 * BAD_BUFFER when the buffer is invalid or is 167 * incompatible with this function. 168 * BAD_VALUE when cpuUsage is 0, contains non-CPU usage 169 * flags, or is incompatible with the buffer. 170 * NO_RESOURCES when the buffer cannot be locked at this 171 * time, but locking may succeed at a future 172 * time. 173 * @return data is a CPU-accessible pointer to the buffer data. 174 */ 175 @callflow(next="unlock") 176 lock(pointer buffer, 177 bitfield<BufferUsage> cpuUsage, 178 Rect accessRegion, 179 handle acquireFence) 180 generates (Error error, 181 pointer data); 182 183 /** 184 * This is largely the same as lock(), except that instead of returning a 185 * pointer directly to the buffer data, it returns an YCbCrLayout struct 186 * describing how to access the data planes. 187 * 188 * This function must work on buffers with PixelFormat::YCbCr_*_888 if 189 * supported by the device, as well as with any other formats requested by 190 * multimedia codecs when they are configured with a 191 * flexible-YUV-compatible color format. 192 * 193 * @param buffer is the buffer to lock. 194 * @param cpuUsage specifies one or more CPU usage flags to request. 195 * @param accessRegion is the portion of the buffer that the client 196 * intends to access. 197 * @param acquireFence when non-empty, is a handle containing a file 198 * descriptor referring to a sync fence object, which will be 199 * signaled when it is safe for the mapper to lock the buffer. If 200 * it is already safe to lock, acquireFence is empty. 201 * @return error is NONE upon success. Otherwise, 202 * BAD_BUFFER when the buffer is invalid or is 203 * incompatible with this function. 204 * BAD_VALUE when cpuUsage is 0, contains non-CPU usage 205 * flags, or is incompatible with the buffer. 206 * NO_RESOURCES when the buffer cannot be locked at this 207 * time, but locking may succeed at a future 208 * time. 209 * @return layout is the data layout of the buffer. 210 */ 211 @callflow(next="unlock") 212 lockYCbCr(pointer buffer, 213 bitfield<BufferUsage> cpuUsage, 214 Rect accessRegion, 215 handle acquireFence) 216 generates (Error error, 217 YCbCrLayout layout); 218 219 /** 220 * Unlocks a buffer to indicate all CPU accesses to the buffer have 221 * completed. 222 * 223 * @param buffer is the buffer to unlock. 224 * @return error is NONE upon success. Otherwise, 225 * BAD_BUFFER when the buffer is invalid or not locked. 226 * @return releaseFence, when non-empty, is a handle containing a file 227 * descriptor referring to a sync fence object. The sync fence 228 * object will be signaled when the mapper has completed any 229 * pending work. 230 */ 231 @callflow(next="*") 232 unlock(pointer buffer) 233 generates (Error error, 234 handle releaseFence); 235}; 236