0
# Camera Features
1

2
Comprehensive camera feature control including exposure, gain, white balance, focus, and advanced parameters for libdc1394.
3

4
## Capabilities
5

6
### Feature Information and Discovery
7

8
Retrieves information about available camera features and their capabilities.
9

10
```java { .api }
11
/**
12
 * Gets information about all camera features
13
 * @param camera Camera instance
14
 * @param features Output feature set structure
15
 * @return DC1394_SUCCESS on success, error code on failure
16
 */
17
int dc1394_feature_get_all(dc1394camera_t camera, dc1394featureset_t features);
18

19
/**
20
 * Gets information about a specific feature
21
 * @param camera Camera instance
22
 * @param feature Feature identifier (DC1394_FEATURE_*)
23
 * @param feature_info Output feature information structure
24
 * @return DC1394_SUCCESS on success, error code on failure
25
 */
26
int dc1394_feature_get(dc1394camera_t camera, int feature, dc1394feature_info_t feature_info);
27

28
/**
29
 * Prints all feature information to stdout
30
 * @param camera Camera instance
31
 * @return DC1394_SUCCESS on success, error code on failure
32
 */
33
int dc1394_feature_print_all(dc1394camera_t camera);
34

35
/**
36
 * Prints specific feature information to stdout
37
 * @param feature_info Feature information structure
38
 * @return DC1394_SUCCESS on success, error code on failure
39
 */
40
int dc1394_feature_print(dc1394feature_info_t feature_info);
41
```
42

43
**Usage Example:**
44

45
```java
46
import org.bytedeco.libdc1394.*;
47
import static org.bytedeco.libdc1394.global.dc1394.*;
48

49
// Get all feature information
50
dc1394featureset_t features = new dc1394featureset_t();
51
int err = dc1394_feature_get_all(camera, features);
52
if (err != DC1394_SUCCESS) {
53
    dc1394_log_error("Failed to get features: " + err);
54
    return;
55
}
56

57
// Check specific feature availability
58
dc1394feature_info_t exposureFeature = features.feature(DC1394_FEATURE_EXPOSURE - DC1394_FEATURE_MIN);
59
if (exposureFeature.available()) {
60
    System.out.println("Exposure control available");
61
    System.out.println("Range: " + exposureFeature.min() + " - " + exposureFeature.max());
62
    System.out.println("Current value: " + exposureFeature.value());
63
    System.out.println("Auto capable: " + exposureFeature.auto_capable());
64
}
65

66
// Print all features
67
dc1394_feature_print_all(camera);
68
```
69

70
### Feature Value Control
71

72
Controls feature values using integer or absolute (floating-point) values.
73

74
```java { .api }
75
/**
76
 * Gets the current value of a feature
77
 * @param camera Camera instance
78
 * @param feature Feature identifier
79
 * @param value Output parameter for current value
80
 * @return DC1394_SUCCESS on success, error code on failure
81
 */
82
int dc1394_feature_get_value(dc1394camera_t camera, int feature, IntPointer value);
83

84
/**
85
 * Sets the value of a feature
86
 * @param camera Camera instance
87
 * @param feature Feature identifier
88
 * @param value New value to set
89
 * @return DC1394_SUCCESS on success, error code on failure
90
 */
91
int dc1394_feature_set_value(dc1394camera_t camera, int feature, int value);
92

93
/**
94
 * Gets the absolute (floating-point) value of a feature
95
 * @param camera Camera instance
96
 * @param feature Feature identifier
97
 * @param value Output parameter for absolute value
98
 * @return DC1394_SUCCESS on success, error code on failure
99
 */
100
int dc1394_feature_get_absolute_value(dc1394camera_t camera, int feature, FloatPointer value);
101

102
/**
103
 * Sets the absolute (floating-point) value of a feature
104
 * @param camera Camera instance
105
 * @param feature Feature identifier
106
 * @param value New absolute value to set
107
 * @return DC1394_SUCCESS on success, error code on failure
108
 */
109
int dc1394_feature_set_absolute_value(dc1394camera_t camera, int feature, float value);
110
```
111

