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,
+  CAMEAR3_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 {
+  uint32 num_streams;
+  array<Camera3Stream> streams;
+  Camera3StreamConfigurationMode operation_mode;
+  int32 error;  // Used to piggyback error code returned by driver.
+};
+
+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 in
+//           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) =>
+      (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.
+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.
+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);
+
+  // Gets the number of cameras currently present on the system.
+  GetNumberOfCameras@1() => (int32 result);
+
+  // Gets various info about a 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);
+};
+
+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.
+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);
+};