พารามิเตอร์การควบคุมกล้องโปรแกรม, พารามิเตอร์การควบคุมกล้องโปรแกรม

ใน Extended View System (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. When it becomes a master, it can
 * 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 enum) ที่ไคลเอนต์สามารถอ่านและเขียนได้ (หากไคลเอนต์เป็นมาสเตอร์) และ getIntParameterRange() ถ่ายทอดช่วงค่าและความละเอียดที่ถูกต้อง เมื่อไคลเอนต์หลักเปลี่ยนพารามิเตอร์กล้อง ไคลเอนต์อื่น ๆ ทั้งหมดบนฮาร์ดแวร์กล้องเดียวกันจะได้รับแจ้งโดยรับเหตุการณ์ PARAMETER_CHANGED พร้อมรหัสพารามิเตอร์และค่าใหม่

หมายเหตุ: ไดรเวอร์เซนเซอร์อาจจัดการค่าพารามิเตอร์ที่ไม่ถูกต้องแตกต่างออกไป โดยอาจส่งคืนรหัสข้อผิดพลาดหรือตัดค่าในช่วงที่ถูกต้องแล้วนำไปใช้ ดังนั้น เมธอด setIntParameter() จะส่งคืนค่าที่มีประสิทธิผล และไคลเอ็นต์สามารถใช้ค่านี้เพื่อยืนยันวิธีจัดการคำขอได้

ขออนุญาโตตุลาการระหว่างไคลเอนต์กล้องหลายตัว

เนื่องจากการออกแบบ EVS ก่อนหน้านี้อนุญาตให้แอปหลายตัวสมัครรับฮาร์ดแวร์กล้องตัวเดียวพร้อมกัน จึงเป็นไปได้ที่แอปหนึ่งอาจรบกวนการทำงานของแอปอื่นโดยการเปลี่ยนพารามิเตอร์ของกล้อง นอกจากนี้ ไคลเอนต์หลายรายอาจต้องการปรับพารามิเตอร์เดียวกันให้แตกต่างกัน และทำให้เกิดลักษณะการทำงานที่ไม่คาดคิดในการเรียกใช้บริการกล้อง

เพื่อหลีกเลี่ยงปัญหาดังกล่าว ตัวจัดการ EVS อนุญาตให้เฉพาะไคลเอ็นต์ หลัก เท่านั้นที่สามารถตั้งโปรแกรมพารามิเตอร์ของกล้องได้ ก่อนที่จะพยายามปรับพารามิเตอร์กล้องใดๆ ไคลเอนต์ จะต้อง กลายเป็นไคลเอนต์หลักโดยการเรียกเมธอด setMaster() หากล้มเหลว แสดงว่ามีไคลเอ็นต์หลักที่ใช้งานอยู่บนฮาร์ดแวร์กล้องนั้นอยู่แล้ว จนกว่าไคลเอ็นต์หลักปัจจุบันจะยุติลง หรือสละบทบาทหลักอย่างชัดเจนผ่าน unsetMaster() ไคลเอ็นต์อื่นจะไม่ได้รับอนุญาตให้เปลี่ยนพารามิเตอร์ของกล้อง เมื่อไคลเอ็นต์หลักคืนสิทธิ์ แอปอื่นๆ ทั้งหมดจะได้รับแจ้งจากเหตุการณ์ MASTER_RELEASED

ลูกค้าที่มีลำดับความสำคัญสูง

ผู้จัดการ EVS จัดการไคลเอนต์ที่เป็นเจ้าของจอแสดงผลที่มีลำดับความสำคัญสูงและอนุญาตให้ขโมยบทบาทหลักจากต้นแบบปัจจุบันได้ เนื่องจากการเป็นเจ้าของจอแสดงผล EVS ขึ้นอยู่กับความใหม่ ไคลเอนต์ใหม่จึงสามารถรับช่วงต่อจากไคลเอนต์ปัจจุบันด้วยจอแสดงผลได้

ไคลเอ็นต์ที่มีลำดับความสำคัญสูงต้องเรียก IEvsCamera::forceMaster(sp<IEvsDisplay>& display) เพื่อรับบทบาทหลัก ผู้จัดการ EVS จะตรวจสอบสถานะของตัวจัดการการแสดงผลที่กำหนด และหาก ( และเฉพาะในกรณีที่ ) สถานะของมันนั้นถูกต้อง และทั้ง DisplayState::NOT_OPEN และ DisplayState::DEAD จะไม่แทนที่ต้นแบบ ลูกค้าซึ่งเพิ่งสูญเสียบทบาทหลักไป จะได้รับแจ้งจากเหตุการณ์ MASTER_RELEASED และ ต้อง จัดการเรื่องนี้อย่างถูกต้อง

