1/*
2 * Copyright 2017 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.1;
18
19import android.hardware.graphics.common@1.1::BufferUsage;
20import android.hardware.graphics.common@1.1::PixelFormat;
21import @2.0::BufferDescriptor;
22import @2.0::Error;
23import @2.0::IMapper;
24
25interface IMapper extends @2.0::IMapper {
26    /**
27     * This is the same as @2.0::IMapper::BufferDescriptorInfo except that it
28     * accepts @1.1::PixelFormat and @1.1::BufferUsage.
29     */
30    struct BufferDescriptorInfo {
31        /**
32         * The width specifies how many columns of pixels must be in the
33         * allocated buffer, but does not necessarily represent the offset in
34         * columns between the same column in adjacent rows. The rows may be
35         * padded.
36         */
37        uint32_t width;
38
39       /**
40        * The height specifies how many rows of pixels must be in the
41        * allocated buffer.
42        */
43        uint32_t height;
44
45       /**
46        * The number of image layers that must be in the allocated buffer.
47        */
48        uint32_t layerCount;
49
50        /** Buffer pixel format. */
51        PixelFormat format;
52
53        /**
54         * Buffer usage mask; valid flags can be found in the definition of
55         * BufferUsage.
56         */
57        bitfield<BufferUsage> usage;
58    };
59
60    /**
61     * Validate that the buffer can be safely accessed by a caller who assumes
62     * the specified descriptorInfo and stride. This must at least validate
63     * that the buffer size is large enough. Validating the buffer against
64     * individual buffer attributes is optional.
65     *
66     * @param buffer is the buffer to validate against.
67     * @param descriptorInfo specifies the attributes of the buffer.
68     * @param stride is the buffer stride returned by IAllocator::allocate.
69     * @return error is NONE upon success. Otherwise,
70     *                  BAD_BUFFER when the buffer is invalid.
71     *                  BAD_VALUE when buffer cannot be safely accessed
72     */
73    validateBufferSize(pointer buffer,
74                       BufferDescriptorInfo descriptorInfo,
75                       uint32_t stride)
76            generates (Error error);
77
78    /**
79     * Get the transport size of a buffer. An imported buffer handle is a raw
80     * buffer handle with the process-local runtime data appended. This
81     * function, for example, allows a caller to omit the process-local
82     * runtime data at the tail when serializing the imported buffer handle.
83     *
84     * Note that a client might or might not omit the process-local runtime
85     * data when sending an imported buffer handle. The mapper must support
86     * both cases on the receiving end.
87     *
88     * @param buffer is the buffer to get the transport size from.
89     * @return error is NONE upon success. Otherwise,
90     *                  BAD_BUFFER when the buffer is invalid.
91     * @return numFds is the number of file descriptors needed for transport.
92     * @return numInts is the number of integers needed for transport.
93     */
94    getTransportSize(pointer buffer)
95            generates (Error error,
96                       uint32_t numFds,
97                       uint32_t numInts);
98
99    /**
100     * This is the same as @2.0::IMapper::createDescriptor except that it
101     * accepts @2.1::IMapper::BufferDescriptorInfo.
102     *
103     * Creates a buffer descriptor. The descriptor can be used with IAllocator
104     * to allocate buffers.
105     *
106     * Since the buffer descriptor fully describes a buffer, any device
107     * dependent or device independent checks must be performed here whenever
108     * possible. Specifically, when layered buffers are not supported, this
109     * function must return UNSUPPORTED if layerCount is great than 1.
110     *
111     * @param descriptorInfo specifies the attributes of the descriptor.
112     * @return error is NONE upon success. Otherwise,
113     *                  BAD_VALUE when any of the specified attributes is
114     *                            invalid or conflicting.
115     *                  NO_RESOURCES when the creation cannot be fullfilled at
116     *                               this time.
117     *                  UNSUPPORTED when any of the specified attributes is
118     *                              not supported.
119     * @return descriptor is the newly created buffer descriptor.
120     */
121    createDescriptor_2_1(BufferDescriptorInfo descriptorInfo)
122              generates (Error error,
123                         BufferDescriptor descriptor);
124};
125