capture.c File Reference

📹 Client webcam capture: dedicated capture thread with frame rate limiting and network transmission More...

Go to the source code of this file.

Macros
#define	CLIENT_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE   32
#define	CAPTURE_TARGET_FPS   6

Functions
int	capture_init ()
	Initialize capture subsystem.
int	capture_start_thread (client_connection_t *connection)
	Start capture thread.
void	capture_stop_thread (client_connection_t *connection)
	Stop capture thread.
bool	capture_thread_exited (client_connection_t *connection)
	Check if capture thread has exited.
void	capture_cleanup ()
	Cleanup capture subsystem.
void *	capture_get_media_source (void)
session_capture_ctx_t *	capture_get_context (void)

Detailed Description

📹 Client webcam capture: dedicated capture thread with frame rate limiting and network transmission

The capture system follows a producer-consumer pattern:

• Producer: Webcam capture thread reads frames from camera
• Processing: Frame resizing and format conversion pipeline
• Consumer: Network transmission thread sends processed frames
• Rate Limiting: Frame rate control to prevent bandwidth overload

Threading Model

Capture operations run in a dedicated thread:

• Main Thread: Manages thread lifecycle and coordination
• Capture Thread: Continuous frame capture and processing loop
• Synchronization: Atomic flags coordinate thread shutdown
• Resource Management: Clean webcam and memory resource cleanup

Frame Processing Pipeline

Raw webcam frames undergo comprehensive processing:

1. Capture: Read raw frame from webcam device
2. Validation: Check frame validity and dimensions
3. Aspect Ratio: Calculate optimal resize dimensions
4. Resizing: Scale frame to network-optimal size (800x600 max)
5. Serialization: Pack frame data into network packet format
6. Transmission: Send via IMAGE_FRAME packet to server

Frame Rate Management

Implements intelligent frame rate limiting:

• Capture Rate: 144 FPS to support high-refresh displays (~6.9ms intervals)
• Timing Control: Monotonic clock for accurate frame intervals
• Adaptive Delays: Dynamic sleep adjustment for consistent timing
• Display Support: High capture rate enables smooth playback on promotion displays

Image Resizing Strategy

Optimizes frame size for network efficiency:

• Maximum Dimensions: 800x600 pixels for reasonable bandwidth
• Aspect Ratio Preservation: Maintain original camera aspect ratio
• Intelligent Scaling: Fit-to-bounds algorithm for optimal sizing
• Quality Balance: Large enough for server flexibility, small enough for efficiency

Packet Format and Transmission

Frame data serialized for network transmission:

• Header: Width and height as 32-bit network byte order integers
• Payload: RGB pixel data as continuous byte array
• Size Limits: Enforce maximum packet size for protocol compliance
• Error Handling: Graceful handling of oversized frames

Platform Compatibility

Uses webcam abstraction layer for cross-platform support:

• Linux: Video4Linux2 (V4L2) webcam interface
• macOS: AVFoundation framework integration
• Windows: DirectShow API wrapper (stub implementation)
• Fallback: Test pattern generation when webcam unavailable

Integration Points

• main.c: Capture subsystem lifecycle management
• server.c: Network packet transmission and connection monitoring
• webcam.c: Low-level webcam device interface and frame reading
• image.c: Image processing and memory management functions

Error Handling

Capture errors handled with appropriate recovery:

• Device Errors: Webcam unavailable or device busy (continue with warnings)
• Memory Errors: Frame allocation failures (skip frame, continue)
• Network Errors: Transmission failures (trigger connection loss detection)
• Processing Errors: Invalid frames or resize failures (skip and retry)

Resource Management

Careful resource lifecycle management:

• Webcam Device: Proper initialization and cleanup
• Frame Buffers: Automatic memory management with leak prevention
• Thread Resources: Clean thread termination and resource release
• Network Buffers: Efficient packet buffer allocation and cleanup

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

2025

Definition in file client/capture.c.

Macro Definition Documentation

CAPTURE_TARGET_FPS

#define CAPTURE_TARGET_FPS   6

Fallback capture FPS when no target was configured

Definition at line 147 of file client/capture.c.

