0
# Trigger Control
1
2
External and software trigger control for synchronized image capture and multi-camera setups for libdc1394.
3
4
## Capabilities
5
6
### External Trigger Configuration
7
8
Controls external hardware trigger settings for synchronized capture.
9
10
```java { .api }
11
/**
12
* Sets the external trigger mode
13
* @param camera Camera instance
14
* @param mode Trigger mode (DC1394_TRIGGER_MODE_*)
15
* @return DC1394_SUCCESS on success, error code on failure
16
*/
17
int dc1394_external_trigger_set_mode(dc1394camera_t camera, int mode);
18
19
/**
20
* Gets the current external trigger mode
21
* @param camera Camera instance
22
* @param mode Output parameter for current trigger mode
23
* @return DC1394_SUCCESS on success, error code on failure
24
*/
25
int dc1394_external_trigger_get_mode(dc1394camera_t camera, IntPointer mode);
26
27
/**
28
* Sets the external trigger source
29
* @param camera Camera instance
30
* @param source Trigger source (DC1394_TRIGGER_SOURCE_*)
31
* @return DC1394_SUCCESS on success, error code on failure
32
*/
33
int dc1394_external_trigger_set_source(dc1394camera_t camera, int source);
34
35
/**
36
* Gets the current external trigger source
37
* @param camera Camera instance
38
* @param source Output parameter for current trigger source
39
* @return DC1394_SUCCESS on success, error code on failure
40
*/
41
int dc1394_external_trigger_get_source(dc1394camera_t camera, IntPointer source);
42
43
/**
44
* Sets the external trigger polarity
45
* @param camera Camera instance
46
* @param polarity Trigger polarity (DC1394_TRIGGER_ACTIVE_LOW or DC1394_TRIGGER_ACTIVE_HIGH)
47
* @return DC1394_SUCCESS on success, error code on failure
48
*/
49
int dc1394_external_trigger_set_polarity(dc1394camera_t camera, int polarity);
50
51
/**
52
* Gets the current external trigger polarity
53
* @param camera Camera instance
54
* @param polarity Output parameter for current trigger polarity
55
* @return DC1394_SUCCESS on success, error code on failure
56
*/
57
int dc1394_external_trigger_get_polarity(dc1394camera_t camera, IntPointer polarity);
58
```
59
60
**Usage Example:**
61
62
```java
63
import org.bytedeco.libdc1394.*;
64
import static org.bytedeco.libdc1394.global.dc1394.*;
65
import org.bytedeco.javacpp.*;
66
67
// Configure external trigger for Mode 0 (standard integration time)
68
int err = dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
69
if (err != DC1394_SUCCESS) {
70
dc1394_log_error("Failed to set trigger mode: " + err);
71
return;
72
}
73
74
// Use trigger source 0 (hardware pin)
75
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);
76
77
// Set trigger to activate on rising edge
78
dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);
79
80
System.out.println("External trigger configured:");
81
System.out.println(" Mode: 0 (standard integration)");
82
System.out.println(" Source: Hardware pin 0");
83
System.out.println(" Polarity: Rising edge");
84
```
85
86
### Trigger Power Control
87
88
Enables or disables trigger functionality.
89
90
```java { .api }
91
/**
92
* Enables or disables external trigger
93
* @param camera Camera instance
94
* @param pwr Power state (DC1394_ON or DC1394_OFF)
95
* @return DC1394_SUCCESS on success, error code on failure
96
*/
97
int dc1394_external_trigger_set_power(dc1394camera_t camera, int pwr);
98
99
/**
100
* Gets the external trigger power state
101
* @param camera Camera instance
102
* @param pwr Output parameter for power state
103
* @return DC1394_SUCCESS on success, error code on failure
104
*/
105
int dc1394_external_trigger_get_power(dc1394camera_t camera, IntPointer pwr);
106
107
/**
108
* Gets supported trigger modes for the camera
109
* @param camera Camera instance
110
* @param modes Output structure containing supported trigger modes
111
* @return DC1394_SUCCESS on success, error code on failure
112
*/
113
int dc1394_external_trigger_get_supported_modes(dc1394camera_t camera, dc1394trigger_modes_t modes);
114
115
/**
116
* Gets supported trigger sources for the camera
117
* @param camera Camera instance
118
* @param sources Output structure containing supported trigger sources
119
* @return DC1394_SUCCESS on success, error code on failure
120
*/
121
int dc1394_external_trigger_get_supported_sources(dc1394camera_t camera, dc1394trigger_sources_t sources);
122
```
123
124
**Usage Example:**
125
126
```java
127
// Check trigger capabilities first
128
dc1394trigger_modes_t modes = new dc1394trigger_modes_t();
129
dc1394trigger_sources_t sources = new dc1394trigger_sources_t();
130
131
dc1394_external_trigger_get_supported_modes(camera, modes);
132
dc1394_external_trigger_get_supported_sources(camera, sources);
133
134
System.out.println("Supported trigger modes: " + modes.num());
135
for (int i = 0; i < modes.num(); i++) {
136
System.out.println(" Mode " + modes.modes(i));
137
}
138
139
System.out.println("Supported trigger sources: " + sources.num());
140
for (int i = 0; i < sources.num(); i++) {
141
System.out.println(" Source " + sources.sources(i));
142
}
143
144
// Enable external trigger
145
dc1394_external_trigger_set_power(camera, DC1394_ON);
146
System.out.println("External trigger enabled");
147
```
148
149
### Software Trigger Control
150
151
Controls software-initiated triggers for programmatic capture control.
152
153
```java { .api }
154
/**
155
* Enables or disables software trigger
156
* @param camera Camera instance
157
* @param pwr Power state (DC1394_ON or DC1394_OFF)
158
* @return DC1394_SUCCESS on success, error code on failure
159
*/
160
int dc1394_software_trigger_set_power(dc1394camera_t camera, int pwr);
161
162
/**
163
* Gets the software trigger power state
164
* @param camera Camera instance
165
* @param pwr Output parameter for power state
166
* @return DC1394_SUCCESS on success, error code on failure
167
*/
168
int dc1394_software_trigger_get_power(dc1394camera_t camera, IntPointer pwr);
169
```
170
171
**Usage Example:**
172
173
```java
174
// Configure software trigger
175
dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
176
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_SOFTWARE);
177
178
// Enable software trigger
179
dc1394_software_trigger_set_power(camera, DC1394_ON);
180
181
// Enable external trigger subsystem (required even for software trigger)
182
dc1394_external_trigger_set_power(camera, DC1394_ON);
183
184
System.out.println("Software trigger ready");
185
186
// Now triggers must be sent via software trigger feature
187
// (typically through the TRIGGER feature control)
188
dc1394_feature_set_mode(camera, DC1394_FEATURE_TRIGGER, DC1394_FEATURE_MODE_MANUAL);
189
```
190
191
### Trigger Delay Control
192
193
Controls the delay between trigger signal and actual image capture.
194
195
```java { .api }
196
/**
197
* Sets trigger delay value
198
* @param camera Camera instance
199
* @param delay Delay value in camera-specific units
200
* @return DC1394_SUCCESS on success, error code on failure
201
*/
202
int dc1394_feature_set_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, int delay);
203
204
/**
205
* Gets current trigger delay value
206
* @param camera Camera instance
207
* @param delay Output parameter for delay value
208
* @return DC1394_SUCCESS on success, error code on failure
209
*/
210
int dc1394_feature_get_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, IntPointer delay);
211
212
/**
213
* Sets absolute trigger delay in seconds
214
* @param camera Camera instance
215
* @param delay Delay in seconds
216
* @return DC1394_SUCCESS on success, error code on failure
217
*/
218
int dc1394_feature_set_absolute_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, float delay);
219
220
/**
221
* Gets absolute trigger delay in seconds
222
* @param camera Camera instance
223
* @param delay Output parameter for delay in seconds
224
* @return DC1394_SUCCESS on success, error code on failure
225
*/
226
int dc1394_feature_get_absolute_value(dc1394camera_t camera, int DC1394_FEATURE_TRIGGER_DELAY, FloatPointer delay);
227
```
228
229
**Usage Example:**
230
231
```java
232
// Check if trigger delay is supported
233
dc1394featureset_t features = new dc1394featureset_t();
234
dc1394_feature_get_all(camera, features);
235
236
dc1394feature_info_t delayFeature = features.feature(DC1394_FEATURE_TRIGGER_DELAY - DC1394_FEATURE_MIN);
237
if (delayFeature.available()) {
238
System.out.println("Trigger delay available");
239
System.out.println("Range: " + delayFeature.min() + " - " + delayFeature.max());
240
241
// Set 100ms delay using absolute values
242
if (delayFeature.absolute_capable()) {
243
dc1394_feature_set_absolute_control(camera, DC1394_FEATURE_TRIGGER_DELAY, DC1394_ON);
244
dc1394_feature_set_absolute_value(camera, DC1394_FEATURE_TRIGGER_DELAY, 0.1f);
245
System.out.println("Set trigger delay to 100ms");
246
}
247
}
248
```
249
250
## Types
251
252
### Trigger Mode Support
253
254
```java { .api }
255
/**
256
* Container for supported trigger modes
257
*/
258
class dc1394trigger_modes_t extends Pointer {
259
/**
260
* Number of supported trigger modes
261
* @return Mode count
262
*/
263
int num();
264
265
/**
266
* Array of supported trigger mode constants
267
* @param i Mode index
268
* @return Trigger mode constant
269
*/
270
int modes(int i);
271
}
272
```
273
274
### Trigger Source Support
275
276
```java { .api }
277
/**
278
* Container for supported trigger sources
279
*/
280
class dc1394trigger_sources_t extends Pointer {
281
/**
282
* Number of supported trigger sources
283
* @return Source count
284
*/
285
int num();
286
287
/**
288
* Array of supported trigger source constants
289
* @param i Source index
290
* @return Trigger source constant
291
*/
292
int sources(int i);
293
}
294
```
295
296
## Constants
297
298
### Trigger Modes
299
300
```java { .api }
301
// Standard trigger modes (integration time control)
302
static final int DC1394_TRIGGER_MODE_0 = 384; // Standard integration time
303
static final int DC1394_TRIGGER_MODE_1 = 385; // Integration time = trigger pulse width
304
static final int DC1394_TRIGGER_MODE_2 = 386; // Integration time = trigger pulse width + offset
305
static final int DC1394_TRIGGER_MODE_3 = 387; // Integration time = exposure feature value
306
static final int DC1394_TRIGGER_MODE_4 = 388; // Multiple exposures
307
static final int DC1394_TRIGGER_MODE_5 = 389; // Multiple exposures with integration time control
308
309
// Advanced trigger modes (camera-specific)
310
static final int DC1394_TRIGGER_MODE_14 = 398; // Vendor-specific mode
311
static final int DC1394_TRIGGER_MODE_15 = 399; // Vendor-specific mode
312
313
// Trigger mode range
314
static final int DC1394_TRIGGER_MODE_MIN = DC1394_TRIGGER_MODE_0;
315
static final int DC1394_TRIGGER_MODE_MAX = DC1394_TRIGGER_MODE_15;
316
```
317
318
### Trigger Sources
319
320
```java { .api }
321
// Hardware trigger sources
322
static final int DC1394_TRIGGER_SOURCE_0 = 576; // External trigger pin 0
323
static final int DC1394_TRIGGER_SOURCE_1 = 577; // External trigger pin 1
324
static final int DC1394_TRIGGER_SOURCE_2 = 578; // External trigger pin 2
325
static final int DC1394_TRIGGER_SOURCE_3 = 579; // External trigger pin 3
326
327
// Software trigger source
328
static final int DC1394_TRIGGER_SOURCE_SOFTWARE = 580; // Software trigger
329
330
// Trigger source range
331
static final int DC1394_TRIGGER_SOURCE_MIN = DC1394_TRIGGER_SOURCE_0;
332
static final int DC1394_TRIGGER_SOURCE_MAX = DC1394_TRIGGER_SOURCE_SOFTWARE;
333
```
334
335
### Trigger Polarity
336
337
```java { .api }
338
// Trigger activation polarity
339
static final int DC1394_TRIGGER_ACTIVE_LOW = 704; // Trigger on falling edge/low level
340
static final int DC1394_TRIGGER_ACTIVE_HIGH = 705; // Trigger on rising edge/high level
341
```
342
343
### Power States
344
345
```java { .api }
346
// Trigger power control
347
static final int DC1394_ON = 1; // Enable trigger
348
static final int DC1394_OFF = 0; // Disable trigger
349
```
350
351
## Trigger Mode Descriptions
352
353
### Mode 0 - Standard Integration
354
355
- **Usage**: Most common trigger mode for standard imaging
356
- **Behavior**: Camera uses preset integration time (shutter/exposure setting)
357
- **Trigger**: Single pulse starts capture with fixed exposure time
358
- **Applications**: General synchronized capture, machine vision
359
360
### Mode 1 - Pulse Width Integration
361
362
- **Usage**: Integration time controlled by trigger pulse width
363
- **Behavior**: Camera integrates while trigger signal is active
364
- **Trigger**: Pulse width determines exposure time
365
- **Applications**: External shutter control, variable exposure from hardware
366
367
### Mode 2 - Pulse Width + Offset
368
369
- **Usage**: Integration time = pulse width + programmable offset
370
- **Behavior**: Combines pulse width timing with camera offset
371
- **Trigger**: More flexible timing control than Mode 1
372
- **Applications**: Precise timing control with hardware compensation
373
374
### Mode 3 - Feature-Controlled Integration
375
376
- **Usage**: Integration time from exposure feature, trigger starts capture
377
- **Behavior**: Camera uses exposure feature value, trigger initiates
378
- **Trigger**: Pulse triggers capture with software-controlled exposure
379
- **Applications**: Software-controlled exposure with hardware synchronization
380
381
### Mode 14/15 - Vendor-Specific
382
383
- **Usage**: Camera manufacturer-specific modes
384
- **Behavior**: Varies by camera model and vendor
385
- **Trigger**: Check camera documentation for specifics
386
- **Applications**: Specialized features unique to camera model
387
388
## Multi-Camera Synchronization
389
390
### Hardware Synchronization
391
392
```java
393
// Configure multiple cameras for synchronized capture
394
void setupMultiCameraSync(dc1394camera_t[] cameras) {
395
for (dc1394camera_t camera : cameras) {
396
// All cameras use same trigger mode and source
397
dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
398
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);
399
dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);
400
401
// Enable trigger
402
dc1394_external_trigger_set_power(camera, DC1394_ON);
403
404
// Start transmission (cameras wait for trigger)
405
dc1394_video_set_transmission(camera, DC1394_ON);
406
}
407
408
System.out.println("Multi-camera synchronization configured");
409
System.out.println("All cameras waiting for trigger on pin 0");
410
}
411
```
412
413
### Software Synchronization
414
415
```java
416
// Software-triggered synchronized capture
417
void softwareSyncCapture(dc1394camera_t[] cameras) {
418
// Configure all cameras for software trigger
419
for (dc1394camera_t camera : cameras) {
420
dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
421
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_SOFTWARE);
422
dc1394_external_trigger_set_power(camera, DC1394_ON);
423
dc1394_software_trigger_set_power(camera, DC1394_ON);
424
425
dc1394_video_set_transmission(camera, DC1394_ON);
426
}
427
428
// Trigger all cameras simultaneously
429
for (dc1394camera_t camera : cameras) {
430
// Send software trigger (implementation varies by camera)
431
dc1394_feature_set_mode(camera, DC1394_FEATURE_TRIGGER, DC1394_FEATURE_MODE_ONE_PUSH_AUTO);
432
}
433
434
System.out.println("Software trigger sent to all cameras");
435
}
436
```
437
438
## Triggered Capture Workflow
439
440
### Basic Triggered Capture
441
442
```java
443
// Complete triggered capture workflow
444
void triggeredCaptureWorkflow(dc1394camera_t camera) {
445
try {
446
// 1. Configure camera (video mode, features, etc.)
447
dc1394_video_set_mode(camera, DC1394_VIDEO_MODE_640x480_RGB8);
448
dc1394_video_set_framerate(camera, DC1394_FRAMERATE_30);
449
450
// 2. Setup capture
451
dc1394_capture_setup(camera, 4, DC1394_CAPTURE_FLAGS_DEFAULT);
452
453
// 3. Configure trigger
454
dc1394_external_trigger_set_mode(camera, DC1394_TRIGGER_MODE_0);
455
dc1394_external_trigger_set_source(camera, DC1394_TRIGGER_SOURCE_0);
456
dc1394_external_trigger_set_polarity(camera, DC1394_TRIGGER_ACTIVE_HIGH);
457
dc1394_external_trigger_set_power(camera, DC1394_ON);
458
459
// 4. Start transmission (camera waits for trigger)
460
dc1394_video_set_transmission(camera, DC1394_ON);
461
System.out.println("Camera ready - waiting for trigger");
462
463
// 5. Wait for triggered frames
464
dc1394video_frame_t frame = new dc1394video_frame_t(null);
465
for (int i = 0; i < 10; i++) { // Capture 10 triggered frames
466
// Wait for trigger (this will block until trigger received)
467
int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_WAIT, frame);
468
if (err == DC1394_SUCCESS) {
469
System.out.println("Triggered frame " + i + " captured");
470
System.out.println(" Timestamp: " + frame.timestamp());
471
System.out.println(" Size: " + frame.total_bytes() + " bytes");
472
473
// Process frame data here...
474
475
// Return frame to queue
476
dc1394_capture_enqueue(camera, frame);
477
} else {
478
dc1394_log_error("Failed to capture triggered frame: " + err);
479
break;
480
}
481
}
482
483
} finally {
484
// 6. Cleanup
485
dc1394_video_set_transmission(camera, DC1394_OFF);
486
dc1394_external_trigger_set_power(camera, DC1394_OFF);
487
dc1394_capture_stop(camera);
488
}
489
}
490
```
491
492
### Trigger Timeout Handling
493
494
```java
495
// Handle trigger timeouts gracefully
496
boolean waitForTriggeredFrame(dc1394camera_t camera, dc1394video_frame_t frame, int timeoutMs) {
497
long startTime = System.currentTimeMillis();
498
499
while (System.currentTimeMillis() - startTime < timeoutMs) {
500
int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame);
501
502
if (err == DC1394_SUCCESS) {
503
return true; // Frame captured
504
} else if (err != DC1394_CAPTURE_POLICY_POLL) {
505
// Actual error occurred
506
dc1394_log_error("Capture error: " + err);
507
return false;
508
}
509
510
// No frame available yet, brief pause
511
try {
512
Thread.sleep(1);
513
} catch (InterruptedException e) {
514
break;
515
}
516
}
517
518
System.err.println("Trigger timeout after " + timeoutMs + "ms");
519
return false; // Timeout
520
}
521
```
522
523
## Best Practices
524
525
### Trigger Setup
526
527
1. **Configure before starting transmission**: Set up all trigger parameters before calling `dc1394_video_set_transmission()`
528
2. **Check trigger support**: Always verify camera supports desired trigger modes and sources
529
3. **Test trigger timing**: Verify trigger delays and response times for your application
530
531
### Performance Optimization
532
533
1. **Use appropriate trigger mode**: Mode 0 for fixed exposure, Mode 1 for variable exposure
534
2. **Minimize trigger delay**: Use fast trigger sources and minimal delay settings
535
3. **Buffer management**: Use sufficient DMA buffers to handle trigger timing variations
536
537
### Error Handling
538
539
```java
540
// Always validate trigger configuration
541
boolean validateTriggerConfig(dc1394camera_t camera, int mode, int source) {
542
// Check if trigger feature is available
543
dc1394featureset_t features = new dc1394featureset_t();
544
dc1394_feature_get_all(camera, features);
545
546
dc1394feature_info_t triggerFeature = features.feature(DC1394_FEATURE_TRIGGER - DC1394_FEATURE_MIN);
547
if (!triggerFeature.available()) {
548
System.err.println("Trigger feature not available");
549
return false;
550
}
551
552
// Check supported modes
553
dc1394trigger_modes_t modes = new dc1394trigger_modes_t();
554
dc1394_external_trigger_get_supported_modes(camera, modes);
555
556
boolean modeSupported = false;
557
for (int i = 0; i < modes.num(); i++) {
558
if (modes.modes(i) == mode) {
559
modeSupported = true;
560
break;
561
}
562
}
563
564
if (!modeSupported) {
565
System.err.println("Trigger mode " + mode + " not supported");
566
return false;
567
}
568
569
// Check supported sources
570
dc1394trigger_sources_t sources = new dc1394trigger_sources_t();
571
dc1394_external_trigger_get_supported_sources(camera, sources);
572
573
boolean sourceSupported = false;
574
for (int i = 0; i < sources.num(); i++) {
575
if (sources.sources(i) == source) {
576
sourceSupported = true;
577
break;
578
}
579
}
580
581
if (!sourceSupported) {
582
System.err.println("Trigger source " + source + " not supported");
583
return false;
584
}
585
586
return true;
587
}
588
```