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
1 change: 1 addition & 0 deletions src/core/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ add_subdirectory(camera_core)
# Camera frames and messages between processes (shared host memory, descriptor passing)
if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
add_subdirectory(camera_ipc)
add_subdirectory(camera_wire)
endif()

# Build OXR library (depends on oxr_utils for types)
Expand Down
16 changes: 16 additions & 0 deletions src/core/camera_wire/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Agent notes — `camera_wire`

**CRITICAL (non-optional):** Before editing this package, complete the mandatory **`AGENTS.md` preflight** in [`../../../AGENTS.md`](../../../AGENTS.md) (read every applicable `AGENTS.md` on your paths, not just this file).

Read [`README.md`](README.md) before changing `fbs/camera_wire.fbs`: a reader and a plugin from different builds must keep understanding each other.

- **The schema only grows.** Append fields with fresh ids, optional; append union members; tables, never structs. Do not reuse or renumber.
- **FlatBuffers stays inside this module.** Its users see `camera_core` types; only the codec and its tests include the generated header.
- **Decoded bytes are untrusted.** Verify, then bound every count against the fixed arrays it fills, and check for a body behind a body type.
- **A new enum value needs both sides.** The core enum and the schema enum carry the same numbers (pinned by `static_assert`), and the decoder must accept the value before a plugin sends it.
- **The frame path does not allocate.** Keep `encode(const FrameEvent&)` free of containers that do.
7 changes: 7 additions & 0 deletions src/core/camera_wire/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20)

add_subdirectory(fbs)
add_subdirectory(cpp)
58 changes: 58 additions & 0 deletions src/core/camera_wire/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Camera interface: messages between the plugin and a reader

What the camera plugin and a reader say to each other over their socket
([`camera_ipc`](../camera_ipc)). Each socket message is one of these:

```text
reader plugin
| Hello (protocol version) |
|------------------------------------>|
| Welcome (what is published) |
|<------------------------------------|
| Subscribe (group, window, order) |
|------------------------------------>|
| Subscribed + one pool descriptor |
| per stream |
|<------------------------------------|
| Frame (lease, slot per image) | once per frame set
|<------------------------------------|
| Release (lease) |
|------------------------------------>|
```

A connection carries one subscription; a reader that wants two groups opens two. Closing the
connection ends the subscription and returns every frame set the reader still held. A `Frame`
can overtake `Subscribed`, because capture does not wait for the answer to be sent; it belongs
to the subscription all the same.

## Schema

[`fbs/camera_wire.fbs`](fbs/camera_wire.fbs) defines the messages as FlatBuffers tables. It is
kept here and not in [`schema`](../schema): that directory holds what goes into recordings,
and these messages are never recorded.

A reader and a plugin may come from different builds, so the schema only grows:

- Append fields with fresh ids and leave them optional; append union members. Never reuse or
renumber an id, and use tables, not structs.
- A message type this build does not know decodes to nothing and is ignored.
- A stream whose format or kind of memory this build does not know makes its group
unreadable, and the reader is told so; other groups are unaffected.
- `WIRE_PROTOCOL_VERSION` changes only when the two sides would misread each other. The
plugin refuses a reader with a different version in `Welcome`.

## Codec

`WireEncoder` and `decode_wire_message` turn [`camera_core`](../camera_core) types into bytes
and back, so nothing outside this module sees FlatBuffers. The encoder reuses its buffer; a
frame event is encoded without allocating. The decoder treats its input as coming from another
process: it verifies the buffer and refuses counts that would not fit a group.

## Tests

`tests/cpp/core/camera_wire`, run with `ctest -L camera_wire`. They are tagged `unit`.
23 changes: 23 additions & 0 deletions src/core/camera_wire/cpp/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20)

# Turns the messages between the camera plugin and its readers into bytes and back. The
# FlatBuffers types stay inside this library; its users see camera_core types.
add_library(camera_wire STATIC
codec.cpp
)

target_include_directories(camera_wire INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/inc>
)

target_link_libraries(camera_wire
PUBLIC
camera::camera_core
PRIVATE
camera::camera_wire_schema
)

add_library(camera::camera_wire ALIAS camera_wire)
Loading
Loading