112
**Usage Example:**
113

114
```java
115
import org.bytedeco.javacpp.*;
116
import static org.bytedeco.libdc1394.global.dc1394.*;
117

118
// Set exposure using integer value
119
int err = dc1394_feature_set_value(camera, DC1394_FEATURE_EXPOSURE, 500);
120
if (err != DC1394_SUCCESS) {
121
    dc1394_log_error("Failed to set exposure: " + err);
122
}
123

124
// Get current exposure value
125
IntPointer exposureValue = new IntPointer(1);
126
dc1394_feature_get_value(camera, DC1394_FEATURE_EXPOSURE, exposureValue);
127
System.out.println("Current exposure: " + exposureValue.get());
128

129
// Use absolute values for more precise control
130
FloatPointer shutterTime = new FloatPointer(1);
131
dc1394_feature_get_absolute_value(camera, DC1394_FEATURE_SHUTTER, shutterTime);
132
System.out.println("Current shutter time: " + shutterTime.get() + " seconds");
133

134
// Set shutter time to 1/60 second
135
dc1394_feature_set_absolute_value(camera, DC1394_FEATURE_SHUTTER, 1.0f/60.0f);
136
```
137

138
### Feature Mode Control
139

140
Controls automatic vs manual modes for camera features.
141

142
```java { .api }
143
/**
144
 * Gets the current mode of a feature
145
 * @param camera Camera instance
146
 * @param feature Feature identifier
147
 * @param mode Output parameter for current mode
148
 * @return DC1394_SUCCESS on success, error code on failure
149
 */
150
int dc1394_feature_get_mode(dc1394camera_t camera, int feature, IntPointer mode);
151

152
/**
153
 * Sets the mode of a feature
154
 * @param camera Camera instance
155
 * @param feature Feature identifier
156
 * @param mode New mode (DC1394_FEATURE_MODE_*)
157
 * @return DC1394_SUCCESS on success, error code on failure
158
 */
159
int dc1394_feature_set_mode(dc1394camera_t camera, int feature, int mode);
160

161
/**
162
 * Enables or disables absolute value control for a feature
163
 * @param camera Camera instance
164
 * @param feature Feature identifier
165
 * @param pwr Enable/disable state (DC1394_ON or DC1394_OFF)
166
 * @return DC1394_SUCCESS on success, error code on failure
167
 */
168
int dc1394_feature_set_absolute_control(dc1394camera_t camera, int feature, int pwr);
169

170
/**
171
 * Gets the absolute control state for a feature
172
 * @param camera Camera instance
173
 * @param feature Feature identifier
174
 * @param pwr Output parameter for absolute control state
175
 * @return DC1394_SUCCESS on success, error code on failure
176
 */
177
int dc1394_feature_get_absolute_control(dc1394camera_t camera, int feature, IntPointer pwr);
178
```
179

180
**Usage Example:**
181

182
```java
183
// Set exposure to manual mode
184
int err = dc1394_feature_set_mode(camera, DC1394_FEATURE_EXPOSURE, DC1394_FEATURE_MODE_MANUAL);
185
if (err == DC1394_SUCCESS) {
186
    System.out.println("Exposure set to manual mode");
187
    
188
    // Now set specific exposure value
189
    dc1394_feature_set_value(camera, DC1394_FEATURE_EXPOSURE, 300);
190
}
191

192
// Enable auto gain
193
dc1394_feature_set_mode(camera, DC1394_FEATURE_GAIN, DC1394_FEATURE_MODE_AUTO);
194

195
// Use one-push auto white balance
196
dc1394_feature_set_mode(camera, DC1394_FEATURE_WHITE_BALANCE, DC1394_FEATURE_MODE_ONE_PUSH_AUTO);
197

198
// Enable absolute control for shutter
199
dc1394_feature_set_absolute_control(camera, DC1394_FEATURE_SHUTTER, DC1394_ON);
200
dc1394_feature_set_absolute_value(camera, DC1394_FEATURE_SHUTTER, 0.01f); // 10ms
201
```
202

