sdk/banjo/fuchsia.hardware.camera.sensor/camera-sensor.banjo - fuchsia - Git at Google

 // Copyright 2020 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.hardware.camera.sensor;

 using fuchsia.hardware.camera;
 using zx;

 const uint32 EXTENSION_VALUE_ARRAY_LEN = 32;

 /// A type used to distinguish extension parameters.
 union ExtensionValueDataType {
     1: int32 int_value;
     2: uint32 uint_value;
     3: array<uint8>:EXTENSION_VALUE_ARRAY_LEN byte_array_value;
     4: fuchsia.hardware.camera.Dimensions dimension_value;
     5: fuchsia.hardware.camera.MinMaxConstraints constraints_value;
     6: array<FrameRateInfo>:EXTENSION_VALUE_ARRAY_LEN frame_rate_info_value;
 };

 enum PixelType : uint8 {
     RAW8 = 1;
     RAW10 = 2;
     RAW12 = 3;
 };

 enum DynamicRangeMode : uint8 {
     LINEAR = 1;
     WIDE = 2;
 };

 enum BinningMode : uint8 {
     NONE = 1;
     ADDITIVE = 2;
     AVERAGE = 3;
 };

 struct SamplingParams {
     BinningMode mode;
     uint32 bin_amount;
     uint32 skip_amount;
 };

 struct ReadoutConfig {
     /// Describes sampling parameters for the x plane.
     SamplingParams sampling_x;
     /// Describes sampling parameters for the y plane.
     SamplingParams sampling_y;
     /// The x and y offset as well as the width and height for cropping.
     fuchsia.hardware.camera.Rect scaler_crop;
 };

 /// A sensor can support several different predefined modes.
 /// This structure keeps all necessary information about a mode.
 // TODO(fxbug.dev/55427): Move non-sensor-specific params out of this struct.
 struct OperatingMode {
     /// This mode's index.
     uint8 idx;
     /// This mode's identifying string.
     string identifier;
     /// Maximum frames per second.
     uint32 fps;
     /// Input resolution, where |x| is pixel width and |y| is pixel height.
     fuchsia.hardware.camera.Dimensions resolution_in;
     /// Output resolution, where |x| is pixel width and |y| is pixel height.
     fuchsia.hardware.camera.Dimensions resolution_out;
     /// How many exposures this mode supports.
     uint8 exposures;
     /// A mode that reflects what dynamic range technique is being used.
     DynamicRangeMode dr_mode;
     /// The pixel type (e.g. whether the output is in RAW8, RAW10, etc. format).
     PixelType pixel_type;
     /// Lane count.
     uint8 lanes;
     /// MBps per lane.
     uint32 mbps;
     /// Line time.
     float32 line_time;
     /// Frame time.
     float32 frame_time;
     /// A structure containing information on binning, skipping, and scaling
     /// operations carried out on frame data.
     ReadoutConfig readout;
 };

 /// This structure maps the sensor's frame rates to coarse max integration time.
 struct FrameRateInfo  {
     fuchsia.hardware.camera.FrameRate frame_rate;
     uint32 max_coarse_integration_time;
 };

 /// Exposes a product-agnostic interface to the camera's sensor.
 /// Allows clients to get and set sensor constraints, sensor mode,
 /// and its dynamic operating state.
 ///
 /// Most methods provide a `zx.status` return value. This can be:
 ///    ZX_OK                      - The operation was successful.
 ///    ZX_ERR_INTERNAL            - The sensor has not been initialized or has encountered an
 ///                                 otherwise unspecified error.
 ///    ZX_ERR_NOT_SUPPORTED       - The operation is not supported on the current device.
 ///    ZX_ERR_INVALID_ARGS        - Invalid args for this operation.
 ///    ZX_ERR_OUT_OF_RANGE        - Args fall outside of min/max constraints.
 ///    ZX_ERR_BUFFER_TOO_SMALL    - Buffer provided cannot hold all required data.
 ///    ZX_ERR_IO_NOT_PRESENT      - There is no sensor device present or bound.
 // TODO(fxbug.dev/55428): Incorporate muting behavior into documentation. Add arg/return value info.
 // TODO(fxbug.dev/56558): Add a versioning mechanism.
 // TODO(fxbug.dev/55430): Transition methods to use [Async].
 [Transport = "Banjo", BanjoLayout = "ddk-protocol"]
 protocol CameraSensor2 {
     /// Initializes the sensor.
     Init() -> (zx.status s);
     /// De-Initializes the sensor.
     DeInit() -> ();

     /// Retrieves the sensor's ID.
     GetSensorId() -> (zx.status s, uint32 id);

     /// Retrieve a vector of available modes.
     GetAvailableModes() -> (zx.status s, vector<OperatingMode> modes);
     /// Use a specific mode for the initialization sequence.
     SetMode(uint32 mode) -> (zx.status s);

     /// Start streaming.
     /// Is safe to call this if streaming is already started.
     StartStreaming() -> (zx.status s);
     /// Stop streaming.
     /// It is safe to call this if streaming is already stopped.
     StopStreaming() -> ();

     // Exposure Settings

     /// Retrieve analog gain value.
     GetAnalogGain() -> (zx.status s, float32 gain);
     /// Changes analog gain value.
     SetAnalogGain(float32 gain) -> (zx.status s, float32 gain);
     /// Retrieve digital gain value.
     GetDigitalGain() -> (zx.status s, float32 gain);
     /// Changes digital gain value.
     SetDigitalGain(float32 gain) -> (zx.status s, float32 gain);
     /// Retrieve integration time value.
     GetIntegrationTime() -> (zx.status s, float32 int_time);
     /// Changes Integration Time.
     SetIntegrationTime(float32 int_time) -> (zx.status s, float32 int_time);

     /// Update the sensor with new parameters.
     Update() -> (zx.status s);

     // OTP

     /// Retrieve the total size of the data stored in the OTP module.
     GetOtpSize() -> (zx.status s, uint32 size);
     /// Retrieve the specified amount of OTP data at the offset and write them to
     /// the provided vmo.
     GetOtpData(uint32 byte_count, uint32 offset) -> (zx.status s, zx.handle:VMO otp_data);

     // Test Controls

     /// Retrieves the test pattern mode the sensor is set to.
     ///    0            – No pattern (default)
     ///    1            – Solid colour
     ///    2            – 100% colour bars
     ///    3            – Fade to grey’ colour bars
     ///    4            - PN9
     ///    5-255        - Reserved
     ///    256-65535    – Manufacturer specific
     GetTestPatternMode() -> (zx.status s, uint16 value);
     /// Changes the sensor's test pattern mode.
     SetTestPatternMode(uint16 mode) -> (zx.status s);
     /// Retrieves the test pattern data being used.
     GetTestPatternData() -> (zx.status s, fuchsia.hardware.camera.ColorVal data);
     /// Changes data used by the test pattern. Only used by certain modes.
     SetTestPatternData(fuchsia.hardware.camera.ColorVal data) -> (zx.status s);

     /// Retrieves the test cursor data being used.
     GetTestCursorData() -> (zx.status s, fuchsia.hardware.camera.Rect data);
     /// Changes the sensor's cursor-related parameters.
     SetTestCursorData(fuchsia.hardware.camera.Rect data) -> (zx.status s);

     // Other Capabilities

     /// This subset of the API provides implementers with the flexibility to provide custom
     /// endpoints for elements not otherwise included.
     /// Retrieves the specified element. The caller must reference the implementer's ID list.
     GetExtensionValue(uint64 id) -> (zx.status s, ExtensionValueDataType value);
     /// This subset of the API provides implementers with the flexibility to provide custom
     /// endpoints for elements not otherwise included.
     /// Changes the specified element. The caller must reference the implementer's ID list.
     SetExtensionValue(uint64 id, ExtensionValueDataType value)
         -> (zx.status s, ExtensionValueDataType value);
 };
	// Copyright 2020 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.hardware.camera.sensor;

	using fuchsia.hardware.camera;
	using zx;

	const uint32 EXTENSION_VALUE_ARRAY_LEN = 32;

	/// A type used to distinguish extension parameters.
	union ExtensionValueDataType {
	1: int32 int_value;
	2: uint32 uint_value;
	3: array<uint8>:EXTENSION_VALUE_ARRAY_LEN byte_array_value;
	4: fuchsia.hardware.camera.Dimensions dimension_value;
	5: fuchsia.hardware.camera.MinMaxConstraints constraints_value;
	6: array<FrameRateInfo>:EXTENSION_VALUE_ARRAY_LEN frame_rate_info_value;
	};

	enum PixelType : uint8 {
	RAW8 = 1;
	RAW10 = 2;
	RAW12 = 3;
	};

	enum DynamicRangeMode : uint8 {
	LINEAR = 1;
	WIDE = 2;
	};

	enum BinningMode : uint8 {
	NONE = 1;
	ADDITIVE = 2;
	AVERAGE = 3;
	};

	struct SamplingParams {
	BinningMode mode;
	uint32 bin_amount;
	uint32 skip_amount;
	};

	struct ReadoutConfig {
	/// Describes sampling parameters for the x plane.
	SamplingParams sampling_x;
	/// Describes sampling parameters for the y plane.
	SamplingParams sampling_y;
	/// The x and y offset as well as the width and height for cropping.
	fuchsia.hardware.camera.Rect scaler_crop;
	};

	/// A sensor can support several different predefined modes.
	/// This structure keeps all necessary information about a mode.
	// TODO(fxbug.dev/55427): Move non-sensor-specific params out of this struct.
	struct OperatingMode {
	/// This mode's index.
	uint8 idx;
	/// This mode's identifying string.
	string identifier;
	/// Maximum frames per second.
	uint32 fps;
	/// Input resolution, where \|x\| is pixel width and \|y\| is pixel height.
	fuchsia.hardware.camera.Dimensions resolution_in;
	/// Output resolution, where \|x\| is pixel width and \|y\| is pixel height.
	fuchsia.hardware.camera.Dimensions resolution_out;
	/// How many exposures this mode supports.
	uint8 exposures;
	/// A mode that reflects what dynamic range technique is being used.
	DynamicRangeMode dr_mode;
	/// The pixel type (e.g. whether the output is in RAW8, RAW10, etc. format).
	PixelType pixel_type;
	/// Lane count.
	uint8 lanes;
	/// MBps per lane.
	uint32 mbps;
	/// Line time.
	float32 line_time;
	/// Frame time.
	float32 frame_time;
	/// A structure containing information on binning, skipping, and scaling
	/// operations carried out on frame data.
	ReadoutConfig readout;
	};

	/// This structure maps the sensor's frame rates to coarse max integration time.
	struct FrameRateInfo {
	fuchsia.hardware.camera.FrameRate frame_rate;
	uint32 max_coarse_integration_time;
	};

	/// Exposes a product-agnostic interface to the camera's sensor.
	/// Allows clients to get and set sensor constraints, sensor mode,
	/// and its dynamic operating state.
	///
	/// Most methods provide a `zx.status` return value. This can be:
	/// ZX_OK - The operation was successful.
	/// ZX_ERR_INTERNAL - The sensor has not been initialized or has encountered an
	/// otherwise unspecified error.
	/// ZX_ERR_NOT_SUPPORTED - The operation is not supported on the current device.
	/// ZX_ERR_INVALID_ARGS - Invalid args for this operation.
	/// ZX_ERR_OUT_OF_RANGE - Args fall outside of min/max constraints.
	/// ZX_ERR_BUFFER_TOO_SMALL - Buffer provided cannot hold all required data.
	/// ZX_ERR_IO_NOT_PRESENT - There is no sensor device present or bound.
	// TODO(fxbug.dev/55428): Incorporate muting behavior into documentation. Add arg/return value info.
	// TODO(fxbug.dev/56558): Add a versioning mechanism.
	// TODO(fxbug.dev/55430): Transition methods to use [Async].
	[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
	protocol CameraSensor2 {
	/// Initializes the sensor.
	Init() -> (zx.status s);
	/// De-Initializes the sensor.
	DeInit() -> ();

	/// Retrieves the sensor's ID.
	GetSensorId() -> (zx.status s, uint32 id);

	/// Retrieve a vector of available modes.
	GetAvailableModes() -> (zx.status s, vector<OperatingMode> modes);
	/// Use a specific mode for the initialization sequence.
	SetMode(uint32 mode) -> (zx.status s);

	/// Start streaming.
	/// Is safe to call this if streaming is already started.
	StartStreaming() -> (zx.status s);
	/// Stop streaming.
	/// It is safe to call this if streaming is already stopped.
	StopStreaming() -> ();

	// Exposure Settings

	/// Retrieve analog gain value.
	GetAnalogGain() -> (zx.status s, float32 gain);
	/// Changes analog gain value.
	SetAnalogGain(float32 gain) -> (zx.status s, float32 gain);
	/// Retrieve digital gain value.
	GetDigitalGain() -> (zx.status s, float32 gain);
	/// Changes digital gain value.
	SetDigitalGain(float32 gain) -> (zx.status s, float32 gain);
	/// Retrieve integration time value.
	GetIntegrationTime() -> (zx.status s, float32 int_time);
	/// Changes Integration Time.
	SetIntegrationTime(float32 int_time) -> (zx.status s, float32 int_time);

	/// Update the sensor with new parameters.
	Update() -> (zx.status s);

	// OTP

	/// Retrieve the total size of the data stored in the OTP module.
	GetOtpSize() -> (zx.status s, uint32 size);
	/// Retrieve the specified amount of OTP data at the offset and write them to
	/// the provided vmo.
	GetOtpData(uint32 byte_count, uint32 offset) -> (zx.status s, zx.handle:VMO otp_data);

	// Test Controls

	/// Retrieves the test pattern mode the sensor is set to.
	/// 0 – No pattern (default)
	/// 1 – Solid colour
	/// 2 – 100% colour bars
	/// 3 – Fade to grey’ colour bars
	/// 4 - PN9
	/// 5-255 - Reserved
	/// 256-65535 – Manufacturer specific
	GetTestPatternMode() -> (zx.status s, uint16 value);
	/// Changes the sensor's test pattern mode.
	SetTestPatternMode(uint16 mode) -> (zx.status s);
	/// Retrieves the test pattern data being used.
	GetTestPatternData() -> (zx.status s, fuchsia.hardware.camera.ColorVal data);
	/// Changes data used by the test pattern. Only used by certain modes.
	SetTestPatternData(fuchsia.hardware.camera.ColorVal data) -> (zx.status s);

	/// Retrieves the test cursor data being used.
	GetTestCursorData() -> (zx.status s, fuchsia.hardware.camera.Rect data);
	/// Changes the sensor's cursor-related parameters.
	SetTestCursorData(fuchsia.hardware.camera.Rect data) -> (zx.status s);

	// Other Capabilities

	/// This subset of the API provides implementers with the flexibility to provide custom
	/// endpoints for elements not otherwise included.
	/// Retrieves the specified element. The caller must reference the implementer's ID list.
	GetExtensionValue(uint64 id) -> (zx.status s, ExtensionValueDataType value);
	/// This subset of the API provides implementers with the flexibility to provide custom
	/// endpoints for elements not otherwise included.
	/// Changes the specified element. The caller must reference the implementer's ID list.
	SetExtensionValue(uint64 id, ExtensionValueDataType value)
	-> (zx.status s, ExtensionValueDataType value);
	};