📷 Cross-platform webcam capture API More...

Files
file	webcam_v4l2.c
	📷 Linux V4L2 webcam capture with multi-format support

file	webcam_avfoundation.m
	📷 macOS AVFoundation webcam capture implementation with hardware acceleration

file	webcam_wasm.c
	WebAssembly (browser) webcam capture backend.

file	webcam_mediafoundation.c
	📷 Windows Media Foundation webcam capture with hardware acceleration support

Data Structures
struct	webcam_device_info_t
	Webcam device information structure. More...

Macros
#define	WEBCAM_DEVICE_NAME_MAX 256
	Maximum length of webcam device name.

Typedefs
typedef struct webcam_context_t	webcam_context_t
	Opaque webcam context structure.

Functions
asciichat_error_t	webcam_list_devices (webcam_device_info_t *devices, unsigned int count)
	Enumerate available webcam devices.

void	webcam_free_device_list (webcam_device_info_t *devices)
	Free device list returned by webcam_list_devices()

void	webcam_print_init_error_help (asciichat_error_t error_code)
	Print helpful error diagnostics for webcam initialization failures.

asciichat_error_t	webcam_init_context (webcam_context_t **ctx, unsigned short int device_index)
	Initialize webcam context for advanced operations.

void	webcam_cleanup_context (webcam_context_t *ctx)
	Clean up webcam context and release resources.

void	webcam_flush_context (webcam_context_t *ctx)
	Flush/interrupt pending read operations on webcam context.

image_t *	webcam_read_context (webcam_context_t *ctx)
	Capture a frame from webcam context.

image_t *	webcam_read_async (webcam_context_t *ctx)
	Get the most recent frame from async camera thread (non-blocking)

asciichat_error_t	webcam_get_dimensions (webcam_context_t ctx, int width, int *height)
	Get webcam frame dimensions.

Detailed Description

📷 Cross-platform webcam capture API

This header provides a cross-platform webcam capture interface for ascii-chat. The system abstracts platform-specific webcam APIs (Windows Media Foundation, Linux V4L2, macOS AVFoundation) behind a unified interface for video frame capture.

CORE FEATURES:

Cross-platform webcam access (Windows, Linux, macOS)
Device enumeration and selection
Real-time video frame capture
Automatic format conversion to RGB
Thread-safe context management
Error handling with helpful diagnostics

PLATFORM SUPPORT:

Windows: Media Foundation API
Linux: Video4Linux2 (V4L2)
macOS: AVFoundation framework

ARCHITECTURE:

The webcam system uses a context-based architecture:

Per-context management for multi-webcam support
Automatic format detection and conversion
Frame rate management and throttling

VIDEO FORMATS:

The system supports:

Various native formats (YUY2, RGB, MJPEG, etc.)
Automatic conversion to RGB for processing
Format negotiation with webcam hardware
Frame rate configuration

Note: Use context-based functions to manage each webcam independently.; Webcam frames are returned as image_t structures compatible with the video conversion pipeline.; Error codes include specific diagnostics for webcam issues (permission denied, device in use, etc.).

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

Date: August 2025

Macro Definition Documentation

◆ WEBCAM_DEVICE_NAME_MAX

#define WEBCAM_DEVICE_NAME_MAX 256

#include <webcam.h>

Maximum length of webcam device name.

Definition at line 74 of file webcam.h.

Typedef Documentation

◆ webcam_context_t

typedef struct webcam_context_t webcam_context_t

#include <webcam.h>

Opaque webcam context structure.

Forward declaration of webcam context for context-based operations. Context provides per-webcam state management for advanced scenarios.

Note: Use webcam_init_context() to create a new context.; Context must be cleaned up with webcam_cleanup_context().

Definition at line 150 of file webcam.h.

Function Documentation

◆ webcam_cleanup_context()

void webcam_cleanup_context ( webcam_context_t * ctx )

#include <webcam.h>

Clean up webcam context and release resources.

Parameters

ctx	Webcam context to clean up (can be NULL)

Cleans up a webcam context and releases all associated resources. Closes the webcam device, frees memory, and invalidates the context.