203
### Feature Boundaries
204

205
Retrieves minimum and maximum values for features.
206

207
```java { .api }
208
/**
209
 * Gets the minimum and maximum values for a feature
210
 * @param camera Camera instance
211
 * @param feature Feature identifier
212
 * @param min Output parameter for minimum value
213
 * @param max Output parameter for maximum value
214
 * @return DC1394_SUCCESS on success, error code on failure
215
 */
216
int dc1394_feature_get_boundaries(dc1394camera_t camera, int feature, 
217
                                 IntPointer min, IntPointer max);
218

219
/**
220
 * Gets the absolute minimum and maximum values for a feature
221
 * @param camera Camera instance
222
 * @param feature Feature identifier
223
 * @param min Output parameter for absolute minimum value
224
 * @param max Output parameter for absolute maximum value
225
 * @return DC1394_SUCCESS on success, error code on failure
226
 */
227
int dc1394_feature_get_absolute_boundaries(dc1394camera_t camera, int feature, 
228
                                          FloatPointer min, FloatPointer max);
229
```
230

231
### White Balance Control
232

233
Special controls for two-component white balance feature.
234

235
```java { .api }
236
/**
237
 * Gets white balance BU (Blue/U) and RV (Red/V) values
238
 * @param camera Camera instance
239
 * @param u_b_value Output parameter for U/B component
240
 * @param v_r_value Output parameter for V/R component
241
 * @return DC1394_SUCCESS on success, error code on failure
242
 */
243
int dc1394_feature_whitebalance_get_value(dc1394camera_t camera, 
244
                                         IntPointer u_b_value, IntPointer v_r_value);
245

246
/**
247
 * Sets white balance BU (Blue/U) and RV (Red/V) values
248
 * @param camera Camera instance
249
 * @param u_b_value U/B component value
250
 * @param v_r_value V/R component value
251
 * @return DC1394_SUCCESS on success, error code on failure
252
 */
253
int dc1394_feature_whitebalance_set_value(dc1394camera_t camera, 
254
                                         int u_b_value, int v_r_value);
255
```
256

257
**Usage Example:**
258

259
```java
260
// Get current white balance values
261
IntPointer uValue = new IntPointer(1);
262
IntPointer vValue = new IntPointer(1);
263
dc1394_feature_whitebalance_get_value(camera, uValue, vValue);
264
System.out.println("White balance - U/B: " + uValue.get() + ", V/R: " + vValue.get());
265

266
// Set white balance for tungsten lighting
267
dc1394_feature_whitebalance_set_value(camera, 95, 150);
268
```
269

270
### Temperature Control
271

272
Special controls for camera temperature feature.
273

274
```java { .api }
275
/**
276
 * Gets camera temperature in Kelvin
277
 * @param camera Camera instance
278
 * @param target_temperature Output parameter for target temperature
279
 * @param current_temperature Output parameter for current temperature
280
 * @return DC1394_SUCCESS on success, error code on failure
281
 */
282
int dc1394_feature_temperature_get_value(dc1394camera_t camera, 
283
                                        IntPointer target_temperature, 
284
                                        IntPointer current_temperature);
285

286
/**
287
 * Sets target camera temperature in Kelvin
288
 * @param camera Camera instance
289
 * @param target_temperature Target temperature in Kelvin
290
 * @return DC1394_SUCCESS on success, error code on failure
291
 */
292
int dc1394_feature_temperature_set_value(dc1394camera_t camera, int target_temperature);
293
```
294

295
### Feature Power Control
296

297
Enables or disables individual features.
298

