1/*
2 * Copyright 2019 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.composer@2.4;
18
19import android.hardware.graphics.common@1.2::PixelFormat;
20import android.hardware.graphics.common@1.2::Dataspace;
21import android.hardware.graphics.composer@2.1::IComposerClient.Command;
22import IComposerCallback;
23import @2.1::Config;
24import @2.1::Display;
25import @2.1::Error;
26import @2.1::IComposerClient;
27import @2.3::IComposerClient;
28
29interface IComposerClient extends @2.3::IComposerClient {
30    /**
31     * Display attributes queryable through getDisplayAttribute_2_4.
32     */
33    enum Attribute : @2.1::IComposerClient.Attribute {
34        /**
35         * The configuration group ID (as int32_t) this config is associated to.
36         * Switching between configurations within the same group may be done seamlessly
37         * in some conditions via setActiveConfigWithConstraints. Configurations which
38         * share the same config group are similar in all attributes except for the
39         * vsync period.
40         */
41        CONFIG_GROUP = 7,
42    };
43
44    /**
45     * Required capabilities which are supported by the display. The
46     * particular set of supported capabilities for a given display may be
47     * retrieved using getDisplayCapabilities.
48     */
49    enum DisplayCapability : @2.3::IComposerClient.DisplayCapability {
50        /**
51         * Indicates that the display supports protected contents.
52         * When returned, hardware composer must be able to accept client target
53         * with protected buffers.
54         */
55        PROTECTED_CONTENTS = 4,
56
57        /**
58         * Indicates that both the composer HAL implementation and the given display
59         * support a low latency mode, such as HDMI 2.1 Auto Low Latency Mode.
60         */
61        AUTO_LOW_LATENCY_MODE = 5,
62    };
63
64    enum Command : @2.3::IComposerClient.Command {
65        /**
66         * SET_CLIENT_TARGET_PROPERTY has this pseudo prototype
67         *
68         * This command has the following binary layout in bytes:
69         *
70         *     0 - 3: clientTargetProperty.pixelFormat
71         *     4 - 7: clientTargetProperty.dataspace
72         *
73         *   setClientTargetProperty(ClientTargetProperty clientTargetProperty);
74         */
75         SET_CLIENT_TARGET_PROPERTY = 0x105 << @2.1::IComposerClient.Command:OPCODE_SHIFT,
76
77        /**
78         * SET_LAYER_GENERIC_METADATA has this pseudo prototype
79         *
80         *   setLayerGenericMetadata(string key, bool mandatory, vec<uint8_t> value);
81         *
82         * Sets a piece of generic metadata for the given layer. If this
83         * function is called twice with the same key but different values, the
84         * newer value must override the older one. Calling this function with a
85         * 0-length value must reset that key's metadata as if it had not been
86         * set.
87         *
88         * A given piece of metadata may either be mandatory or a hint
89         * (non-mandatory) as indicated by the second parameter. Mandatory
90         * metadata may affect the composition result, which is to say that it
91         * may cause a visible change in the final image. By contrast, hints may
92         * only affect the composition strategy, such as which layers are
93         * composited by the client, but must not cause a visible change in the
94         * final image. The value of the mandatory flag shall match the value
95         * returned from getLayerGenericMetadataKeys for the given key.
96         *
97         * Only keys which have been returned from getLayerGenericMetadataKeys()
98         * shall be accepted. Any other keys must result in an UNSUPPORTED error.
99         *
100         * The value passed into this function shall be the binary
101         * representation of a HIDL type corresponding to the given key. For
102         * example, a key of 'com.example.V1_3.Foo' shall be paired with a
103         * value of type com.example@1.3::Foo, which would be defined in a
104         * vendor HAL extension.
105         *
106         * This function will be encoded in the command buffer in this order:
107         *   1) The key length, stored as a uint32_t
108         *   2) The key itself, padded to a uint32_t boundary if necessary
109         *   3) The mandatory flag, stored as a uint32_t
110         *   4) The value length in bytes, stored as a uint32_t
111         *   5) The value itself, padded to a uint32_t boundary if necessary
112         *
113         * @param key indicates which metadata value should be set on this layer
114         * @param mandatory indicates whether this particular key represents
115         *        mandatory metadata or a hint (non-mandatory metadata), as
116         *        described above
117         * @param value is a binary representation of a HIDL struct
118         *        corresponding to the key as described above
119         */
120        SET_LAYER_GENERIC_METADATA = 0x40e << @2.1::IComposerClient.Command:OPCODE_SHIFT,
121    };
122
123    /**
124     * Supersedes {@link @2.1::IComposerClient.DisplayType}.
125     */
126    enum DisplayConnectionType : uint32_t {
127        /**
128         * Display is connected through internal port, e.g. DSI, eDP.
129         */
130        INTERNAL = 0,
131        /**
132         * Display is connected through external port, e.g. HDMI, DisplayPort.
133         */
134        EXTERNAL = 1,
135    };
136
137    enum ContentType : uint32_t {
138        NONE = 0,
139
140        /**
141         * These modes correspond to those found in the HDMI 1.4 specification.
142         */
143        GRAPHICS = 1,
144        PHOTO = 2,
145        CINEMA = 3,
146        GAME = 4,
147    };
148
149    /**
150     * Constraints for changing vsync period.
151     */
152    struct VsyncPeriodChangeConstraints {
153        /**
154         * Time in CLOCK_MONOTONIC after which the vsync period may change
155         * (i.e., the vsync period must not change before this time).
156         */
157        int64_t desiredTimeNanos;
158
159        /**
160         * If true, requires that the vsync period change must happen seamlessly without
161         * a noticeable visual artifact.
162         */
163        bool seamlessRequired;
164    };
165
166    struct ClientTargetProperty {
167        PixelFormat pixelFormat;
168        Dataspace dataspace;
169    };
170
171    /**
172     * Provides a IComposerCallback object for the device to call.
173     *
174     * This function must be called only once.
175     *
176     * @param callback is the IComposerCallback object.
177     */
178    registerCallback_2_4(IComposerCallback callback);
179
180    /**
181     * Provides a list of supported capabilities (as described in the
182     * definition of DisplayCapability above). This list must not change after
183     * initialization.
184     *
185     * @return error is NONE upon success. Otherwise,
186     *     BAD_DISPLAY when an invalid display handle was passed in.
187     * @return capabilities is a list of supported capabilities.
188     */
189    getDisplayCapabilities_2_4(Display display)
190        generates (Error error, vec<DisplayCapability> capabilities);
191
192    /**
193     * Returns whether the given physical display is internal or external.
194     *
195     * @return error is NONE upon success. Otherwise,
196     *     BAD_DISPLAY when the given display is invalid or virtual.
197     * @return type is the connection type of the display.
198     */
199    getDisplayConnectionType(Display display) generates (Error error, DisplayConnectionType type);
200
201    /**
202     * Returns a display attribute value for a particular display
203     * configuration.
204     *
205     * @param display is the display to query.
206     * @param config is the display configuration for which to return
207     *        attribute values.
208     * @return error is NONE upon success. Otherwise,
209     *         BAD_DISPLAY when an invalid display handle was passed in.
210     *         BAD_CONFIG when config does not name a valid configuration for
211     *                    this display.
212     *         BAD_PARAMETER when attribute is unrecognized.
213     *         UNSUPPORTED when attribute cannot be queried for the config.
214     * @return value is the value of the attribute.
215     */
216    getDisplayAttribute_2_4(Display display, Config config, Attribute attribute)
217        generates (Error error, int32_t value);
218
219    /**
220     * Retrieves which vsync period the display is currently using.
221     *
222     * If no display configuration is currently active, this function must
223     * return BAD_CONFIG. If the vsync period is about to change due to a
224     * setActiveConfigWithConstraints call, this function must return the current vsync period
225     * until the change takes place.
226     *
227     * @param display is the display for which the vsync period is queried.
228     * @return error is NONE upon success. Otherwise,
229     *         BAD_DISPLAY when an invalid display handle was passed in.
230     *         BAD_CONFIG when no configuration is currently active.
231     * @return vsyncPeriodNanos is the current vsync period of the display.
232     */
233    getDisplayVsyncPeriod(Display display)
234        generates (Error error, VsyncPeriodNanos vsyncPeriodNanos);
235
236    /**
237     * Sets the active configuration and the refresh rate for this display.
238     * If the new config shares the same config group as the current config,
239     * only the vsync period shall change.
240     * Upon returning, the given display configuration, except vsync period, must be active and
241     * remain so until either this function is called again or the display is disconnected.
242     * When the display starts to refresh at the new vsync period, onVsync_2_4 callback must be
243     * called with the new vsync period.
244     *
245     * @param display is the display for which the active config is set.
246     * @param config is the new display configuration.
247     * @param vsyncPeriodChangeConstraints are the constraints required for changing vsync period.
248     *
249     * @return error is NONE upon success. Otherwise,
250     *         BAD_DISPLAY when an invalid display handle was passed in.
251     *         BAD_CONFIG when the configuration handle passed in is not valid
252     *                    for this display.
253     *         SEAMLESS_NOT_ALLOWED when seamlessRequired was true but config provided doesn't
254     *                              share the same config group as the current config.
255     *         SEAMLESS_NOT_POSSIBLE when seamlessRequired was true but the display cannot achieve
256     *                               the vsync period change without a noticeable visual artifact.
257     *                               When the conditions change and it may be possible to change
258     *                               the vsync period seamlessly, onSeamlessPossible callback
259     *                               must be called to indicate that caller should retry.
260     * @return timeline is the timeline for the vsync period change.
261     */
262    setActiveConfigWithConstraints(Display display, Config config,
263        VsyncPeriodChangeConstraints vsyncPeriodChangeConstraints)
264        generates (Error error, VsyncPeriodChangeTimeline timeline);
265
266    /**
267     * Requests the display to enable/disable its low latency mode.
268     *
269     * If the display is connected via HDMI 2.1, then Auto Low Latency Mode should be triggered. If
270     * the display is internally connected and a custom low latency mode is available, that should
271     * be triggered.
272     *
273     * This function should only be called if the display reports support for
274     * DisplayCapability::AUTO_LOW_LATENCY_MODE from getDisplayCapabilities_2_4.
275     *
276     * @return error is NONE upon success. Otherwise,
277     *     BAD_DISPLAY when an invalid display handle was passed in.
278     *     UNSUPPORTED when AUTO_LOW_LATENCY_MODE is not supported by the composer
279     *         implementation or the given display
280     */
281    setAutoLowLatencyMode(Display display, bool on)
282        generates (Error error);
283
284    /**
285     * Provides a list of all the content types supported by this display (any of
286     * ContentType::{GRAPHICS, PHOTO, CINEMA, GAME}). This list must not change after
287     * initialization.
288     *
289     * Content types are introduced in HDMI 1.4 and supporting them is optional. The
290     * ContentType::NONE is always supported and will not be returned by this method..
291     *
292     * @return error is NONE upon success. Otherwise,
293     *     BAD_DISPLAY when an invalid display handle was passed in.
294     * @return supportedContentTypes is a list of supported content types.
295     */
296    getSupportedContentTypes(Display display)
297        generates(Error error, vec<ContentType> supportedContentTypes);
298
299    /**
300     * Instructs the connected display that the content being shown is of the given type - one of
301     * GRAPHICS, PHOTO, CINEMA, GAME.
302     *
303     * Content types are introduced in HDMI 1.4 and supporting them is optional. If they are
304     * supported, this signal should switch the display to a mode that is optimal for the given
305     * type of content. See HDMI 1.4 specification for more information.
306     *
307     * If the display is internally connected (not through HDMI), and such modes are available,
308     * this method should trigger them.
309     *
310     * This function should only be called if the display reports support for the corresponding
311     * content type (ContentType::{GRAPHICS, PHOTO, CINEMA, GAME}) from getSupportedContentTypes.
312     * ContentType::NONE is supported by default and can always be set.
313     *
314     * @return error is NONE upon success. Otherwise,
315     *     BAD_DISPLAY when an invalid display handle was passed in.
316     *     UNSUPPORTED when the given content type is not supported by the composer
317     *         implementation or the given display
318     */
319    setContentType(Display display, ContentType type)
320        generates (Error error);
321
322    struct LayerGenericMetadataKey {
323        /**
324         * Key names must comply with the requirements specified for
325         * getLayerGenericMetadataKeys below
326         */
327        string name;
328
329        /**
330         * The mandatory flag is defined in the description of
331         * setLayerGenericMetadata above
332         */
333        bool mandatory;
334    };
335
336    /**
337     * Retrieves the set of keys that may be passed into setLayerGenericMetadata
338     *
339     * Key names must meet the following requirements:
340     * - Must be specified in reverse domain name notation
341     * - Must not start with 'com.android' or 'android'
342     * - Must be unique within the returned vector
343     * - Must correspond to a matching HIDL struct type, which defines the
344     *   structure of its values. For example, the key 'com.example.V1-3.Foo'
345     *   should correspond to a value of type com.example@1.3::Foo, which is
346     *   defined in a vendor HAL extension
347     */
348    getLayerGenericMetadataKeys()
349        generates(Error error, vec<LayerGenericMetadataKey> keys);
350};
351