CtrlK
BlogDocsLog inGet started
Tessl Logo

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

trigger-control.mddocs/

Trigger Control

External and software trigger control for synchronized image capture and multi-camera setups for libdc1394.

Capabilities

External Trigger Configuration

Controls external hardware trigger settings for synchronized capture.

/**
 * Sets the external trigger mode
 * @param camera Camera instance
 * @param mode Trigger mode (DC1394_TRIGGER_MODE_*)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_set_mode(dc1394camera_t camera, int mode);

/**
 * Gets the current external trigger mode
 * @param camera Camera instance
 * @param mode Output parameter for current trigger mode
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_mode(dc1394camera_t camera, IntPointer mode);

/**
 * Sets the external trigger source
 * @param camera Camera instance
 * @param source Trigger source (DC1394_TRIGGER_SOURCE_*)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_set_source(dc1394camera_t camera, int source);

/**
 * Gets the current external trigger source
 * @param camera Camera instance
 * @param source Output parameter for current trigger source
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_source(dc1394camera_t camera, IntPointer source);

/**
 * Sets the external trigger polarity
 * @param camera Camera instance
 * @param polarity Trigger polarity (DC1394_TRIGGER_ACTIVE_LOW or DC1394_TRIGGER_ACTIVE_HIGH)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_set_polarity(dc1394camera_t camera, int polarity);

/**
 * Gets the current external trigger polarity
 * @param camera Camera instance
 * @param polarity Output parameter for current trigger polarity
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_polarity(dc1394camera_t camera, IntPointer polarity);

Usage Example:

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

// Configure external trigger for Mode 0 (standard integration time)
int err = dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
if (err != DC1394_SUCCESS) {
    dc1394_log_error("Failed to set trigger mode: " + err);
    return;
}

// Use trigger source 0 (hardware pin)
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);

// Set trigger to activate on rising edge
dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);

System.out.println("External trigger configured:");
System.out.println("  Mode: 0 (standard integration)");
System.out.println("  Source: Hardware pin 0");
System.out.println("  Polarity: Rising edge");

Trigger Power Control

Enables or disables trigger functionality.

/**
 * Enables or disables external trigger
 * @param camera Camera instance
 * @param pwr Power state (DC1394_ON or DC1394_OFF)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_set_power(dc1394camera_t camera, int pwr);

/**
 * Gets the external trigger power state
 * @param camera Camera instance
 * @param pwr Output parameter for power state
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_power(dc1394camera_t camera, IntPointer pwr);

/**
 * Gets supported trigger modes for the camera
 * @param camera Camera instance
 * @param modes Output structure containing supported trigger modes
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_supported_modes(dc1394camera_t camera, dc1394trigger_modes_t modes);

/**
 * Gets supported trigger sources for the camera
 * @param camera Camera instance
 * @param sources Output structure containing supported trigger sources
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_external_trigger_get_supported_sources(dc1394camera_t camera, dc1394trigger_sources_t sources);

Usage Example:

// Check trigger capabilities first
dc1394trigger_modes_t modes = new dc1394trigger_modes_t();
dc1394trigger_sources_t sources = new dc1394trigger_sources_t();

dc1394_external_trigger_get_supported_modes(camera, modes);
dc1394_external_trigger_get_supported_sources(camera, sources);

System.out.println("Supported trigger modes: " + modes.num());
for (int i = 0; i < modes.num(); i++) {
    System.out.println("  Mode " + modes.modes(i));
}

System.out.println("Supported trigger sources: " + sources.num());
for (int i = 0; i < sources.num(); i++) {
    System.out.println("  Source " + sources.sources(i));
}

// Enable external trigger
dc1394_external_trigger_set_power(camera, DC1394_ON);
System.out.println("External trigger enabled");

Software Trigger Control

Controls software-initiated triggers for programmatic capture control.

/**
 * Enables or disables software trigger
 * @param camera Camera instance
 * @param pwr Power state (DC1394_ON or DC1394_OFF)
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_software_trigger_set_power(dc1394camera_t camera, int pwr);

/**
 * Gets the software trigger power state
 * @param camera Camera instance
 * @param pwr Output parameter for power state
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_software_trigger_get_power(dc1394camera_t camera, IntPointer pwr);

Usage Example:

// Configure software trigger
dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_SOFTWARE);

// Enable software trigger
dc1394_software_trigger_set_power(camera, DC1394_ON);

// Enable external trigger subsystem (required even for software trigger)
dc1394_external_trigger_set_power(camera, DC1394_ON);

System.out.println("Software trigger ready");

// Now triggers must be sent via software trigger feature
// (typically through the TRIGGER feature control)
dc1394_feature_set_mode(camera, DC1394_FEATURE_TRIGGER, DC1394_FEATURE_MODE_MANUAL);

Trigger Delay Control

Controls the delay between trigger signal and actual image capture.

/**
 * Sets trigger delay value
 * @param camera Camera instance
 * @param delay Delay value in camera-specific units
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_feature_set_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, int delay);

/**
 * Gets current trigger delay value
 * @param camera Camera instance
 * @param delay Output parameter for delay value
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_feature_get_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, IntPointer delay);

/**
 * Sets absolute trigger delay in seconds
 * @param camera Camera instance
 * @param delay Delay in seconds
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_feature_set_absolute_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, float delay);

/**
 * Gets absolute trigger delay in seconds
 * @param camera Camera instance
 * @param delay Output parameter for delay in seconds
 * @return DC1394_SUCCESS on success, error code on failure
 */
