blob: 8ca568f275679d8aa90640ffdbefbbeced5e72f4 [file] [log] [blame]
Chia-I Wua7f234c2016-11-22 11:37:04 +08001/*
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.allocator@2.0;
18
19import android.hardware.graphics.common@1.0::PixelFormat;
20
21interface IAllocatorClient {
22 struct BufferDescriptorInfo {
Andreas Huber40d3a9b2017-03-28 16:19:16 -070023 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080024 * 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
Andreas Huber40d3a9b2017-03-28 16:19:16 -070031 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080032 * The height specifies how many rows of pixels must be in the
33 * allocated buffer.
34 */
35 uint32_t height;
36
Andreas Huber40d3a9b2017-03-28 16:19:16 -070037 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080038 * The number of image layers that must be in the allocated buffer.
39 */
40 uint32_t layerCount;
41
Andreas Huber40d3a9b2017-03-28 16:19:16 -070042 /** Buffer pixel format. */
Chia-I Wua7f234c2016-11-22 11:37:04 +080043 PixelFormat format;
44
Andreas Huber40d3a9b2017-03-28 16:19:16 -070045 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080046 * Buffer producer usage mask; valid flags can be found in the
47 * definition of ProducerUsage.
48 */
49 uint64_t producerUsageMask;
50
Andreas Huber40d3a9b2017-03-28 16:19:16 -070051 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080052 * Buffer consumer usage mask; valid flags can be found in the
53 * definition of ConsumerUsage.
54 */
55 uint64_t consumerUsageMask;
56 };
57
Andreas Huber40d3a9b2017-03-28 16:19:16 -070058 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080059 * Creates a new, opaque buffer descriptor.
60 *
61 * @param descriptorInfo specifies the attributes of the buffer
62 * descriptor.
63 * @return error is NONE upon success. Otherwise,
64 * BAD_VALUE when any attribute in descriptorInfo is invalid.
65 * NO_RESOURCES when no more descriptors can currently be created.
66 * @return descriptor is the newly created buffer descriptor.
67 */
68 @entry
69 @callflow(next="*")
70 createDescriptor(BufferDescriptorInfo descriptorInfo)
71 generates (Error error,
72 BufferDescriptor descriptor);
73
Andreas Huber40d3a9b2017-03-28 16:19:16 -070074 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080075 * Destroys an existing buffer descriptor.
76 *
77 * @param descriptor is the descriptor to destroy.
78 * @return error is either NONE or BAD_DESCRIPTOR.
79 */
80 @exit
81 @callflow(next="*")
82 destroyDescriptor(BufferDescriptor descriptor) generates (Error error);
83
Andreas Huber40d3a9b2017-03-28 16:19:16 -070084 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +080085 * Tests whether a buffer allocation can succeed, ignoring potential
86 * resource contention which might lead to a NO_RESOURCES error.
87 *
88 * @param descriptors is a list of buffer descriptors.
89 * @return error is NONE or NOT_SHARED upon success;
90 * NONE when buffers can be created and share a backing store.
91 * NOT_SHARED when buffers can be created but require more than a
92 * backing store.
93 * Otherwise,
94 * BAD_DESCRIPTOR when any of the descriptors is invalid.
95 * UNSUPPORTED when any of the descriptors can never be satisfied.
96 * UNDEFINED when TEST_ALLOCATE is not listed in getCapabilities.
97 */
98 @callflow(next="allocate")
99 testAllocate(vec<BufferDescriptor> descriptors) generates (Error error);
100
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700101 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +0800102 * Attempts to allocate a list of buffers sharing a backing store.
103 *
104 * Each buffer must correspond to one of the descriptors passed into the
105 * function and must hold a reference to its backing store. If the device
106 * is unable to share the backing store between the buffers, it must
107 * attempt to allocate the buffers with different backing stores and
108 * return NOT_SHARED if it is successful.
109 *
110 * @param descriptors is the buffer descriptors to attempt to allocate.
111 * @return error is NONE or NOT_SHARED upon success;
112 * NONE when buffers can be created and share a backing store.
113 * NOT_SHARED when buffers can be created but require more than a
114 * backing store.
115 * Otherwise,
116 * BAD_DESCRIPTOR when any of the descriptors is invalid.
117 * UNSUPPORTED when any of the descriptors can never be satisfied.
118 * NO_RESOURCES when any of the buffers cannot be created at this
119 * time.
120 * @return buffers is the allocated buffers.
121 */
122 @callflow(next="exportHandle")
123 allocate(vec<BufferDescriptor> descriptors)
124 generates (Error error,
125 vec<Buffer> buffers);
126
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700127 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +0800128 * Frees a buffer.
129 *
130 * @param buffer is the buffer to be freed.
131 * @return error is NONE upon success. Otherwise,
132 * BAD_BUFFER when the buffer is invalid.
133 */
134 @exit
135 @callflow(next="*")
136 free(Buffer buffer) generates (Error error);
137
Andreas Huber40d3a9b2017-03-28 16:19:16 -0700138 /**
Chia-I Wua7f234c2016-11-22 11:37:04 +0800139 * Exports a buffer for use in other client libraries or for cross-process
140 * sharing.
141 *
142 * The exported handle is a handle to the backing store of the buffer, not
143 * to the buffer itself. It however may not hold any reference to the
144 * backing store and may be considered invalid by client libraries. To use
145 * it and, in most cases, to save it for later use, a client must make a
146 * clone of the handle and have the cloned handle hold a reference to the
147 * backing store. Such a cloned handle will stay valid even after the
148 * original buffer is freed. Refer to native_handle_clone and IMapper for
149 * how a handle is cloned and how a reference is added.
150 *
151 * @param descriptor is the descriptor used to allocate the buffer.
152 * @param buffer is the buffer to be exported.
153 * @return error is NONE upon success. Otherwise,
154 * BAD_DESCRIPTOR when the descriptor is invalid.
155 * BAD_BUFFER when the buffer is invalid.
156 * BAD_VALUE when descriptor and buffer do not match.
157 * NO_RESOURCES when the buffer cannot be exported at this time.
158 * @return bufferHandle is the exported handle.
159 */
160 @callflow(next="free")
161 exportHandle(BufferDescriptor descriptor,
162 Buffer buffer)
163 generates (Error error,
164 handle bufferHandle);
165};