tessl/maven-org-bytedeco--libdc1394

JavaCPP Presets for libdc1394 - Java bindings for controlling IEEE 1394 (FireWire) digital cameras following IIDC/DCAM specifications

—

Pending

Overview

Eval results

Files

Video Capture

Name: tessl/maven-org-bytedeco--libdc1394
Author: tessl

High-performance video frame capture with DMA support and flexible capture policies for libdc1394.

Capabilities

Capture Setup and Control

Configures and manages the video capture system with DMA buffer allocation.

/**
 * Sets up the capture system with DMA buffers
 * @param camera Camera instance
 * @param num_dma_buffers Number of DMA buffers to allocate (typically 4-16)
 * @param flags Capture flags (use DC1394_CAPTURE_FLAGS_DEFAULT)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_capture_setup(dc1394camera_t camera, int num_dma_buffers, int flags);

/**
 * Stops capture and releases DMA buffers
 * @param camera Camera instance
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_capture_stop(dc1394camera_t camera);

/**
 * Checks if a frame is corrupted
 * @param frame Frame to check
 * @return true if frame is corrupted, false if valid
 */
boolean dc1394_capture_is_frame_corrupt(dc1394video_frame_t frame);

Usage Example:

import org.bytedeco.libdc1394.*;
import static org.bytedeco.libdc1394.global.dc1394.*;

// Assume camera is already initialized and configured
dc1394camera_t camera; // ... initialized elsewhere

// Setup capture with 4 DMA buffers
int err = dc1394_capture_setup(camera, 4, DC1394_CAPTURE_FLAGS_DEFAULT);
if (err != DC1394_SUCCESS) {
    dc1394_log_error("Failed to setup capture: " + err);
    return;
}

// Start transmission
dc1394_video_set_transmission(camera, DC1394_ON);

// ... perform capture operations ...

// Stop transmission and capture
dc1394_video_set_transmission(camera, DC1394_OFF);
dc1394_capture_stop(camera);

Frame Dequeue and Enqueue

Retrieves frames from the capture buffer and returns them for reuse.

/**
 * Retrieves a frame from the capture queue
 * @param camera Camera instance
 * @param policy Capture policy (DC1394_CAPTURE_POLICY_WAIT or DC1394_CAPTURE_POLICY_POLL)
 * @param frame Output frame structure to populate
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_capture_dequeue(dc1394camera_t camera, int policy, dc1394video_frame_t frame);

/**
 * Returns a frame to the capture queue for reuse
 * @param camera Camera instance
 * @param frame Frame to return to queue
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_capture_enqueue(dc1394camera_t camera, dc1394video_frame_t frame);

Usage Example:

import org.bytedeco.libdc1394.*;
import static org.bytedeco.libdc1394.global.dc1394.*;

// Capture single frame
dc1394video_frame_t frame = new dc1394video_frame_t(null);

// Wait for frame (blocking)
int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_WAIT, frame);
if (err != DC1394_SUCCESS) {
    dc1394_log_error("Failed to capture frame: " + err);
    return;
}

// Check frame integrity
if (dc1394_capture_is_frame_corrupt(frame)) {
    System.err.println("Warning: Captured frame is corrupted");
}

// Process frame data
processFrameData(frame);

// Return frame to queue
dc1394_capture_enqueue(camera, frame);

Continuous Capture Loop

// Continuous capture example
dc1394video_frame_t frame = new dc1394video_frame_t(null);
boolean capturing = true;

while (capturing) {
    // Poll for frame (non-blocking)
    int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame);
    
    if (err == DC1394_SUCCESS) {
        // Process frame
        System.out.println("Frame captured: " + frame.total_bytes() + " bytes");
        System.out.println("Timestamp: " + frame.timestamp());
        System.out.println("Size: " + frame.size(0) + "x" + frame.size(1));
        
        // Return frame immediately
        dc1394_capture_enqueue(camera, frame);
    } else if (err == DC1394_CAPTURE_POLICY_POLL) {
        // No frame available, continue polling
        try {
            Thread.sleep(1); // Brief pause
        } catch (InterruptedException e) {
            break;
        }
    } else {
        // Actual error occurred
        dc1394_log_error("Capture error: " + err);
        break;
    }
}

Callback-based Capture

Sets up automatic callback notification when frames are available.

/**
 * Sets a callback function to be called when frames are captured
 * @param camera Camera instance
 * @param callback Callback function to invoke
 * @param user_data User data passed to callback
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_capture_set_callback(dc1394camera_t camera, dc1394capture_callback_t callback, 
                               Pointer user_data);

Usage Example:

import org.bytedeco.libdc1394.*;
import static org.bytedeco.libdc1394.global.dc1394.*;

// Create callback implementation
dc1394capture_callback_t callback = new dc1394capture_callback_t() {
    @Override
    public void call(dc1394camera_t camera, Pointer user_data) {
        // Frame is ready - dequeue and process
        dc1394video_frame_t frame = new dc1394video_frame_t(null);
        
        if (dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame) == DC1394_SUCCESS) {
            System.out.println("Callback: Frame captured with timestamp " + frame.timestamp());
            
            // Process frame here...
            
            // Return frame
            dc1394_capture_enqueue(camera, frame);
        }
    }
};

// Set callback
dc1394_capture_set_callback(camera, callback, null);

Video Transmission Control

Controls the start/stop of video data transmission from camera.

/**
 * Starts or stops video transmission
 * @param camera Camera instance
 * @param pwr Transmission state (DC1394_ON or DC1394_OFF)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_video_set_transmission(dc1394camera_t camera, int pwr);

/**
 * Gets current video transmission state
 * @param camera Camera instance
 * @param pwr Output parameter for transmission state
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_video_get_transmission(dc1394camera_t camera, IntPointer pwr);

Types

Video Frame Structure

/**
 * Video frame structure containing image data and comprehensive metadata
 */