int dc1394_feature_get_absolute_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, FloatPointer delay);

Usage Example:

// Check if trigger delay is supported
dc1394featureset_t features = new dc1394featureset_t();
dc1394_feature_get_all(camera, features);

dc1394feature_info_t delayFeature = features.feature(DC1394_FEATURE_TRIGGER_DELAY - DC1394_FEATURE_MIN);
if (delayFeature.available()) {
    System.out.println("Trigger delay available");
    System.out.println("Range: " + delayFeature.min() + " - " + delayFeature.max());
    
    // Set 100ms delay using absolute values
    if (delayFeature.absolute_capable()) {
        dc1394_feature_set_absolute_control(camera, DC1394_FEATURE_TRIGGER_DELAY, DC1394_ON);
        dc1394_feature_set_absolute_value(camera, DC1394_FEATURE_TRIGGER_DELAY, 0.1f);
        System.out.println("Set trigger delay to 100ms");
    }
}

Types

Trigger Mode Support

/**
 * Container for supported trigger modes
 */
class dc1394trigger_modes_t extends Pointer {
    /**
     * Number of supported trigger modes
     * @return Mode count
     */
    int num();
    
    /**
     * Array of supported trigger mode constants
     * @param i Mode index
     * @return Trigger mode constant
     */
    int modes(int i);
}

Trigger Source Support

/**
 * Container for supported trigger sources
 */
class dc1394trigger_sources_t extends Pointer {
    /**
     * Number of supported trigger sources
     * @return Source count
     */
    int num();
    
    /**
     * Array of supported trigger source constants
     * @param i Source index
     * @return Trigger source constant
     */
    int sources(int i);
}

Constants

Trigger Modes

// Standard trigger modes (integration time control)
static final int DC1394_TRIGGER_MODE_0 = 384;   // Standard integration time
static final int DC1394_TRIGGER_MODE_1 = 385;   // Integration time = trigger pulse width
static final int DC1394_TRIGGER_MODE_2 = 386;   // Integration time = trigger pulse width + offset
static final int DC1394_TRIGGER_MODE_3 = 387;   // Integration time = exposure feature value
static final int DC1394_TRIGGER_MODE_4 = 388;   // Multiple exposures
static final int DC1394_TRIGGER_MODE_5 = 389;   // Multiple exposures with integration time control

// Advanced trigger modes (camera-specific)
static final int DC1394_TRIGGER_MODE_14 = 398;  // Vendor-specific mode
static final int DC1394_TRIGGER_MODE_15 = 399;  // Vendor-specific mode

// Trigger mode range
static final int DC1394_TRIGGER_MODE_MIN = DC1394_TRIGGER_MODE_0;
static final int DC1394_TRIGGER_MODE_MAX = DC1394_TRIGGER_MODE_15;

Trigger Sources

// Hardware trigger sources
static final int DC1394_TRIGGER_SOURCE_0 = 576;  // External trigger pin 0
static final int DC1394_TRIGGER_SOURCE_1 = 577;  // External trigger pin 1
static final int DC1394_TRIGGER_SOURCE_2 = 578;  // External trigger pin 2
static final int DC1394_TRIGGER_SOURCE_3 = 579;  // External trigger pin 3

