0
# Format7 Support
1

2
Advanced scalable format support allowing custom image sizes, positions, and region of interest (ROI) configuration for libdc1394.
3

4
## Capabilities
5

6
### Format7 Mode Discovery
7

8
Discovers available Format7 modes and their capabilities.
9

10
```java { .api }
11
/**
12
 * Gets information about all Format7 modes
13
 * @param camera Camera instance
14
 * @param modeset Output structure containing all Format7 modes
15
 * @return DC1394_SUCCESS on success, error code on failure
16
 */
17
int dc1394_format7_get_modeset(dc1394camera_t camera, dc1394format7modeset_t modeset);
18

19
/**
20
 * Gets information about a specific Format7 mode
21
 * @param camera Camera instance
22
 * @param mode Format7 mode number (0-7)
23
 * @param mode_info Output structure for mode information
24
 * @return DC1394_SUCCESS on success, error code on failure
25
 */
26
int dc1394_format7_get_mode_info(dc1394camera_t camera, int mode, dc1394format7mode_t mode_info);
27

28
/**
29
 * Gets supported color codings for a Format7 mode
30
 * @param camera Camera instance
31
 * @param mode Format7 mode number
32
 * @param codings Output structure containing supported color codings
33
 * @return DC1394_SUCCESS on success, error code on failure
34
 */
35
int dc1394_format7_get_color_codings(dc1394camera_t camera, int mode, dc1394color_codings_t codings);
36
```
37

38
**Usage Example:**
39

40
```java
41
import org.bytedeco.libdc1394.*;
42
import static org.bytedeco.libdc1394.global.dc1394.*;
43

44
// Get all Format7 mode information
45
dc1394format7modeset_t modeset = new dc1394format7modeset_t();
46
int err = dc1394_format7_get_modeset(camera, modeset);
47
if (err != DC1394_SUCCESS) {
48
    dc1394_log_error("Failed to get Format7 modeset: " + err);
49
    return;
50
}
51

52
// Check each Format7 mode
53
for (int i = 0; i < 8; i++) {
54
    dc1394format7mode_t mode = modeset.mode(i);
55
    if (mode.present()) {
56
        System.out.println("Format7 Mode " + i + ":");
57
        System.out.println("  Max size: " + mode.max_size_x() + "x" + mode.max_size_y());
58
        System.out.println("  Unit size: " + mode.unit_size_x() + "x" + mode.unit_size_y());
59
        System.out.println("  Pixel unit: " + mode.unit_pos_x() + "x" + mode.unit_pos_y());
60
        
61
        // Get supported color codings
62
        dc1394color_codings_t codings = new dc1394color_codings_t();
63
        dc1394_format7_get_color_codings(camera, i, codings);
64
        System.out.println("  Color codings: " + codings.num());
65
    }
66
}
67
```
68

69
### Image Size and Position Control
70

71
Controls the image size and position within the sensor area.
72