Referenced by capture_init().

CLIENT_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE

#define CLIENT_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE   32

Definition at line 3 of file client/capture.c.

Referenced by capture_init().

Function Documentation

capture_cleanup()

void capture_cleanup

(

)

Cleanup capture subsystem.

Cleanup capture subsystem

Stops capture thread and cleans up media source resources. Called during client shutdown.

Definition at line 554 of file client/capture.c.

                       {
 
  // Destroy capture context
  if (g_capture_capture_ctx) {
    session_capture_destroy(g_capture_capture_ctx);
    g_capture_capture_ctx = NULL;
  }
}

References session_capture_destroy().

capture_get_context()

session_capture_ctx_t * capture_get_context

(

void

)

Definition at line 567 of file client/capture.c.

                                                 {
  return g_capture_capture_ctx;
}

capture_get_media_source()

void * capture_get_media_source

(

void

)

Definition at line 563 of file client/capture.c.

                                     {
  return session_capture_get_media_source(g_capture_capture_ctx);
}

References session_capture_get_media_source().

capture_init()

int capture_init

(

)

Initialize capture subsystem.

Initialize capture subsystem

Sets up media source (webcam, file, or stdin) and prepares capture system for operation. Must be called once during client initialization.

Returns

0 on success, negative on error

Definition at line 412 of file client/capture.c.

                   {
  // Build capture configuration from options
  session_capture_config_t config = {0};
  const char *media_url = GET_OPTION(media_url);
  const char *media_file = GET_OPTION(media_file);
  bool media_from_stdin = GET_OPTION(media_from_stdin);
 
  if (media_url && media_url[0] != '\0') {
    // Network URL streaming (takes priority over --file)
    // Don't open webcam when streaming from URL
    config.type = MEDIA_SOURCE_FILE;
    config.path = media_url;
    config.loop = false; // Network URLs cannot be looped
    log_debug("Using network URL: %s (webcam disabled)", media_url);
  } else if (media_file && media_file[0] != '\0') {
    // File or stdin streaming - don't open webcam
    config.type = media_from_stdin ? MEDIA_SOURCE_STDIN : MEDIA_SOURCE_FILE;
    config.path = media_file;
    config.loop = GET_OPTION(media_loop) && !media_from_stdin;
    log_debug("Using media %s: %s (webcam disabled)", media_from_stdin ? "stdin" : "file", media_file);
  } else if (GET_OPTION(test_pattern)) {
    // Test pattern mode - don't open real webcam
    config.type = MEDIA_SOURCE_TEST;
    config.path = NULL;
    log_debug("Using test pattern mode");
  } else {
    // Webcam mode (default)
    static char webcam_index_str[CLIENT_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE];
    safe_snprintf(webcam_index_str, sizeof(webcam_index_str), "%u", GET_OPTION(webcam_index));
    config.type = MEDIA_SOURCE_WEBCAM;
    config.path = webcam_index_str;
    log_debug("Using webcam device %u", GET_OPTION(webcam_index));
  }
  int configured_fps = GET_OPTION(fps);
  config.target_fps = configured_fps > 0 ? (uint32_t)configured_fps : CAPTURE_TARGET_FPS;
  config.resize_for_network = true; // Client always resizes for network transmission
 
  // Configure audio capture with fallback to microphone
  config.enable_audio = true;
  config.audio_fallback_to_mic = true;
  config.mic_audio_ctx = audio_get_context();
 
  // Add seek timestamp if specified
  config.initial_seek_timestamp = GET_OPTION(media_seek_timestamp);
 
  // Create capture context using session library
  asciichat_errno_scope_t create_scope = errno_checkpoint();
  g_capture_capture_ctx = session_capture_create(&config);
  if (!g_capture_capture_ctx) {
    // Check if there's already an error set (e.g., ERROR_WEBCAM_IN_USE)
    asciichat_error_context_t failure;
    asciichat_error_t existing_error = errno_peek_since(create_scope, &failure) ? failure.code : ASCIICHAT_OK;
    log_debug("session_capture_create failed %s", asciichat_error_format(NULL, existing_error));
    if (existing_error != ASCIICHAT_OK) {
      log_debug("Returning existing error %s", asciichat_error_format(NULL, existing_error));
      return existing_error;
    }
    SET_ERRNO(ERROR_MEDIA_INIT, "Failed to initialize capture source");
    return -1;
  }
 
  return 0;
}