// Software trigger source
static final int DC1394_TRIGGER_SOURCE_SOFTWARE = 580;  // Software trigger

// Trigger source range
static final int DC1394_TRIGGER_SOURCE_MIN = DC1394_TRIGGER_SOURCE_0;
static final int DC1394_TRIGGER_SOURCE_MAX = DC1394_TRIGGER_SOURCE_SOFTWARE;

Trigger Polarity

// Trigger activation polarity
static final int DC1394_TRIGGER_ACTIVE_LOW = 704;   // Trigger on falling edge/low level
static final int DC1394_TRIGGER_ACTIVE_HIGH = 705;  // Trigger on rising edge/high level

Power States

// Trigger power control
static final int DC1394_ON = 1;   // Enable trigger
static final int DC1394_OFF = 0;  // Disable trigger

Trigger Mode Descriptions

Mode 0 - Standard Integration

  • Usage: Most common trigger mode for standard imaging
  • Behavior: Camera uses preset integration time (shutter/exposure setting)
  • Trigger: Single pulse starts capture with fixed exposure time
  • Applications: General synchronized capture, machine vision

Mode 1 - Pulse Width Integration

  • Usage: Integration time controlled by trigger pulse width
  • Behavior: Camera integrates while trigger signal is active
  • Trigger: Pulse width determines exposure time
  • Applications: External shutter control, variable exposure from hardware

Mode 2 - Pulse Width + Offset

  • Usage: Integration time = pulse width + programmable offset
  • Behavior: Combines pulse width timing with camera offset
  • Trigger: More flexible timing control than Mode 1
  • Applications: Precise timing control with hardware compensation

Mode 3 - Feature-Controlled Integration

  • Usage: Integration time from exposure feature, trigger starts capture
  • Behavior: Camera uses exposure feature value, trigger initiates
  • Trigger: Pulse triggers capture with software-controlled exposure
  • Applications: Software-controlled exposure with hardware synchronization

Mode 14/15 - Vendor-Specific

  • Usage: Camera manufacturer-specific modes
  • Behavior: Varies by camera model and vendor
  • Trigger: Check camera documentation for specifics
  • Applications: Specialized features unique to camera model

Multi-Camera Synchronization

Hardware Synchronization

// Configure multiple cameras for synchronized capture
void setupMultiCameraSync(dc1394camera_t[] cameras) {
    for (dc1394camera_t camera : cameras) {
        // All cameras use same trigger mode and source
        dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
        dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);
        dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);
        
        // Enable trigger
        dc1394_external_trigger_set_power(camera, DC1394_ON);
        
        // Start transmission (cameras wait for trigger)
        dc1394_video_set_transmission(camera, DC1394_ON);
    }
    
    System.out.println("Multi-camera synchronization configured");
    System.out.println("All cameras waiting for trigger on pin 0");
}

Software Synchronization

// Software-triggered synchronized capture
void softwareSyncCapture(dc1394camera_t[] cameras) {
    // Configure all cameras for software trigger
    for (dc1394camera_t camera : cameras) {
        dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
        dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_SOFTWARE);
        dc1394_external_trigger_set_power(camera, DC1394_ON);
        dc1394_software_trigger_set_power(camera, DC1394_ON);
        
        dc1394_video_set_transmission(camera, DC1394_ON);
    }
    
    // Trigger all cameras simultaneously
    for (dc1394camera_t camera : cameras) {
        // Send software trigger (implementation varies by camera)
        dc1394_feature_set_mode(camera, DC1394_FEATURE_TRIGGER, DC1394_FEATURE_MODE_ONE_PUSH_AUTO);
    }
    
    System.out.println("Software trigger sent to all cameras");
}

Triggered Capture Workflow

Basic Triggered Capture