73
```java { .api }
74
/**
75
 * Gets the maximum image size for a Format7 mode
76
 * @param camera Camera instance
77
 * @param mode Format7 mode number
78
 * @param h_size Output parameter for maximum width
79
 * @param v_size Output parameter for maximum height
80
 * @return DC1394_SUCCESS on success, error code on failure
81
 */
82
int dc1394_format7_get_max_image_size(dc1394camera_t camera, int mode, 
83
                                     IntPointer h_size, IntPointer v_size);
84

85
/**
86
 * Sets the image size for a Format7 mode
87
 * @param camera Camera instance
88
 * @param mode Format7 mode number
89
 * @param width Image width in pixels
90
 * @param height Image height in pixels
91
 * @return DC1394_SUCCESS on success, error code on failure
92
 */
93
int dc1394_format7_set_image_size(dc1394camera_t camera, int mode, int width, int height);
94

95
/**
96
 * Gets the current image size
97
 * @param camera Camera instance
98
 * @param mode Format7 mode number
99
 * @param width Output parameter for current width
100
 * @param height Output parameter for current height
101
 * @return DC1394_SUCCESS on success, error code on failure
102
 */
103
int dc1394_format7_get_image_size(dc1394camera_t camera, int mode, 
104
                                 IntPointer width, IntPointer height);
105

106
/**
107
 * Sets the image position (top-left corner) within the sensor
108
 * @param camera Camera instance
109
 * @param mode Format7 mode number
110
 * @param left Left position in pixels
111
 * @param top Top position in pixels
112
 * @return DC1394_SUCCESS on success, error code on failure
113
 */
114
int dc1394_format7_set_image_position(dc1394camera_t camera, int mode, int left, int top);
115

116
/**
117
 * Gets the current image position
118
 * @param camera Camera instance
119
 * @param mode Format7 mode number
120
 * @param left Output parameter for left position
121
 * @param top Output parameter for top position
122
 * @return DC1394_SUCCESS on success, error code on failure
123
 */
124
int dc1394_format7_get_image_position(dc1394camera_t camera, int mode, 
125
                                     IntPointer left, IntPointer top);
126
```
127

128
**Usage Example:**
129

130
```java
131
// Set custom image size for Format7 Mode 0
132
int mode = 0;
133

134
// Get maximum size first
135
IntPointer maxWidth = new IntPointer(1);
136
IntPointer maxHeight = new IntPointer(1);
137
dc1394_format7_get_max_image_size(camera, mode, maxWidth, maxHeight);
138
System.out.println("Max size: " + maxWidth.get() + "x" + maxHeight.get());
139

140
// Set image size to half maximum
141
int width = maxWidth.get() / 2;
142
int height = maxHeight.get() / 2;
143
int err = dc1394_format7_set_image_size(camera, mode, width, height);
144
if (err != DC1394_SUCCESS) {
145
    dc1394_log_error("Failed to set image size: " + err);
146
}
147

148
// Center the image on sensor
149
int left = (maxWidth.get() - width) / 2;
150
int top = (maxHeight.get() - height) / 2;
151
dc1394_format7_set_image_position(camera, mode, left, top);
152
```
153

154
### Color Coding Control
155

156
Controls the pixel format for Format7 modes.
157

158
```java { .api }
159
/**
160
 * Sets the color coding for a Format7 mode
161
 * @param camera Camera instance
162
 * @param mode Format7 mode number
163
 * @param color_coding Color coding constant (DC1394_COLOR_CODING_*)
164
 * @return DC1394_SUCCESS on success, error code on failure
165
 */
166
int dc1394_format7_set_color_coding(dc1394camera_t camera, int mode, int color_coding);
167

168
/**
169
 * Gets the current color coding
170
 * @param camera Camera instance
171
 * @param mode Format7 mode number
172
 * @param color_coding Output parameter for current color coding
173
 * @return DC1394_SUCCESS on success, error code on failure
174
 */
175
int dc1394_format7_get_color_coding(dc1394camera_t camera, int mode, IntPointer color_coding);
176

177
/**
178
 * Gets the color filter pattern for RAW color codings
179
 * @param camera Camera instance
180
 * @param mode Format7 mode number
181
 * @param color_filter Output parameter for color filter pattern
182
 * @return DC1394_SUCCESS on success, error code on failure
183
 */
184
int dc1394_format7_get_color_filter(dc1394camera_t camera, int mode, IntPointer color_filter);
185
```
186

187
### Packet Size Control
188

189
Controls packet size for optimal bandwidth utilization.
190

