FlashCap

When processing high-frequency video frames (e.g., 30 or 60 FPS), minimizing data copies is critical for performance. FlashCap provides different methods to access frame data via PixelBufferScope within the OpenAsync callback.

Image Access Methods Comparison

Usage Guidelines

1. For safety (accessing data outside the callback): Use CopyImage(). This ensures the data is copied into a new buffer that you own.
2. For performance (processing data inside the callback): Use ReferImage(). This avoids an extra copy by providing an ArraySegment<byte> pointing to the existing buffer. To use it with a Stream, use the AsStream() extension method or manually construct a MemoryStream using image.Array, image.Offset, and image.Count.
3. To achieve a single copy: Avoid decoding the image (e.g., converting to Bitmap). Instead, write the raw bytes directly to a file using the ArraySegment<byte> provided by ReferImage().

using var device = await descriptor0.OpenAsync(
  descriptor0.Characteristics[0],
  async bufferScope =>  // <-- `PixelBufferScope` (1 copy already occurred)
  {
    // High-performance: No extra copy (unless transcoding is required)
    ArraySegment<byte> image = bufferScope.Buffer.ReferImage();

    // Example: Writing directly to file to maintain 1-copy efficiency
    using var fs = File.Create("output.jpg");
    await fs.WriteAsync(image.Array, image.Offset, image.Count);
  });

FlashCap uses V4L2 (Video4Linux2) for Linux image capture. If you wish to port FlashCap to a Linux platform not currently supported (e.g., mips64, riscv32/64, sparc64), follow these guidelines.

Core Mechanism: V4L2Generator

Because standard .NET interop defaults are optimized for Windows and may not match the target Linux ABI, FlashCap uses FlashCap.V4L2Generator. This generator uses Clang JSON AST files to automatically generate C# interop source code that strictly adheres to the correct ABI structures for the target platform.

Porting Requirements

• Clang: You must use a Clang version compatible with your target Linux ABI. Verified versions include 13, 11, and 10.
• Runtime: A working .NET or mono runtime is required on the target Linux platform.
• Build Environment: It is highly recommended to use a QEMU-based virtual machine for a stable build environment. Automation scripts for this are located in the qemu-vm-builder/ directory.

Implementation Steps

1. Build the Generator: Build FlashCap.V4L2Generator first. If the target environment lacks the .NET SDK, use build-mono.sh to compile using mcs (mono).
2. Generate Code: Follow the procedure outlined in the dumper.sh script (you may need to adapt it for your specific environment).
3. Integrate Source: The generated code will be placed in FlashCap.Core/Internal/V4L2/.
4. Update Type Initializer: Add a new platform branch to the switch statement in NativeMethods_V4L2.cs to handle the new architecture.

// Example of adding a new platform branch in NativeMethods_V4L2.cs
switch (buf.machine)
{
    // ... existing cases ...
    case "loongarch64":
        Interop = new NativeMethods_V4L2_Interop_loongarch64();
        break;

    // Add your new port here
    case "your_new_arch":
        Interop = new NativeMethods_V4L2_Interop_your_new_arch();
        break;

    default:
        throw new InvalidOperationException($"FlashCap: Architecture '{buf.machine}' is not supported.");
}

Submitting a Pull Request

When submitting a port, please include the following details for documentation:

• Target physical machine model.
• Capture unit/camera model.
• Connection method (e.g., USB, PCIe, internal camera).
• Source of the hardware (if not a common retail item).
• Any known constraints or limitations (e.g., specific video characteristics that don't work).

FlashCap uses the V4L2 (Video4Linux2) API for Linux image capture. If you need to port it to an unsupported architecture (e.g., mips64, riscv, sparc64), you must use the FlashCap.V4L2Generator to create the necessary C# interoperability definitions from V4L2 header files.

Prerequisites

• Clang: Required to generate JSON AST files from V4L2 headers. Verified versions: 10, 11, and 13.
• Runtime: A stable .NET or Mono runtime must be available on the target Linux platform.

Porting Workflow

1. Generate Interop Code: Build FlashCap.V4L2Generator. If the target environment lacks the .NET SDK, use the provided build-mono.sh to compile using the Mono mcs compiler.
2. Automate with Scripts: Use the dumper.sh script as a template and customize it for your target environment to automate the generation process.
3. Integrate into Core: The generated source code should be placed in FlashCap.Core/Internal/V4L2/.
4. Register the Architecture: You must update the switch statement in the type initializer of NativeMethods_V4L2.cs to include your new platform branch.

Verification

• Use the Avalonia sample code for verification if supported.
• If Avalonia is unavailable, use the OneShot sample code or extend it to save continuous bitmaps for inspection.

// In FlashCap.Core/Internal/V4L2/NativeMethods_V4L2.cs
switch (buf.machine)
{
    // ... existing cases ...

    // (Insert your cool platform ported interop...)
    case "your_new_arch":
        Interop = new NativeMethods_V4L2_Interop_your_new_arch();
        break;

    default:
        throw new InvalidOperationException(
            $"FlashCap: Architecture '{buf.machine}' is not supported.");
}