Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions src/core/camera_ipc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,14 @@ HostPoolView view(std::move(message.descriptors[0]), slot_count, slot_bytes);
file left by a crashed process is replaced safely. Anything else found at the path is left
alone. The lock file stays behind, empty.

## Where the plugin listens

`default_endpoint_path()` is the socket path a camera plugin and its readers agree on without
being told: `$XDG_RUNTIME_DIR/isaaccapture/camera.sock`, or under `/tmp/isaaccapture-<uid>/`
when that variable is not set. A second plugin on the same machine is a named instance and
listens on `camera-<instance>.sock` beside it. The plugin makes the directory for its owner
alone and refuses one that others can enter.

## Why a socket and shared memory, and not a messaging library

Three things have to cross between the processes: the frame memory, a small event per frame
Expand Down
1 change: 1 addition & 0 deletions src/core/camera_ipc/cpp/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ cmake_minimum_required(VERSION 3.20)
# memory that readers can only map read-only, and a socket that carries whole messages with
# file descriptors. Linux only.
add_library(camera_ipc STATIC
endpoint_path.cpp
host_pool.cpp
message_socket.cpp
)
Expand Down
65 changes: 65 additions & 0 deletions src/core/camera_ipc/cpp/endpoint_path.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#include "inc/camera_ipc/endpoint_path.hpp"

#include <sys/stat.h>

#include <algorithm>
#include <cctype>
#include <cerrno>
#include <cstdlib>
#include <stdexcept>
#include <system_error>
#include <unistd.h>

namespace core::camera
{

std::string default_endpoint_path(std::string_view instance)
{
const auto allowed = [](unsigned char c) { return std::isalnum(c) != 0 || c == '-' || c == '_'; };
if (!std::all_of(instance.begin(), instance.end(), allowed))
{
throw std::invalid_argument("camera plugin instance '" + std::string(instance) +
"' may only have letters, digits, '-' and '_' in its name");
}
const char* runtime_directory = std::getenv("XDG_RUNTIME_DIR");
std::string path = runtime_directory != nullptr && runtime_directory[0] != '\0' ?
std::string(runtime_directory) + "/isaaccapture" :
"/tmp/isaaccapture-" + std::to_string(::geteuid());
path += "/camera";
if (!instance.empty())
{
path += "-" + std::string(instance);
}
return path + ".sock";
}

void prepare_endpoint_directory(const std::string& endpoint_path)
{
const std::size_t slash = endpoint_path.rfind('/');
if (slash == std::string::npos || slash == 0)
{
return; // the current directory or the root: nothing to prepare
}
const std::string directory = endpoint_path.substr(0, slash);
if (::mkdir(directory.c_str(), S_IRWXU) != 0 && errno != EEXIST)
{
throw std::system_error(errno, std::generic_category(), "creating '" + directory + "'");
}
// A directory somebody else made in a shared place could be used to watch or replace the
// socket file, so only one that is this user's alone will do.
struct stat entry = {};
if (::lstat(directory.c_str(), &entry) != 0)
{
throw std::system_error(errno, std::generic_category(), "inspecting '" + directory + "'");
}
if (!S_ISDIR(entry.st_mode) || entry.st_uid != ::geteuid() || (entry.st_mode & (S_IRWXG | S_IRWXO)) != 0)
{
throw std::system_error(
EACCES, std::generic_category(), "'" + directory + "' is not a directory that belongs to this user alone");
}
}

} // namespace core::camera
31 changes: 31 additions & 0 deletions src/core/camera_ipc/cpp/inc/camera_ipc/endpoint_path.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#pragma once

#include <string>
#include <string_view>

