/*
 * Copyright (C) 2016 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.1;

import android.hardware.graphics.common@1.0;
import IComposerCallback;

interface IComposerClient {
    /** Display attributes queryable through getDisplayAttribute. */
    enum Attribute : int32_t {
        INVALID = 0,

        /** Dimensions in pixels */
        WIDTH = 1,
        HEIGHT = 2,

        /** Vsync period in nanoseconds */
        VSYNC_PERIOD = 3,

        /**
         * Dots per thousand inches (DPI * 1000). Scaling by 1000 allows these
         * numbers to be stored in an int32_t without losing too much
         * precision. If the DPI for a configuration is unavailable or is
         * considered unreliable, the device may return UNSUPPORTED instead.
         */
        DPI_X = 4,
        DPI_Y = 5,
    };

    /** Display requests returned by getDisplayRequests. */
    enum DisplayRequest : uint32_t {
        /**
         * Instructs the client to provide a new client target buffer, even if
         * no layers are marked for client composition.
         */
        FLIP_CLIENT_TARGET = 1 << 0,

        /**
         * Instructs the client to write the result of client composition
         * directly into the virtual display output buffer. If any of the
         * layers are not marked as Composition::CLIENT or the given display
         * is not a virtual display, this request has no effect.
         */
        WRITE_CLIENT_TARGET_TO_OUTPUT = 1 << 1,
    };

    /** Layer requests returned from getDisplayRequests. */
    enum LayerRequest : uint32_t {
        /**
         * The client must clear its target with transparent pixels where
         * this layer would be. The client may ignore this request if the
         * layer must be blended.
         */
        CLEAR_CLIENT_TARGET = 1 << 0,
    };

    /** Power modes for use with setPowerMode. */
    enum PowerMode : int32_t {
        /** The display is fully off (blanked). */
        OFF = 0,

        /**
         * These are optional low power modes. getDozeSupport may be called to
         * determine whether a given display supports these modes.
         */

        /**
         * The display is turned on and configured in a low power state that
         * is suitable for presenting ambient information to the user,
         * possibly with lower fidelity than ON, but with greater efficiency.
         */
        DOZE = 1,

        /**
         * The display is configured as in DOZE 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 in a low power state 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
         * doze functionality. In this case, the device is free to take over
         * the display and manage it autonomously to implement a low power
         * always-on display.
         */
        DOZE_SUSPEND = 3,

        /** The display is fully on. */
        ON = 2,
    };

    /** Vsync values passed to setVsyncEnabled. */
    enum Vsync : int32_t {
        INVALID = 0,

        /** Enable vsync. */
        ENABLE = 1,

        /** Disable vsync. */
        DISABLE = 2,
    };

    /** Blend modes, settable per layer. */
    enum BlendMode : int32_t {
        INVALID = 0,

        /** colorOut = colorSrc */
        NONE = 1,

        /** colorOut = colorSrc + colorDst * (1 - alphaSrc) */
        PREMULTIPLIED = 2,

        /** colorOut = colorSrc * alphaSrc + colorDst * (1 - alphaSrc) */
        COVERAGE = 3,
    };

    /** Possible composition types for a given layer. */
    enum Composition : int32_t {
        INVALID = 0,

        /**
         * The client must composite this layer into the client target buffer
         * (provided to the device through setClientTarget).
         *
         * The device must not request any composition type changes for layers
         * of this type.
         */
        CLIENT = 1,

        /**
         * The device must handle the composition of this layer through a
         * hardware overlay or other similar means.
         *
         * Upon validateDisplay, the device may request a change from this
         * type to CLIENT.
         */
        DEVICE = 2,

        /**
         * The device must render this layer using the color set through
         * setLayerColor. If this functionality is not supported on a layer
         * that the client sets to SOLID_COLOR, the device must request that
         * the composition type of that layer is changed to CLIENT upon the
         * next call to validateDisplay.
         *
         * Upon validateDisplay, the device may request a change from this
         * type to CLIENT.
         */
        SOLID_COLOR = 3,

        /**
         * Similar to DEVICE, but the position of this layer may also be set
         * asynchronously through setCursorPosition. If this functionality is
         * not supported on a layer that the client sets to CURSOR, the device
         * must request that the composition type of that layer is changed to
         * CLIENT upon the next call to validateDisplay.
         *
         * Upon validateDisplay, the device may request a change from this
         * type to either DEVICE or CLIENT.  Changing to DEVICE will prevent
         * the use of setCursorPosition but still permit the device to
         * composite the layer.
         */
        CURSOR = 4,

        /**
         * The device must handle the composition of this layer, as well as
         * its buffer updates and content synchronization. Only supported on
         * devices which provide Capability::SIDEBAND_STREAM.
         *
         * Upon validateDisplay, the device may request a change from this
         * type to either DEVICE or CLIENT, but it is unlikely that content
         * will display correctly in these cases.
         */
        SIDEBAND = 5,
    };

    /** Display types returned by getDisplayType. */
    enum DisplayType : int32_t {
        INVALID = 0,

        /**
         * All physical displays, including both internal displays and
         * hotpluggable external displays.
         */
        PHYSICAL = 1,

        /** Virtual displays created by createVirtualDisplay. */
        VIRTUAL = 2,
    };

    /** Special index values (always negative) for command queue commands. */
    enum HandleIndex : int32_t {
        /** No handle */
        EMPTY = -1,

        /** Use cached handle */
        CACHED = -2,
    };

    struct Rect {
        int32_t left;
        int32_t top;
        int32_t right;
        int32_t bottom;
    };

    struct FRect {
        float left;
        float top;
        float right;
        float bottom;
    };

    struct Color {
        uint8_t r;
        uint8_t g;
        uint8_t b;
        uint8_t a;
    };

    /**
     * Provides a IComposerCallback object for the device to call.
     *
     * This function must be called only once.
     *
     * @param callback is the IComposerCallback object.
     */
    @entry
    @callflow(next="*")
    registerCallback(IComposerCallback callback);

    /**
     * Returns the maximum number of virtual displays supported by this device
     * (which may be 0). The client must not attempt to create more than this
     * many virtual displays on this device. This number must not change for
     * the lifetime of the device.
     *
     * @return count is the maximum number of virtual displays supported.
     */
    @callflow(next="*")
    getMaxVirtualDisplayCount() generates (uint32_t count);

    /**
     * Creates a new virtual display with the given width and height. The
     * format passed into this function is the default format requested by the
     * consumer of the virtual display output buffers.
     *
     * The display must be assumed to be on from the time the first frame is
     * presented until the display is destroyed.
     *
     * @param width is the width in pixels.
     * @param height is the height in pixels.
     * @param formatHint is the default output buffer format selected by
     *        the consumer.
     * @param outputBufferSlotCount is the number of output buffer slots to be
     *        reserved.
     * @return error is NONE upon success. Otherwise,
     *         UNSUPPORTED when the width or height is too large for the
     *                     device to be able to create a virtual display.
     *         NO_RESOURCES when the device is unable to create a new virtual
     *                      display at this time.
     * @return display is the newly-created virtual display.
     * @return format is the format of the buffer the device will produce.
     */
    @callflow(next="*")
    createVirtualDisplay(uint32_t width,
                         uint32_t height,
                         PixelFormat formatHint,
                         uint32_t outputBufferSlotCount)
              generates (Error error,
                         Display display,
                         PixelFormat format);

    /**
     * Destroys a virtual display. After this call all resources consumed by
     * this display may be freed by the device and any operations performed on
     * this display must fail.
     *
     * @param display is the virtual display to destroy.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_PARAMETER when the display handle which was passed in does
     *                       not refer to a virtual display.
     */
    @callflow(next="*")
    destroyVirtualDisplay(Display display) generates (Error error);

    /**
     * Creates a new layer on the given display.
     *
     * @param display is the display on which to create the layer.
     * @param bufferSlotCount is the number of buffer slot to be reserved.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         NO_RESOURCES when the device was unable to create a layer this
     *                      time.
     * @return layer is the handle of the new layer.
     */
    @callflow(next="*")
    createLayer(Display display,
                uint32_t bufferSlotCount)
     generates (Error error,
                Layer layer);

    /**
     * Destroys the given layer.
     *
     * @param display is the display on which the layer was created.
     * @param layer is the layer to destroy.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_LAYER when an invalid layer handle was passed in.
     */
    @callflow(next="*")
    destroyLayer(Display display, Layer layer) generates (Error error);

    /**
     * Retrieves which display configuration is currently active.
     *
     * If no display configuration is currently active, this function must
     * return BAD_CONFIG. It is the responsibility of the client to call
     * setActiveConfig with a valid configuration before attempting to present
     * anything on the display.
     *
     * @param display is the display to which the active config is queried.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_CONFIG when no configuration is currently active.
     * @return config is the currently active display configuration.
     */
    @callflow(next="*")
    getActiveConfig(Display display) generates (Error error, Config config);

    /**
     * Returns whether a client target with the given properties can be
     * handled by the device.
     *
     * This function must return true for a client target with width and
     * height equal to the active display configuration dimensions,
     * PixelFormat::RGBA_8888, and Dataspace::UNKNOWN. It is not required to
     * return true for any other configuration.
     *
     * @param display is the display to query.
     * @param width is the client target width in pixels.
     * @param height is the client target height in pixels.
     * @param format is the client target format.
     * @param dataspace is the client target dataspace, as described in
     *        setLayerDataspace.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         UNSUPPORTED when the given configuration is not supported.
     */
    @callflow(next="*")
    getClientTargetSupport(Display display,
                           uint32_t width,
                           uint32_t height,
                           PixelFormat format,
                           Dataspace dataspace)
                generates (Error error);

    /**
     * Returns the color modes supported on this display.
     *
     * All devices must support at least ColorMode::NATIVE.
     *
     * @param display is the display to query.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return modes is an array of color modes.
     */
    @callflow(next="*")
    getColorModes(Display display)
       generates (Error error,
                  vec<ColorMode> modes);

    /**
     * Returns a display attribute value for a particular display
     * configuration.
     *
     * @param display is the display to query.
     * @param config is the display configuration for which to return
     *        attribute values.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_CONFIG when config does not name a valid configuration for
     *                    this display.
     *         BAD_PARAMETER when attribute is unrecognized.
     *         UNSUPPORTED when attribute cannot be queried for the config.
     * @return value is the value of the attribute.
     */
    @callflow(next="*")
    getDisplayAttribute(Display display,
                        Config config,
                        Attribute attribute)
             generates (Error error,
                        int32_t value);

    /**
     * Returns handles for all of the valid display configurations on this
     * display.
     *
     * @param display is the display to query.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return configs is an array of configuration handles.
     */
    @callflow(next="*")
    getDisplayConfigs(Display display)
           generates (Error error,
                      vec<Config> configs);

    /**
     * Returns a human-readable version of the display's name.
     *
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return name is the name of the display.
     */
    @callflow(next="*")
    getDisplayName(Display display) generates (Error error, string name);

    /**
     * Returns whether the given display is a physical or virtual display.
     *
     * @param display is the display to query.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return type is the type of the display.
     */
    @callflow(next="*")
    getDisplayType(Display display) generates (Error error, DisplayType type);

    /**
     * Returns whether the given display supports PowerMode::DOZE and
     * PowerMode::DOZE_SUSPEND. DOZE_SUSPEND may not provide any benefit over
     * DOZE (see the definition of PowerMode for more information), but if
     * both DOZE and DOZE_SUSPEND are no different from PowerMode::ON, the
     * device must not claim support.
     *
     * @param display is the display to query.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return support is true only when the display supports doze modes.
     */
    @callflow(next="*")
    getDozeSupport(Display display) generates (Error error, bool support);

    /**
     * Returns the high dynamic range (HDR) capabilities of the given display,
     * which are invariant with regard to the active configuration.
     *
     * Displays which are not HDR-capable must return no types.
     *
     * @param display is the display to query.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     * @return types is an array of HDR types, may have 0 elements if the
     *         display is not HDR-capable.
     * @return maxLuminance is the desired content maximum luminance for this
     *         display in cd/m^2.
     * @return maxAverageLuminance - the desired content maximum frame-average
     *         luminance for this display in cd/m^2.
     * @return minLuminance is the desired content minimum luminance for this
     *         display in cd/m^2.
     */
    @callflow(next="*")
    getHdrCapabilities(Display display)
            generates (Error error,
                       vec<Hdr> types,
                       float maxLuminance,
                       float maxAverageLuminance,
                       float minLuminance);

    /**
     * Set the number of client target slots to be reserved.
     *
     * @param display is the display to which the slots are reserved.
     * @param clientTargetSlotCount is the slot count for client targets.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         NO_RESOURCES when unable to reserve the slots.
     */
    @callflow(next="*")
    setClientTargetSlotCount(Display display,
                             uint32_t clientTargetSlotCount)
                  generates (Error error);

    /**
     * Sets the active configuration for this display. Upon returning, the
     * given display configuration must be active and remain so until either
     * this function is called again or the display is disconnected.
     *
     * @param display is the display to which the active config is set.
     * @param config is the new display configuration.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_CONFIG when the configuration handle passed in is not valid
     *                    for this display.
     */
    @callflow(next="*")
    setActiveConfig(Display display, Config config) generates (Error error);

    /**
     * Sets the color mode of the given display.
     *
     * Upon returning from this function, the color mode change must have
     * fully taken effect.
     *
     * All devices must support at least ColorMode::NATIVE, and displays are
     * assumed to be in this mode upon hotplug.
     *
     * @param display is the display to which the color mode is set.
     * @param mode is the mode to set to.
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_PARAMETER when mode is not a valid color mode.
     *         UNSUPPORTED when mode is not supported on this display.
     */
    @callflow(next="*")
    setColorMode(Display display, ColorMode mode) generates (Error error);

    /**
     * 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.
     */
    @callflow(next="*")
    setPowerMode(Display display, PowerMode mode) generates (Error error);

    /**
     * Enables or disables the vsync signal for the given display. Virtual
     * displays never generate vsync callbacks, and any attempt to enable
     * vsync for a virtual display though this function must succeed and have
     * no other effect.
     *
     * @param display is the display to which the vsync mode is set.
     * @param enabled indicates whether to enable or disable vsync
     * @return error is NONE upon success. Otherwise,
     *         BAD_DISPLAY when an invalid display handle was passed in.
     *         BAD_PARAMETER when enabled was an invalid value.
     */
    @callflow(next="*")
    setVsyncEnabled(Display display, Vsync enabled) generates (Error error);

    /**
     * Sets the input command message queue.
     *
     * @param descriptor is the descriptor of the input command message queue.
     * @return error is NONE upon success. Otherwise,
     *         NO_RESOURCES when failed to set the queue temporarily.
     */
    @callflow(next="*")
    setInputCommandQueue(fmq_sync<uint32_t> descriptor)
              generates (Error error);

    /**
     * Gets the output command message queue.
     *
     * This function must only be called inside executeCommands closure.
     *
     * @return error is NONE upon success. Otherwise,
     *         NO_RESOURCES when failed to get the queue temporarily.
     * @return descriptor is the descriptor of the output command queue.
     */
    @callflow(next="*")
    getOutputCommandQueue()
              generates (Error error,
                         fmq_sync<uint32_t> descriptor);

    /**
     * Executes commands from the input command message queue. Return values
     * generated by the input commands are written to the output command
     * message queue in the form of value commands.
     *
     * @param inLength is the length of input commands.
     * @param inHandles is an array of handles referenced by the input
     *        commands.
     * @return error is NONE upon success. Otherwise,
     *         BAD_PARAMETER when inLength is not equal to the length of
     *                       commands in the input command message queue.
     *         NO_RESOURCES when the output command message queue was not
     *                      properly drained.
     * @param outQueueChanged indicates whether the output command message
     *        queue has changed.
     * @param outLength is the length of output commands.
     * @param outHandles is an array of handles referenced by the output
     *        commands.
     */
    @callflow(next="*")
    executeCommands(uint32_t inLength,
                    vec<handle> inHandles)
         generates (Error error,
                    bool outQueueChanged,
                    uint32_t outLength,
                    vec<handle> outHandles);

    /**
     * SELECT_DISPLAY has this pseudo prototype
     *
     *   selectDisplay(Display display);
     *
     * Selects the current display implied by all other commands.
     *
     * @param display is the newly selected display.
     *
     *
     * SELECT_LAYER has this pseudo prototype
     *
     *   selectLayer(Layer layer);
     *
     * Selects the current layer implied by all implicit layer commands.
     *
     * @param layer is the newly selected layer.
     *
     *
     * SET_ERROR has this pseudo prototype
     *
     *   setError(uint32_t location, Error error);
     *
     * Indicates an error generated by a command.
     *
     * @param location is the offset of the command in the input command
     *        message queue.
     * @param error is the error generated by the command.
     *
     *
     * SET_CHANGED_COMPOSITION_TYPES has this pseudo prototype
     *
     *   setChangedCompositionTypes(vec<Layer> layers,
     *                              vec<Composition> types);
     *
     * Sets the layers for which the device requires a different composition
     * type than had been set prior to the last call to VALIDATE_DISPLAY. The
     * client must either update its state with these types and call
     * ACCEPT_DISPLAY_CHANGES, or must set new types and attempt to validate
     * the display again.
     *
     * @param layers is an array of layer handles.
     * @param types is an array of composition types, each corresponding to
     *         an element of layers.
     *
     *
     * SET_DISPLAY_REQUESTS has this pseudo prototype
     *
     *   setDisplayRequests(uint32_t displayRequestMask,
     *                      vec<Layer> layers,
     *                      vec<uint32_t> layerRequestMasks);
     *
     * Sets the display requests and the layer requests required for the last
     * validated configuration.
     *
     * Display requests provide information about how the client must handle
     * the client target. Layer requests provide information about how the
     * client must handle an individual layer.
     *
     * @param displayRequestMask is the display requests for the current
     *        validated state.
     * @param layers is an array of layers which all have at least one
     *        request.
     * @param layerRequestMasks is the requests corresponding to each element
     *        of layers.
     *
     *
     * SET_PRESENT_FENCE has this pseudo prototype
     *
     *   setPresentFence(int32_t presentFenceIndex);
     *
     * Sets the present fence as a result of PRESENT_DISPLAY. For physical
     * displays, this fence must be signaled at the vsync when the result
     * of composition of this frame starts to appear (for video-mode panels)
     * or starts to transfer to panel memory (for command-mode panels). For
     * virtual displays, this fence must be signaled when writes to the output
     * buffer have completed and it is safe to read from it.
     *
     * @param presentFenceIndex is an index into outHandles array.
     *
     *
     * SET_RELEASE_FENCES has this pseudo prototype
     *
     *   setReleaseFences(vec<Layer> layers,
     *                    vec<int32_t> releaseFenceIndices);
     *
     * Sets the release fences for device layers on this display which will
     * receive new buffer contents this frame.
     *
     * A release fence is a file descriptor referring to a sync fence object
     * which must be signaled after the device has finished reading from the
     * buffer presented in the prior frame. This indicates that it is safe to
     * start writing to the buffer again. If a given layer's fence is not
     * returned from this function, it must be assumed that the buffer
     * presented on the previous frame is ready to be written.
     *
     * The fences returned by this function must be unique for each layer
     * (even if they point to the same underlying sync object).
     *
     * @param layers is an array of layer handles.
     * @param releaseFenceIndices are indices into outHandles array, each
     *        corresponding to an element of layers.
     *
     *
     * SET_COLOR_TRANSFORM has this pseudo prototype
     *
     *   setColorTransform(float[16] matrix,
     *                     ColorTransform hint);
     *
     * Sets a color transform which will be applied after composition.
     *
     * If hint is not ColorTransform::ARBITRARY, then the device may use the
     * hint to apply the desired color transform instead of using the color
     * matrix directly.
     *
     * If the device is not capable of either using the hint or the matrix to
     * apply the desired color transform, it must force all layers to client
     * composition during VALIDATE_DISPLAY.
     *
     * If IComposer::Capability::SKIP_CLIENT_COLOR_TRANSFORM is present, then
     * the client must never apply the color transform during client
     * composition, even if all layers are being composed by the client.
     *
     * The matrix provided is an affine color transformation of the following
     * form:
     *
     * |r.r r.g r.b 0|
     * |g.r g.g g.b 0|
     * |b.r b.g b.b 0|
     * |Tr  Tg  Tb  1|
     *
     * This matrix must be provided in row-major form:
     *
     * {r.r, r.g, r.b, 0, g.r, ...}.
     *
     * Given a matrix of this form and an input color [R_in, G_in, B_in], the
     * output color [R_out, G_out, B_out] will be:
     *
     * R_out = R_in * r.r + G_in * g.r + B_in * b.r + Tr
     * G_out = R_in * r.g + G_in * g.g + B_in * b.g + Tg
     * B_out = R_in * r.b + G_in * g.b + B_in * b.b + Tb
     *
     * @param matrix is a 4x4 transform matrix (16 floats) as described above.
     * @param hint is a hint value which may be used instead of the given
     *        matrix unless it is ColorTransform::ARBITRARY.
     *
     *
     * SET_CLIENT_TARGET has this pseudo prototype
     *
     *   setClientTarget(uint32_t targetSlot,
     *                   int32_t targetIndex,
     *                   int32_t acquireFenceIndex,
     *                   Dataspace dataspace,
     *                   vec<Rect> damage);
     *
     * Sets the buffer handle which will receive the output of client
     * composition.  Layers marked as Composition::CLIENT must be composited
     * into this buffer prior to the call to PRESENT_DISPLAY, and layers not
     * marked as Composition::CLIENT must be composited with this buffer by
     * the device.
     *
     * The buffer handle provided may be empty if no layers are being
     * composited by the client. This must not result in an error (unless an
     * invalid display handle is also provided).
     *
     * Also provides a file descriptor referring to an acquire sync fence
     * object, which must be signaled when it is safe to read from the client
     * target buffer.  If it is already safe to read from this buffer, an
     * empty handle may be passed instead.
     *
     * For more about dataspaces, see SET_LAYER_DATASPACE.
     *
     * The damage parameter describes a surface damage region as defined in
     * the description of SET_LAYER_SURFACE_DAMAGE.
     *
     * Will be called before PRESENT_DISPLAY if any of the layers are marked
     * as Composition::CLIENT. If no layers are so marked, then it is not
     * necessary to call this function. It is not necessary to call
     * validateDisplay after changing the target through this function.
     *
     * @param targetSlot is the client target buffer slot to use.
     * @param targetIndex is an index into inHandles for the new target
     *        buffer.
     * @param acquireFenceIndex is an index into inHandles for a sync fence
     *        file descriptor as described above.
     * @param dataspace is the dataspace of the buffer, as described in
     *        setLayerDataspace.
     * @param damage is the surface damage region.
     *
     *
     * SET_OUTPUT_BUFFER has this pseudo prototype
     *
     *   setOutputBuffer(uint32_t bufferSlot,
     *                   int32_t bufferIndex,
     *                   int32_t releaseFenceIndex);
     *
     * Sets the output buffer for a virtual display. That is, the buffer to
     * which the composition result will be written.
     *
     * Also provides a file descriptor referring to a release sync fence
     * object, which must be signaled when it is safe to write to the output
     * buffer. If it is already safe to write to the output buffer, an empty
     * handle may be passed instead.
     *
     * Must be called at least once before PRESENT_DISPLAY, but does not have
     * any interaction with layer state or display validation.
     *
     * @param bufferSlot is the new output buffer.
     * @param bufferIndex is the new output buffer.
     * @param releaseFenceIndex is a sync fence file descriptor as described
     *        above.
     *
     *
     * VALIDATE_DISPLAY has this pseudo prototype
     *
     *   validateDisplay();
     *
     * Instructs the device to inspect all of the layer state and determine if
     * there are any composition type changes necessary before presenting the
     * display. Permitted changes are described in the definition of
     * Composition above.
     *
     *
     * ACCEPT_DISPLAY_CHANGES has this pseudo prototype
     *
     *   acceptDisplayChanges();
     *
     * Accepts the changes required by the device from the previous
     * validateDisplay call (which may be queried using
     * getChangedCompositionTypes) and revalidates the display. This function
     * is equivalent to requesting the changed types from
     * getChangedCompositionTypes, setting those types on the corresponding
     * layers, and then calling validateDisplay again.
     *
     * After this call it must be valid to present this display. Calling this
     * after validateDisplay returns 0 changes must succeed with NONE, but
     * must have no other effect.
     *
     *
     * PRESENT_DISPLAY has this pseudo prototype
     *
     *   presentDisplay();
     *
     * Presents the current display contents on the screen (or in the case of
     * virtual displays, into the output buffer).
     *
     * Prior to calling this function, the display must be successfully
     * validated with validateDisplay. Note that setLayerBuffer and
     * setLayerSurfaceDamage specifically do not count as layer state, so if
     * there are no other changes to the layer state (or to the buffer's
     * properties as described in setLayerBuffer), then it is safe to call
     * this function without first validating the display.
     *
     *
     * SET_LAYER_CURSOR_POSITION has this pseudo prototype
     *
     *   setLayerCursorPosition(int32_t x, int32_t y);
     *
     * Asynchronously sets the position of a cursor layer.
     *
     * Prior to validateDisplay, a layer may be marked as Composition::CURSOR.
     * If validation succeeds (i.e., the device does not request a composition
     * change for that layer), then once a buffer has been set for the layer
     * and it has been presented, its position may be set by this function at
     * any time between presentDisplay and any subsequent validateDisplay
     * calls for this display.
     *
     * Once validateDisplay is called, this function must not be called again
     * until the validate/present sequence is completed.
     *
     * May be called from any thread so long as it is not interleaved with the
     * validate/present sequence as described above.
     *
     * @param layer is the layer to which the position is set.
     * @param x is the new x coordinate (in pixels from the left of the
     *        screen).
     * @param y is the new y coordinate (in pixels from the top of the
     *        screen).
     *
     *
     * SET_LAYER_BUFFER has this pseudo prototype
     *
     *   setLayerBuffer(uint32_t bufferSlot,
     *                  int32_t bufferIndex,
     *                  int32_t acquireFenceIndex);
     *
     * Sets the buffer handle to be displayed for this layer. If the buffer
     * properties set at allocation time (width, height, format, and usage)
     * have not changed since the previous frame, it is not necessary to call
     * validateDisplay before calling presentDisplay unless new state needs to
     * be validated in the interim.
     *
     * Also provides a file descriptor referring to an acquire sync fence
     * object, which must be signaled when it is safe to read from the given
     * buffer. If it is already safe to read from the buffer, an empty handle
     * may be passed instead.
     *
     * This function must return NONE and have no other effect if called for a
     * layer with a composition type of Composition::SOLID_COLOR (because it
     * has no buffer) or Composition::SIDEBAND or Composition::CLIENT (because
     * synchronization and buffer updates for these layers are handled
     * elsewhere).
     *
     * @param layer is the layer to which the buffer is set.
     * @param bufferSlot is the buffer slot to use.
     * @param bufferIndex is the buffer handle to set.
     * @param acquireFenceIndex is a sync fence file descriptor as described above.
     *
     *
     * SET_LAYER_SURFACE_DAMAGE has this pseudo prototype
     *
     *   setLayerSurfaceDamage(vec<Rect> damage);
     *
     * Provides the region of the source buffer which has been modified since
     * the last frame. This region does not need to be validated before
     * calling presentDisplay.
     *
     * Once set through this function, the damage region remains the same
     * until a subsequent call to this function.
     *
     * If damage is non-empty, then it may be assumed that any portion of the
     * source buffer not covered by one of the rects has not been modified
     * this frame. If damage is empty, then the whole source buffer must be
     * treated as if it has been modified.
     *
     * If the layer's contents are not modified relative to the prior frame,
     * damage must contain exactly one empty rect([0, 0, 0, 0]).
     *
     * The damage rects are relative to the pre-transformed buffer, and their
     * origin is the top-left corner. They must not exceed the dimensions of
     * the latched buffer.
     *
     * @param layer is the layer to which the damage region is set.
     * @param damage is the new surface damage region.
     *
     *
     * SET_LAYER_BLEND_MODE has this pseudo prototype
     *
     *   setLayerBlendMode(BlendMode mode)
     *
     * Sets the blend mode of the given layer.
     *
     * @param mode is the new blend mode.
     *
     *
     * SET_LAYER_COLOR has this pseudo prototype
     *
     *   setLayerColor(Color 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.
     *
     *
     * SET_LAYER_COMPOSITION_TYPE has this pseudo prototype
     *
     *   setLayerCompositionType(Composition type);
     *
     * Sets the desired composition type of the given layer. During
     * validateDisplay, the device may request changes to the composition
     * types of any of the layers as described in the definition of
     * Composition above.
     *
     * @param type is the new composition type.
     *
     *
     * SET_LAYER_DATASPACE has this pseudo prototype
     *
     *   setLayerDataspace(Dataspace dataspace);
     *
     * Sets the dataspace of the layer.
     *
     * The dataspace provides more information about how to interpret the buffer
     * or solid color, such as the encoding standard and color transform.
     *
     * See the values of Dataspace for more information.
     *
     * @param dataspace is the new dataspace.
     *
     *
     * SET_LAYER_DISPLAY_FRAME has this pseudo prototype
     *
     *   setLayerDisplayFrame(Rect frame);
     *
     * Sets the display frame (the portion of the display covered by a layer)
     * of the given layer. This frame must not exceed the display dimensions.
     *
     * @param frame is the new display frame.
     *
     *
     * SET_LAYER_PLANE_ALPHA has this pseudo prototype
     *
     *   setLayerPlaneAlpha(float alpha);
     *
     * Sets an alpha value (a floating point value in the range [0.0, 1.0])
     * which will be applied to the whole layer. It can be conceptualized as a
     * preprocessing step which applies the following function:
     *   if (blendMode == BlendMode::PREMULTIPLIED)
     *       out.rgb = in.rgb * planeAlpha
     *   out.a = in.a * planeAlpha
     *
     * If the device does not support this operation on a layer which is
     * marked Composition::DEVICE, it must request a composition type change
     * to Composition::CLIENT upon the next validateDisplay call.
     *
     * @param alpha is the plane alpha value to apply.
     *
     *
     * SET_LAYER_SIDEBAND_STREAM has this pseudo prototype
     *
     *   setLayerSidebandStream(int32_t streamIndex)
     *
     * Sets the sideband stream for this layer. If the composition type of the
     * given layer is not Composition::SIDEBAND, this call must succeed and
     * have no other effect.
     *
     * @param streamIndex is the new sideband stream.
     *
     *
     * SET_LAYER_SOURCE_CROP has this pseudo prototype
     *
     *   setLayerSourceCrop(FRect crop);
     *
     * Sets the source crop (the portion of the source buffer which will fill
     * the display frame) of the given layer. This crop rectangle must not
     * exceed the dimensions of the latched buffer.
     *
     * If the device is not capable of supporting a true float source crop
     * (i.e., it will truncate or round the floats to integers), it must set
     * this layer to Composition::CLIENT when crop is non-integral for the
     * most accurate rendering.
     *
     * If the device cannot support float source crops, but still wants to
     * handle the layer, it must use the following code (or similar) to
     * convert to an integer crop:
     *   intCrop.left = (int) ceilf(crop.left);
     *   intCrop.top = (int) ceilf(crop.top);
     *   intCrop.right = (int) floorf(crop.right);
     *   intCrop.bottom = (int) floorf(crop.bottom);
     *
     * @param crop is the new source crop.
     *
     *
     * SET_LAYER_TRANSFORM has this pseudo prototype
     *
     * Sets the transform (rotation/flip) of the given layer.
     *
     *   setLayerTransform(Transform transform);
     *
     * @param transform is the new transform.
     *
     *
     * SET_LAYER_VISIBLE_REGION has this pseudo prototype
     *
     *   setLayerVisibleRegion(vec<Rect> visible);
     *
     * Specifies the portion of the layer that is visible, including portions
     * under translucent areas of other layers. The region is in screen space,
     * and must not exceed the dimensions of the screen.
     *
     * @param visible is the new visible region, in screen space.
     *
     *
     * SET_LAYER_Z_ORDER has this pseudo prototype
     *
     *   setLayerZOrder(uint32_t z);
     *
     * Sets the desired Z order (height) of the given layer. A layer with a
     * greater Z value occludes a layer with a lesser Z value.
     *
     * @param z is the new Z order.
     */
    enum Command : int32_t {
        LENGTH_MASK                        = 0xffff,
        OPCODE_SHIFT                       = 16,
        OPCODE_MASK                        = 0xffff << OPCODE_SHIFT,

        /** special commands */
        SELECT_DISPLAY                     = 0x000 << OPCODE_SHIFT,
        SELECT_LAYER                       = 0x001 << OPCODE_SHIFT,

        /** value commands (for return values) */
        SET_ERROR                          = 0x100 << OPCODE_SHIFT,
        SET_CHANGED_COMPOSITION_TYPES      = 0x101 << OPCODE_SHIFT,
        SET_DISPLAY_REQUESTS               = 0x102 << OPCODE_SHIFT,
        SET_PRESENT_FENCE                  = 0x103 << OPCODE_SHIFT,
        SET_RELEASE_FENCES                 = 0x104 << OPCODE_SHIFT,

        /** display commands */
        SET_COLOR_TRANSFORM                = 0x200 << OPCODE_SHIFT,
        SET_CLIENT_TARGET                  = 0x201 << OPCODE_SHIFT,
        SET_OUTPUT_BUFFER                  = 0x202 << OPCODE_SHIFT,
        VALIDATE_DISPLAY                   = 0x203 << OPCODE_SHIFT,
        ACCEPT_DISPLAY_CHANGES             = 0x204 << OPCODE_SHIFT,
        PRESENT_DISPLAY                    = 0x205 << OPCODE_SHIFT,
        PRESENT_OR_VALIDATE_DISPLAY        = 0x206 << OPCODE_SHIFT,

        /** layer commands (VALIDATE_DISPLAY not required) */
        SET_LAYER_CURSOR_POSITION          = 0x300 << OPCODE_SHIFT,
        SET_LAYER_BUFFER                   = 0x301 << OPCODE_SHIFT,
        SET_LAYER_SURFACE_DAMAGE           = 0x302 << OPCODE_SHIFT,

        /** layer state commands (VALIDATE_DISPLAY required) */
        SET_LAYER_BLEND_MODE               = 0x400 << OPCODE_SHIFT,
        SET_LAYER_COLOR                    = 0x401 << OPCODE_SHIFT,
        SET_LAYER_COMPOSITION_TYPE         = 0x402 << OPCODE_SHIFT,
        SET_LAYER_DATASPACE                = 0x403 << OPCODE_SHIFT,
        SET_LAYER_DISPLAY_FRAME            = 0x404 << OPCODE_SHIFT,
        SET_LAYER_PLANE_ALPHA              = 0x405 << OPCODE_SHIFT,
        SET_LAYER_SIDEBAND_STREAM          = 0x406 << OPCODE_SHIFT,
        SET_LAYER_SOURCE_CROP              = 0x407 << OPCODE_SHIFT,
        SET_LAYER_TRANSFORM                = 0x408 << OPCODE_SHIFT,
        SET_LAYER_VISIBLE_REGION           = 0x409 << OPCODE_SHIFT,
        SET_LAYER_Z_ORDER                  = 0x40a << OPCODE_SHIFT,
        SET_PRESENT_OR_VALIDATE_DISPLAY_RESULT = 0x40b << OPCODE_SHIFT,

        /* 0x800 - 0xfff are reserved for vendor extensions */
        /* 0x1000 - 0xffff are reserved */
    };
};