summaryrefslogtreecommitdiffstats
blob: dcd9c8d04a4a67a64d53a911d5b89cee20251742 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.graphics.composer@2.2;

import android.hardware.graphics.common@1.0::PixelFormat;
import android.hardware.graphics.common@1.0::Dataspace;
import @2.1::IComposerClient;
import @2.1::Display;
import @2.1::Error;

interface IComposerClient extends @2.1::IComposerClient {

    enum PowerMode : @2.1::IComposerClient.PowerMode {
        /**
         * The display is configured as in ON but may stop applying display
         * updates from the client. This is effectively a hint to the device
         * that drawing to the display has been suspended and that the the
         * device must remain on and continue displaying its current contents
         * indefinitely until the power mode changes.
         *
         * This mode may also be used as a signal to enable hardware-based
         * functionality to take over the display and manage it autonomously
         * to implement a low power always-on display.
         */
        ON_SUSPEND = 4
    };

    /**
     * Following enums define keys for metadata defined by SMPTE ST 2086:2014
     * and CTA 861.3.
     */
    enum PerFrameMetadataKey : int32_t {
        /** SMPTE ST 2084:2014.
         * Coordinates defined in CIE 1931 xy chromaticity space
         */
        /** SMPTE ST 2084:2014 */
        DISPLAY_RED_PRIMARY_X,
        /** SMPTE ST 2084:2014 */
        DISPLAY_RED_PRIMARY_Y,
        /** SMPTE ST 2084:2014 */
        DISPLAY_GREEN_PRIMARY_X,
        /** SMPTE ST 2084:2014 */
        DISPLAY_GREEN_PRIMARY_Y,
        /** SMPTE ST 2084:2014 */
        DISPLAY_BLUE_PRIMARY_X,
        /** SMPTE ST 2084:2014 */
        DISPLAY_BLUE_PRIMARY_Y,
        /** SMPTE ST 2084:2014 */
        WHITE_POINT_X,
        /** SMPTE ST 2084:2014 */
        WHITE_POINT_Y,
        /** SMPTE ST 2084:2014.
         * Units: nits
         * max as defined by ST 2048: 10,000 nits
         */
        MAX_LUMINANCE,
        /** SMPTE ST 2084:2014 */
        MIN_LUMINANCE,
        /** CTA 861.3 */
        MAX_CONTENT_LIGHT_LEVEL,
        /** CTA 861.3 */
        MAX_FRAME_AVERAGE_LIGHT_LEVEL,
    };

    struct PerFrameMetadata {
        PerFrameMetadataKey key;
        float value;
    };

    struct FloatColor {
        float r;
        float g;
        float b;
        float a;
    };

    enum Command : @2.1::IComposerClient.Command {
        /**
         * setPerFrameMetadata(Display display, vec<PerFrameMetadata> data)
         * Sets the PerFrameMetadata for the display. This metadata must be used
         * by the implementation to better tone map content to that display.
         *
         * This is a method that may be called every frame. Thus it's
         * implemented using buffered transport.
         * SET_PER_FRAME_METADATA is the command used by the buffered transport
         * mechanism.
         */
        SET_PER_FRAME_METADATA = 0x207 << @2.1::IComposerClient.Command:OPCODE_SHIFT,

        /**
         * SET_LAYER_COLOR has this pseudo prototype
         *
         *   setLayerColor(FloatColor color);
         *
         * Sets the color of the given layer. If the composition type of the layer
         * is not Composition::SOLID_COLOR, this call must succeed and have no
         * other effect.
         *
         * @param color is the new color using float type.
         */
        SET_LAYER_FLOAT_COLOR = 0x40c << @2.1::IComposerClient.Command:OPCODE_SHIFT,
    };

    /**
     * Returns the PerFrameMetadataKeys that are supported by this device.
     *
     * @param display is the display on which to create the layer.
     * @return keys is the vector of PerFrameMetadataKey keys that are
     *        supported by this device.
     * @return error is NONE upon success. Otherwise,
     *         UNSUPPORTED if not supported on underlying HAL
     */
    getPerFrameMetadataKeys(Display display)
        generates (Error error,
                   vec<PerFrameMetadataKey> keys);