191
```java { .api }
192
/**
193
 * Gets recommended packet size for current Format7 configuration
194
 * @param camera Camera instance
195
 * @param mode Format7 mode number
196
 * @param packet_size Output parameter for recommended packet size
197
 * @return DC1394_SUCCESS on success, error code on failure
198
 */
199
int dc1394_format7_get_recommended_packet_size(dc1394camera_t camera, int mode, 
200
                                              IntPointer packet_size);
201

202
/**
203
 * Gets packet size unit (minimum increment)
204
 * @param camera Camera instance
205
 * @param mode Format7 mode number
206
 * @param unit_bytes Output parameter for packet size unit
207
 * @return DC1394_SUCCESS on success, error code on failure
208
 */
209
int dc1394_format7_get_unit_size_and_position(dc1394camera_t camera, int mode,
210
                                             IntPointer unit_x, IntPointer unit_y,
211
                                             IntPointer unit_pos_x, IntPointer unit_pos_y);
212

213
/**
214
 * Sets the packet size for a Format7 mode
215
 * @param camera Camera instance
216
 * @param mode Format7 mode number
217
 * @param packet_size Packet size in bytes (must be multiple of unit)
218
 * @return DC1394_SUCCESS on success, error code on failure
219
 */
220
int dc1394_format7_set_packet_size(dc1394camera_t camera, int mode, int packet_size);
221

222
/**
223
 * Gets the current packet size
224
 * @param camera Camera instance
225
 * @param mode Format7 mode number
226
 * @param packet_size Output parameter for current packet size
227
 * @return DC1394_SUCCESS on success, error code on failure
228
 */
229
int dc1394_format7_get_packet_size(dc1394camera_t camera, int mode, IntPointer packet_size);
230
```
231

232
**Usage Example:**
233

234
```java
235
// Set color coding to RGB8
236
int err = dc1394_format7_set_color_coding(camera, mode, DC1394_COLOR_CODING_RGB8);
237
if (err != DC1394_SUCCESS) {
238
    dc1394_log_error("Failed to set color coding: " + err);
239
}
240

241
// Get and set recommended packet size
242
IntPointer packetSize = new IntPointer(1);
243
dc1394_format7_get_recommended_packet_size(camera, mode, packetSize);
244
System.out.println("Recommended packet size: " + packetSize.get());
245

246
dc1394_format7_set_packet_size(camera, mode, packetSize.get());
247
```
248

249
### Region of Interest (ROI) Control
250

251
Convenient function to set up complete ROI configuration.
252

253
```java { .api }
254
/**
255
 * Sets up complete Region of Interest configuration
256
 * @param camera Camera instance
257
 * @param mode Format7 mode number
258
 * @param color_coding Color coding to use
259
 * @param packet_size Packet size (use DC1394_USE_RECOMMENDED for automatic)
260
 * @param left Left position of ROI
261
 * @param top Top position of ROI
262
 * @param width Width of ROI
263
 * @param height Height of ROI
264
 * @return DC1394_SUCCESS on success, error code on failure
265
 */
266
int dc1394_format7_set_roi(dc1394camera_t camera, int mode, int color_coding, int packet_size,
267
                          int left, int top, int width, int height);
268

269
/**
270
 * Gets the current ROI configuration
271
 * @param camera Camera instance
272
 * @param mode Format7 mode number
273
 * @param color_coding Output parameter for color coding
274
 * @param packet_size Output parameter for packet size
275
 * @param left Output parameter for left position
276
 * @param top Output parameter for top position
277
 * @param width Output parameter for width
278
 * @param height Output parameter for height
279
 * @return DC1394_SUCCESS on success, error code on failure
280
 */
281
int dc1394_format7_get_roi(dc1394camera_t camera, int mode, IntPointer color_coding, 
282
                          IntPointer packet_size, IntPointer left, IntPointer top,
283
                          IntPointer width, IntPointer height);
284
```
285

286
**Usage Example:**
287

288
```java
289
// Set up ROI for center 800x600 region with RGB8 format
290
int mode = 0;
291
int err = dc1394_format7_set_roi(camera, mode, 
292
                                DC1394_COLOR_CODING_RGB8,    // Color format
293
                                DC1394_USE_RECOMMENDED,      // Auto packet size
294
                                200, 150,                    // Position (left, top)
295
                                800, 600);                   // Size (width, height)
296

297
if (err != DC1394_SUCCESS) {
298
    dc1394_log_error("Failed to set ROI: " + err);
299
} else {
300
    System.out.println("ROI configured successfully");
301
}
302

303
// Switch to this Format7 mode
304
dc1394_video_set_mode(camera, DC1394_VIDEO_MODE_FORMAT7_0 + mode);
305
```
306

