media: add video capture device for ARC++ camera HAL v3

media/capture/video/chromeos/mojo/arc_camera3.mojom

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+module arc.mojom;
+
+import "arc_camera3_metadata.mojom";
+
+[Extensible]
+enum HalPixelFormat {
+  HAL_PIXEL_FORMAT_RGBA_8888 = 0x1,
+  HAL_PIXEL_FORMAT_RGBX_8888 = 0x2,
+  HAL_PIXEL_FORMAT_BGRA_8888 = 0x5,
+  HAL_PIXEL_FORMAT_YCrCb_420_SP = 0x11,
+  HAL_PIXEL_FORMAT_YCbCr_422_I = 0x14,
+  HAL_PIXEL_FORMAT_BLOB = 0x21,
+  HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22,
+  HAL_PIXEL_FORMAT_YCbCr_420_888 = 0x23,
+  HAL_PIXEL_FORMAT_YV12 = 0x32315659,
+};
+
+// The following enums are from Android's camera HAL v3 API header
+// (https://goo.gl/jciSjC).
+
+enum CameraFacing {
+  CAMERA_FACING_BACK = 0,
+  CAMERA_FACING_FRONT = 1,
+  CAMERA_FACING_EXTERNAL = 2,
+};
+
+enum Camera3StreamType {
+  CAMERA3_STREAM_OUTPUT = 0,
+  CAMERA3_STREAM_INPUT = 1,
+  CAMERA3_STREAM_BIDIRECTIONAL = 2,
+  CAMERA3_NUM_STREAM_TYPES,
+};
+
+enum Camera3StreamRotation {
+  CAMERA3_STREAM_ROTATION_0 = 0,
+  CAMERA3_STREAM_ROTATION_90 = 1,
+  CAMERA3_STREAM_ROTATION_180 = 2,
+  CAMERA3_STREAM_ROTATION_270 = 3,
+};
+
+[Extensible]
+enum Camera3StreamConfigurationMode {
+  CAMERA3_STREAM_CONFIGURATION_NORMAL_MODE = 0,
+  CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED_MODE =1,
+  CAMERA3_VENDOR_STREAM_CONFIGURATION_MODE_START = 0x8000,
+};
+
+[Extensible]
+enum Camera3RequestTemplate {
+  CAMERA3_TEMPLATE_PREVIEW = 1,
+  CAMERA3_TEMPLATE_STILL_CAPTURE = 2,
+  CAMERA3_TEMPLATE_VIDEO_RECORD = 3,
+  CAMERA3_TEMPLATE_VIDEO_SNAPSHOT = 4,
+  CAMERA3_TEMPLATE_ZERO_SHUTTER_LAG = 5,
+  CAMERA3_TEMPLATE_MANUAL = 6,
+  CAMERA3_TEMPLATE_COUNT,
+  CAMERA3_VENDOR_TEMPLATE_START = 0x40000000,
+};
+
+enum Camera3BufferStatus {
+  CAMERA3_BUFFER_STATUS_OK = 0,
+  CAMERA3_BUFFER_STATUS_ERROR = 1,
+};
+
+enum Camera3MsgType {
+  CAMERA3_MSG_ERROR = 1,
+  CAMERA3_MSG_SHUTTER = 2,
+  CAMERA3_NUM_MESSAGES,
+};
+
+struct Camera3Stream {
+  uint64 id;
+  Camera3StreamType stream_type;
+  uint32 width;
+  uint32 height;
+  HalPixelFormat format;
+  uint32 usage;
+  uint32 max_buffers;
+  uint32 data_space;
+  Camera3StreamRotation rotation;
+};
+
+struct Camera3StreamConfiguration {
+  array<Camera3Stream> streams;
+  Camera3StreamConfigurationMode operation_mode;
+};
+
+struct Camera3StreamBuffer {
+  uint64 stream_id;
+  uint64 buffer_id;
+  Camera3BufferStatus status;
+  handle? acquire_fence;
+  handle? release_fence;
+};
+
+struct Camera3CaptureRequest {
+  uint32 frame_number;
+  CameraMetadata settings;
+  Camera3StreamBuffer? input_buffer;
+  array<Camera3StreamBuffer> output_buffers;
+};
+
+// Camera3DeviceOps is mostly a translation of the camera3_device_ops_t API from
+// Android camera HAL v3, with the additional RegisterBuffer() function to pass
+// buffer handles across processes.  This is the interface to interact with a
+// camera device in the camera HAL.
+//
+// The work flow of the Camera3DeviceOps is:
+//
+//   1. Call Initialize() to register the Camera3CallbackOps interface with the
+//      camera HAL.
+//
+//   2. Call ConfigureStreams() to negotiate the set of usable video streams
+//      with the camera HAL.
+//
+//   3. After the video streams are successfully configured, call
+//      ConstructDefaultRequestSettings() to get the capture settings for each
+//      stream.  The capture settings of a stream will be associated with the
+//      capture requests of the stream.
+//
+//   4. Start the capture loop. The capture loop is composed of a series of
+//      capture requests and results.
+//
+//      For each capture request:
+//        a. Call RegisterBuffer() for each buffer associated with the request
+//           to register the buffers which will later be filled by the camera
+//           HAL with capture result.  For example, the client may register one
+//           small buffer for the low-resolution preview stream and one large
+//           buffer for the high-resolution still capture stream.
+//        b. Call ProcessCaptureRequest() to request capturing one frame.  A
+//           request may contain multiple streams and the camera HAL would fill
+//           the buffers of each streams per requirements specified in
+//           ConfigureStreams() and RegisterBuffer().  For example, the camera
+//           HAL may fill a frame to a still capture buffer with the native
+//           capture resolution, and down-scale the same frame to a lower
+//           resolution for the preview buffer.
+//      The client may continue with RegisterBuffer() -> ProcessCaptureRequest()
+//      up to the pipe-line depth configured in ConfigureStreams().
+//
+//      When the camera HAL is done with a capture request, the capture result
+//      is sent back to the client through the callbacks in Camera3CallbackOps.
+//
+//      For each capture result:
+//        a. The camera HAL notifies the client through Notify() of the shutter
+//           time of the captured frame.  If an error happens while capturing a
+//           frame or filling a buffer, the camera HAL notifies the client
+//           through Notify() of the error.
+//        b. The camera HAL returns the capture result with various result
+//           metadata and the filled buffers to the client in
+//           ProcessCaptureResult().  The result metadata may be sent partially
+//           in multiple stages, and the client must wait until all the partial
+//           metadata are received before handing the capture result to upper
+//           layer.
+//
+//    5. Dump() can be used to dump various information of the camera HAL for
+//       debug purpose.
+//
+//    6. Flush() tells the camera HAL to finish processing or discard the
+//       current on-going capture requests and return to the state where
+//       ConfigureStreams() can be called again to set up new streams.
+//
+//    7. Close() closes the camera device.
+
+interface Camera3DeviceOps {
+  // Initialize() is called once after the camera device is opened to register
+  // the Camera3CallbackOps handle.
+  Initialize@0(Camera3CallbackOps callback_ops) => (int32 result);
+
+  // ConfigureStreams() is called every time the client needs to set up new set
+  // of streams.
+  ConfigureStreams@1(Camera3StreamConfiguration config) =>
+      (int32 result, Camera3StreamConfiguration? updated_config);
+
+  // ConstructDefaultRequestSettings() is called to get the request settings for
+  // common use cases, e.g. preview, still capture, video recording...etc.
+  ConstructDefaultRequestSettings@2(Camera3RequestTemplate type) =>
+      (CameraMetadata? settings);
+
+  // ProcessCaptureRequest() is the core method and is called for every captured
+  // frame to provide the camera HAL with the capture settings and the
+  // associated buffers to fill.
+  ProcessCaptureRequest@3(Camera3CaptureRequest request) => (int32 result);
+
+  // Dump() is called to gather various states and information about the camera
+  // HAL; it is mainly for debug purpose.
+  Dump@4(handle fd);
+
+  // Flush() is called to clear out any in-progress captures and return the
+  // camera HAL to idle state.
+  Flush@5() => (int32 result);
+
+  // The type of buffers the ARC++ camera service currently supports.
+  // GRALLOC is for the platform-specific gralloc buffer allocated by Android.
+  // SHM is for the shared memory buffer allocated by Chrome.
+  enum BufferType {
+    GRALLOC = 0,  // gralloc buffer. Needs to be imported through GBM.
+    SHM = 1,      // shared memory buffer. Can be mmapped directly.
+    // Add DMABUF when needed.
+  };
+
+  // RegisterBuffer() is called to register a buffer with the camera HAL.  The
+  // registered buffer can then be specified in ProcessCaptureRequest() for the
+  // camera HAL to fill captured frame.  RegisterBuffer() is not part of the
+  // Android camera HAL v3 API; it is added for ARC++ camera service to pass
+  // buffer handles across different processes.
+  RegisterBuffer@6(uint64 buffer_id, BufferType type, array<handle> fds,
+                   uint32 drm_format, HalPixelFormat hal_pixel_format,
+                   uint32 width, uint32 height, array<uint32> strides,
+                   array<uint32> offsets) =>
+      (int32 result);
+
+  // Close() is called to close the camera device.
+  Close@7() => (int32 result);
+};
+
+struct Camera3CaptureResult {
+  uint32 frame_number;
+  CameraMetadata result;
+  array<Camera3StreamBuffer>? output_buffers;
+  Camera3StreamBuffer? input_buffer;
+  uint32 partial_result;
+};
+
+enum Camera3ErrorMsgCode {
+  CAMERA3_MSG_ERROR_DEVICE = 1,
+  CAMERA3_MSG_ERROR_REQUEST = 2,
+  CAMERA3_MSG_ERROR_RESULT = 3,
+  CAMERA3_MSG_ERROR_BUFFER = 4,
+  CAMERA3_MSG_NUM_ERRORS,
+};
+
+struct Camera3ErrorMsg {
+  uint32 frame_number;
+  uint64 error_stream_id;
+  Camera3ErrorMsgCode error_code;
+};
+
+struct Camera3ShutterMsg {
+  uint32 frame_number;
+  uint64 timestamp;
+};
+
+union Camera3NotifyMsgMessage {
+  Camera3ErrorMsg error;
+  Camera3ShutterMsg shutter;
+  array<uint8> generic;
+};
+
+struct Camera3NotifyMsg {
+  Camera3MsgType type;
+  Camera3NotifyMsgMessage message;
+};
+
+// Camera3CallbackOps is a translation of the camera3_callback_ops_t API
+// in Android camera HAL v3.  For the work flow of the functions in
+// Camera3CallbackOps, see the comments about Camear3DeviceOps above.