References asciichat_error_format(), ASCIICHAT_OK, session_capture_config_t::audio_fallback_to_mic, audio_get_context(), CAPTURE_TARGET_FPS, CLIENT_CAPTURE_WEBCAM_INDEX_BUFFER_SIZE, asciichat_error_context_t::code, session_capture_config_t::enable_audio, errno_checkpoint(), errno_peek_since(), ERROR_MEDIA_INIT, GET_OPTION, session_capture_config_t::initial_seek_timestamp, log_debug, session_capture_config_t::loop, MEDIA_SOURCE_FILE, MEDIA_SOURCE_STDIN, MEDIA_SOURCE_TEST, MEDIA_SOURCE_WEBCAM, session_capture_config_t::mic_audio_ctx, session_capture_config_t::path, session_capture_config_t::resize_for_network, safe_snprintf(), session_capture_create(), SET_ERRNO, session_capture_config_t::target_fps, and session_capture_config_t::type.

capture_start_thread()

int capture_start_thread

(

client_connection_t *

connection

)

Start capture thread.

Start capture thread

Creates and starts the webcam capture thread. Also sends stream start notification to server.

Returns

0 on success, negative on error

Definition at line 485 of file client/capture.c.

                                                          {
  if (!connection->capture_context)
    return 0;
  if (THREAD_IS_CREATED(connection->capture_thread_created)) {
    log_warn("Capture thread already created");
    return 0;
  }
 
  // Start webcam capture thread
  atomic_store_bool(&connection->capture_thread_exited, false);
  if (thread_pool_spawn(connection->client_worker_pool, webcam_capture_thread_func, connection, 2, "webcam_capture") !=
      ASCIICHAT_OK) {
    SET_ERRNO(ERROR_THREAD, "Webcam capture thread creation failed");
    LOG_ERRNO_IF_SET("Webcam capture thread creation failed");
    return -1;
  }
 
  connection->capture_thread_created = true;
  log_debug("Webcam capture thread created successfully");
 
  return 0;
}

References ASCIICHAT_OK, client_connection::capture_context, client_connection::capture_thread_created, client_connection::capture_thread_exited, client_connection::client_worker_pool, ERROR_THREAD, log_debug, LOG_ERRNO_IF_SET, log_warn, SET_ERRNO, THREAD_IS_CREATED, and thread_pool_spawn().

Referenced by client_protocol_start().

capture_stop_thread()

void capture_stop_thread

(

client_connection_t *

connection

)

Stop capture thread.

Stop capture thread

Gracefully stops the capture thread and cleans up resources. Safe to call multiple times.

Definition at line 515 of file client/capture.c.

                                                          {
  if (!connection)
    return;
  if (!THREAD_IS_CREATED(connection->capture_thread_created)) {
    return;
  }
 
  // Wait for thread to exit gracefully
  int wait_count = 0;
  while (wait_count < 20 && !atomic_load_bool(&connection->capture_thread_exited)) {
    platform_sleep_us(100 * US_PER_MS_INT); // 100ms
    wait_count++;
  }
 
  if (!atomic_load_bool(&connection->capture_thread_exited)) {
    log_warn("Capture thread not responding after 2 seconds - will be joined by thread pool");
  }
 
  // Thread will be joined by thread_pool_stop_all() in client_connection_stop()
  connection->capture_thread_created = false;
}

References client_connection::capture_thread_created, client_connection::capture_thread_exited, log_warn, THREAD_IS_CREATED, and US_PER_MS_INT.

capture_thread_exited()

bool capture_thread_exited

(

client_connection_t *

connection

)

Check if capture thread has exited.

Check if capture thread has exited

Returns

true if thread has exited, false otherwise

Definition at line 543 of file client/capture.c.

                                                            {
  return atomic_load_bool(&connection->capture_thread_exited);
}

References client_connection::capture_thread_exited.