307
### Bandwidth and Timing
308

309
Gets timing information for Format7 configurations.
310

311
```java { .api }
312
/**
313
 * Gets data rate for current Format7 configuration
314
 * @param camera Camera instance
315
 * @param mode Format7 mode number
316
 * @param data_rate Output parameter for data rate in bytes/second
317
 * @return DC1394_SUCCESS on success, error code on failure
318
 */
319
int dc1394_format7_get_data_depth(dc1394camera_t camera, int mode, IntPointer data_depth);
320

321
/**
322
 * Gets frame interval for Format7 mode
323
 * @param camera Camera instance
324
 * @param mode Format7 mode number
325
 * @param interval Output parameter for frame interval in microseconds
326
 * @return DC1394_SUCCESS on success, error code on failure
327
 */
328
int dc1394_format7_get_frame_interval(dc1394camera_t camera, int mode, FloatPointer interval);
329
```
330

331
## Types
332

333
### Format7 Mode Information
334

335
```java { .api }
336
/**
337
 * Comprehensive Format7 mode information structure (19 fields)
338
 */
339
class dc1394format7mode_t extends Pointer {
340
    /**
341
     * Mode availability
342
     * @return true if mode is present/supported, false otherwise
343
     */
344
    boolean present();
345
    
346
    /**
347
     * Maximum image width for this mode
348
     * @return Maximum width in pixels
349
     */
350
    int max_size_x();
351
    
352
    /**
353
     * Maximum image height for this mode
354
     * @return Maximum height in pixels
355
     */
356
    int max_size_y();
357
    
358
    /**
359
     * Width increment unit (image width must be multiple of this)
360
     * @return Width unit in pixels
361
     */
362
    int unit_size_x();
363
    
364
    /**
365
     * Height increment unit (image height must be multiple of this)
366
     * @return Height unit in pixels
367
     */
368
    int unit_size_y();
369
    
370
    /**
371
     * Horizontal position unit (left position must be multiple of this)
372
     * @return Position unit in pixels
373
     */
374
    int unit_pos_x();
375
    
376
    /**
377
     * Vertical position unit (top position must be multiple of this)
378
     * @return Position unit in pixels
379
     */
380
    int unit_pos_y();
381
    
382
    /**
383
     * Current image width
384
     * @return Current width in pixels
385
     */
386
    int size_x();
387
    
388
    /**
389
     * Current image height
390
     * @return Current height in pixels
391
     */
392
    int size_y();
393
    
394
    /**
395
     * Current horizontal position
396
     * @return Current left position in pixels
397
     */
398
    int pos_x();
399
    
400
    /**
401
     * Current vertical position
402
     * @return Current top position in pixels
403
     */
404
    int pos_y();
405
    
406
    /**
407
     * Current color coding
408
     * @return Color coding constant
409
     */
410
    int color_coding();
411
    
412
    /**
413
     * Color filter pattern for RAW formats
414
     * @return Color filter constant
415
     */
416
    int color_filter();
417
    
418
    /**
419
     * Current packet size
420
     * @return Packet size in bytes
421
     */
422
    int packet_size();
423
    
424
    /**
425
     * Packet size per unit
426
     * @return Bytes per packet unit
427
     */
428
    int packet_size_per_unit();
429
    
430
    /**
431
     * Recommended packet size
432
     * @return Recommended packet size in bytes
433
     */
434
    int packet_size_recommended();
435
    
436
    /**
437
     * Maximum packet size
438
     * @return Maximum packet size in bytes
439
     */
440
    int packet_size_max();
441
    
442
    /**
443
     * Data depth in bits per pixel
444
     * @return Bits per pixel
445
     */
446
    int data_depth();
447
    
448
    /**
449
     * Bytes per packet
450
     * @return Bytes per packet
451
     */
452
    int pixnum_per_packet();
453
}
454
```
455

