ra8_camera.c File Reference

Validation and opaque-vtable dispatch for ra8_camera. More...

#include "ra8_camera.h"
#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_camera_internal.h"
#include "ra8_err.h"

Include dependency graph for ra8_camera.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_frame_row_bytes (const ra8_camera_frame_t *frame, uint32_t *out_row)
	Return the minimum bytes in one uncompressed row.
ra8_err_t	ra8_camera_frame_validate (const ra8_camera_frame_t *frame)
	Validate the geometry and storage coverage of a frame view.
static ra8_err_t	internal_source_validate (const ra8_camera_source_t *source)
	Validate a source handle and its mandatory vtable rows.
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

Validation and opaque-vtable dispatch for ra8_camera.

Tag

[Ring 4 / Service] {World: NS}

Keeps generic frame rules and backend dispatch in one hardware-free translation unit. Backends remain responsible only for their source or codec operation.

Copyright

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

Since

0.1.0

Definition in file ra8_camera.c.

Function Documentation

internal_frame_row_bytes()

ra8_err_t internal_frame_row_bytes ( const ra8_camera_frame_t * frame, uint32_t * out_row )

static

Return the minimum bytes in one uncompressed row.

Maps each raw format to its packed row size and rejects compressed, unknown, or geometrically invalid formats.

Parameters

[in]	frame	Frame whose row layout is inspected.
[out]	out_row	Receives the minimum packed row size.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Row size returned.
k_ra8_err_invalid_arg	Format is unsupported or UYVY width is odd.

Precondition

frame and out_row are non-NULL.

frame->width is non-zero.

Postcondition

On success out_row is the packed row size.

No frame storage is modified.

Note

This helper does not validate total frame storage.

Since

0.1.0

Definition at line 44 of file ra8_camera.c.

References ra8_camera_frame_t::format, k_ra8_camera_format_rgb888, k_ra8_camera_format_uyvy422, k_ra8_err_invalid_arg, k_ra8_ok, RA8_INTERNAL, and ra8_camera_frame_t::width.

Referenced by ra8_camera_frame_validate().

internal_source_validate()

ra8_err_t internal_source_validate ( const ra8_camera_source_t * source )

static

Validate a source handle and its mandatory vtable rows.

Centralizes bound-source validation before public dispatch.

Parameters

[in]

source

Candidate source handle.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Source is ready for dispatch.
k_ra8_err_null_ptr	Source handle is NULL.
k_ra8_err_not_initialized	Source or a mandatory row is unbound.

Precondition

No initialization is required.

A non-NULL source is readable.

Postcondition

No source state is modified.

Success guarantees both mandatory rows are non-NULL.

Note

Thread-safe because it reads only handle fields.

Since

0.1.0

Definition at line 115 of file ra8_camera.c.

References ra8_camera_source_iface::capture, ra8_camera_source_iface::get_info, ra8_camera_source_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by priv_fmt_host_source_open(), ra8_camera_source_capture(), and ra8_camera_source_get_info().

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.