automotive/evs/1.1/IEvsCamera.hal

/*
 * Copyright (C) 2019 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.automotive.evs@1.1;

import @1.0::IEvsCamera;
import @1.0::IEvsDisplay;
import @1.0::EvsResult;
import IEvsCameraStream;

/**
 * Represents a single camera and is the primary interface for capturing images.
 */
interface IEvsCamera extends @1.0::IEvsCamera {
    /**
     * Requests to pause EVS camera stream events.
     *
     * Like stopVideoStream(), events may continue to arrive for some time
     * after this call returns. Delivered frame buffers must be returned.
     *
     * @return result EvsResult::OK is returned if this call is successful.
     */
    pauseVideoStream() generates (EvsResult result);

    /**
     * Requests to resume EVS camera stream.
     *
     * @return result EvsResult::OK is returned if this call is successful.
     */
    resumeVideoStream() generates (EvsResult result);

    /**
     * Returns a frame that was delivered by to the IEvsCameraStream.
     *
     * When done consuming a frame delivered to the IEvsCameraStream
     * interface, it must be returned to the IEvsCamera for reuse.
     * A small, finite number of buffers are available (possibly as small
     * as one), and if the supply is exhausted, no further frames may be
     * delivered until a buffer is returned.
     *
     * @param  buffer A buffer to be returned.
     * @return result Return EvsResult::OK if this call is successful.
     */
    doneWithFrame_1_1(BufferDesc buffer) generates (EvsResult result);

    /**
     * Requests to be a master client.
     *
     * When multiple clients subscribe to a single camera hardware and one of
     * them adjusts a camera parameter such as the contrast, it may disturb
     * other clients' operations.  Therefore, the client must call this method
     * to be a master client.  Once it becomes a master, it will be able to
     * change camera parameters until either it dies or explicitly gives up the
     * role.
     *
     * @return result EvsResult::OK if a master role is granted.
     *                EvsResult::OWNERSHIP_LOST if there is already a
     *                master client.
     */
    setMaster() generates (EvsResult result);

    /**
     * Sets to be a master client forcibly.
     *
     * The client, which owns the display, has a high priority and can take over
     * a master role from other clients without the display.
     *
     * @param  display IEvsDisplay handle.  If a given display is in either
     *                 NOT_VISIBLE, VISIBLE_ON_NEXT_FRAME, or VISIBLE state, the
     *                 calling client is considered as the high priority client
     *                 and therefore allowed to take over a master role from
     *                 existing master client.
     *
     * @return result  EvsResult::OK if a master role is granted.
     *                 EvsResult::INVALID_ARG if a given display handle is null
     *                 or in valid states.
     */
    forceMaster(IEvsDisplay display) generates (EvsResult result);

    /**
     * Retires from a master client role.
     *
     * @return result EvsResult::OK if this call is successful.
     *                EvsResult::INVALID_ARG if the caller client is not a
     *                master client.
     */
    unsetMaster() generates (EvsResult result);

    /**
     * Requests to set a camera parameter.
     *
     * @param  id             The identifier of camera parameter, CameraParam enum.
     *         value          A desired parameter value.
     * @return result         EvsResult::OK if it succeeds to set a parameter.
     *                        EvsResult::INVALID_ARG if either the request is
     *                        not made by a master client, or a requested
     *                        parameter is not supported.
     *                        EvsResult::UNDERLYING_SERVICE_ERROR if it fails to
     *                        program a value by any other reason.
     *         effectiveValue A programmed parameter value.  This may differ
     *                        from what the client gives if, for example, the
     *                        driver does not support a target parameter.
     */
    setParameter(CameraParam id, int32_t value)
        generates (EvsResult result, int32_t effectiveValue);

    /**
     * Retrieves a value of given camera parameter.
     *
     * @param  id     The identifier of camera parameter, CameraParam enum.
     * @return result EvsResult::OK if it succeeds to read a parameter.
     *                EvsResult::INVALID_ARG if either a requested parameter is
     *                not supported.
     *         value  A value of requested camera parameter.
     */
    getParameter(CameraParam id) generates(EvsResult result, int32_t value);
};