456
### Format7 Mode Set
457

458
```java { .api }
459
/**
460
 * Container for all Format7 modes (0-7)
461
 */
462
class dc1394format7modeset_t extends Pointer {
463
    /**
464
     * Access individual Format7 mode information
465
     * @param i Mode number (0-7)
466
     * @return Format7 mode information structure
467
     */
468
    dc1394format7mode_t mode(int i);
469
}
470
```
471

472
## Constants
473

474
### Format7 Special Values
475

476
```java { .api }
477
// Special values for Format7 configuration
478
static final int DC1394_QUERY_FROM_CAMERA = Integer.MAX_VALUE;    // Query value from camera
479
static final int DC1394_USE_MAX_AVAIL = 0;                       // Use maximum available
480
static final int DC1394_USE_RECOMMENDED = -1;                     // Use recommended value
481
```
482

483
### Format7 Mode Numbers
484

485
```java { .api }
486
// Format7 mode identifiers (0-7)
487
static final int DC1394_FORMAT7_MODE_0 = 0;
488
static final int DC1394_FORMAT7_MODE_1 = 1;
489
static final int DC1394_FORMAT7_MODE_2 = 2;
490
static final int DC1394_FORMAT7_MODE_3 = 3;
491
static final int DC1394_FORMAT7_MODE_4 = 4;
492
static final int DC1394_FORMAT7_MODE_5 = 5;
493
static final int DC1394_FORMAT7_MODE_6 = 6;
494
static final int DC1394_FORMAT7_MODE_7 = 7;
495
```
496

497
## Advanced Format7 Usage
498

499
### Multi-ROI Configuration
500

501
```java
502
// Configure multiple ROIs for different applications
503
void configureMultiROI(dc1394camera_t camera) {
504
    // High-speed small ROI for tracking
505
    dc1394_format7_set_roi(camera, 0, 
506
                          DC1394_COLOR_CODING_MONO8,     // Fast monochrome
507
                          DC1394_USE_RECOMMENDED,
508
                          400, 300, 200, 200);           // 200x200 center region
509
    
510
    // High-quality large ROI for imaging
511
    dc1394_format7_set_roi(camera, 1,
512
                          DC1394_COLOR_CODING_RGB8,      // Full color
513
                          DC1394_USE_RECOMMENDED,
514
                          100, 100, 1000, 800);         // Large region
515
    
516
    // RAW capture for scientific imaging
517
    dc1394_format7_set_roi(camera, 2,
518
                          DC1394_COLOR_CODING_RAW8,      // Bayer pattern
519
                          DC1394_USE_MAX_AVAIL,          // Maximum packet size
520
                          0, 0, 1600, 1200);            // Full sensor
521
}
522
```
523

524
### Dynamic ROI Adjustment
525

526
```java
527
// Adjust ROI during capture for tracking applications
528
void adjustROIForTracking(dc1394camera_t camera, int mode, int targetX, int targetY) {
529
    // Get mode constraints
530
    dc1394format7mode_t modeInfo = new dc1394format7mode_t();
531
    dc1394_format7_get_mode_info(camera, mode, modeInfo);
532
    
533
    // Calculate new ROI centered on target
534
    int roiSize = 400;  // 400x400 tracking window
535
    
536
    // Ensure alignment with unit constraints
537
    int unitX = modeInfo.unit_pos_x();
538
    int unitY = modeInfo.unit_pos_y();
539
    
540
    int left = ((targetX - roiSize/2) / unitX) * unitX;
541
    int top = ((targetY - roiSize/2) / unitY) * unitY;
542
    
543
    // Clamp to sensor bounds
544
    left = Math.max(0, Math.min(left, modeInfo.max_size_x() - roiSize));
545
    top = Math.max(0, Math.min(top, modeInfo.max_size_y() - roiSize));
546
    
547
    // Update ROI
548
    dc1394_format7_set_image_position(camera, mode, left, top);
549
    dc1394_format7_set_image_size(camera, mode, roiSize, roiSize);
550
}
551
```
552

