ra8_camera.h File Reference

Transport-neutral camera source and image-codec facade. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_camera.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_camera_buffer_t
	Caller-owned writable byte-buffer description. More...
struct	ra8_camera_frame_t
	Immutable view of one captured or encoded image. More...
struct	ra8_camera_source_info_t
	Native geometry and worst-case storage required by a source. More...
struct	ra8_camera_source_t
	Caller-owned handle binding one source backend and its context. More...
struct	ra8_camera_codec_t
	Caller-owned handle binding one image codec and its context. More...

Typedefs
typedef struct ra8_camera_source_iface	ra8_camera_source_iface_t
	Opaque source vtable; concrete source backends define its rows.
typedef struct ra8_camera_codec_iface	ra8_camera_codec_iface_t
	Opaque codec vtable; concrete codec backends define its rows.

Enumerations
enum	ra8_camera_format_t : uint8_t {   k_ra8_camera_format_rgb888 = 0U ,   k_ra8_camera_format_uyvy422 ,   k_ra8_camera_format_jpeg }
	Pixel and compressed-image layouts understood by the facade. More...

Functions
ra8_err_t	ra8_camera_frame_validate (const ra8_camera_frame_t *frame)
	Validate the geometry and storage coverage of a frame view.
ra8_err_t	ra8_camera_source_get_info (ra8_camera_source_t *source, ra8_camera_source_info_t *out_info)
	Query a bound source's native output and capture-buffer bound.
ra8_err_t	ra8_camera_source_capture (ra8_camera_source_t *source, const ra8_camera_buffer_t *buffer, ra8_camera_frame_t *out_frame)
	Capture one frame into a caller-owned buffer.
ra8_err_t	ra8_camera_codec_encode (ra8_camera_codec_t *codec, const ra8_camera_frame_t *input, const ra8_camera_buffer_t *output_buffer, ra8_camera_frame_t *out_frame)
	Encode or transform one frame through a bound codec.

Detailed Description

Transport-neutral camera source and image-codec facade.

Tag

[Ring 4 / Service] {World: NS}

A camera source captures into storage supplied by its caller and returns an immutable frame view describing the bytes it produced. A codec consumes one such view and either fills another caller-owned buffer or, for a zero-copy backend such as JPEG passthrough, returns a view of the original bytes. Concrete sources and codecs bind opaque vtables through backend-specific _init() helpers, following the same pattern as ra8_io_stream.

No function allocates memory. Handles, backend state, capture buffers, and encoded-output buffers all belong to the caller and must out-live operations that use them.

uint8_t capture_bytes[640U * 480U * 3U];
uint8_t jpeg_bytes[128U * 1024U];
ra8_camera_buffer_t capture = {capture_bytes, sizeof capture_bytes};
ra8_camera_buffer_t encoded = {jpeg_bytes, sizeof jpeg_bytes};
ra8_camera_frame_t frame = {};
ra8_camera_frame_t jpeg = {};
(void)ra8_camera_source_capture(&source, &capture, &frame);
(void)ra8_camera_codec_encode(&codec, &frame, &encoded, &jpeg);

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_camera.h.

Typedef Documentation

ra8_camera_codec_iface_t

typedef struct ra8_camera_codec_iface ra8_camera_codec_iface_t

Opaque codec vtable; concrete codec backends define its rows.

Definition at line 51 of file ra8_camera.h.

ra8_camera_source_iface_t

typedef struct ra8_camera_source_iface ra8_camera_source_iface_t

Opaque source vtable; concrete source backends define its rows.

Definition at line 48 of file ra8_camera.h.

Enumeration Type Documentation

ra8_camera_format_t

enum ra8_camera_format_t : uint8_t

Pixel and compressed-image layouts understood by the facade.

Uncompressed formats are tightly described by stride_bytes in a frame. JPEG is a complete compressed byte stream and has stride 0.

Invariant

Every value has a stable one-byte representation.

k_ra8_camera_format_jpeg denotes a complete SOI-to-EOI stream.

Since

0.1.0

Enumerator
k_ra8_camera_format_rgb888	Packed R, G, B bytes per pixel.
k_ra8_camera_format_uyvy422	Packed Cb, Y0, Cr, Y1 pixel pairs.
k_ra8_camera_format_jpeg	Complete encoded JPEG byte stream.

Definition at line 63 of file ra8_camera.h.

Function Documentation

ra8_camera_codec_encode()

ra8_err_t ra8_camera_codec_encode ( ra8_camera_codec_t * codec, const ra8_camera_frame_t * input, const ra8_camera_buffer_t * output_buffer, ra8_camera_frame_t * out_frame )

nodiscard

Encode or transform one frame through a bound codec.

