用程序编写摄像头控制参数

在之前的增强型视觉系统 (EVS) 1.0 版本中,摄像头设备被视为只读设备,因此不存在任何可让应用更改摄像头控制参数(如缩放或亮度)的方法。

由于这可能会限制 EVS 应用的功能,因此新的 EVS 1.1 引入了新的方法,让应用能够用程序编写多个摄像头控制参数,所有这些参数都在 enum CameraParam 中定义:

/**
 * EVS Camera Parameter
 */
enum CameraParam : uint32_t {
    /**
     * The brightness of image frames
     */
    BRIGHTNESS,
    /**
     * The contrast of image frames
     */
    CONTRAST,
    /**
     * Automatic gain/exposure control
     */
    AUTOGAIN,
    /**
     * Gain control
     */
    GAIN,
    /**
     * Automatic Whitebalance
     */
    AUTO_WHITE_BALANCE,
    /**
     * Manual white balance setting as a color temperature in Kelvin.
     */
    WHITE_BALANCE_TEMPERATURE,
    /**
     * Image sharpness adjustment
     */
    SHARPNESS,
    /**
     * Auto Exposure Control modes; auto, manual, shutter priority, or
     * aperture priority.
     */
    AUTO_EXPOSURE,
    /**
     * Manual exposure time of the camera
     */
    ABSOLUTE_EXPOSURE,
    /**
     * Set the focal point of the camera to the specified position. This
     * parameter may not be effective when auto focus is enabled.
     */
    ABSOLUTE_FOCUS,
    /**
     * Enables continuous automatic focus adjustments.
     */
    AUTO_FOCUS,
    /**
     * Specify the objective lens focal length as an absolute value.
     */
    ABSOLUTE_ZOOM,
};

方法定义如下:

/**
 * 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 this is valid, the calling client
 *                 is considered as the high priority client and therefore
 *                 it would take over a master role.
 *
 * @return result  EvsResult::OK if a master role is granted.
 *                 EvsResult::OWNERSHIP_LOST if there is already a
 *                 master client with the display.
 */
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);

/**
 * Retrieves a list of parameters this camera supports.
 *
 * @return params A list of CameraParam that this camera supports.
 */
getParameterList() generates (vec<CameraParam> params);

/**
 * Requests a valid value range of a camera parameter
 *
 * @param  id    The identifier of camera parameter, CameraParam enum.
 *
 * @return min   The lower bound of the valid parameter value range.
 * @return max   The upper bound of the valid parameter value range.
 * @return step  The resolution of values in valid range.
 */
getIntParameterRange(CameraParam id)
    generates (int32_t min, int32_t max, int32_t step);

/**
 * 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 a requested
 *                        parameter is not supported or a given value is out
 *                        of bounds.
 *         effectiveValue A programmed parameter value. This may differ
 *                        from what the client gives if, for example, the
 *                        driver does not support a target parameter.
 */
setIntParameter(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.
 */
getIntParameter(CameraParam id) generates(EvsResult result, int32_t value);

getParameterList() 返回客户端可以读取和写入(如果客户端是主客户端)的参数列表(CameraParam 枚举),getIntParameterRange() 则传递有效的值范围和分辨率。当主客户端更改摄像头参数时,系统会通过发送带有参数 ID 和新值的 PARAMETER_CHANGED 事件通知同一摄像头硬件上的所有其他客户端。

注意:传感器驱动程序可能会以不同的方式处理无效参数值。它可能会只返回错误代码,也可能会裁剪有效范围内的值并加以应用。因此,setIntParameter() 方法会返回一个有效值,客户端可以使用此值来确认请求的处理方式。

多个摄像头客户端之间的请求仲裁

由于之前的 EVS 设计允许多个应用同时订阅一个摄像头硬件,因此一个应用有可能通过更改摄像头参数干扰其他应用的操作。此外,多个客户端可能需要以不同方式调整同一参数,因而导致运行摄像头服务时出现意外行为。

为了避免此类问题,EVS 管理器仅允许主客户端用程序编写摄像头参数。在尝试调整任何摄像头参数之前,客户端必须通过调用 setMaster() 方法成为主客户端。如果调用失败,则表示该摄像头硬件上已有活动的主客户端。在当前主客户端崩溃或通过 unsetMaster() 明确放弃主客户端角色之前,系统不会允许任何其他客户端更改摄像头参数。当主客户端退回其特权时,系统会通过 MASTER_RELEASED 事件向所有其他应用发送通知。

高优先级客户端

EVS 管理器会以高优先级处理拥有屏幕的客户端,并允许它窃取当前主客户端的角色。由于 EVS 屏幕所有权基于新近度,因此新客户端甚至可以从当前客户端接管屏幕。

高优先级客户端必须调用 IEvsCamera::forceMaster(sp<IEvsDisplay>& display) 才能获得主客户端角色。EVS 管理器会检查给定屏幕句柄的状态,当(且仅当)其状态有效且不为 DisplayState::NOT_OPENDisplayState::DEAD 时,才会替换主客户端。刚刚失去主客户端角色的客户端将通过 MASTER_RELEASED 事件获得通知,并且必须正确处理这一情况。