553
### Optimal Bandwidth Usage
554

555
```java
556
// Calculate and set optimal packet size for bandwidth
557
void optimizePacketSize(dc1394camera_t camera, int mode) {
558
    // Get current configuration
559
    IntPointer width = new IntPointer(1);
560
    IntPointer height = new IntPointer(1);
561
    IntPointer colorCoding = new IntPointer(1);
562
    
563
    dc1394_format7_get_image_size(camera, mode, width, height);
564
    dc1394_format7_get_color_coding(camera, mode, colorCoding);
565
    
566
    // Calculate data per frame
567
    int bytesPerPixel = dc1394_get_color_coding_data_depth(colorCoding.get()) / 8;
568
    long frameBytes = width.get() * height.get() * bytesPerPixel;
569
    
570
    // Get packet constraints
571
    dc1394format7mode_t modeInfo = new dc1394format7mode_t();
572
    dc1394_format7_get_mode_info(camera, mode, modeInfo);
573
    
574
    int packetUnit = modeInfo.packet_size_per_unit();
575
    int maxPacket = modeInfo.packet_size_max();
576
    
577
    // Calculate optimal packet size (balance between latency and efficiency)
578
    int optimalPacket = (int)Math.min(maxPacket, frameBytes / 50); // ~50 packets per frame
579
    optimalPacket = (optimalPacket / packetUnit) * packetUnit;     // Align to unit
580
    
581
    if (optimalPacket > 0) {
582
        dc1394_format7_set_packet_size(camera, mode, optimalPacket);
583
        System.out.println("Set packet size to " + optimalPacket + " bytes");
584
    }
585
}
586
```
587

588
## Format7 Best Practices
589

590
### Mode Selection
591

592
- **Mode 0**: Often highest resolution, good for general imaging
593
- **Mode 1**: May offer different aspect ratio or color format options
594
- **Mode 7**: Often optimized for specific sensor regions or speeds
595

596
### ROI Alignment
597

598
- Always respect unit size constraints (`unit_size_x`, `unit_size_y`)
599
- Position must be aligned to `unit_pos_x` and `unit_pos_y`
600
- Check constraints before setting ROI to avoid errors
601

602
### Performance Optimization
603

604
- Smaller ROIs = higher possible framerates
605
- Monochrome formats process faster than color
606
- RAW formats require post-processing but offer best quality
607
- Balance packet size: too small = overhead, too large = latency
608

609
### Error Handling
610

611
```java
612
// Always validate Format7 parameters before use
613
boolean validateFormat7ROI(dc1394camera_t camera, int mode, int left, int top, int width, int height) {
614
    dc1394format7mode_t modeInfo = new dc1394format7mode_t();
615
    if (dc1394_format7_get_mode_info(camera, mode, modeInfo) != DC1394_SUCCESS) {
616
        return false;
617
    }
618
    
619
    if (!modeInfo.present()) {
620
        System.err.println("Format7 mode " + mode + " not available");
621
        return false;
622
    }
623
    
624
    // Check size constraints
625
    if (width % modeInfo.unit_size_x() != 0 || height % modeInfo.unit_size_y() != 0) {
626
        System.err.println("Size not aligned to unit constraints");
627
        return false;
628
    }
629
    
630
    // Check position constraints
631
    if (left % modeInfo.unit_pos_x() != 0 || top % modeInfo.unit_pos_y() != 0) {
632
        System.err.println("Position not aligned to unit constraints");
633
        return false;
634
    }
635
    
636
    // Check bounds
637
    if (left + width > modeInfo.max_size_x() || top + height > modeInfo.max_size_y()) {
638
        System.err.println("ROI exceeds sensor bounds");
639
        return false;
640
    }
641
    
642
    return true;
643
}
644
```