system/fidl/camera/camera_stream.fidl

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.camera_stream;

// TODO: Add when Zircon's build supports library dependencies.
// using sysmen;

enum CameraCaptureType {
  INVALID = 0;
  STILL_IMAGE = 1;       // The source will provide on image.
  BURST  = 2;              // The source will provide a set of images.
  STREAM = 3;              // The source will be continuously providing frames
                           // until signalled to stop.
};


// This pixel type is a stand-in for the pixel_format that will be defined in
// the buffer collections.
enum CameraPixelFormat {
  INVALID = 0;      // default value, not supported
  RGB32 = 1;        // 32bpp BGRA, 1 plane.
  I420 = 2;
  M420 = 3;
  NV12 = 4;
  YUY2 = 5;
  MJPEG = 6;
};

// A structure used along with the CAMERA_STREAM_CMD_GET_FORMATS command
// in order to describe the formats supported by a video stream.
struct CameraVideoFormat {
  CameraCaptureType capture_type;
  // The width, in pixels, of the decoded video.
  uint16 width;
  // The height, in pixels, of the decoded video.
  uint16 height;
  // The number of bytes per line of video.
  uint32 stride;
  // The number of bits per pixel used to specify color in the decoded video.
  uint8 bits_per_pixel;
  CameraPixelFormat pixel_format;
  // The frame rate is frames_per_sec_numerator / frames_per_sec_denominator.
  uint32 frames_per_sec_numerator;
  uint32 frames_per_sec_denominator;
};

// Status to be set when a frame is signalled available.
enum FrameStatus {
  CAMERA_ERROR_NONE = 0;
  // An error occurred during the production of a frame.
  // No data will be available in the data buffer corresponding to this
  // notification.
  CAMERA_ERROR_FRAME = 1;

  // No space was available in the data buffer, resulting in a dropped frame.
  CAMERA_ERROR_BUFFER_FULL = 2;
};

// Sent by the driver to the client when a frame is available for processing,
// or an error occurred.
struct FrameAvailable {
  // Non zero if an error occurred.
  FrameStatus error;

  // The index of the buffer in the buffer collection
  uint32 buffer_id;

  // Number of bytes in the frame.
  uint32 frame_size;

  // The position (in bytes) of the start of the frame in the data buffer.
  uint64 data_vb_offset;

 // TODO(garratt): Add metadata.
};

// A stand-in for the Video buffer collection:
struct BufferCollection {
  vector<handle> buffers;
  CameraVideoFormat format;
};

// Streaming Controls:
// A StreamFactory lets you request streams from the camera.  It may be possible
// to request more than one stream.  The number of streams will be limited by
// the hardware, and the interface you received.
interface StreamFactory {
  1: GetFormats() -> (vector<CameraVideoFormat> formats);
  2: RequestStream(BufferCollection buffer_collection, request<StreamControl> stream) -> (uint32 status_code);
};

// A stream control interface allows you to start and stop the stream,
// and notifies you when a frame is available. Closing the channel will
// end the stream.
interface StreamControl {
  1: Start();
  2: Stop();
  // These functions may be taken care of by BufferCollection in the future
  3: -> OnFrameAvailable(FrameAvailable frame);
  4: ReleaseFrame(uint32 buffer_id);
};