ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
Video Frame Buffers

📹 High-performance video frame management with double-buffering and lock-free operations More...

Files

file  video_frame.c
 ðŸŽ¬ Video frame buffer management for client-specific ASCII rendering

Data Structures

struct  video_frame_t
 When code needs to work with simple frame swap, it keeps current_frame, frame_a, frame_b, use_frame_a here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields. More...
struct  video_frame_buffer_t
 One captured, decoded, or rendered video frame and its timing metadata. More...
struct  video_frame_stats_t
 Counters and timing measurements used to monitor frame delivery and quality. More...
struct  simple_frame_swap_t
 Counters and timing measurements used to monitor frame delivery and quality. More...

Macros

#define VIDEO_FRAME_BUFFER_SIZE   MAX_FRAME_BUFFER_SIZE
 Video frame buffer size (2MB per frame).
#define MAX_FRAME_BUFFERS   2
 Maximum number of frame buffers (double buffering).

Functions

video_frame_buffer_t * video_frame_buffer_create (const char *client_id)
 Create a double-buffered video frame manager.
void video_frame_buffer_destroy (video_frame_buffer_t *vfb)
 Destroy frame buffer and free all resources.
video_frame_t * video_frame_begin_write (video_frame_buffer_t *vfb)
 Writer API: Start writing a new frame.
void video_frame_commit (video_frame_buffer_t *vfb)
 Writer API: Commit the frame and swap buffers.
const video_frame_t * video_frame_get_latest (video_frame_buffer_t *vfb)
 Reader API: Get latest frame if available.
const video_frame_t * video_frame_peek_latest (video_frame_buffer_t *vfb)
void video_frame_get_stats (video_frame_buffer_t *vfb, video_frame_stats_t *stats)
 Get frame statistics for quality monitoring.
simple_frame_swap_t * simple_frame_swap_create (void)
 Create a simple atomic frame swap.
void simple_frame_swap_destroy (simple_frame_swap_t *sfs)
 Destroy simple frame swap and free resources.
void simple_frame_swap_update (simple_frame_swap_t *sfs, const void *data, size_t size)
 Update frame data in simple frame swap.
const video_frame_t * simple_frame_swap_get (simple_frame_swap_t *sfs)
 Get current frame from simple frame swap.

Detailed Description

📹 High-performance video frame management with double-buffering and lock-free operations

This header provides a high-performance video frame management system inspired by WebRTC, Zoom, and Google Meet architectures. It implements a lock-free double-buffering system with atomic pointer swaps for zero-copy frame transfer.

CORE FEATURES:

  • Zero-copy frame transfer (pointer swaps only)
  • Lock-free read operations (reader never blocks writer)
  • Latest-frame-wins semantics (old frames are dropped, not queued)
  • Double buffering with atomic pointer swaps
  • Comprehensive quality metrics tracking
  • Pre-allocated buffers for zero-allocation operation
  • Frame sequence numbering for drop detection

ARCHITECTURE:

The system uses a double-buffering pattern:

  • Front Buffer: Currently being displayed (reader owns)
  • Back Buffer: Currently being written (writer owns)
  • Atomic swap: Makes new frame available without blocking

WRITER API:

  1. Call video_frame_begin_write() to get back buffer pointer
  2. Write frame data directly to back buffer
  3. Call video_frame_commit() to atomically swap buffers

READER API:

  1. Call video_frame_get_latest() to get current frame
  2. Returns NULL if no new frame since last read
  3. Lock-free operation never blocks writer

PERFORMANCE BENEFITS:

  • Zero-copy eliminates memcpy overhead
  • Lock-free reads minimize latency
  • Pre-allocated buffers avoid runtime allocations
  • Latest-frame-wins prevents buffer buildup
  • Metrics enable adaptive quality control

QUALITY METRICS:

The system tracks:

  • Total frames received
  • Total frames dropped
  • Frame drop rate
  • Average decode time
  • Average render time

These metrics enable adaptive streaming quality based on performance.

Note
Frame data is not owned by the frame structure - it points to pre-allocated buffers managed by the frame buffer.
The writer must call video_frame_commit() after writing each frame to make it available to readers.
Readers should check for NULL returns from video_frame_get_latest() to handle cases where no new frame is available.
Author
Zachary Fogg me@zf.nosp@m.o.gg
Date
October 2025

Video Frame README

Overview

The Video Frame module provides structures and utilities for managing video frames throughout the ascii-chat pipeline. It handles RGB image data, frame metadata, and efficient frame lifecycle management.

Implementation: lib/video_frame.h

Key Features:

  • Zero-copy frame transfer (pointer swaps only)
  • Lock-free double-buffering system
  • Latest-frame-wins semantics (old frames dropped, not queued)
  • Pre-allocated buffers for zero-allocation operation
  • RGB24 image frame representation
  • Frame metadata (timestamp, dimensions, client ID)
  • Frame sequence numbering for drop detection
  • Comprehensive quality metrics tracking