ใน Extended View System (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. When it becomes a master, it can
 * 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 enum) ที่ไคลเอนต์สามารถอ่านและเขียนได้ (หากไคลเอนต์เป็นมาสเตอร์) และ getIntParameterRange() ถ่ายทอดช่วงค่าและความละเอียดที่ถูกต้อง เมื่อไคลเอนต์หลักเปลี่ยนพารามิเตอร์กล้อง ไคลเอนต์อื่น ๆ ทั้งหมดบนฮาร์ดแวร์กล้องเดียวกันจะได้รับแจ้งโดยรับเหตุการณ์ PARAMETER_CHANGED พร้อมรหัสพารามิเตอร์และค่าใหม่

หมายเหตุ: ไดรเวอร์เซนเซอร์อาจจัดการค่าพารามิเตอร์ที่ไม่ถูกต้องแตกต่างออกไป โดยอาจส่งคืนรหัสข้อผิดพลาดหรือตัดค่าในช่วงที่ถูกต้องแล้วนำไปใช้ ดังนั้น เมธอด setIntParameter() จะส่งคืนค่าที่มีประสิทธิผล และไคลเอ็นต์สามารถใช้ค่านี้เพื่อยืนยันวิธีจัดการคำขอได้

ขออนุญาโตตุลาการระหว่างไคลเอนต์กล้องหลายตัว

เนื่องจากการออกแบบ EVS ก่อนหน้านี้อนุญาตให้แอปหลายตัวสมัครรับฮาร์ดแวร์กล้องตัวเดียวพร้อมกัน จึงเป็นไปได้ที่แอปหนึ่งอาจรบกวนการทำงานของแอปอื่นโดยการเปลี่ยนพารามิเตอร์ของกล้อง นอกจากนี้ ไคลเอนต์หลายรายอาจต้องการปรับพารามิเตอร์เดียวกันให้แตกต่างกัน และทำให้เกิดลักษณะการทำงานที่ไม่คาดคิดในการเรียกใช้บริการกล้อง

เพื่อหลีกเลี่ยงปัญหาดังกล่าว ตัวจัดการ EVS อนุญาตให้เฉพาะไคลเอ็นต์ หลัก เท่านั้นที่สามารถตั้งโปรแกรมพารามิเตอร์ของกล้องได้ ก่อนที่จะพยายามปรับพารามิเตอร์กล้องใดๆ ไคลเอนต์ จะต้อง กลายเป็นไคลเอนต์หลักโดยการเรียกเมธอด setMaster() หากล้มเหลว แสดงว่ามีไคลเอ็นต์หลักที่ใช้งานอยู่บนฮาร์ดแวร์กล้องนั้นอยู่แล้ว จนกว่าไคลเอ็นต์หลักปัจจุบันจะยุติลง หรือสละบทบาทหลักอย่างชัดเจนผ่าน unsetMaster() ไคลเอ็นต์อื่นจะไม่ได้รับอนุญาตให้เปลี่ยนพารามิเตอร์ของกล้อง เมื่อไคลเอ็นต์หลักคืนสิทธิ์ แอปอื่นๆ ทั้งหมดจะได้รับแจ้งจากเหตุการณ์ MASTER_RELEASED

ลูกค้าที่มีลำดับความสำคัญสูง

ผู้จัดการ EVS จัดการไคลเอนต์ที่เป็นเจ้าของจอแสดงผลที่มีลำดับความสำคัญสูงและอนุญาตให้ขโมยบทบาทหลักจากต้นแบบปัจจุบันได้ เนื่องจากการเป็นเจ้าของจอแสดงผล EVS ขึ้นอยู่กับความใหม่ ไคลเอนต์ใหม่จึงสามารถรับช่วงต่อจากไคลเอนต์ปัจจุบันด้วยจอแสดงผลได้

ไคลเอนต์ที่มีลำดับความสำคัญสูงต้องเรียก IEvsCamera::forceMaster(sp<IEvsDisplay>& display) เพื่อรับบทบาทหลัก ผู้จัดการ EVS จะตรวจสอบสถานะของตัวจัดการการแสดงผลที่กำหนด และหาก ( และเฉพาะในกรณีที่ ) สถานะของมันนั้นถูกต้อง และทั้ง DisplayState::NOT_OPEN และ DisplayState::DEAD จะไม่แทนที่ต้นแบบ ลูกค้าซึ่งเพิ่งสูญเสียบทบาทหลักไป จะได้รับแจ้งจากเหตุการณ์ MASTER_RELEASED และ ต้อง จัดการเรื่องนี้อย่างถูกต้อง