299
```java { .api }
300
/**
301
 * Turns a feature on or off
302
 * @param camera Camera instance
303
 * @param feature Feature identifier
304
 * @param pwr Power state (DC1394_ON or DC1394_OFF)
305
 * @return DC1394_SUCCESS on success, error code on failure
306
 */
307
int dc1394_feature_set_power(dc1394camera_t camera, int feature, int pwr);
308

309
/**
310
 * Gets the power state of a feature
311
 * @param camera Camera instance
312
 * @param feature Feature identifier
313
 * @param pwr Output parameter for power state
314
 * @return DC1394_SUCCESS on success, error code on failure
315
 */
316
int dc1394_feature_get_power(dc1394camera_t camera, int feature, IntPointer pwr);
317
```
318

319
## Types
320

321
### Feature Information Structure
322

323
```java { .api }
324
/**
325
 * Comprehensive feature information structure with complete field set
326
 */
327
class dc1394feature_info_t extends Pointer {
328
    /**
329
     * Feature identifier (DC1394_FEATURE_*)
330
     * @return Feature ID constant
331
     */
332
    int id();
333
    
334
    /**
335
     * Feature availability on this camera
336
     * @return true if feature is available, false otherwise
337
     */
338
    boolean available();
339
    
340
    /**
341
     * Absolute value control capability
342
     * @return true if absolute values supported, false otherwise
343
     */
344
    boolean absolute_capable();
345
    
346
    /**
347
     * Readout capability
348
     * @return true if feature can be read, false otherwise
349
     */
350
    boolean readout_capable();
351
    
352
    /**
353
     * On/off control capability
354
     * @return true if feature can be turned on/off, false otherwise
355
     */
356
    boolean on_off_capable();
357
    
358
    /**
359
     * Polarity control capability
360
     * @return true if polarity can be controlled, false otherwise
361
     */
362
    boolean polarity_capable();
363
    
364
    /**
365
     * Current on/off state
366
     * @return Current switch state
367
     */
368
    int is_on();
369
    
370
    /**
371
     * Current control mode
372
     * @return Mode constant (DC1394_FEATURE_MODE_*)
373
     */
374
    int current_mode();
375
    
376
    /**
377
     * Available modes for this feature
378
     * @return Structure containing supported modes
379
     */
380
    dc1394feature_modes_t modes();
381
    
382
    /**
383
     * Available trigger modes (for trigger feature)
384
     * @return Structure containing supported trigger modes
385
     */
386
    dc1394trigger_modes_t trigger_modes();
387
    
388
    /**
389
     * Current trigger mode (for trigger feature)
390
     * @return Trigger mode constant
391
     */
392
    int trigger_mode();
393
    
394
    /**
395
     * Current trigger polarity (for trigger feature)
396
     * @return Trigger polarity constant
397
     */
398
    int trigger_polarity();
399
    
400
    /**
401
     * Available trigger sources (for trigger feature)
402
     * @return Structure containing supported trigger sources
403
     */
404
    dc1394trigger_sources_t trigger_sources();
405
    
406
    /**
407
     * Current trigger source (for trigger feature)
408
     * @return Trigger source constant
409
     */
410
    int trigger_source();
411
    
412
    /**
413
     * Minimum feature value
414
     * @return Minimum integer value
415
     */
416
    int min();
417
    
418
    /**
419
     * Maximum feature value
420
     * @return Maximum integer value
421
     */
422
    int max();
423
    
424
    /**
425
     * Current feature value
426
     * @return Current integer value
427
     */
428
    int value();
429
    
430
    /**
431
     * Blue/U component value for white balance
432
     * @return BU component value
433
     */
434
    int BU_value();
435
    
436
    /**
437
     * Red/V component value for white balance
438
     * @return RV component value
439
     */
440
    int RV_value();
441
    
442
    /**
443
     * Blue component value for white balance
444
     * @return B component value
445
     */
446
    int B_value();
447
    
448
    /**
449
     * Red component value for white balance
450
     * @return R component value
451
     */
452
    int R_value();
453
    
454
    /**
455
     * Green component value for white balance
456
     * @return G component value
457
     */
458
    int G_value();
459
    
460
    /**
461
     * Target value for auto mode
462
     * @return Target value
463
     */
464
    int target_value();
465
    
466
    /**
467
     * Absolute control state
468
     * @return Current absolute control switch state
469
     */
470
    int abs_control();
471
    
472
    /**
473
     * Current absolute value
474
     * @return Current floating-point value
475
     */
476
    float abs_value();
477
    
478
    /**
479
     * Maximum absolute value
480
     * @return Maximum floating-point value
481
     */
482
    float abs_max();
483
    
484
    /**
485
     * Minimum absolute value
486
     * @return Minimum floating-point value
487
     */
488
    float abs_min();
489
}
490
```
491