Frame Structure

video_frame_t:

typedef struct {
uint8_t *data; // RGB24 pixel data
uint32_t width; // Frame width in pixels
uint32_t height; // Frame height in pixels
size_t data_size; // Total bytes (width * height * 3)
uint32_t client_id; // Client that owns this frame
uint64_t timestamp; // Capture timestamp (microseconds)
bool owns_data; // Whether this frame owns the data buffer
unsigned int height
Definition fft.c:24
unsigned int width
Definition fft.c:24
unsigned int uint32_t
unsigned long long uint64_t
unsigned char uint8_t
When code needs to work with simple frame swap, it keeps current_frame, frame_a, frame_b,...

Frame Properties:

  • data: RGB24 format (3 bytes per pixel: R, G, B)
  • width/height: Frame dimensions
  • data_size: Always equals width * height * 3
  • client_id: Which client this frame belongs to
  • timestamp: Microsecond-precision capture time
  • owns_data: Memory ownership flag

Operations

Double-Buffering API

The recommended way to use video frames is through the lock-free double-buffering API:

Writer API (producer thread):

// 1. Get pointer to back buffer for writing
// 2. Write frame data directly to back buffer
memcpy(write_buffer, captured_rgb_data, width * height * 3);
// 3. Atomically swap buffers to make frame available
video_frame_t * video_frame_begin_write(video_frame_buffer_t *vfb)
Writer API: Start writing a new frame.
void video_frame_commit(video_frame_buffer_t *vfb)
Writer API: Commit the frame and swap buffers.
Growable byte buffer for assembling one complete terminal frame.

Reader API (consumer thread):

// Get latest frame (returns NULL if no new frame since last read)
if (frame) {
// Process frame data
render_ascii(frame->data, frame->width, frame->height);
}
const video_frame_t * video_frame_get_latest(video_frame_buffer_t *vfb)
Reader API: Get latest frame if available.
uint32_t height
Frame height in pixels.
uint32_t width
Frame width in pixels.
void * data
Frame data pointer (points to pre-allocated buffer).

Manual Creation (for special cases)

For cases where you need standalone frames without the double-buffering system:

Create from Existing Data:

video_frame_t frame = {
.data = existing_rgb_data,
.width = 1920,
.height = 1080,
.data_size = 1920 * 1080 * 3,
.client_id = client_id,
.timestamp = get_timestamp_usec(),
.owns_data = false // Don't free existing_rgb_data
};

Data Access

Pixel Access:

// Get pixel at (x, y)
size_t offset = (y * frame->width + x) * 3;
uint8_t r = frame->data[offset + 0];
uint8_t g = frame->data[offset + 1];
uint8_t b = frame->data[offset + 2];
// Set pixel at (x, y)
frame->data[offset + 0] = 255; // R
frame->data[offset + 1] = 128; // G
frame->data[offset + 2] = 0; // B

Row Access:

// Get pointer to row y
uint8_t *row = &frame->data[y * frame->width * 3];
// Process entire row
for (uint32_t x = 0; x < frame->width; x++) {
uint8_t r = row[x * 3 + 0];
uint8_t g = row[x * 3 + 1];
uint8_t b = row[x * 3 + 2];
// Process pixel...
}

Copying

Deep Copy:

copy->width = src->width;
copy->height = src->height;
copy->data_size = src->data_size;
copy->client_id = src->client_id;
copy->timestamp = src->timestamp;
copy->owns_data = true;
// Allocate and copy pixel data
copy->data = SAFE_MALLOC(copy->data_size, uint8_t *);
memcpy(copy->data, src->data, copy->data_size);
#define SAFE_MALLOC(size, cast)

Shallow Copy (reference):

video_frame_t reference = *src;
reference.owns_data = false; // Don't free the data when done

Cleanup

Free Frame:

if (frame->owns_data && frame->data) {
free(frame->data);
frame->data = NULL;
}
free(frame);
frame = NULL;

Validation

Validate Frame:

bool is_valid_frame(const video_frame_t *frame) {
if (!frame) return false;
if (!frame->data) return false;
if (frame->width == 0 || frame->height == 0) return false;
if (frame->data_size != frame->width * frame->height * 3) return false;
return true;
}

Check Frame Dimensions:

if (frame->width > MAX_WIDTH || frame->height > MAX_HEIGHT) {
log_error("Frame dimensions too large: %ux%u", frame->width, frame->height);
}
@ ERROR_INVALID_PARAM
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628

Ownership Rules

Ownership Flag:

  • owns_data = true: Frame owns the data buffer, must free on cleanup
  • owns_data = false: Frame references external data, do NOT free

Ownership Transfer:

// Sender transfers ownership
video_frame_t *frame = create_frame();
frame->owns_data = true;
send_to_queue(frame);
// Sender no longer responsible for freeing frame->data
// Receiver takes ownership
video_frame_t *received = receive_from_queue();
if (received->owns_data) {
// Must free when done
free(received->data);
}

Frame Pipeline

Capture → Process → Encode → Send:

// 1. Capture from webcam
video_frame_t *frame = webcam_capture();
frame->owns_data = true;
frame->timestamp = get_timestamp_usec();
// 2. Process (resize, flip, etc.)
video_frame_t *processed = process_frame(frame);
// 3. Convert to ASCII
ascii_frame_t *ascii = image_to_ascii(processed);
// 4. Send over network
send_ascii_frame(client_id, ascii);
// 5. Cleanup
if (frame->owns_data) free(frame->data);
free(frame);
if (processed->owns_data) free(processed->data);
free(processed);
free(ascii);
When code needs to work with ascii frame, it keeps output, output_target, width, source_height here i...

Memory Management

Allocation Strategy:

// Calculate size with overflow protection
size_t data_size = (size_t)width * (size_t)height * 3;
// Allocate frame data
uint8_t *data = SAFE_MALLOC(data_size, uint8_t *);
if (!data) {
return SET_ERRNO(ERROR_OUT_OF_MEMORY, "Failed to allocate frame data");
}
#define SET_ERRNO(code,...)

Buffer Reuse:

// Reuse existing buffer if same size
if (frame->data_size == new_size) {
// Reuse existing buffer
memcpy(frame->data, new_data, new_size);
} else {
// Reallocate if size changed
if (frame->owns_data) free(frame->data);
frame->data = SAFE_MALLOC(new_size, uint8_t *);
frame->data_size = new_size;
}

Timestamps

Microsecond Precision:

#include <sys/time.h>
uint64_t get_timestamp_usec(void) {
struct timeval tv;
gettimeofday(&tv, NULL);
return (uint64_t)tv.tv_sec * 1000000 + tv.tv_usec;
}
frame->timestamp = get_timestamp_usec();

Calculate Frame Age:

uint64_t now = get_timestamp_usec();
uint64_t age_usec = now - frame->timestamp;
double age_ms = age_usec / 1000.0;
if (age_ms > 100.0) {
log_warn("Frame is stale: %.1fms old", age_ms);
}
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615

Best Practices

DO:

  • Always set owns_data correctly
  • Validate frame dimensions before allocation
  • Use overflow-safe size calculations
  • Set timestamp when capturing frames
  • Free frames when done
  • Check for NULL before dereferencing

DON'T:

  • Don't free frame->data if owns_data is false
  • Don't use frame after freeing
  • Don't assume frame->data is aligned
  • Don't modify shared frame data
  • Don't forget to set client_id
  • Don't use stale frames (check timestamp)

Integration Example

Complete Usage:

// Capture frame
frame->width = 640;
frame->height = 480;
frame->data_size = 640 * 480 * 3;
frame->data = SAFE_MALLOC(frame->data_size, uint8_t *);
frame->owns_data = true;
frame->client_id = my_client_id;
frame->timestamp = get_timestamp_usec();
// Fill with webcam data
image_t *captured = webcam_read_context(webcam);
if (captured) {
memcpy(frame->data, captured->pixels, frame->data_size);
}
// Process and send
process_and_send_frame(frame);
// Cleanup (if still owning data)
if (frame->owns_data && frame->data) {
free(frame->data);
}
free(frame);
image_t * webcam_read_context(webcam_context_t *ctx)
Capture a frame from webcam context.
rgb_pixel_t * pixels
Pixel data array (width * height RGB pixels, row-major order).
See also
video_frame.h
video/image.h
os/webcam.h

Macro Definition Documentation

◆ MAX_FRAME_BUFFERS

#define MAX_FRAME_BUFFERS   2

#include <include/ascii-chat/video/rgba/video_frame.h>

Maximum number of frame buffers (double buffering).

Definition at line 94 of file video_frame.h.

◆ VIDEO_FRAME_BUFFER_SIZE

#define VIDEO_FRAME_BUFFER_SIZE   MAX_FRAME_BUFFER_SIZE

#include <include/ascii-chat/video/rgba/video_frame.h>

Video frame buffer size (2MB per frame).

Definition at line 92 of file video_frame.h.

Function Documentation

◆ simple_frame_swap_create()

simple_frame_swap_t * simple_frame_swap_create ( void )

#include <include/ascii-chat/video/rgba/video_frame.h>

Create a simple atomic frame swap.

Returns
Pointer to newly created frame swap, or NULL on failure

Creates a lightweight frame swap structure for basic use cases that don't need statistics tracking. Uses atomic pointer swaps for lock-free operation.

Note
This is a simpler alternative to video_frame_buffer_t.
Pre-allocates two frame structures that alternate on each update.
No statistics tracking (lighter weight than full frame buffer).
Warning
Must call simple_frame_swap_destroy() to free resources.

Definition at line 220 of file video_frame.c.

220 {
222
223 // Pre-allocate both frames
224 const size_t frame_size = (size_t)MAX_FRAME_BUFFER_SIZE;
225 sfs->frame_a.data = SAFE_MALLOC(frame_size, void *);
226 sfs->frame_b.data = SAFE_MALLOC(frame_size, void *);
227
229 atomic_store_bool(&sfs->use_frame_a, false); // Next write goes to frame_b
230
231 return sfs;
232}
void atomic_store_bool(atomic_t *a, bool value)
Atomically store a boolean value.
void atomic_store_u64(atomic_t *a, uint64_t value)
Atomically store a uint64_t value.
#define MAX_FRAME_BUFFER_SIZE
Maximum frame buffer size including headers and compression.
#define SAFE_CALLOC(count, size, cast)
Counters and timing measurements used to monitor frame delivery and quality.
atomic_t use_frame_a
Atomic flag: true = use frame_a next, false = use frame_b.
video_frame_t frame_b
Second pre-allocated frame.
atomic_t current_frame
Atomic pointer to current frame (stored as uint64_t).
video_frame_t frame_a
First pre-allocated frame.

References atomic_store_bool(), atomic_store_u64(), simple_frame_swap_t::current_frame, video_frame_t::data, simple_frame_swap_t::frame_a, simple_frame_swap_t::frame_b, MAX_FRAME_BUFFER_SIZE, SAFE_CALLOC, SAFE_MALLOC, and simple_frame_swap_t::use_frame_a.

◆ simple_frame_swap_destroy()

void simple_frame_swap_destroy ( simple_frame_swap_t * sfs)

#include <include/ascii-chat/video/rgba/video_frame.h>

Destroy simple frame swap and free resources.

Parameters
sfsFrame swap to destroy (can be NULL)

Destroys the simple frame swap and frees all associated resources. Safe to call multiple times or with NULL pointer.

Definition at line 234 of file video_frame.c.

234 {
235 if (!sfs) {
236 SET_ERRNO(ERROR_INVALID_PARAM, "Simple frame swap is NULL");
237 return;
238 }
239 SAFE_FREE(sfs->frame_a.data);
240 SAFE_FREE(sfs->frame_b.data);
241 SAFE_FREE(sfs);
242}
#define SAFE_FREE(ptr)

References video_frame_t::data, ERROR_INVALID_PARAM, simple_frame_swap_t::frame_a, simple_frame_swap_t::frame_b, SAFE_FREE, and SET_ERRNO.

◆ simple_frame_swap_get()

const video_frame_t * simple_frame_swap_get ( simple_frame_swap_t * sfs)

#include <include/ascii-chat/video/rgba/video_frame.h>

Get current frame from simple frame swap.

Parameters
sfsFrame swap (must not be NULL)
Returns
Pointer to current frame, or NULL if no frame available

Gets a pointer to the current frame. This is a lock-free read operation that reads the atomic frame pointer. Returns NULL if no frame has been updated yet.

Note
Frame pointer is valid until next simple_frame_swap_update() call.
Lock-free operation (uses atomic pointer read).

Definition at line 268 of file video_frame.c.

268 {
269 if (!sfs) {
270 SET_ERRNO(ERROR_INVALID_PARAM, "Simple frame swap is NULL");
271 return NULL;
272 }
273 uintptr_t frame_ptr = atomic_load_u64(&sfs->current_frame);
274 return (const video_frame_t *)(void *)frame_ptr; // NOLINT(bugprone-casting-through-void,performance-no-int-to-ptr)
275}
uint64_t atomic_load_u64(atomic_t *a)
Atomically load a uint64_t value.

References atomic_load_u64(), simple_frame_swap_t::current_frame, ERROR_INVALID_PARAM, and SET_ERRNO.

◆ simple_frame_swap_update()

void simple_frame_swap_update ( simple_frame_swap_t * sfs,
const void * data,
size_t size )

#include <include/ascii-chat/video/rgba/video_frame.h>

Update frame data in simple frame swap.

Parameters
sfsFrame swap (must not be NULL)
dataFrame data pointer (must not be NULL)
sizeSize of frame data in bytes

Updates the current frame with new data. Atomically swaps the active frame pointer to make new data available to readers. This is a zero-copy operation (only pointer is updated, data is not copied).

Note
Frame data should remain valid until next update or destruction.
Atomic pointer swap ensures readers see consistent frame pointer.
Alternates between frame_a and frame_b on each update.
Warning
Frame data pointer must remain valid until next update.

Definition at line 244 of file video_frame.c.

244 {
245 if (!sfs || !data) {
246 SET_ERRNO(ERROR_INVALID_PARAM, "Simple frame swap or data is NULL");
247 return;
248 }
249
250 // Determine which frame to write to
251 bool use_a = atomic_load_bool(&sfs->use_frame_a);
252 video_frame_t *write_frame = use_a ? &sfs->frame_a : &sfs->frame_b;
253
254 // Copy data to write frame
255 if (size <= (size_t)MAX_FRAME_BUFFER_SIZE) {
256 SAFE_MEMCPY(write_frame->data, size, data, size);
257 write_frame->size = size;
258 write_frame->capture_timestamp_ns = time_get_ns();
259
260 // Atomically update current frame pointer
261 atomic_store_u64(&sfs->current_frame, (uintptr_t)write_frame);
262
263 // Toggle for next write
264 atomic_store_bool(&sfs->use_frame_a, !use_a);
265 }
266}
bool atomic_load_bool(atomic_t *a)
Atomic pointer wrapper.
#define SAFE_MEMCPY(dest, dest_size, src, count)
size_t size
Size of frame data in bytes.
uint64_t capture_timestamp_ns
Timestamp when frame was captured (nanoseconds).

References atomic_load_bool(), atomic_store_bool(), atomic_store_u64(), video_frame_t::capture_timestamp_ns, simple_frame_swap_t::current_frame, video_frame_t::data, ERROR_INVALID_PARAM, simple_frame_swap_t::frame_a, simple_frame_swap_t::frame_b, MAX_FRAME_BUFFER_SIZE, SAFE_MEMCPY, SET_ERRNO, video_frame_t::size, and simple_frame_swap_t::use_frame_a.

◆ video_frame_begin_write()

video_frame_t * video_frame_begin_write ( video_frame_buffer_t * vfb)

#include <include/ascii-chat/video/rgba/video_frame.h>

Writer API: Start writing a new frame.

Parameters
vfbFrame buffer manager (must not be NULL)
Returns
Pointer to back buffer for writing, or NULL on error

Gets a pointer to the back buffer for writing a new frame. Writer thread can write frame data directly to this buffer. MUST call video_frame_commit() after writing to make the frame available to readers.

Note
Writer should fill in all frame fields (data, size, width, height, etc.).
Back buffer is exclusive to writer until video_frame_commit() is called.
If previous frame wasn't committed, it will be lost (latest-frame-wins).
Warning
Must call video_frame_commit() after writing to make frame available.

Definition at line 124 of file video_frame.c.

124 {
125 if (!vfb) {
126 SET_ERRNO(ERROR_INVALID_PARAM, "Video frame buffer is NULL");
127 return NULL;
128 }
129 if (!vfb->active) {
130 SET_ERRNO(ERROR_INVALID_STATE, "vfb->active is not true");
131 return NULL;
132 }
133
134 // Writer always owns the back buffer
135 return vfb->back_buffer;
136}
@ ERROR_INVALID_STATE
bool active
True if buffer is active (receiving frames).
video_frame_t * back_buffer
Currently written frame (writer owns).

References video_frame_buffer_t::active, video_frame_buffer_t::back_buffer, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

Referenced by handle_image_frame_h265_packet(), and handle_image_frame_packet().

◆ video_frame_buffer_create()

video_frame_buffer_t * video_frame_buffer_create ( const char * client_id)

#include <include/ascii-chat/video/rgba/video_frame.h>

Create a double-buffered video frame manager.

Parameters
client_idClient ID for this frame buffer
Returns
Pointer to newly created frame buffer, or NULL on failure

Creates a new video frame buffer manager with double buffering. Pre-allocates all buffers (frame structures and data buffers) for zero-allocation operation. Initializes atomic counters and synchronization primitives.

Note
Pre-allocates 2MB × 2 buffers = 4MB total per frame buffer.
Frame buffers are reused forever (no runtime allocations).
Thread-safe: Can be used concurrently by writer and reader threads.
Warning
Must call video_frame_buffer_destroy() to free resources.

Definition at line 19 of file video_frame.c.

19 {
20 if (client_id == 0) {
21 SET_ERRNO(ERROR_INVALID_PARAM, "Client ID is 0");
22 return NULL;
23 }
24
26
27 // Copy client_id string - we own this memory now
28 // (caller's client_id may be a stack variable that goes out of scope)
29 size_t client_id_len = strlen(client_id) + 1;
30 SAFE_MALLOC_DEFER_FREE(client_id_copy, client_id_len, char *);
31 if (!client_id_copy) {
32 SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for client_id copy");
33 return NULL;
34 }
35 asciichat_error_t strcpy_result = SAFE_STRCPY(client_id_copy, client_id_len, client_id);
36 if (strcpy_result != ASCIICHAT_OK) {
37 log_error("Failed to copy client_id: %s", asciichat_error_format(NULL, strcpy_result));
38 return NULL;
39 }
40 vfb->client_id = client_id_copy;
41 vfb->active = true;
42
43 // Initialize double buffers
44 vfb->front_buffer = &vfb->frames[0];
45 vfb->back_buffer = &vfb->frames[1];
46
47 const size_t frame_size = (size_t)MAX_FRAME_BUFFER_SIZE;
48 vfb->frames[0].data = buffer_alloc(NULL, frame_size);
49 vfb->frames[1].data = buffer_alloc(NULL, frame_size);
50 defer_named(first_frame, buffer_release(vfb->frames[0].data));
51 defer_named(second_frame, buffer_release(vfb->frames[1].data));
52 if (!vfb->frames[0].data || !vfb->frames[1].data) {
53 SET_ERRNO(ERROR_MEMORY, "Video frame buffers exceed memory budget");
54 return NULL;
55 }
56 vfb->allocated_buffer_size = frame_size;
57 memset(vfb->frames[0].data, 0, frame_size);
58 memset(vfb->frames[1].data, 0, frame_size);
59
60 // Initialize synchronization
61 log_info("VFB_MUTEX_INIT_START: About to init mutex for client_id=%s", client_id);
62 if (mutex_init(&vfb->swap_mutex, "video_frame_swap") != 0) {
63 log_error("VFB_MUTEX_INIT_FAILED: mutex_init returned error");
64 SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize mutex for video frame buffer");
65 return NULL;
66 }
67 log_info("VFB_MUTEX_INIT_DONE: mutex initialized successfully");
68 atomic_store_bool(&vfb->new_frame_available, false);
69
70 // Initialize statistics
71 atomic_store_u64(&vfb->total_frames_received, 0);
72 atomic_store_u64(&vfb->total_frames_dropped, 0);
73 atomic_store_u64(&vfb->last_frame_sequence, 0);
74
75 log_debug("Created video frame buffer for client %s with double buffering", client_id);
76
77 // DEBUG: Final state check
78 log_info("VFB_FINAL: vfb=%p, back_buffer=%p (should be %p), frames[0].data=%p, frames[1].data=%p, allocated_size=%zu", (void *)vfb, (void *)vfb->back_buffer, (void *)&vfb->frames[1],
79 (void *)vfb->frames[0].data, (void *)vfb->frames[1].data, vfb->allocated_buffer_size);
80
81 NAMED_REGISTER_VIDEO_FRAME_BUFFER(vfb, "buffer", NULL);
82
83 // Register atomic fields with descriptive names - vfb is their parent
84 NAMED_REGISTER_ATOMIC(&vfb->new_frame_available, "new_frame_available_flag", (uintptr_t)(const void *)(vfb));
85 NAMED_REGISTER_ATOMIC(&vfb->total_frames_received, "total_frames_received_counter", (uintptr_t)(const void *)(vfb));
86 NAMED_REGISTER_ATOMIC(&vfb->total_frames_dropped, "total_frames_dropped_counter", (uintptr_t)(const void *)(vfb));
87 NAMED_REGISTER_ATOMIC(&vfb->last_frame_sequence, "last_frame_sequence_number", (uintptr_t)(const void *)(vfb));
88
89 defer_cancel(second_frame);
90 defer_cancel(first_frame);
91 video_frame_buffer_t *result = vfb;
92 vfb = NULL;
93 client_id_copy = NULL;
94 return result;
95}
const char * asciichat_error_format(const char *message, asciichat_error_t code)
void * buffer_alloc(buffer_domain_t *domain, size_t size)
Definition buffer.c:272
#define buffer_release(data)
Definition buffer.h:99
#define SAFE_MALLOC_DEFER_FREE(name, size, cast)
#define SAFE_STRCPY(dest, dest_size, src)
#define SAFE_CALLOC_DEFER_FREE(name, count, size, cast)
#define NAMED_REGISTER_ATOMIC(a, name, parent_ptr)
Register an atomic_t with automatic format specifier.
#define NAMED_REGISTER_VIDEO_FRAME_BUFFER(buf, name, parent_ptr)
Register a video frame buffer with automatic format specifier.
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_PLATFORM_INIT
Definition error_codes.h:59
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
One captured, decoded, or rendered video frame and its timing metadata.

References asciichat_error_format(), ASCIICHAT_OK, atomic_store_bool(), atomic_store_u64(), buffer_alloc(), buffer_release, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_PLATFORM_INIT, log_debug, log_error, log_info, MAX_FRAME_BUFFER_SIZE, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_VIDEO_FRAME_BUFFER, SAFE_CALLOC_DEFER_FREE, SAFE_MALLOC_DEFER_FREE, SAFE_STRCPY, and SET_ERRNO.

◆ video_frame_buffer_destroy()

void video_frame_buffer_destroy ( video_frame_buffer_t * vfb)

#include <include/ascii-chat/video/rgba/video_frame.h>

Destroy frame buffer and free all resources.

Parameters
vfbFrame buffer to destroy (can be NULL)

Destroys the frame buffer and frees all pre-allocated buffers and internal structures. Safe to call multiple times or with NULL pointer.

Note
All frame data and statistics are lost after destruction.

Definition at line 97 of file video_frame.c.

97 {
98 if (!vfb) {
99 SET_ERRNO(ERROR_INVALID_PARAM, "Video frame buffer is NULL");
100 return;
101 }
102
103 NAMED_UNREGISTER(vfb);
104
105 // Unregister atomic fields
110
111 vfb->active = false;
112
113 buffer_release(vfb->frames[0].data);
114 buffer_release(vfb->frames[1].data);
115
116 mutex_destroy(&vfb->swap_mutex);
117
118 // Free the allocated client_id string
119 SAFE_FREE(vfb->client_id);
120
121 SAFE_FREE(vfb);
122}
#define NAMED_UNREGISTER(ptr)
Unregister a pointer.
mutex_t swap_mutex
Brief mutex for pointer swap only.
atomic_t new_frame_available
Atomic flag: true when new frame available.
atomic_t total_frames_dropped
Total frames dropped (atomic counter).
video_frame_t frames[2]
Pre-allocated frame structures (reused forever).
atomic_t total_frames_received
Total frames received (atomic counter).
atomic_t last_frame_sequence
Last frame sequence number (atomic).
const char * client_id
Client ID (name) this buffer belongs to.

References video_frame_buffer_t::active, buffer_release, video_frame_buffer_t::client_id, video_frame_t::data, ERROR_INVALID_PARAM, video_frame_buffer_t::frames, video_frame_buffer_t::last_frame_sequence, NAMED_UNREGISTER, video_frame_buffer_t::new_frame_available, SAFE_FREE, SET_ERRNO, video_frame_buffer_t::swap_mutex, video_frame_buffer_t::total_frames_dropped, and video_frame_buffer_t::total_frames_received.

Referenced by cleanup_client_media_buffers().

◆ video_frame_commit()

void video_frame_commit ( video_frame_buffer_t * vfb)

#include <include/ascii-chat/video/rgba/video_frame.h>

Writer API: Commit the frame and swap buffers.

Parameters
vfbFrame buffer manager (must not be NULL)

Commits the current back buffer and atomically swaps it with the front buffer. Makes the new frame available to readers immediately. This is a brief critical section (uses mutex), but readers continue reading from old front buffer during swap, so they never block.

Note
After this call, the previously written frame becomes the front buffer.
Atomic flag is set to signal readers that a new frame is available.
Frame statistics are updated (total_frames_received, etc.).
Thread-safe: Writer can commit while reader is reading (no blocking).

Definition at line 138 of file video_frame.c.

138 {
139 if (!vfb) {
140 SET_ERRNO(ERROR_INVALID_PARAM, "Video frame buffer or active is NULL");
141 return;
142 }
143 if (!vfb->active) {
144 SET_ERRNO(ERROR_INVALID_STATE, "vfb->active is not true");
145 return;
146 }
147
148 // Keep the unread check, pointer swap, and publication atomic with respect
149 // to readers. Checking front_buffer before taking this mutex races with a
150 // reader consuming the previous frame and with another commit swapping it.
151 mutex_lock(&vfb->swap_mutex);
152 if (atomic_load_bool(&vfb->new_frame_available) && vfb->front_buffer->size > 0) {
156 if (drops == 1 || drops % 100 == 0) {
157 log_dev_every(4500 * US_PER_MS_INT, "Dropping frame for client %s (reader too slow, total drops: %llu)", vfb->client_id, (unsigned long long)drops);
158 }
159 }
160 video_frame_t *temp = vfb->front_buffer;
161 vfb->front_buffer = vfb->back_buffer;
162 vfb->back_buffer = temp;
164 mutex_unlock(&vfb->swap_mutex);
165
168}
uint64_t atomic_fetch_add_u64(atomic_t *a, uint64_t delta)
Atomically add to a uint64_t and return the previous value.
#define US_PER_MS_INT
Definition time.h:176
void stats_counter_add(stats_scope_t *scope, stats_counter_id_t id, uint64_t amount)
#define log_dev_every(interval_us, fmt,...)
Rate-limited DEV logging.
Definition log/log.h:740
stats_scope_t * stats_runtime_scope(void)
Definition runtime.c:78
video_frame_t * front_buffer
Currently displayed frame (reader owns).

References video_frame_buffer_t::active, atomic_fetch_add_u64(), atomic_load_bool(), atomic_store_bool(), video_frame_buffer_t::back_buffer, video_frame_buffer_t::client_id, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, video_frame_buffer_t::front_buffer, log_dev_every, video_frame_buffer_t::new_frame_available, SET_ERRNO, video_frame_t::size, stats_counter_add(), STATS_COUNTER_FRAMES_DROPPED, STATS_COUNTER_FRAMES_ENQUEUED, STATS_COUNTER_QUEUE_DROPS, stats_runtime_scope(), video_frame_buffer_t::swap_mutex, video_frame_buffer_t::total_frames_dropped, video_frame_buffer_t::total_frames_received, and US_PER_MS_INT.

Referenced by handle_image_frame_h265_packet(), and handle_image_frame_packet().

◆ video_frame_get_latest()

const video_frame_t * video_frame_get_latest ( video_frame_buffer_t * vfb)

#include <include/ascii-chat/video/rgba/video_frame.h>

Reader API: Get latest frame if available.

Parameters
vfbFrame buffer manager (must not be NULL)
Returns
Pointer to latest frame, or NULL if no new frame available

Gets a pointer to the latest frame if one is available. Returns NULL if no new frame has been committed since the last call. This is a lock-free operation that never blocks the writer thread.

Note
Frame pointer is valid until next video_frame_commit() call.
Lock-free read operation (uses atomic flag check).
Reader should check for NULL returns and handle accordingly.
Thread-safe: Reader can read while writer is writing (no blocking).

Definition at line 170 of file video_frame.c.

170 {
171 if (!vfb) {
172 SET_ERRNO(ERROR_INVALID_PARAM, "Video frame buffer is not active");
173 return NULL;
174 }
175 if (!vfb->active) {
176 SET_ERRNO(ERROR_INVALID_STATE, "vfb->active is not true");
177 return NULL;
178 }
179
180 mutex_lock(&vfb->swap_mutex);
182 mutex_unlock(&vfb->swap_mutex);
183 return NULL;
184 }
186 const video_frame_t *result = vfb->front_buffer;
187 mutex_unlock(&vfb->swap_mutex);
188
189 return result;
190}