class dc1394video_frame_t extends Pointer {
    // Image data access
    /**
     * Raw image data pointer
     * @return BytePointer to image data
     */
    BytePointer image();
    
    /**
     * Total frame size in bytes
     * @return Total bytes including metadata
     */
    long total_bytes();
    
    /**
     * Image data size in bytes
     * @return Image data bytes only
     */
    long image_bytes();
    
    /**
     * Allocated buffer size in bytes
     * @return Allocated buffer size
     */
    long allocated_image_bytes();
    
    // Frame dimensions
    /**
     * Frame dimensions: width (i=0) and height (i=1)
     * @param i Dimension index (0=width, 1=height)
     * @return Dimension value in pixels
     */
    int size(int i);
    
    /**
     * Frame position: left (i=0) and top (i=1) for Format7
     * @param i Position index (0=left, 1=top)
     * @return Position value in pixels
     */
    int _position(int i);
    
    // Format information
    /**
     * Color coding format
     * @return Color coding constant (DC1394_COLOR_CODING_*)
     */
    int color_coding();
    
    /**
     * Bayer color filter pattern for RAW formats
     * @return Color filter constant (DC1394_COLOR_FILTER_*)
     */
    int color_filter();
    
    /**
     * Video mode used for capture
     * @return Video mode constant (DC1394_VIDEO_MODE_*)
     */
    int video_mode();
    
    /**
     * Data depth in bits per pixel
     * @return Bits per pixel
     */
    int data_depth();
    
    /**
     * Bytes per line (stride)
     * @return Bytes per line
     */
    int stride();
    
    // Timing information
    /**
     * Frame timestamp in microseconds
     * @return Timestamp value
     */
    long timestamp();
    
    /**
     * Number of frames behind in buffer
     * @return Frames behind count
     */
    int frames_behind();
    
    // Format7 specific
    /**
     * Packet size for Format7 modes
     * @return Packet size in bytes
     */
    int packet_size();
    
    /**
     * Packets per frame for Format7 modes
     * @return Number of packets
     */
    int packets_per_frame();
    
    // Status information
    /**
     * YUV byte order
     * @return Byte order constant
     */
    int yuv_byte_order();
    
    /**
     * Padding bytes at end of line
     * @return Padding byte count
     */
    int padding_bytes();
    
    /**
     * Data byte order (little endian flag)
     * @return true if little endian, false if big endian
     */
    boolean little_endian();
    
    /**
     * Whether valid data is stored in padding area
     * @return true if data in padding, false otherwise
     */
    boolean data_in_padding();
    
    // Source information
    /**
     * Source camera that captured this frame
     * @return Camera instance
     */
    dc1394camera_t camera();
    
