Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
camera_capture.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#ifndef USHER_CAMERA_CAPTURE_H
19#define USHER_CAMERA_CAPTURE_H
20
21/**
22 * @file camera_capture.h
23 * @brief Optional split-phase capture contract for USHER image backends.
24 * @details Separating acquisition from publication lets a driver return its camera
25 * buffers before JPEG encoding or storage finishes. Only advertise this interface
26 * when the driver actually owns the selected pixels; a queued shutter request is
27 * not a retained image. Synchronous backends need not implement these hooks.
28 */
29
30#include <stdbool.h>
31#include <stddef.h>
32#include <signal.h>
33
34#if __GCC_ATOMIC_INT_LOCK_FREE != 2
35#error "Cancellation requires lock-free integer atomic operations"
36#endif
37#if defined(__cplusplus)
38static_assert(sizeof(sig_atomic_t) == sizeof(int) && alignof(sig_atomic_t) >= alignof(int),
39 "Cancellation flags must match the lock-free integer representation");
40#else
41_Static_assert(sizeof(sig_atomic_t) == sizeof(int) && _Alignof(sig_atomic_t) >= _Alignof(int),
42 "Cancellation flags must match the lock-free integer representation");
43#endif
44
45/** @brief Atomically poll a borrowed cancellation flag; NULL means no cancellation. */
46static inline bool capture_running(const volatile sig_atomic_t *running)
47{
48 return !running || __atomic_load_n(running, __ATOMIC_RELAXED) != 0;
49}
50
51/** @brief Update cancellation without locks; this flag does not publish other shared state. */
52static inline void capture_set_running(volatile sig_atomic_t *running, bool active)
53{
54 __atomic_store_n(running, active ? 1 : 0, __ATOMIC_RELAXED);
55}
56
57/** @brief Per-image ownership record, kept alive until the matching finish call.
58 * @details Paths are bounded bookkeeping, not pixel buffers. The driver owns any
59 * image memory and its capacity accounting. Never reuse this record while acquired.
60 */
62 char source[4096]; /**< Private driver output; retain on publication failure when possible. */
63 char destination[4096]; /**< Requested public filename; existing originals must not be replaced. */
64 bool acquired; /**< The driver owns pixels for this capture and owes a finish operation. */
65};
66
67/** @brief Driver capabilities whose table must outlive every pending image.
68 * @details USHER snapshots the table pointer with the image, not the currently
69 * selected camera. This keeps a later backend switch from finishing the wrong job.
70 * Acquisition is serialized by the camera owner; finish may overlap later captures.
71 * Implementations must synchronize their shared state and bound memory and waits.
72 */
74 /** @brief Retain one exposure without waiting for its final JPEG publication.
75 * @param[out] pending Ownership record filled by the driver.
76 * @param image_number Original USHER shot number.
77 * @return Zero with acquired set when pixels are owned; positive for synchronous
78 * fallback before any exposure; negative for failure without a duplicate retry.
79 */
80 int (*acquire)(struct camera_pending *pending, int image_number);
81 /** @brief Finish the exact acquisition represented by pending.
82 * @param[in,out] pending Record to release, including admission accounting, on every exit.
83 * @param[out] filename Published filename on success; empty on failure.
84 * @param size Filename capacity including its terminating NUL.
85 * @param running Optional shutdown flag to check during bounded waits.
86 * @return Zero for a verified published file, negative on failure or cancellation.
87 * @warning Failure is not permission to discard an existing original or recapture
88 * using the old pose. Preserve recoverable private files and report the failure.
89 */
90 int (*finish)(struct camera_pending *pending, char *filename, size_t size,
91 const volatile sig_atomic_t *running);
92 /** @brief Nonblocking capacity snapshot; acquisition remains the admission authority.
93 * @return True when another capture may be attempted. NULL means no extra readiness gate.
94 */
95 bool (*has_capacity)(void);
96 unsigned max_in_flight; /**< Per-camera limit, currently 1..2; not a whole-MORA memory budget. */
97};
98
99#endif
static void capture_set_running(volatile sig_atomic_t *running, bool active)
Update cancellation without locks; this flag does not publish other shared state.
static bool capture_running(const volatile sig_atomic_t *running)
Atomically poll a borrowed cancellation flag; NULL means no cancellation.
static struct capture_intent active[2 *COVERAGE_CAMERAS]
size_t size
Definition chdk_pipe.c:143
static bool pending
static const volatile sig_atomic_t * running
Driver capabilities whose table must outlive every pending image.
int(* finish)(struct camera_pending *pending, char *filename, size_t size, const volatile sig_atomic_t *running)
Finish the exact acquisition represented by pending.
bool(* has_capacity)(void)
Nonblocking capacity snapshot; acquisition remains the admission authority.
int(* acquire)(struct camera_pending *pending, int image_number)
Retain one exposure without waiting for its final JPEG publication.
Per-image ownership record, kept alive until the matching finish call.
char destination[4096]
char source[4096]