Note: Safe to call multiple times or with NULL pointer (no-op).; After cleanup, context pointer is invalid and must not be used.

Definition at line 98 of file video/webcam/webcam.c.

                                                   {
  (void)ctx;
  log_warn("Webcam cleanup called on unsupported platform");
}

References log_warn.

Referenced by media_source_destroy().

◆ webcam_flush_context()

void webcam_flush_context ( webcam_context_t * ctx )

#include <webcam.h>

Flush/interrupt pending read operations on webcam context.

Parameters

ctx	Webcam context (may be NULL - no-op)

Cancels any blocking read operations. Call before stopping capture thread.

Definition at line 103 of file video/webcam/webcam.c.

                                                 {
  (void)ctx;
  // No-op on unsupported platforms
}

◆ webcam_free_device_list()

void webcam_free_device_list ( webcam_device_info_t * devices )

#include <webcam.h>

Free device list returned by webcam_list_devices()

Parameters

devices Device list to free (can be NULL)

Frees a device list allocated by webcam_list_devices(). Safe to call with NULL pointer (no-op).

Definition at line 129 of file video/webcam/webcam.c.

                                                            {
  (void)devices;
  // No-op on unsupported platforms
}

◆ webcam_get_dimensions()

asciichat_error_t webcam_get_dimensions	(	webcam_context_t *	ctx,
		int *	width,
		int *	height
	)

#include <webcam.h>

Get webcam frame dimensions.

Parameters