A codec may fill output_buffer or return a zero-copy view which aliases input. The returned frame's lifetime is therefore bounded by both input and output storage.

Parameters

[in,out]	codec	Bound codec handle.
[in]	input	Valid source frame.
[in]	output_buffer	Caller-owned output storage; may be empty for a backend documented as zero-copy.
[out]	out_frame	Receives the encoded frame view.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Frame produced.
k_ra8_err_null_ptr	An argument was NULL.
k_ra8_err_not_initialized	No codec is bound.
k_ra8_err_not_supported	Codec cannot accept input->format.
other	Propagated from validation or the backend.

Precondition

input passes ra8_camera_frame_validate.

Output storage does not overlap input unless the backend allows it.

Postcondition

On success out_frame passes ra8_camera_frame_validate.

On error out_frame is zeroed.

Note

Not thread-safe with respect to the same codec or buffers.

Since

0.1.0

Definition at line 187 of file ra8_camera.c.

References ra8_camera_codec_t::ctx, ra8_camera_codec_iface::encode, ra8_camera_codec_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and ra8_camera_frame_validate().

Referenced by c6_cam_camera_capture_jpeg(), and ra8_camera_codec_encode_to_stream().

ra8_camera_frame_validate()

ra8_err_t ra8_camera_frame_validate ( const ra8_camera_frame_t * frame )

nodiscard

Validate the geometry and storage coverage of a frame view.

Parameters

[in]

frame

Candidate frame.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Frame is internally consistent.
k_ra8_err_null_ptr	frame or frame->data is NULL.
k_ra8_err_invalid_arg	Format is unknown or geometry is invalid.
k_ra8_err_invalid_size	Byte count or stride cannot cover the frame.

Precondition

frame points to readable metadata.

When non-NULL, frame->data is readable for frame->bytes bytes.

Postcondition

No state is modified.

Success means a backend may safely read the described bytes.

Note

Thread-safe; reads only its argument.

Since

0.1.0

Definition at line 61 of file ra8_camera.c.

References ra8_camera_frame_t::bytes, ra8_camera_frame_t::data, ra8_camera_frame_t::format, ra8_camera_frame_t::height, internal_frame_row_bytes(), k_ra8_camera_format_jpeg, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, ra8_camera_frame_t::stride_bytes, and ra8_camera_frame_t::width.

Referenced by ra8_camera_codec_encode(), ra8_camera_source_capture(), and ra8_camera_source_memory_init().

ra8_camera_source_capture()

ra8_err_t ra8_camera_source_capture ( ra8_camera_source_t * source, const ra8_camera_buffer_t * buffer, ra8_camera_frame_t * out_frame )

nodiscard

Capture one frame into a caller-owned buffer.

Parameters

[in,out]	source	Bound source handle.
[in]	buffer	Writable capture buffer.
[out]	out_frame	Receives an immutable view of captured bytes.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	One valid frame captured.
k_ra8_err_null_ptr	An argument or buffer pointer was NULL.
k_ra8_err_not_initialized	No source is bound.
k_ra8_err_invalid_size	Buffer is too small for the source.
other	Propagated from the source backend.

Precondition

buffer->data covers buffer->capacity writable bytes.

No other call is using source or buffer.

Postcondition

On success out_frame->data == buffer->data and validates.

On error out_frame is zeroed.

Note

Not thread-safe with respect to the same source or buffer.

Since

0.1.0

Definition at line 146 of file ra8_camera.c.

References ra8_camera_frame_t::bytes, ra8_camera_buffer_t::capacity, ra8_camera_source_iface::capture, ra8_camera_source_t::ctx, ra8_camera_buffer_t::data, ra8_camera_frame_t::data, ra8_camera_source_t::iface, internal_source_validate(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_ok, and ra8_camera_frame_validate().

Referenced by c6_cam_camera_capture_jpeg(), and cam_capture_frame_and_report().

ra8_camera_source_get_info()

ra8_err_t ra8_camera_source_get_info ( ra8_camera_source_t * source, ra8_camera_source_info_t * out_info )

nodiscard

Query a bound source's native output and capture-buffer bound.

Parameters

[in]	source	Bound source handle.
[out]	out_info	Receives source information.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Information returned.
k_ra8_err_null_ptr	An argument was NULL.
k_ra8_err_not_initialized	No source is bound.
other	Propagated from the source backend.

Precondition

source was initialised by a source backend.

out_info is writable.

Postcondition

On success out_info describes every later capture.

On error out_info is zeroed.

Note

Not thread-safe with respect to the same source.

Since

0.1.0

Definition at line 132 of file ra8_camera.c.

References ra8_camera_source_t::ctx, ra8_camera_source_iface::get_info, ra8_camera_source_t::iface, internal_source_validate(), k_ra8_err_null_ptr, and k_ra8_ok.