SpecsCamera
SPECS NDK reference for the SpecsCamera API, which discovers cameras and their stream configurations, opens camera streams and delivers frames.
SpecsCamera is the camera stream management API for SPECS. It connects to the camera service, enumerates the device's physical cameras by location and modality, lists the stream configurations each camera supports, and opens streaming and still-capture streams that deliver frames through callbacks.
Include and link SpecsCamera
#include <SpecsCameraManager.h>
// Transitively includes:
// SpecsCameraDefinitions.h — enums, result codes and handle types
// SpecsCameraStructures.h — camera, frame, config and stream description structs
target_link_libraries(myapp specs_camera)
The library is libspecs_camera.so, with the shared-object name (SONAME) libspecs_camera.so.2.
Required permission: CAMERA_RAW—SpecsCameraStream_add, SpecsCameraStream_setupCapture, and SpecsCameraStream_captureOnce are annotated with SPECS_REQUIRES_PERMISSION(CAMERA_RAW). The permission is recorded in your library's .snap.permissions manifest at build time; see Permission Annotations and Manifest Embedding. A permission or lifecycle denial returns SPECSCAMERA_PERMISSION_DENIED.
SpecsCamera core concepts
| Concept | Type | Description |
|---|---|---|
| Client | SpecsCamera_Client_t * | Connection to the camera service. Required before any discovery or stream operation. Discovery results are cached for the client's lifetime. |
| Camera | SpecsCamera_CameraInfo_t | A physical camera, identified by its exact location mask (SpecsCamera_Location_t) and its sensor modality (SpecsCamera_Modality_t). Returned by SpecsCamera_camerasGet(). |
| StreamDescription | SpecsCamera_StreamDescription_t | A stream configuration: camera, resolution, quality preference, frame rate, initial config and callbacks. SpecsCamera_cameraStreamsGet() returns the supported ones; each is for exactly one operation (SpecsCamera_StreamOperation_t). |
| Stream | SpecsCamera_StreamId_t | An active camera pipeline, identified by an opaque int64_t ID returned by SpecsCameraStream_add() (streaming) or SpecsCameraStream_setupCapture() (still capture). |
| Frame | SpecsCamera_Frame_t | A captured image buffer with timestamp, pixel data and metadata. Delivered through SpecsCamera_FrameCallback_t. |
| ConfigItem | SpecsCamera_ConfigItem_t | A tagged value array used for initial stream configuration, runtime updates and per-frame metadata. |
A typical session:
- Create a client with
SpecsCameraClient_create(). - List the physical cameras with
SpecsCamera_camerasGet(). - Pass a camera's exact
locationandmodalitytoSpecsCamera_cameraStreamsGet()to list its stream descriptions. - Pick a description by its
operationfield, copy it, and set callbacks (and any other changes) on the copy. - Open the stream:
SpecsCameraStream_add()for aSPECSCAMERA_STREAM_OPERATION_STREAMINGdescription, orSpecsCameraStream_setupCapture()thenSpecsCameraStream_captureOnce()for aSPECSCAMERA_STREAM_OPERATION_SNAPSHOTdescription.
The client handle and stream identifier are declared in SpecsCameraDefinitions.h:
// Opaque stream identifier type.
// Since: v1.3.0
typedef int64_t SpecsCamera_StreamId_t;
// Opaque client handle (implementation-private).
// Since: v1.3.0
typedef struct SpecsCamera_Client_s SpecsCamera_Client_t;
SpecsCamera result codes
// Since: v1.3.0
typedef enum SpecsCamera_Result_t {
SPECSCAMERA_SUCCESS = 0, ///< Operation succeeded.
SPECSCAMERA_ERROR_GENERIC = 1, ///< Generic/unspecified error.
SPECSCAMERA_INVALID_ARGUMENT = 2, ///< Invalid input argument.
SPECSCAMERA_SERVICE_CONNECTION_FAILED = 3, ///< Failed to connect to the camera service.
SPECSCAMERA_PERMISSION_DENIED = 4 ///< APP permission or lifecycle admission denied.
} SpecsCamera_Result_t;
SpecsCamera_Result_t is the status code that SpecsCamera functions return.
| Code | Value | Meaning |
|---|---|---|
SPECSCAMERA_SUCCESS | 0 | Operation succeeded |
SPECSCAMERA_ERROR_GENERIC | 1 | Generic or unspecified error |
SPECSCAMERA_INVALID_ARGUMENT | 2 | Invalid input argument, including a configuration the requested operation doesn't support and an unknown camera |
SPECSCAMERA_SERVICE_CONNECTION_FAILED | 3 | Failed to connect to the camera service |
SPECSCAMERA_PERMISSION_DENIED | 4 | App permission or lifecycle admission denied |
SpecsCamera cameras
SpecsCamera_camerasGet() lists the device's physical cameras. Each camera has an exact location mask and a sensor modality; pass both, unchanged, to SpecsCamera_cameraStreamsGet().
SpecsCamera_CameraInfo_t
Since: v1.3.0
A physical camera, as returned by SpecsCamera_camerasGet().
typedef struct SpecsCamera_CameraInfo_s {
SpecsCamera_Location_t location; ///< Exact location mask.
SpecsCamera_Modality_t modality; ///< Sensor modality.
char name[64]; ///< Human-readable camera name; informational only.
} SpecsCamera_CameraInfo_t;
| Field | Description |
|---|---|
location | Exact location mask. Pass it to SpecsCamera_cameraStreamsGet() as is. |
modality | Sensor modality. Pass it to SpecsCamera_cameraStreamsGet() with location. |
name | Human-readable camera name; informational only. |
SpecsCamera_Location_t
Since: v1.3.0
typedef enum SpecsCamera_Location_t {
SPECSCAMERA_LOCATION_NONE = 0,
SPECSCAMERA_LOCATION_TOP = 1 << 0,
SPECSCAMERA_LOCATION_BOTTOM = 1 << 1,
SPECSCAMERA_LOCATION_LEFT = 1 << 2,
SPECSCAMERA_LOCATION_RIGHT = 1 << 3,
SPECSCAMERA_LOCATION_INNER = 1 << 4,
SPECSCAMERA_LOCATION_OUTER = 1 << 5,
SPECSCAMERA_LOCATION_WORLD_FACING = 1 << 6,
SPECSCAMERA_LOCATION_USER_FACING = 1 << 7,
} SpecsCamera_Location_t;
SpecsCamera_Location_t holds OR-able position and facing bits. A camera's location is a combination of these bits. Use the exact mask that SpecsCamera_camerasGet() returns rather than a partial mask you build yourself.
| Enum value | Value | Bit |
|---|---|---|
SPECSCAMERA_LOCATION_NONE | 0 | No bits set |
SPECSCAMERA_LOCATION_TOP | 1 << 0 | Top |
SPECSCAMERA_LOCATION_BOTTOM | 1 << 1 | Bottom |
SPECSCAMERA_LOCATION_LEFT | 1 << 2 | Left |
SPECSCAMERA_LOCATION_RIGHT | 1 << 3 | Right |
SPECSCAMERA_LOCATION_INNER | 1 << 4 | Inner |
SPECSCAMERA_LOCATION_OUTER | 1 << 5 | Outer |
SPECSCAMERA_LOCATION_WORLD_FACING | 1 << 6 | World-facing |
SPECSCAMERA_LOCATION_USER_FACING | 1 << 7 | User-facing |
SpecsCamera_Modality_t
Since: v1.3.0
typedef enum SpecsCamera_Modality_t {
SPECSCAMERA_MODALITY_COLOR = 0,
SPECSCAMERA_MODALITY_MONO = 1,
} SpecsCamera_Modality_t;
SpecsCamera_Modality_t is the sensor modality, independent of the camera's physical position.
| Enum value | Value | Description |
|---|---|---|
SPECSCAMERA_MODALITY_COLOR | 0 | Color sensor |
SPECSCAMERA_MODALITY_MONO | 1 | Monochrome sensor |
SpecsCamera stream configurations
SpecsCamera_cameraStreamsGet() returns the geometry, format, frame-rate and quality combinations that a camera supports, as SpecsCamera_StreamDescription_t entries. Each entry is for exactly one operation, reported in its operation field, and its description label ends with the matching comma-delimited tag, streaming or snapshot. Choose a configuration by its operation; image format and dimensions don't identify it, and the same geometry and format may appear once for each operation.
SpecsCamera_StreamOperation_t
Since: v1.3.0
typedef enum SpecsCamera_StreamOperation_t {
SPECSCAMERA_STREAM_OPERATION_UNSPECIFIED = 0, ///< Reported by a library that predates this field.
SPECSCAMERA_STREAM_OPERATION_STREAMING = 1, ///< SpecsCameraStream_add.
SPECSCAMERA_STREAM_OPERATION_SNAPSHOT = 2, ///< SpecsCameraStream_setupCapture.
} SpecsCamera_StreamOperation_t;
SpecsCamera_StreamOperation_t is the entry point that a stream description from SpecsCamera_cameraStreamsGet() is for. In a request, the entry point you call selects the operation and the operation field is ignored.
| Enum value | Value | Entry point |
|---|---|---|
SPECSCAMERA_STREAM_OPERATION_UNSPECIFIED | 0 | Reported by a library that predates this field |
SPECSCAMERA_STREAM_OPERATION_STREAMING | 1 | SpecsCameraStream_add() |
SPECSCAMERA_STREAM_OPERATION_SNAPSHOT | 2 | SpecsCameraStream_setupCapture() |
SpecsCamera_Quality_t
Since: v1.3.0
typedef enum SpecsCamera_Quality_t {
SPECSCAMERA_QUALITY_PERFORMANCE = 0,
SPECSCAMERA_QUALITY_BALANCED = 1,
SPECSCAMERA_QUALITY_ENHANCED = 2,
} SpecsCamera_Quality_t;
SpecsCamera_Quality_t is a best-effort quality preference; it isn't a latency, power or image-quality guarantee. A zero-initialized description selects SPECSCAMERA_QUALITY_PERFORMANCE. Selection prefers the requested quality tier, then the nearest available tier, choosing the cheaper tier on a tie.
| Enum value | Value |
|---|---|
SPECSCAMERA_QUALITY_PERFORMANCE | 0 |
SPECSCAMERA_QUALITY_BALANCED | 1 |
SPECSCAMERA_QUALITY_ENHANCED | 2 |
SpecsCamera image formats
// Since: v1.3.0
typedef enum SpecsCamera_ImageFormat_t {
SPECSCAMERA_IMAGEFORMAT_YUV_420_888 = 0, /**< YUV 4:2:0. */
SPECSCAMERA_IMAGEFORMAT_Y8 = 1, /**< 8-bit grayscale. */
SPECSCAMERA_IMAGEFORMAT_JPEG = 2, /**< Encoded JPEG. */
} SpecsCamera_ImageFormat_t;
SpecsCamera_ImageFormat_t lists the supported image formats. Only frames in these formats are delivered to the frame callback.
| Enum value | Value | Description |
|---|---|---|
SPECSCAMERA_IMAGEFORMAT_YUV_420_888 | 0 | YUV 4:2:0 |
SPECSCAMERA_IMAGEFORMAT_Y8 | 1 | 8-bit grayscale |
SPECSCAMERA_IMAGEFORMAT_JPEG | 2 | Encoded JPEG |
SpecsCamera configuration tags
// Since: v1.3.0
typedef enum SpecsCamera_ConfigTag_t {
SPECSCAMERA_CONFIGTAG_SENSITIVITY_ISO = 0, ///< Sensitivity / ISO gain in use (int64). [R]
SPECSCAMERA_CONFIGTAG_EXPOSURE_TIME_NS = 1, ///< Exposure time in use, in nanoseconds (int64). [R]
SPECSCAMERA_CONFIGTAG_ROLLING_SHUTTER_SKEW_NS = 2, ///< Rolling shutter skew in nanoseconds (int64). [R]
SPECSCAMERA_CONFIGTAG_TEMPERATURE_C = 3, ///< Sensor temperature in degrees Celsius (float). [R]
SPECSCAMERA_CONFIGTAG_MAX_EXPOSURE_NS = 4, ///< Maximum exposure in nanoseconds (int64). [RW]
SPECSCAMERA_CONFIGTAG_REGION_OF_INTEREST = 5, ///< AE region(s) of interest (float array). [RW]
SPECSCAMERA_CONFIGTAG_FRAME_RATE = 6, ///< Frame rate in Hz (rational). [RW]
SPECSCAMERA_CONFIGTAG_CONVERGE = 7, ///< Require 3A convergence before capture (bool). [W]
SPECSCAMERA_CONFIGTAG_IMAGE_FORMAT = 8, ///< Image format (SpecsCamera_ImageFormat_t as int64); set at add/setupCapture, reported in metadata. [RW]
SPECSCAMERA_CONFIGTAG_CROP = 9, ///< Crop rectangle [x, y, width, height] in output pixels (int64 array); not reported back. [W]
SPECSCAMERA_CONFIGTAG_REQUEST_FRAME_COUNT = 10, ///< Number of frames to request (int64). [RW]
SPECSCAMERA_CONFIGTAG_READOUT_TIME_NS = 12, ///< Sensor readout time in nanoseconds (int64). [R]
SPECSCAMERA_CONFIGTAG_SYNC_POINT = 13, ///< Multi-camera synchronization point (int64 enum). [R]
SPECSCAMERA_CONFIGTAG_SNAPSHOT_MFNR_ENABLE = 14, ///< Enable multi-frame noise reduction for a still stream (bool). [W]
} SpecsCamera_ConfigTag_t;
SpecsCamera_ConfigTag_t keys are used in SpecsCamera_ConfigItem_t for requests (initial stream configs, SpecsCameraStream_configChange() and SpecsCameraStream_captureOnce()) and for per-frame metadata. The Access column shows how each tag is used: R is returned in frame metadata, W is set on a request, RW is both.
Cameras always run automatic exposure, so SPECSCAMERA_CONFIGTAG_SENSITIVITY_ISO and SPECSCAMERA_CONFIGTAG_EXPOSURE_TIME_NS report the values in use. The header marks writing them as deprecated, and writing them has no effect.
| Tag | Value | Data type | Access | Description |
|---|---|---|---|---|
SPECSCAMERA_CONFIGTAG_SENSITIVITY_ISO | 0 | int64 | R | Sensitivity / ISO gain in use |
SPECSCAMERA_CONFIGTAG_EXPOSURE_TIME_NS | 1 | int64 | R | Exposure time in use, in nanoseconds |
SPECSCAMERA_CONFIGTAG_ROLLING_SHUTTER_SKEW_NS | 2 | int64 | R | Rolling shutter skew in nanoseconds |
SPECSCAMERA_CONFIGTAG_TEMPERATURE_C | 3 | float | R | Sensor temperature in degrees Celsius |
SPECSCAMERA_CONFIGTAG_MAX_EXPOSURE_NS | 4 | int64 | RW | Maximum exposure in nanoseconds |
SPECSCAMERA_CONFIGTAG_REGION_OF_INTEREST | 5 | float[] | RW | Auto-exposure region or regions of interest |
SPECSCAMERA_CONFIGTAG_FRAME_RATE | 6 | rational | RW | Frame rate in Hz |
SPECSCAMERA_CONFIGTAG_CONVERGE | 7 | bool | W | Require 3A convergence before capture |
SPECSCAMERA_CONFIGTAG_IMAGE_FORMAT | 8 | int64 | RW | SpecsCamera_ImageFormat_t value. Set when the stream is created with SpecsCameraStream_add() or SpecsCameraStream_setupCapture(); reported in metadata. SpecsCameraStream_configChange() rejects it |
SPECSCAMERA_CONFIGTAG_CROP | 9 | int64[] | W | Crop rectangle [x, y, width, height] in output pixels; not reported back |
SPECSCAMERA_CONFIGTAG_REQUEST_FRAME_COUNT | 10 | int64 | RW | Number of frames to request |
SPECSCAMERA_CONFIGTAG_READOUT_TIME_NS | 12 | int64 | R | Sensor readout time in nanoseconds |
SPECSCAMERA_CONFIGTAG_SYNC_POINT | 13 | int64 (enum) | R | Multi-camera synchronization point |
SPECSCAMERA_CONFIGTAG_SNAPSHOT_MFNR_ENABLE | 14 | bool | W | Enable multi-frame noise reduction for a still stream |
SpecsCamera stream notifications
// Since: v1.3.0
typedef enum SpecsCamera_StreamNotificationTag_t {
SPECSCAMERA_STREAMNOTIFY_INTERRUPTION_START = 0, ///< Stream interrupted; frame delivery paused.
SPECSCAMERA_STREAMNOTIFY_INTERRUPTION_OVER = 1, ///< Prior interruption ended; frames resume.
SPECSCAMERA_STREAMNOTIFY_CLIENT_EVICTION = 2, ///< The stream ended: the service stopped it (the client held delivered frames too long, a still stream went 60 s without captureOnce, or the camera switched to a mode without this stream's size), or the camera service restarted. Remove it and set it up again; captureOnce also sets a still stream up again.
SPECSCAMERA_STREAMNOTIFY_CAMERA_ACCESS_REVOKED = 3, ///< Camera permission revoked; frames stop and delivered buffers are no longer accessible. Remove the stream.
} SpecsCamera_StreamNotificationTag_t;
SpecsCamera_StreamNotificationTag_t values are passed to SpecsCamera_NotificationCallback_t. Only these notifications are delivered.
| Tag | Value | Meaning |
|---|---|---|
SPECSCAMERA_STREAMNOTIFY_INTERRUPTION_START | 0 | Stream interrupted; frame delivery paused |
SPECSCAMERA_STREAMNOTIFY_INTERRUPTION_OVER | 1 | The interruption ended; frames resume |
SPECSCAMERA_STREAMNOTIFY_CLIENT_EVICTION | 2 | The stream ended. Either the service stopped it (the client held delivered frames too long, a still stream went 60 seconds without SpecsCameraStream_captureOnce(), or the camera switched to a mode without this stream's size) or the camera service restarted. Remove the stream and set it up again; SpecsCameraStream_captureOnce() also sets a still stream up again |
SPECSCAMERA_STREAMNOTIFY_CAMERA_ACCESS_REVOKED | 3 | Camera permission revoked; frames stop and buffers already delivered can't be accessed. Remove the stream |
SpecsCamera key structures
SpecsCamera_StreamDescription_t
Since: v1.3.0
A stream configuration and its callbacks. SpecsCamera_cameraStreamsGet() returns these as read-only discovery rows; to request a stream, copy a row, set callbacks and any other changes on the copy, and pass it to SpecsCameraStream_add() or SpecsCameraStream_setupCapture().
typedef struct SpecsCamera_StreamDescription_s {
char description[128]; ///< Discovery label ending in ",streaming" or ",snapshot". Caller-provided label on input; does not select the operation.
SpecsCamera_Location_t location; ///< Exact enumerated location mask.
SpecsCamera_Modality_t modality; ///< Enumerated sensor modality.
SpecsCamera_Quality_t quality; ///< Best-effort quality preference.
int32_t width; ///< Requested width in pixels.
int32_t height; ///< Requested height in pixels.
SpecsCamera_StreamOperation_t operation; ///< In a discovery row: the entry point it is for. Ignored in a request; the entry point selects the operation.
SpecsCamera_Rational_t frame_rate; ///< Hz. In a discovery row: the advertised maximum. In a request: the minimum the client needs; the camera runs at the highest rate any client requests, up to that maximum.
SpecsCamera_ConfigItem_t* configs; ///< Optional initial config array.
size_t config_count; ///< Number of initial config items.
SpecsCamera_StreamCallbacks_t callbacks; ///< Frame and notification callbacks.
void* cbk_context; ///< Passed to callbacks.
} SpecsCamera_StreamDescription_t;
| Field | Description |
|---|---|
description | In a discovery row, a label ending in ,streaming or ,snapshot. On input, a caller-provided label that doesn't select the operation or affect selection. |
location | Exact enumerated location mask, as returned by SpecsCamera_camerasGet(). |
modality | Enumerated sensor modality. |
quality | Best-effort quality preference (SpecsCamera_Quality_t). |
width, height | Requested width and height in pixels. |
operation | In a discovery row, the entry point the row is for. Ignored in a request; the entry point you call selects the operation. |
frame_rate | In Hz. In a discovery row, the advertised maximum. In a request, the minimum the client needs (positive, up to the advertised maximum); the camera runs at the highest rate requested across clients, subject to the service's sensor-specific constraints. |
configs, config_count | Optional initial config array and its item count. To change configs, use a separate array rather than editing the one in a discovery row. |
callbacks | Frame and notification callbacks. |
cbk_context | User context pointer passed to both callbacks. |
SpecsCamera_StreamCallbacks_t
Since: v1.3.0
The stream-level callbacks in SpecsCamera_StreamDescription_t. Both callbacks receive the cbk_context pointer from the stream description, and either may be NULL.
// Per-frame callback.
// Only SpecsCamera_ImageFormat_t frames are delivered. The frame, metadata and
// image planes are borrowed and valid only during this callback. Copy any data
// needed after the callback returns; do not free it.
// Since: v1.3.0
typedef void (*SpecsCamera_FrameCallback_t)(const SpecsCamera_Frame_t* frame, void* cbk_ctx);
// Stream notification callback. notificationTag: see SpecsCamera_StreamNotificationTag_t.
// Since: v1.3.0
typedef void (*SpecsCamera_NotificationCallback_t)(int32_t notificationTag, void* cbk_ctx);
typedef struct SpecsCamera_StreamCallbacks_s {
SpecsCamera_FrameCallback_t frame_callback; ///< Invoked per delivered frame (may be NULL).
SpecsCamera_NotificationCallback_t notification_callback; ///< Invoked on stream notifications (may be NULL).
} SpecsCamera_StreamCallbacks_t;
SpecsCamera_Frame_t
Since: v1.3.0
A captured frame and its metadata, delivered to the frame callback. The frame, its metadata and its image planes are borrowed and valid only during the callback; copy any data you need afterwards, and don't free it.
typedef struct SpecsCamera_Frame_s {
int64_t timestamp_ns; ///< CLOCK_MONOTONIC ns.
SpecsCamera_BufferInfo_t buffer_info; ///< Image buffer for this frame.
size_t metadata_count; ///< Number of entries in the metadata array.
SpecsCamera_ConfigItem_t* metadata; ///< Array of metadata entries.
} SpecsCamera_Frame_t;
SpecsCamera_BufferInfo_t
Since: v1.3.0
The image buffer description and plane layout within a frame.
typedef struct SpecsCamera_BufferInfo_s {
int32_t fd; ///< Buffer file descriptor, or -1 if not provided.
int32_t buffer_size; ///< Total buffer size in bytes.
int32_t buffer_handle_id; ///< Opaque identifier for the shared image buffer.
int32_t image_format; ///< SpecsCamera_ImageFormat_t.
int32_t image_width; ///< Image width in pixels.
int32_t image_height; ///< Image height in pixels.
int32_t num_channels; ///< Number of valid planes in the channel_* arrays.
uint8_t* channel_data[3]; ///< Per-plane pixel pointers; NULL when not directly mapped.
int32_t channel_length[3]; ///< Per-plane data length in bytes.
int32_t channel_row_strides[3]; ///< Per-plane row stride in bytes.
int32_t channel_pixel_strides[3]; ///< Per-plane pixel stride in bytes.
} SpecsCamera_BufferInfo_t;
SpecsCamera_ConfigItem_t
Since: v1.3.0
A single configuration or metadata item.
typedef struct SpecsCamera_ConfigItem_s {
SpecsCamera_ConfigTag_t config_tag; ///< Which config/metadata tag this item carries.
size_t data_length; ///< Number of elements in data array.
SpecsCamera_ConfigDataUnion_t data; ///< Element array; union member selected by the tag's data type.
} SpecsCamera_ConfigItem_t;
SpecsCamera_ConfigDataUnion_t
Since: v1.3.0
The variant payload of a SpecsCamera_ConfigItem_t. The tag's data type (see configuration tags) selects the union member, and data_length gives the number of elements in the array.
typedef union SpecsCamera_ConfigDataUnion_u {
int64_t* int64_array; ///< int64 element array.
float* float_array; ///< float element array.
bool* bool_array; ///< bool element array.
SpecsCamera_Rational_t* rational_array; ///< Rational element array.
} SpecsCamera_ConfigDataUnion_t;
SpecsCamera_Rational_t
Since: v1.3.0
A rational number (numerator/denominator), used for frame rates.
typedef struct SpecsCamera_Rational_s {
int64_t numerator; ///< Numerator.
int64_t denominator; ///< Denominator.
} SpecsCamera_Rational_t;
SpecsCamera function reference
Client lifecycle
*outClient must be NULL on entry; a non-null *outClient returns SPECSCAMERA_INVALID_ARGUMENT and is left unchanged. App clients require permission at creation, and a permission or lifecycle denial returns SPECSCAMERA_PERMISSION_DENIED. An unreachable camera service returns SPECSCAMERA_SERVICE_CONNECTION_FAILED. Destroying a client requires all calls using it to finish first.
// Create a new SpecsCamera client. *outClient must be NULL on entry.
// APP clients require ARM permission at creation; native CV creation stays local.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraClient_create(SpecsCamera_Client_t **outClient);
// Destroy a SpecsCamera client.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraClient_destroy(SpecsCamera_Client_t *client);
Camera and stream discovery
SpecsCamera_camerasGet() enumerates the physical cameras. SpecsCamera_cameraStreamsGet() returns the supported geometry, format, frame-rate and quality combinations for one camera; pass the exact location mask and modality from SpecsCamera_camerasGet(), not a partial location mask. An unknown camera returns SPECSCAMERA_INVALID_ARGUMENT.
Rules for both functions:
- The returned arrays and their nested config data are read-only, library-owned and valid until the client is destroyed. Don't modify or free them, and don't pass their configs to
SpecsCameraConfigItems_cleanup(). - Copy a stream description before setting callbacks or changing fields, and use a separate config array when changing configs.
- Repeated queries, including queries for other cameras, don't invalidate earlier results. Discovery is cached for the client's lifetime; create a new client to refresh it.
- Concurrent queries are supported.
- On failure, the provided outputs are reset to
NULLand zero. A device with no advertised cameras returnsSPECSCAMERA_SUCCESSwith zero entries.
// Enumerate physical cameras. *outArray is library-owned and read-only.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCamera_camerasGet(
SpecsCamera_Client_t *client,
SpecsCamera_CameraInfo_t **outArray,
size_t *outCount);
// Query supported geometry, format, frame-rate, and quality combinations for a camera.
// location and modality: the exact values from SpecsCamera_camerasGet.
// *outArray is library-owned and read-only.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCamera_cameraStreamsGet(
SpecsCamera_Client_t *client,
SpecsCamera_Location_t location,
SpecsCamera_Modality_t modality,
SpecsCamera_StreamDescription_t **outArray,
size_t *outCount);
Stream management
To add a streaming stream, copy a description from SpecsCamera_cameraStreamsGet() whose operation is SPECSCAMERA_STREAM_OPERATION_STREAMING and set callbacks on the copy. Streaming requires the advertised geometry and format; a configuration that doesn't support streaming returns SPECSCAMERA_INVALID_ARGUMENT.
Ordinary adds reuse the client's authorization. After a camera service restart or a lifecycle revocation, an add attempts one fresh authorized backend session. Clients in the background remain denied. Remove old streams before replacing them; buffers delivered earlier and revoked streams remain invalid after resume.
// Add a streaming camera stream. Fills *outStreamId on success.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_add(
SpecsCamera_Client_t *client,
const SpecsCamera_StreamDescription_t *desc,
SpecsCamera_StreamId_t *outStreamId);
// Remove an existing camera stream.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_remove(
SpecsCamera_Client_t *client,
SpecsCamera_StreamId_t streamId);
Configuration
SpecsCameraStream_configChange() applies configuration changes to a stream. An SPECSCAMERA_CONFIGTAG_IMAGE_FORMAT item returns SPECSCAMERA_INVALID_ARGUMENT without applying any items; recreate the stream to change its format.
retConfigs is an optional caller-allocated array that receives the validated or updated items. *retCount is the array's capacity on input (it must be positive) and the item count on success. Pass both retConfigs and retCount as NULL to omit the returned items. Free the returned items' inner arrays with SpecsCameraConfigItems_cleanup().
// Apply configuration changes to a stream.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_configChange(
SpecsCamera_Client_t *client,
const SpecsCamera_ConfigItem_t *configs,
size_t configCount,
SpecsCamera_StreamId_t *streamId,
SpecsCamera_ConfigItem_t *retConfigs, // optional, caller-allocated
size_t *retCount); // capacity in, item count out
// Free the inner data arrays of config items returned by configChange.
// Frees each item's inner data array and zeroes the pointer and length; does NOT
// free the items array itself. Safe to call multiple times (idempotent).
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraConfigItems_cleanup(
SpecsCamera_ConfigItem_t *items,
size_t count);
Frame validity
// How long a delivered frame remains valid. *validForNs is the validity
// duration measured from the frame timestamp, in nanoseconds.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_frameValidity(
SpecsCamera_Client_t *client,
const SpecsCamera_Frame_t *frame,
int64_t *validForNs,
SpecsCamera_StreamId_t streamId);
Frame validity caveat. Query SpecsCameraStream_frameValidity soon after the frame is delivered; results are unreliable across suspend/resume.
Snapshot capture
Still capture takes two steps: prepare the pipeline with SpecsCameraStream_setupCapture(), then request one-shot or burst captures with SpecsCameraStream_captureOnce().
To set up a still stream, query the camera's configurations with SpecsCamera_cameraStreamsGet() and copy a description whose operation is SPECSCAMERA_STREAM_OPERATION_SNAPSHOT before editing it. The requested configuration must support still capture; unsupported combinations return SPECSCAMERA_INVALID_ARGUMENT. Select the image format (SPECSCAMERA_CONFIGTAG_IMAGE_FORMAT) during setup.
Resized still requests may use positive, even dimensions within an advertised snapshot's width and height for the same camera and format. The camera's existing size and format constraints still apply. Exact geometry is preferred, then quality among eligible source profiles, and the requested output dimensions are preserved.
To save power, the camera service tears a still stream down after 60 seconds without a SpecsCameraStream_captureOnce() call and sends SPECSCAMERA_STREAMNOTIFY_CLIENT_EVICTION. Each SpecsCameraStream_captureOnce() restarts the 60-second timer. The next SpecsCameraStream_captureOnce() after a teardown sets the stream up again, with first-capture latency; *streamId may change, but the previous value keeps working.
// Prepare the camera pipeline for one-shot or burst still capture.
// desc: a copy of a SPECSCAMERA_STREAM_OPERATION_SNAPSHOT description.
// Must be called before SpecsCameraStream_captureOnce.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_setupCapture(
SpecsCamera_Client_t *client,
SpecsCamera_StreamDescription_t *desc,
SpecsCamera_StreamId_t *outStreamId);
// Request a one-shot or burst capture from a prepared still stream.
// configs apply to this request. *streamId is updated if the stream is recreated.
// Requires a prior successful call to SpecsCameraStream_setupCapture.
// Since: v1.3.0
SpecsCamera_Result_t SpecsCameraStream_captureOnce(
SpecsCamera_Client_t *client,
const SpecsCamera_ConfigItem_t *configs,
size_t configCount,
size_t frameCount,
SpecsCamera_StreamId_t *streamId);