// Complete triggered capture workflow
void triggeredCaptureWorkflow(dc1394camera_t camera) {
    try {
        // 1. Configure camera (video mode, features, etc.)
        dc1394_video_set_mode(camera, DC1394_VIDEO_MODE_640x480_RGB8);
        dc1394_video_set_framerate(camera, DC1394_FRAMERATE_30);
        
        // 2. Setup capture
        dc1394_capture_setup(camera, 4, DC1394_CAPTURE_FLAGS_DEFAULT);
        
        // 3. Configure trigger
        dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
        dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);
        dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);
        dc1394_external_trigger_set_power(camera, DC1394_ON);
        
        // 4. Start transmission (camera waits for trigger)
        dc1394_video_set_transmission(camera, DC1394_ON);
        System.out.println("Camera ready - waiting for trigger");
        
        // 5. Wait for triggered frames
        dc1394video_frame_t frame = new dc1394video_frame_t(null);
        for (int i = 0; i < 10; i++) {  // Capture 10 triggered frames
            // Wait for trigger (this will block until trigger received)
            int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_WAIT, frame);
            if (err == DC1394_SUCCESS) {
                System.out.println("Triggered frame " + i + " captured");
                System.out.println("  Timestamp: " + frame.timestamp());
                System.out.println("  Size: " + frame.total_bytes() + " bytes");
                
                // Process frame data here...
                
                // Return frame to queue
                dc1394_capture_enqueue(camera, frame);
            } else {
                dc1394_log_error("Failed to capture triggered frame: " + err);
                break;
            }
        }
        
    } finally {
        // 6. Cleanup
        dc1394_video_set_transmission(camera, DC1394_OFF);
        dc1394_external_trigger_set_power(camera, DC1394_OFF);
        dc1394_capture_stop(camera);
    }
}

Trigger Timeout Handling

// Handle trigger timeouts gracefully
boolean waitForTriggeredFrame(dc1394camera_t camera, dc1394video_frame_t frame, int timeoutMs) {
    long startTime = System.currentTimeMillis();
    
    while (System.currentTimeMillis() - startTime < timeoutMs) {
        int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame);
        
        if (err == DC1394_SUCCESS) {
            return true;  // Frame captured
        } else if (err != DC1394_CAPTURE_POLICY_POLL) {
            // Actual error occurred
            dc1394_log_error("Capture error: " + err);
            return false;
        }
        
        // No frame available yet, brief pause
        try {
            Thread.sleep(1);
        } catch (InterruptedException e) {
            break;
        }
    }
    
    System.err.println("Trigger timeout after " + timeoutMs + "ms");
    return false;  // Timeout
}

Best Practices

Trigger Setup

  1. Configure before starting transmission: Set up all trigger parameters before calling dc1394_video_set_transmission()
  2. Check trigger support: Always verify camera supports desired trigger modes and sources
  3. Test trigger timing: Verify trigger delays and response times for your application

Performance Optimization

  1. Use appropriate trigger mode: Mode 0 for fixed exposure, Mode 1 for variable exposure
  2. Minimize trigger delay: Use fast trigger sources and minimal delay settings
  3. Buffer management: Use sufficient DMA buffers to handle trigger timing variations

Error Handling

// Always validate trigger configuration
boolean validateTriggerConfig(dc1394camera_t camera, int mode, int source) {
    // Check if trigger feature is available
    dc1394featureset_t features = new dc1394featureset_t();
    dc1394_feature_get_all(camera, features);
    
    dc1394feature_info_t triggerFeature = features.feature(DC1394_FEATURE_TRIGGER - DC1394_FEATURE_MIN);
    if (!triggerFeature.available()) {
        System.err.println("Trigger feature not available");
        return false;
    }
    
    // Check supported modes
    dc1394trigger_modes_t modes = new dc1394trigger_modes_t();
    dc1394_external_trigger_get_supported_modes(camera, modes);
    
    boolean modeSupported = false;
    for (int i = 0; i < modes.num(); i++) {
        if (modes.modes(i) == mode) {
            modeSupported = true;
            break;
        }
    }
    
    if (!modeSupported) {
        System.err.println("Trigger mode " + mode + " not supported");
        return false;
    }
    
    // Check supported sources
    dc1394trigger_sources_t sources = new dc1394trigger_sources_t();
    dc1394_external_trigger_get_supported_sources(camera, sources);
    
    boolean sourceSupported = false;
    for (int i = 0; i < sources.num(); i++) {
        if (sources.sources(i) == source) {
            sourceSupported = true;
            break;
        }
    }
    
    if (!sourceSupported) {
        System.err.println("Trigger source " + source + " not supported");
        return false;
    }
    
    return true;
}

Install with Tessl CLI

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

docs

camera-features.md

format7.md

image-conversion.md

index.md

iso-resource-management.md

logging.md

system-management.md

trigger-control.md

utility-functions.md

video-capture.md

video-modes.md

tile.json