References video_frame_buffer_t::active, atomic_load_bool(), atomic_store_bool(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, video_frame_buffer_t::front_buffer, video_frame_buffer_t::new_frame_available, SET_ERRNO, and video_frame_buffer_t::swap_mutex.

◆ video_frame_get_stats()

void video_frame_get_stats ( video_frame_buffer_t * vfb,
video_frame_stats_t * stats )

#include <include/ascii-chat/video/rgba/video_frame.h>

Get frame statistics for quality monitoring.

Parameters
vfbFrame buffer manager (must not be NULL)
statsOutput structure for statistics (must not be NULL)

Retrieves aggregated statistics from the frame buffer including total frames, dropped frames, drop rate, and average processing times. Useful for adaptive streaming quality control.

Note
All statistics are calculated atomically from atomic counters.
Drop rate is calculated as dropped_frames / total_frames.

Definition at line 202 of file video_frame.c.

202 {
203 if (!vfb || !stats) {
204 SET_ERRNO(ERROR_INVALID_PARAM, "Video frame buffer or stats is NULL");
205 return;
206 }
207 if (!vfb->active) {
208 SET_ERRNO(ERROR_INVALID_STATE, "vfb->active is not true");
209 return;
210 }
211
214 stats->drop_rate = (stats->total_frames > 0) ? (float)stats->dropped_frames / (float)stats->total_frames : 0.0f;
217}
atomic_t avg_render_time_ns
Average render time in nanoseconds (atomic).
atomic_t avg_decode_time_ns
Average decode time in nanoseconds (atomic).
uint64_t dropped_frames
Total frames dropped (due to buffer full or errors).
uint64_t total_frames
Total frames received since creation.
uint64_t avg_render_time_ns
Average frame render time in nanoseconds.
float drop_rate
Frame drop rate (dropped_frames / total_frames, 0.0-1.0).
uint64_t avg_decode_time_ns
Average frame decode time in nanoseconds.

References video_frame_buffer_t::active, atomic_load_u64(), video_frame_buffer_t::avg_decode_time_ns, video_frame_stats_t::avg_decode_time_ns, video_frame_buffer_t::avg_render_time_ns, video_frame_stats_t::avg_render_time_ns, video_frame_stats_t::drop_rate, video_frame_stats_t::dropped_frames, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, SET_ERRNO, video_frame_stats_t::total_frames, video_frame_buffer_t::total_frames_dropped, and video_frame_buffer_t::total_frames_received.

◆ video_frame_peek_latest()

const video_frame_t * video_frame_peek_latest ( video_frame_buffer_t * vfb)

#include <include/ascii-chat/video/rgba/video_frame.h>

Return the latest committed frame without consuming the new-frame flag. The returned pointer has the same borrowed lifetime as video_frame_get_latest().

Definition at line 192 of file video_frame.c.

192 {
193 if (!vfb || !vfb->active)
194 return NULL;
195 mutex_lock(&vfb->swap_mutex);
196 const video_frame_t *frame = vfb->front_buffer;
197 const video_frame_t *result = frame && frame->size > 0 ? frame : NULL;
198 mutex_unlock(&vfb->swap_mutex);
199 return result;
200}

References video_frame_buffer_t::active, video_frame_buffer_t::front_buffer, video_frame_t::size, and video_frame_buffer_t::swap_mutex.