    /**
     * getReadbackBufferAttributes
     * Returns the format which should be used when allocating a buffer for use by
     * device readback as well as the dataspace in which its contents should be
     * interpreted.
     *
     * The width and height of this buffer must be those of the currently-active
     * display configuration, and the usage flags must consist of the following:
     *   BufferUsage::CPU_READ | BufferUsage::GPU_TEXTURE |
     *   BufferUsage::COMPOSER_OUTPUT
     *
     * The format and dataspace provided must be sufficient such that if a
     * correctly-configured buffer is passed into setReadbackBuffer, filled by
     * the device, and then displayed by the client as a full-screen buffer, the
     * output of the display remains the same (subject to the note about protected
     * content in the description of setReadbackBuffer).
     *
     * Parameters:
     * @param display - the display on which to create the layer.
     *
     * @return format - the format the client should use when allocating a device
     *       readback buffer
     * @return dataspace - the dataspace to use when interpreting the
     *       contents of a device readback buffer
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         UNSUPPORTED if not supported on underlying HAL
     *
     * See also:
     *   setReadbackBuffer
     *   getReadbackBufferFence
     */
    getReadbackBufferAttributes(Display display)
        generates (Error error,
                   PixelFormat format,
                   Dataspace dataspace);

    /**
     * getReadbackBufferFence
     * Returns an acquire sync fence file descriptor which must signal when the
     * buffer provided to setReadbackBuffer has been filled by the device and is
     * safe for the client to read.
     *
     * If it is already safe to read from this buffer, -1 may be returned instead.
     * The client takes ownership of this file descriptor and is responsible for
     * closing it when it is no longer needed.
     *
     * This function must be called immediately after the composition cycle being
     * captured into the readback buffer. The complete ordering of a readback buffer
     * capture is as follows:
     *
     *   getReadbackBufferAttributes
     *   // Readback buffer is allocated
     *   // Many frames may pass
     *
     *   setReadbackBuffer
     *   validateDisplay
     *   presentDisplay
     *   getReadbackBufferFence
     *   // Implicitly wait on the acquire fence before accessing the buffer
     *
     * Parameters:
     * @param display - the display on which to create the layer.
     *
     * @return acquireFence - a sync fence file descriptor as described above; pointer
     *       must be non-NULL
     * @return error - is HWC2_ERROR_NONE or one of the following errors:
     *         BAD_DISPLAY - an invalid display handle was passed in
     *         UNSUPPORTED if not supported on underlying HAL
     *
     * See also:
     *   getReadbackBufferAttributes
     *   setReadbackBuffer
     */
    getReadbackBufferFence(Display display)
                generates (Error error,
                           handle acquireFence);

    /**
     * setReadbackBuffer
     * Sets the readback buffer to be filled with the contents of the next
     * composition performed for this display (i.e., the contents present at the
     * time of the next validateDisplay/presentDisplay cycle).
     *
     * This buffer must have been allocated as described in
     * getReadbackBufferAttributes and is in the dataspace provided by the same.
     *
     * If there is hardware protected content on the display at the time of the next
     * composition, the area of the readback buffer covered by such content must be
     * completely black. Any areas of the buffer not covered by such content may
     * optionally be black as well.
     *
     * The release fence file descriptor provided works identically to the one
     * described for setOutputBuffer.
     *
     * This function must not be called between any call to validateDisplay and a
     * subsequent call to presentDisplay.
     *
     * Parameters:
     * @param display - the display on which to create the layer.
     * @param buffer - the new readback buffer
     * @param releaseFence - a sync fence file descriptor as described in setOutputBuffer
     *
     * @return error - is HWC2_ERROR_NONE or one of the following errors:
     *   HWC2_ERROR_BAD_DISPLAY - an invalid display handle was passed in
     *   HWC2_ERROR_BAD_PARAMETER - the new readback buffer handle was invalid
     *
     * See also:
     *   getReadbackBufferAttributes
     *   getReadbackBufferFence
     */
    setReadbackBuffer(Display display, handle buffer, handle releaseFence) generates (Error error);

    /**
     * setPowerMode_2_2
     * Sets the power mode of the given display. The transition must be
     * complete when this function returns. It is valid to call this function
     * multiple times with the same power mode.
     *
     * All displays must support PowerMode::ON and PowerMode::OFF.  Whether a
     * display supports PowerMode::DOZE or PowerMode::DOZE_SUSPEND may be
     * queried using getDozeSupport.
     *
     * @param display is the display to which the power mode is set.
     * @param mode is the new power mode.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_PARAMETER when mode was not a valid power mode.
     *         UNSUPPORTED when mode is not supported on this display.
     */
    setPowerMode_2_2(Display display, PowerMode mode) generates (Error error);

};