ctx	Webcam context (must not be NULL)
width	Output pointer for frame width (must not be NULL)
height	Output pointer for frame height (must not be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Queries the webcam context for current frame dimensions. Returns the width and height in pixels as determined during format negotiation with the webcam hardware.

Note: Dimensions may change if webcam format is renegotiated.; Frame dimensions are set during webcam_init_context().

Definition at line 114 of file video/webcam/webcam.c.

                                                                                        {
  (void)ctx;
  (void)width;
  (void)height;
  return SET_ERRNO(ERROR_WEBCAM, "Webcam get dimensions not supported on this platform");
}

References ERROR_WEBCAM, and SET_ERRNO.

◆ webcam_init_context()

asciichat_error_t webcam_init_context	(	webcam_context_t **	ctx,
		unsigned short int	device_index
	)

#include <webcam.h>

Initialize webcam context for advanced operations.

Parameters

ctx	Output pointer to webcam context (must not be NULL)
device_index	Webcam device index (0 for default device)

Returns: ASCIICHAT_OK on success, error code on failure

Initializes a new webcam context for context-based webcam management. This allows multiple webcams to be used simultaneously or provides more control over webcam lifecycle. Context must be cleaned up with webcam_cleanup_context() when done.

Note: Context is allocated by this function and must be freed with webcam_cleanup_context().; Use webcam_read_context() to capture frames from this context.; Use webcam_get_dimensions() to query frame dimensions.

Warning: On failure, use webcam_print_init_error_help() for diagnostics.

Definition at line 91 of file video/webcam/webcam.c.

                                                                                               {
  (void)ctx;
  (void)device_index;
  SET_ERRNO(ERROR_WEBCAM, "Webcam platform not supported on this system");
  return ERROR_WEBCAM;
}

References ERROR_WEBCAM, and SET_ERRNO.

Referenced by media_source_create(), and media_source_start_video().

◆ webcam_list_devices()

asciichat_error_t webcam_list_devices	(	webcam_device_info_t **	devices,
		unsigned int *	count
	)

#include <webcam.h>

Enumerate available webcam devices.

Parameters

devices	Output pointer to array of device info structures (must not be NULL)
count	Output pointer to number of devices found (must not be NULL)

Returns: ASCIICHAT_OK on success, error code on failure

Enumerates all available webcam devices and returns their information. The devices array is allocated by this function and must be freed with webcam_free_device_list().

Note: On success, *devices will point to a dynamically allocated array.; If no devices are found, *count will be 0 and *devices will be NULL.; Call webcam_free_device_list() to free the returned array.

Example:

webcam_device_info_t *devices = NULL;
unsigned int count = 0;
if (webcam_list_devices(&devices, &count) == ASCIICHAT_OK) {
    for (unsigned int i = 0; i < count; i++) {
        printf("Device %u: %s\n", devices[i].index, devices[i].name);
    }
    webcam_free_device_list(devices);
}

Definition at line 121 of file video/webcam/webcam.c.

                                                                                                   {
  if (out_devices)
    *out_devices = NULL;
  if (out_count)
    *out_count = 0;
  return SET_ERRNO(ERROR_WEBCAM, "Webcam device enumeration not supported on this platform");
}

References ERROR_WEBCAM, and SET_ERRNO.

◆ webcam_print_init_error_help()

void webcam_print_init_error_help ( asciichat_error_t error_code )

#include <webcam.h>

Print helpful error diagnostics for webcam initialization failures.

Parameters

error_code Error code from webcam_init_context()

Prints human-readable error diagnostics to help diagnose webcam initialization failures. Includes platform-specific troubleshooting advice for common issues (permission denied, device in use, etc.).

Note: This function prints to stderr with detailed diagnostics.; Useful for debugging webcam access issues.

Definition at line 14 of file video/webcam/webcam.c.

                                                                {
  // Platform-specific error messages and troubleshooting help
#ifdef __linux__
  safe_fprintf(stderr, "\n");
 
  if (error_code == ERROR_WEBCAM) {
    safe_fprintf(stderr, "Webcam initialization failed on Linux.\n\n");
    safe_fprintf(stderr, "Common solutions:\n");
    safe_fprintf(stderr, "  1. Check if a camera is connected:\n");
    safe_fprintf(stderr, "       ls /dev/video*\n\n");
    safe_fprintf(stderr, "  2. If no camera is available, use test pattern mode:\n");
    safe_fprintf(stderr, "       ascii-chat client --test-pattern\n\n");
    safe_fprintf(stderr, "  3. Install V4L2 drivers if needed:\n");
    safe_fprintf(stderr, "       sudo apt-get install v4l-utils\n");
  } else if (error_code == ERROR_WEBCAM_PERMISSION) {
    safe_fprintf(stderr, "Camera permission denied.\n\n");
    safe_fprintf(stderr, "Fix permissions with:\n");
    safe_fprintf(stderr, "  sudo usermod -a -G video $USER\n");
    safe_fprintf(stderr, "Then log out and log back in for changes to take effect.\n");
  } else if (error_code == ERROR_WEBCAM_IN_USE) {
    safe_fprintf(stderr, "Camera is already in use by another application.\n\n");
    safe_fprintf(stderr, "Try closing other camera apps or use test pattern mode:\n");
    safe_fprintf(stderr, "  ascii-chat client --test-pattern\n");
  } else {
    safe_fprintf(stderr, "Webcam error on Linux.\n\n");
    safe_fprintf(stderr, "General troubleshooting:\n");
    safe_fprintf(stderr, "* Check camera: ls /dev/video*\n");
    safe_fprintf(stderr, "* Check permissions: groups | grep video\n");
    safe_fprintf(stderr, "* Use test pattern: ascii-chat client --test-pattern\n");
  }
  (void)fflush(stderr);
#elif defined(__APPLE__)
  (void)error_code;
  safe_fprintf(stderr, "\n");
  safe_fprintf(stderr, "On macOS, you may need to grant camera permissions:\n");
  safe_fprintf(stderr,
               "* Say \"yes\" to the popup about system camera access that you see when running this program for the "
               "first time.\n");
  safe_fprintf(
      stderr, "* If you said \"no\" to the popup, go to System Preferences > Security & Privacy > Privacy > Camera.\n");
  safe_fprintf(stderr,
               "   Now flip the switch next to your terminal application in that privacy list to allow ascii-chat to "
               "access your camera.\n");
  safe_fprintf(stderr, "   Then just run this program again.\n");
  (void)fflush(stderr);
#elif defined(_WIN32)
  if (error_code == ERROR_WEBCAM_IN_USE) {
    // Device is in use by another application - this is a fatal error on Windows
    safe_fprintf(stderr, "\n");
    safe_fprintf(stderr, "Webcam is already in use by another application.\n");
    safe_fprintf(stderr, "Windows allows only one application to access the webcam at a time.\n");
    safe_fprintf(stderr, "\n");
    safe_fprintf(stderr, "To use ascii-chat with multiple clients, try these alternatives:\n");
    safe_fprintf(stderr, "  --test-pattern    Generate a colorful test pattern instead of using webcam\n");
    safe_fprintf(stderr, "  --file VIDEO.mp4  Use a video file as input (to be implemented)\n");
    safe_fprintf(stderr, "\n");
    safe_fprintf(stderr, "Example: ascii-chat client --test-pattern\n");
    (void)fflush(stderr);
  } else {
    // Other webcam errors - general failure
    safe_fprintf(stderr, "\n");
    safe_fprintf(stderr, "On Windows, this might be because:\n");
    safe_fprintf(stderr, "* Camera permissions are not granted\n");
    safe_fprintf(stderr, "* Camera driver issues\n");
    safe_fprintf(stderr, "* No webcam device found\n");
    (void)fflush(stderr);
  }
#else
  // Unknown platform
  (void)error_code;
  safe_fprintf(stderr, "\nWebcam initialization failed on unsupported platform.\n");
  (void)fflush(stderr);
#endif
}

References error_code, ERROR_WEBCAM, ERROR_WEBCAM_IN_USE, ERROR_WEBCAM_PERMISSION, and safe_fprintf().

Referenced by client_main().

◆ webcam_read_async()

image_t * webcam_read_async ( webcam_context_t * ctx )

#include <webcam.h>

Get the most recent frame from async camera thread (non-blocking)

Parameters

ctx	Webcam context (must not be NULL)

Returns: Pointer to captured image, or NULL if no frame available yet

Retrieves the most recent frame from the background camera thread without blocking. Returns an image_t structure containing the latest frame data in RGB format, or NULL if the async thread hasn't yet captured a frame.

This function is used with async camera initialization to decouple slow camera I/O from the render loop. The background thread continuously captures frames at the camera's native frame rate, and this function retrieves the latest available frame on demand without waiting.

Note: Returns NULL if no frame has been captured yet by the background thread.; The caller takes ownership of the returned frame and must NOT free it.; Subsequent calls may return NULL if no new frame is available.; Only valid after webcam_init_context() has started the background thread.

◆ webcam_read_context()

image_t * webcam_read_context ( webcam_context_t * ctx )

#include <webcam.h>

Capture a frame from webcam context.

Parameters

ctx	Webcam context (must not be NULL)

Returns: Pointer to captured image, or NULL on error

Captures a single video frame from the specified webcam context. Returns an image_t structure containing the frame data in RGB format. The image is automatically converted from native webcam format to RGB.

Note: Returns NULL on error (device disconnected, I/O error, etc.).; Image structure is allocated internally and must NOT be freed by caller.; Subsequent calls reuse the same buffer (frame overwrites previous frame).; Frame rate is limited by webcam hardware and format negotiation.

Definition at line 108 of file video/webcam/webcam.c.

                                                    {
  (void)ctx;
  SET_ERRNO(ERROR_WEBCAM, "Webcam read not supported on this platform");
  return NULL;
}

References ERROR_WEBCAM, and SET_ERRNO.

Referenced by media_source_read_video().

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

CORE FEATURES:

PLATFORM SUPPORT:

ARCHITECTURE:

VIDEO FORMATS:

Macro Definition Documentation

◆ WEBCAM_DEVICE_NAME_MAX

Typedef Documentation

◆ webcam_context_t

Function Documentation

◆ webcam_cleanup_context()

◆ webcam_flush_context()

◆ webcam_free_device_list()

◆ webcam_get_dimensions()

◆ webcam_init_context()

◆ webcam_list_devices()

◆ webcam_print_init_error_help()

◆ webcam_read_async()

◆ webcam_read_context()