blob: ec11bc16c4deeea90198064faf5d063d3c3d2304 [file] [log] [blame]
// 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 EXTENSION_VALUE_ARRAY_LEN uint32 = 32;
/// A type used to distinguish extension parameters.
type ExtensionValueDataType = strict union {
1: int_value int32;
2: uint_value uint32;
3: byte_array_value array<uint8, EXTENSION_VALUE_ARRAY_LEN>;
4: dimension_value fuchsia.hardware.camera.Dimensions;
5: constraints_value fuchsia.hardware.camera.MinMaxConstraints;
6: frame_rate_info_value array<FrameRateInfo, EXTENSION_VALUE_ARRAY_LEN>;
};
type PixelType = strict enum : uint8 {
RAW8 = 1;
RAW10 = 2;
RAW12 = 3;
};
type DynamicRangeMode = strict enum : uint8 {
LINEAR = 1;
WIDE = 2;
};
type BinningMode = strict enum : uint8 {
NONE = 1;
ADDITIVE = 2;
AVERAGE = 3;
};
type SamplingParams = struct {
mode BinningMode;
bin_amount uint32;
skip_amount uint32;
};
type ReadoutConfig = struct {
/// Describes sampling parameters for the x plane.
sampling_x SamplingParams;
/// Describes sampling parameters for the y plane.
sampling_y SamplingParams;
/// The x and y offset as well as the width and height for cropping.
scaler_crop fuchsia.hardware.camera.Rect;
};
/// 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.
type OperatingMode = struct {
/// This mode's index.
idx uint8;
/// This mode's identifying string.
identifier string:MAX;
/// Maximum frames per second.
fps uint32;
/// Input resolution, where |x| is pixel width and |y| is pixel height.
resolution_in fuchsia.hardware.camera.Dimensions;
/// Output resolution, where |x| is pixel width and |y| is pixel height.
resolution_out fuchsia.hardware.camera.Dimensions;
/// How many exposures this mode supports.
exposures uint8;
/// A mode that reflects what dynamic range technique is being used.
dr_mode DynamicRangeMode;
/// The pixel type (e.g. whether the output is in RAW8, RAW10, etc. format).
pixel_type PixelType;
/// Lane count.
lanes uint8;
/// MBps per lane.
mbps uint32;
/// Line time.
line_time float32;
/// Frame time.
frame_time float32;
/// A structure containing information on binning, skipping, and scaling
/// operations carried out on frame data.
readout ReadoutConfig;
};
/// This structure maps the sensor's frame rates to coarse max integration time.
type FrameRateInfo = struct {
frame_rate fuchsia.hardware.camera.FrameRate;
max_coarse_integration_time uint32;
};
// 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].
/// 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.
@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol CameraSensor2 {
/// Initializes the sensor.
Init() -> (struct {
s zx.status;
});
/// De-Initializes the sensor.
DeInit() -> ();
/// Retrieves the sensor's ID.
GetSensorId() -> (struct {
s zx.status;
id uint32;
});
/// Retrieve a vector of available modes.
GetAvailableModes() -> (struct {
s zx.status;
modes vector<OperatingMode>:MAX;
});
/// Use a specific mode for the initialization sequence.
SetMode(struct {
mode uint32;
}) -> (struct {
s zx.status;
});
/// Start streaming.
/// Is safe to call this if streaming is already started.
StartStreaming() -> (struct {
s zx.status;
});
/// Stop streaming.
/// It is safe to call this if streaming is already stopped.
StopStreaming() -> ();
// Exposure Settings
/// Retrieve analog gain value.
GetAnalogGain() -> (struct {
s zx.status;
gain float32;
});
/// Changes analog gain value.
SetAnalogGain(struct {
gain float32;
}) -> (struct {
s zx.status;
gain float32;
});
/// Retrieve digital gain value.
GetDigitalGain() -> (struct {
s zx.status;
gain float32;
});
/// Changes digital gain value.
SetDigitalGain(struct {
gain float32;
}) -> (struct {
s zx.status;
gain float32;
});
/// Retrieve integration time value.
GetIntegrationTime() -> (struct {
s zx.status;
int_time float32;
});
/// Changes Integration Time.
SetIntegrationTime(struct {
int_time float32;
}) -> (struct {
s zx.status;
int_time float32;
});
/// Update the sensor with new parameters.
Update() -> (struct {
s zx.status;
});
// OTP
/// Retrieve the total size of the data stored in the OTP module.
GetOtpSize() -> (struct {
s zx.status;
size uint32;
});
/// Retrieve the specified amount of OTP data at the offset and write them to
/// the provided vmo.
GetOtpData(struct {
byte_count uint32;
offset uint32;
}) -> (resource struct {
s zx.status;
otp_data zx.handle:VMO;
});
// 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() -> (struct {
s zx.status;
value uint16;
});
/// Changes the sensor's test pattern mode.
SetTestPatternMode(struct {
mode uint16;
}) -> (struct {
s zx.status;
});
/// Retrieves the test pattern data being used.
GetTestPatternData() -> (struct {
s zx.status;
data fuchsia.hardware.camera.ColorVal;
});
/// Changes data used by the test pattern. Only used by certain modes.
SetTestPatternData(struct {
data fuchsia.hardware.camera.ColorVal;
}) -> (struct {
s zx.status;
});
/// Retrieves the test cursor data being used.
GetTestCursorData() -> (struct {
s zx.status;
data fuchsia.hardware.camera.Rect;
});
/// Changes the sensor's cursor-related parameters.
SetTestCursorData(struct {
data fuchsia.hardware.camera.Rect;
}) -> (struct {
s zx.status;
});
// 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(struct {
id uint64;
}) -> (struct {
s zx.status;
value ExtensionValueDataType;
});
/// 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(struct {
id uint64;
value ExtensionValueDataType;
}) -> (struct {
s zx.status;
value ExtensionValueDataType;
});
};