namespace core::camera
{

/**
* @brief Where this user's camera plugin listens when nobody says otherwise.
*
* `$XDG_RUNTIME_DIR/isaaccapture/camera.sock`, or under `/tmp/isaaccapture-<uid>/` when that
* variable is not set. A named instance, for a second plugin on the same machine, listens on
* `camera-<instance>.sock` next to it.
*
* @throws std::invalid_argument for an instance name with anything but letters, digits, '-' and '_'.
*/
std::string default_endpoint_path(std::string_view instance = {});

/**
* @brief Make sure the directory of an endpoint path exists and belongs to this user alone.
* Creates it with mode 0700 when it is missing.
* @throws std::system_error if it cannot be created, or exists and is not a directory this
* user owns with no access for anyone else.
*/
void prepare_endpoint_directory(const std::string& endpoint_path);

} // namespace core::camera
4 changes: 3 additions & 1 deletion src/core/camera_reader/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ buffers, mapped read-only; nothing is copied.
```cpp
#include <camera_reader/camera_reader.hpp>

CameraReader reader = CameraReader::open(endpoint, "head");
CameraReader reader = CameraReader::open("head");
while (auto frames = reader.next(std::chrono::seconds(1)))
{
const ImageView left = frames->image(0);
Expand All @@ -29,6 +29,8 @@ while (auto frames = reader.next(std::chrono::seconds(1)))
- **`next` returns nothing on timeout** and throws `CameraDisconnected` when the plugin is
gone. Opening fails with a `CameraReaderError` that says why: nothing listens on the
endpoint, the group does not exist, or the subscription does not fit the pool.
- **Which plugin.** By default the reader looks for this user's plugin on its default
endpoint. A `PluginLocation` names another instance of the plugin, or a socket path.
- **One reader reads one group.** For two groups, open two readers; `descriptor()` lets an
application wait on several at once.
- A `FrameSet` may be given back from another thread than the one that calls `next`, and
Expand Down
24 changes: 19 additions & 5 deletions src/core/camera_reader/cpp/camera_reader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

#include "inc/camera_reader/camera_reader.hpp"

#include <camera_ipc/endpoint_path.hpp>
#include <camera_ipc/host_pool.hpp>
#include <camera_ipc/message_socket.hpp>
#include <camera_wire/messages.hpp>
Expand Down Expand Up @@ -54,16 +55,29 @@ std::optional<Received> receive(MessageSocket& socket, std::span<std::byte> buff
}
}

MessageSocket connect_to(const std::string& endpoint)
MessageSocket connect_to(const PluginLocation& plugin)
{
if (!plugin.endpoint.empty() && !plugin.instance.empty())
{
throw CameraReaderError("a camera plugin is named by its endpoint or by its instance, not both");
}
std::string endpoint = plugin.endpoint;
try
{
if (endpoint.empty())
{
endpoint = default_endpoint_path(plugin.instance);
}
return MessageSocket::connect(endpoint);
}
catch (const std::system_error& error)
{
throw CameraReaderError("no camera plugin answers on '" + endpoint + "': " + error.code().message());
}
catch (const std::invalid_argument& error)
{
throw CameraReaderError(error.what());
}
}

// Says hello and returns what the plugin publishes.
Expand Down Expand Up @@ -246,17 +260,17 @@ void FrameSet::release() noexcept
}
}

std::vector<GroupDescription> CameraReader::list(const std::string& endpoint)
std::vector<GroupDescription> CameraReader::list(const PluginLocation& plugin)
{
MessageSocket socket = connect_to(endpoint);
MessageSocket socket = connect_to(plugin);
WireEncoder encoder;
std::vector<std::byte> buffer(MAX_WIRE_MESSAGE_BYTES);
return greet(socket, encoder, buffer);
}

CameraReader CameraReader::open(const std::string& endpoint, const std::string& group, const ReaderOptions& options)
CameraReader CameraReader::open(const std::string& group, const ReaderOptions& options, const PluginLocation& plugin)
{
auto state = std::make_shared<detail::ReaderState>(connect_to(endpoint));
auto state = std::make_shared<detail::ReaderState>(connect_to(plugin));
WireEncoder encoder;
greet(state->socket, encoder, state->buffer);

Expand Down
23 changes: 16 additions & 7 deletions src/core/camera_reader/cpp/inc/camera_reader/camera_reader.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,13 @@ class CameraDisconnected : public CameraReaderError
using CameraReaderError::CameraReaderError;
};

// Which camera plugin to read from. Left empty, it is this user's plugin on this machine.
struct PluginLocation
{
std::string endpoint; // a socket path; empty for the default endpoint of `instance`
std::string instance; // a named plugin instance; empty for the default one
};

/**
* @brief One image of a frame set. The memory is the plugin's pool, mapped read-only, and
* stays as it is for as long as the FrameSet the view came from is held.
Expand Down Expand Up @@ -122,7 +129,7 @@ class FrameSet
* @brief Reads one group of cameras from the camera plugin.
*
* @code
* CameraReader reader = CameraReader::open(endpoint, "head");
* CameraReader reader = CameraReader::open("head");
* while (auto frames = reader.next(std::chrono::seconds(1)))
* {
* std::span<const std::byte> left = frames->image(0).data;
Expand All @@ -133,17 +140,19 @@ class CameraReader
{
public:
/**
* @brief What the plugin behind `endpoint` publishes.
* @throws CameraReaderError if nothing listens there or the plugin refuses this reader.
* @brief What a camera plugin publishes.
* @throws CameraReaderError if no plugin answers or the plugin refuses this reader.
*/
static std::vector<GroupDescription> list(const std::string& endpoint);
static std::vector<GroupDescription> list(const PluginLocation& plugin = {});

/**
* @brief Subscribe to one group. A reader for a second group is a second CameraReader.
* @throws CameraReaderError if nothing listens on the endpoint or the plugin refuses the
* subscription; the message says why.
* @throws CameraReaderError if no plugin answers or the plugin refuses the subscription;
* the message says why.
*/
static CameraReader open(const std::string& endpoint, const std::string& group, const ReaderOptions& options = {});
static CameraReader open(const std::string& group,
const ReaderOptions& options = {},
const PluginLocation& plugin = {});

CameraReader(CameraReader&& other) noexcept;
CameraReader& operator=(CameraReader&& other) noexcept;
Expand Down
46 changes: 35 additions & 11 deletions src/plugins/camera/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,53 @@ One process that owns the cameras and serves their frames to any number of reade
processes. Viewers, encoders and recorders read the plugin's buffers in place through
[`camera_reader`](../../core/camera_reader); none of them links a camera SDK.

```yaml
# ~/.config/isaaccapture/cameras.yaml
cameras:
head:
backend: synthetic
```

```bash
camera_plugin --endpoint=/tmp/cameras.sock --camera=head:synthetic
camera_plugin
```

```cpp
CameraReader reader = CameraReader::open("/tmp/cameras.sock", "head");
CameraReader reader = CameraReader::open("head");
while (auto frames = reader.next(std::chrono::seconds(1)))
{
const ImageView left = frames->image(0);
}
```

Neither side is told where the other is: the plugin listens on this user's default endpoint
and readers look there.

## Running it

| Argument | Meaning |
|---|---|
| `--endpoint=PATH` | The socket file readers connect to. Only one plugin serves a path at a time. |
| `--camera=ID:BACKEND[:KEY=VALUE,...]` | One camera: the id readers ask for, the backend that opens it, and that backend's options. Repeat it for each camera. |
| `--slots=N` | Frames kept per stream, 8 by default. A pool holds the newest frame set, one slot for the camera to write ahead, and the windows of all readers; a reader that does not fit is refused with the numbers. |
| `--list-backends` | Print the backends this build has. |
**Which cameras.** A camera has an id that readers ask for, a backend that opens it, and that
backend's options. The plugin takes them from, in this order:

1. `--camera=ID:BACKEND[:KEY=VALUE,...]` on the command line, once per camera;
2. `--config=FILE`, or without it `$XDG_CONFIG_HOME/isaaccapture/cameras.yaml`
(`~/.config/isaaccapture/cameras.yaml`) when that file exists. A camera takes three lines:
its id, `backend:`, and any option of that backend as `name: value`. `slots:` at the top
level sets the pool size;
3. otherwise, or with `--auto`, every camera the backends of this build find plugged in.

**Where it listens.** By default on `$XDG_RUNTIME_DIR/isaaccapture/camera.sock`. A second
plugin on the same machine runs as a named instance, `--instance=NAME`, on its own endpoint,
and readers name the same instance. `--endpoint=PATH` sets the socket file outright. Only one
plugin serves an endpoint at a time.

**Pool size.** `--slots=N`, 8 by default, is the number of frames kept per stream. A pool
holds the newest frame set, one slot for the camera to write ahead, and the windows of all
readers; a reader that does not fit is refused with the numbers. A reader that wants every
frame in order counts its window twice, because the frames waiting for it are kept as well.

A misspelt argument or option is an error, not something ignored. `SIGINT` and `SIGTERM` stop
the plugin cleanly; readers see their connection close.
A misspelt argument, option or setting is an error, not something ignored. `SIGINT` and
`SIGTERM` stop the plugin cleanly; readers see their connection close. `--list-backends`
prints the backends of the build.

Every ten seconds the plugin logs, per camera, how many frame sets it published. It warns
when a camera had to drop frame sets because its pool was full, or when a reader did not take
Expand All @@ -43,7 +67,7 @@ Every frame set carries the times it passed each step, on the host's monotonic c
`camera_bench` reads a group like any other reader and prints them:

```text
$ camera_bench --endpoint=/tmp/cameras.sock --group=head --frames=600
$ camera_bench --group=head --frames=600
head: 2 stream(s)
head/left 1280x720 bgra8, 60.00 fps, 8 slots of 3686400 bytes
head/right 1280x720 bgra8, 60.00 fps, 8 slots of 3686400 bytes
Expand Down
1 change: 1 addition & 0 deletions src/plugins/camera/app/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ add_executable(camera_plugin
target_link_libraries(camera_plugin PRIVATE
camera::plugin_core
camera::plugin_backends
camera::camera_ipc
log_bridge::log_bridge_core
Threads::Threads
)
Expand Down
Loading
Loading