492
### Feature Set Container
493

494
```java { .api }
495
/**
496
 * Container for all camera features
497
 */
498
class dc1394featureset_t extends Pointer {
499
    /**
500
     * Access individual feature by index
501
     * @param i Feature index (feature_id - DC1394_FEATURE_MIN)
502
     * @return Feature information structure
503
     */
504
    dc1394feature_info_t feature(int i);
505
}
506
```
507

508
### Feature Modes Structure
509

510
```java { .api }
511
/**
512
 * Available modes for a specific feature
513
 */
514
class dc1394feature_modes_t extends Pointer {
515
    /**
516
     * Number of available modes
517
     * @return Mode count
518
     */
519
    int num();
520
    
521
    /**
522
     * Array of available mode constants
523
     * @param i Mode index
524
     * @return Mode constant
525
     */
526
    int modes(int i);
527
}
528
```
529

530
## Constants
531

532
### Feature Identifiers
533

534
```java { .api }
535
// Basic image quality features
536
static final int DC1394_FEATURE_BRIGHTNESS = 416;
537
static final int DC1394_FEATURE_EXPOSURE = 417;
538
static final int DC1394_FEATURE_SHARPNESS = 418;
539
static final int DC1394_FEATURE_WHITE_BALANCE = 419;
540
static final int DC1394_FEATURE_HUE = 420;
541
static final int DC1394_FEATURE_SATURATION = 421;
542
static final int DC1394_FEATURE_GAMMA = 422;
543

544
// Camera control features
545
static final int DC1394_FEATURE_SHUTTER = 423;
546
static final int DC1394_FEATURE_GAIN = 424;
547
static final int DC1394_FEATURE_IRIS = 425;
548
static final int DC1394_FEATURE_FOCUS = 426;
549

550
// Advanced features
551
static final int DC1394_FEATURE_TEMPERATURE = 427;
552
static final int DC1394_FEATURE_TRIGGER = 428;
553
static final int DC1394_FEATURE_TRIGGER_DELAY = 429;
554
static final int DC1394_FEATURE_WHITE_SHADING = 430;
555
static final int DC1394_FEATURE_FRAME_RATE = 431;
556

557
// Mechanical control features  
558
static final int DC1394_FEATURE_ZOOM = 432;
559
static final int DC1394_FEATURE_PAN = 433;
560
static final int DC1394_FEATURE_TILT = 434;
561
static final int DC1394_FEATURE_OPTICAL_FILTER = 435;
562

563
// Additional features
564
static final int DC1394_FEATURE_CAPTURE_SIZE = 436;
565
static final int DC1394_FEATURE_CAPTURE_QUALITY = 437;
566

567
// Feature range constants
568
static final int DC1394_FEATURE_MIN = DC1394_FEATURE_BRIGHTNESS;
569
static final int DC1394_FEATURE_MAX = DC1394_FEATURE_CAPTURE_QUALITY;
570
static final int DC1394_FEATURE_NUM = (DC1394_FEATURE_MAX - DC1394_FEATURE_MIN + 1);
571
```
572