    /**
     * Frame identifier
     * @return Frame ID
     */
    long id();
}

Abstract Frame Base Class

/**
 * Abstract base class for video frames with utility methods
 */
abstract class dc1394video_frame_t_abstract extends Pointer {
    /**
     * Raw image data pointer
     * @return BytePointer to image data
     */
    abstract BytePointer image();
    
    /**
     * Total frame size in bytes
     * @return Total bytes
     */
    abstract long total_bytes();
    
    /**
     * Converts frame data to Java ByteBuffer for easier access
     * @return ByteBuffer view of frame data
     */
    ByteBuffer getByteBuffer() {
        return image().capacity((int)total_bytes()).asByteBuffer();
    }
}

Capture Callback Interface

/**
 * Callback interface for frame capture notifications
 */
abstract class dc1394capture_callback_t extends FunctionPointer {
    /**
     * Called when a frame is available for capture
     * @param camera Source camera
     * @param user_data User-provided data pointer
     */
    abstract void call(dc1394camera_t camera, Pointer user_data);
}

Constants

Capture Policies

// Frame dequeue policies
static final int DC1394_CAPTURE_POLICY_WAIT = 672;  // Block until frame available
static final int DC1394_CAPTURE_POLICY_POLL = 673;  // Return immediately if no frame

Capture Flags

// Capture setup flags
static final int DC1394_CAPTURE_FLAGS_DEFAULT = 0;   // Use default capture settings
static final int DC1394_CAPTURE_FLAGS_AUTO_ISO = 1; // Auto ISO channel allocation
static final int DC1394_CAPTURE_FLAGS_CHANNEL_ALLOC = 2; // Auto channel allocation
static final int DC1394_CAPTURE_FLAGS_BANDWIDTH_ALLOC = 4; // Auto bandwidth allocation

Transmission States

// Video transmission control
static final int DC1394_ON = 1;   // Enable transmission
static final int DC1394_OFF = 0;  // Disable transmission

Image Data Access

Reading Frame Data

// Get frame dimensions
int width = frame.size(0);
int height = frame.size(1);
long imageBytes = frame.image_bytes();

// Direct byte array access
byte[] imageData = new byte[(int)imageBytes];
frame.image().get(imageData);

// ByteBuffer access (for easier data manipulation)
ByteBuffer buffer = frame.image().capacity((int)imageBytes).asByteBuffer();

Pixel Format Information

// Check color format
int colorCoding = frame.color_coding();
switch (colorCoding) {
    case DC1394_COLOR_CODING_RGB8:
        System.out.println("RGB 8-bit format, 3 bytes per pixel");
        break;
    case DC1394_COLOR_CODING_MONO8:
        System.out.println("Monochrome 8-bit format, 1 byte per pixel");
        break;
    case DC1394_COLOR_CODING_RAW8:
        System.out.println("Raw Bayer 8-bit format, needs debayering");
        int colorFilter = frame.color_filter();
        System.out.println("Bayer pattern: " + colorFilter);
        break;
}

// Get bit depth and stride
int bitsPerPixel = frame.data_depth();
int bytesPerLine = frame.stride();

Performance Considerations

Buffer Management

Use 4-8 DMA buffers for most applications
More buffers = higher latency but better frame rate stability
Fewer buffers = lower latency but higher chance of dropped frames

Frame Processing

Process frames quickly and return them to queue immediately
Consider copying frame data if processing takes significant time
Use callback-based capture for highest performance applications

Memory Access

Use ByteBuffer for efficient data access
Consider direct memory access patterns for real-time applications
Be aware of byte order (little/big endian) for multi-byte pixel formats

Install with Tessl CLI

npx tessl i tessl/maven-org-bytedeco--libdc1394

docs

iso-resource-management.md

tessl/maven-org-bytedeco--libdc1394

video-capture.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Video Capture

Capabilities

Capture Setup and Control

Frame Dequeue and Enqueue

Continuous Capture Loop

Callback-based Capture

Video Transmission Control

Types

Video Frame Structure

Abstract Frame Base Class

Capture Callback Interface

Constants

Capture Policies

Capture Flags

Transmission States

Image Data Access

Reading Frame Data

Pixel Format Information

Performance Considerations

Buffer Management

Frame Processing

Memory Access

video-capture.mddocs/