[chfremer, 2017/05/26 17:40:58]

typo: Camera3DeviceOps

[jcliang, 2017/05/31 14:58:07]

Done.

+interface Camera3CallbackOps {
+  // ProcessCaptureResult() is called by the camera HAL to send result metadata
+  // and filled buffer to the client.
+  ProcessCaptureResult@0(Camera3CaptureResult result);
+
+  // Notify() is called by the camera HAL to notify the client of the start of
+  // each capture, and of errors encountered.
+  Notify@1(Camera3NotifyMsg msg);
+};
+
+struct CameraInfo {
+  CameraFacing facing;
+  int32 orientation;
+  uint32 device_version;
+  CameraMetadata static_camera_characteristics;
+  // resource cost is not valid in CAMERA_MODULE_API_VERSION_2_3 or lower.
+  // conflicting_devices is not valid in CAMERA_MODULE_API_VERSION_2_3 or lower.
+  // conflicting_devices_length is not valid in CAMERA_MODULE_API_VERSION_2_3 or
+  // lower.
+};
+
+// CameraModule is a translation of the camera_module_t API
+// (https://goo.gl/8Hf8S8).  CameraModule is the interface to interact with a
+// camera HAL to query device info and open camera devices.
+interface CameraModule {
+  // Opens the camera device specified by |camera_id|.  On success, the camera
+  // device is accessible through the |device_ops| returned.
+  OpenDevice@0(int32 camera_id) => (int32 result, Camera3DeviceOps? device_ops);

[chfremer, 2017/05/26 17:40:58]

When I worked on the video_capture service mojoms, I was told that the standard
"Mojo" way of "returning" an instance of an interface is not to use an output
parameter but instead pass-in a "request" along with the input parameters, see
for example
https://cs.chromium.org/chromium/src/services/video_capture/public/interfaces....

Assuming that is still the case, we may want to do this here as well.

[jcliang, 2017/05/31 14:58:07]

Done.

+
+  // Gets the number of cameras currently present on the system.
+  GetNumberOfCameras@1() => (int32 result);
+
+  // Gets various info about the camera specified by |camera_id|.
+  GetCameraInfo@2(int32 camera_id) => (int32 result, CameraInfo? camera_info);
+
+  // Registers the CameraModuleCallbacks interface with the camera HAL.
+  SetCallbacks@3(CameraModuleCallbacks callbacks) => (int32 result);

[chfremer, 2017/05/26 17:40:58]

Any reason why we wouldn't want to use an enum for result codes instead of an
int32?

[jcliang, 2017/05/31 14:58:07]

The returned result codes are either 0 or the standard errno defined in errno.h.
Is it a convention in Chrome to explicitly define the standard errno in mojom?

[chfremer, 2017/05/31 18:30:41]

I assume you are referring to errno.h from the C standard library?
I don't know about any conventions, but as a reader (and someone who does not
use C much), I had no clue or expectation that error codes could be assumed to
be related to some C standard. If you prefer to use them, please document it
somewhere in the description. Otherwise, I feel an explicit enum would be more
clear.

[jcliang, 2017/06/01 17:11:16]

Yes I mean the errno.h from C standard library. I can change the return values
to enum but I'd like to do that in another CL. These Mojo interfaces are in
active use between Chrome OS and Android container now. I'll need to collect all
the error numbers we use in every function.

+};
+
+enum CameraDeviceStatus {
+  CAMERA_DEVICE_STATUS_NOT_PRESENT = 0,
+  CAMERA_DEVICE_STATUS_PRESENT = 1,
+  CAMERA_DEVICE_STATUS_ENUMERATING = 2,
+};
+
+// CameraModuleCallbacks is a translation of the camera_module_callbacks_t API
+// (https://goo.gl/8Hf8S8).  CameraModuleCallbacks is used by the camera HAL to
+// inform the client of the various status change of a camera.
+interface CameraModuleCallbacks {
+  // CameraDeviceStatusChange() is called by the camera HAL to notify the client
+  // of the new status of the camera device specified by |camera_id|.
+  CameraDeviceStatusChange@0(int32 camera_id, CameraDeviceStatus new_status);
+};