573
### Feature Modes
574

575
```java { .api }
576
// Control modes
577
static final int DC1394_FEATURE_MODE_MANUAL = 736;      // Manual control
578
static final int DC1394_FEATURE_MODE_AUTO = 737;        // Automatic control
579
static final int DC1394_FEATURE_MODE_ONE_PUSH_AUTO = 738; // One-time auto adjustment
580
```
581

582
### Power States
583

584
```java { .api }
585
// Feature power control
586
static final int DC1394_ON = 1;   // Feature enabled
587
static final int DC1394_OFF = 0;  // Feature disabled
588
```
589

590
## Utility Functions
591

592
### Feature Name Conversion
593

594
```java { .api }
595
/**
596
 * Gets human-readable string for feature identifier
597
 * @param feature Feature identifier
598
 * @return Feature name string
599
 */
600
String dc1394_feature_get_string(int feature);
601
```
602

603
**Usage Example:**
604

605
```java
606
for (int feature = DC1394_FEATURE_MIN; feature <= DC1394_FEATURE_MAX; feature++) {
607
    dc1394feature_info_t info = features.feature(feature - DC1394_FEATURE_MIN);
608
    if (info.available()) {
609
        String featureName = dc1394_feature_get_string(feature);
610
        System.out.println(featureName + ": " + info.min() + "-" + info.max());
611
    }
612
}
613
```
614

615
## Common Feature Usage Patterns
616

617
### Auto Exposure Setup
618

619
```java
620
// Enable auto exposure with specific target value
621
dc1394_feature_set_mode(camera, DC1394_FEATURE_EXPOSURE, DC1394_FEATURE_MODE_AUTO);
622

623
// Set brightness target for auto exposure (if supported)
624
dc1394feature_info_t brightnessInfo = features.feature(DC1394_FEATURE_BRIGHTNESS - DC1394_FEATURE_MIN);
625
if (brightnessInfo.available()) {
626
    int targetBrightness = (brightnessInfo.min() + brightnessInfo.max()) / 2;
627
    dc1394_feature_set_value(camera, DC1394_FEATURE_BRIGHTNESS, targetBrightness);
628
}
629
```
630

631
### Manual Camera Setup
632

633
```java
634
// Set all features to manual for consistent capture
635
dc1394_feature_set_mode(camera, DC1394_FEATURE_EXPOSURE, DC1394_FEATURE_MODE_MANUAL);
636
dc1394_feature_set_value(camera, DC1394_FEATURE_EXPOSURE, 400);
637

638
dc1394_feature_set_mode(camera, DC1394_FEATURE_GAIN, DC1394_FEATURE_MODE_MANUAL);
639
dc1394_feature_set_value(camera, DC1394_FEATURE_GAIN, 100);
640

641
dc1394_feature_set_mode(camera, DC1394_FEATURE_WHITE_BALANCE, DC1394_FEATURE_MODE_MANUAL);
642
dc1394_feature_whitebalance_set_value(camera, 95, 150);
643
```
644

645
### Feature Validation
646

647
```java
648
// Always check feature availability before use
649
dc1394feature_info_t shutterInfo = features.feature(DC1394_FEATURE_SHUTTER - DC1394_FEATURE_MIN);
650
if (shutterInfo.available() && shutterInfo.manual_capable()) {
651
    dc1394_feature_set_mode(camera, DC1394_FEATURE_SHUTTER, DC1394_FEATURE_MODE_MANUAL);
652
    
653
    // Set to middle of range
654
    int midValue = (shutterInfo.min() + shutterInfo.max()) / 2;
655
    dc1394_feature_set_value(camera, DC1394_FEATURE_SHUTTER, midValue);
656
} else {
657
    System.out.println("Manual shutter control not available");
658
}
659
```