0
# Video Capture
1

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

4
## Capabilities
5

6
### Capture Setup and Control
7

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

10
```java { .api }
11
/**
12
 * Sets up the capture system with DMA buffers
13
 * @param camera Camera instance
14
 * @param num_dma_buffers Number of DMA buffers to allocate (typically 4-16)
15
 * @param flags Capture flags (use DC1394_CAPTURE_FLAGS_DEFAULT)
16
 * @return DC1394_SUCCESS on success, error code on failure
17
 */
18
int dc1394_capture_setup(dc1394camera_t camera, int num_dma_buffers, int flags);
19

20
/**
21
 * Stops capture and releases DMA buffers
22
 * @param camera Camera instance
23
 * @return DC1394_SUCCESS on success, error code on failure
24
 */
25
int dc1394_capture_stop(dc1394camera_t camera);
26

27
/**
28
 * Checks if a frame is corrupted
29
 * @param frame Frame to check
30
 * @return true if frame is corrupted, false if valid
31
 */
32
boolean dc1394_capture_is_frame_corrupt(dc1394video_frame_t frame);
33
```
34

35
**Usage Example:**
36

37
```java
38
import org.bytedeco.libdc1394.*;
39
import static org.bytedeco.libdc1394.global.dc1394.*;
40

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

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

51
// Start transmission
52
dc1394_video_set_transmission(camera, DC1394_ON);
53

54
// ... perform capture operations ...
55

56
// Stop transmission and capture
57
dc1394_video_set_transmission(camera, DC1394_OFF);
58
dc1394_capture_stop(camera);
59
```
60

61
### Frame Dequeue and Enqueue
62

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

65
```java { .api }
66
/**
67
 * Retrieves a frame from the capture queue
68
 * @param camera Camera instance
69
 * @param policy Capture policy (DC1394_CAPTURE_POLICY_WAIT or DC1394_CAPTURE_POLICY_POLL)
70
 * @param frame Output frame structure to populate
71
 * @return DC1394_SUCCESS on success, error code on failure
72
 */
73
int dc1394_capture_dequeue(dc1394camera_t camera, int policy, dc1394video_frame_t frame);
74

75
/**
76
 * Returns a frame to the capture queue for reuse
77
 * @param camera Camera instance
78
 * @param frame Frame to return to queue
79
 * @return DC1394_SUCCESS on success, error code on failure
80
 */
81
int dc1394_capture_enqueue(dc1394camera_t camera, dc1394video_frame_t frame);
82
```
83

84
**Usage Example:**
85

86
```java
87
import org.bytedeco.libdc1394.*;
88
import static org.bytedeco.libdc1394.global.dc1394.*;
89

90
// Capture single frame
91
dc1394video_frame_t frame = new dc1394video_frame_t(null);
92

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

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

105
// Process frame data
106
processFrameData(frame);
107

108
// Return frame to queue
109
dc1394_capture_enqueue(camera, frame);
110
```
111

112
### Continuous Capture Loop
113

114
```java
115
// Continuous capture example
116
dc1394video_frame_t frame = new dc1394video_frame_t(null);
117
boolean capturing = true;
118

119
while (capturing) {
120
    // Poll for frame (non-blocking)
121
    int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame);
122
    
123
    if (err == DC1394_SUCCESS) {
124
        // Process frame
125
        System.out.println("Frame captured: " + frame.total_bytes() + " bytes");
126
        System.out.println("Timestamp: " + frame.timestamp());
127
        System.out.println("Size: " + frame.size(0) + "x" + frame.size(1));
128
        
129
        // Return frame immediately
130
        dc1394_capture_enqueue(camera, frame);
131
    } else if (err == DC1394_CAPTURE_POLICY_POLL) {
132
        // No frame available, continue polling
133
        try {
134
            Thread.sleep(1); // Brief pause
135
        } catch (InterruptedException e) {
136
            break;
137
        }
138
    } else {
139
        // Actual error occurred
140
        dc1394_log_error("Capture error: " + err);
141
        break;
142
    }
143
}
144
```
145

146
### Callback-based Capture
147

148
Sets up automatic callback notification when frames are available.
149

150
```java { .api }
151
/**
152
 * Sets a callback function to be called when frames are captured
153
 * @param camera Camera instance
154
 * @param callback Callback function to invoke
155
 * @param user_data User data passed to callback
156
 * @return DC1394_SUCCESS on success, error code on failure
157
 */
158
int dc1394_capture_set_callback(dc1394camera_t camera, dc1394capture_callback_t callback, 
159
                               Pointer user_data);
160
```
161

162
**Usage Example:**
163

164
```java
165
import org.bytedeco.libdc1394.*;
166
import static org.bytedeco.libdc1394.global.dc1394.*;
167

168
// Create callback implementation
169
dc1394capture_callback_t callback = new dc1394capture_callback_t() {
170
    @Override
171
    public void call(dc1394camera_t camera, Pointer user_data) {
172
        // Frame is ready - dequeue and process
173
        dc1394video_frame_t frame = new dc1394video_frame_t(null);
174
        
175
        if (dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_POLL, frame) == DC1394_SUCCESS) {
176
            System.out.println("Callback: Frame captured with timestamp " + frame.timestamp());
177
            
178
            // Process frame here...
179
            
180
            // Return frame
181
            dc1394_capture_enqueue(camera, frame);
182
        }
183
    }
184
};
185

186
// Set callback
187
dc1394_capture_set_callback(camera, callback, null);
188
```
189

190
### Video Transmission Control
191

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

194
```java { .api }
195
/**
196
 * Starts or stops video transmission
197
 * @param camera Camera instance
198
 * @param pwr Transmission state (DC1394_ON or DC1394_OFF)
199
 * @return DC1394_SUCCESS on success, error code on failure
200
 */
201
int dc1394_video_set_transmission(dc1394camera_t camera, int pwr);
202

203
/**
204
 * Gets current video transmission state
205
 * @param camera Camera instance
206
 * @param pwr Output parameter for transmission state
207
 * @return DC1394_SUCCESS on success, error code on failure
208
 */
209
int dc1394_video_get_transmission(dc1394camera_t camera, IntPointer pwr);
210
```
211

212
## Types
213

214
### Video Frame Structure
215

216
```java { .api }
217
/**
218
 * Video frame structure containing image data and comprehensive metadata
219
 */
220
class dc1394video_frame_t extends Pointer {
221
    // Image data access
222
    /**
223
     * Raw image data pointer
224
     * @return BytePointer to image data
225
     */
226
    BytePointer image();
227
    
228
    /**
229
     * Total frame size in bytes
230
     * @return Total bytes including metadata
231
     */
232
    long total_bytes();
233
    
234
    /**
235
     * Image data size in bytes
236
     * @return Image data bytes only
237
     */
238
    long image_bytes();
239
    
240
    /**
241
     * Allocated buffer size in bytes
242
     * @return Allocated buffer size
243
     */
244
    long allocated_image_bytes();
245
    
246
    // Frame dimensions
247
    /**
248
     * Frame dimensions: width (i=0) and height (i=1)
249
     * @param i Dimension index (0=width, 1=height)
250
     * @return Dimension value in pixels
251
     */
252
    int size(int i);
253
    
254
    /**
255
     * Frame position: left (i=0) and top (i=1) for Format7
256
     * @param i Position index (0=left, 1=top)
257
     * @return Position value in pixels
258
     */
259
    int _position(int i);
260
    
261
    // Format information
262
    /**
263
     * Color coding format
264
     * @return Color coding constant (DC1394_COLOR_CODING_*)
265
     */
266
    int color_coding();
267
    
268
    /**
269
     * Bayer color filter pattern for RAW formats
270
     * @return Color filter constant (DC1394_COLOR_FILTER_*)
271
     */
272
    int color_filter();
273
    
274
    /**
275
     * Video mode used for capture
276
     * @return Video mode constant (DC1394_VIDEO_MODE_*)
277
     */
278
    int video_mode();
279
    
280
    /**
281
     * Data depth in bits per pixel
282
     * @return Bits per pixel
283
     */
284
    int data_depth();
285
    
286
    /**
287
     * Bytes per line (stride)
288
     * @return Bytes per line
289
     */
290
    int stride();
291
    
292
    // Timing information
293
    /**
294
     * Frame timestamp in microseconds
295
     * @return Timestamp value
296
     */
297
    long timestamp();
298
    
299
    /**
300
     * Number of frames behind in buffer
301
     * @return Frames behind count
302
     */
303
    int frames_behind();
304
    
305
    // Format7 specific
306
    /**
307
     * Packet size for Format7 modes
308
     * @return Packet size in bytes
309
     */
310
    int packet_size();
311
    
312
    /**
313
     * Packets per frame for Format7 modes
314
     * @return Number of packets
315
     */
316
    int packets_per_frame();
317
    
318
    // Status information
319
    /**
320
     * YUV byte order
321
     * @return Byte order constant
322
     */
323
    int yuv_byte_order();
324
    
325
    /**
326
     * Padding bytes at end of line
327
     * @return Padding byte count
328
     */
329
    int padding_bytes();
330
    
331
    /**
332
     * Data byte order (little endian flag)
333
     * @return true if little endian, false if big endian
334
     */
335
    boolean little_endian();
336
    
337
    /**
338
     * Whether valid data is stored in padding area
339
     * @return true if data in padding, false otherwise
340
     */
341
    boolean data_in_padding();
342
    
343
    // Source information
344
    /**
345
     * Source camera that captured this frame
346
     * @return Camera instance
347
     */
348
    dc1394camera_t camera();
349
    
350
    /**
351
     * Frame identifier
352
     * @return Frame ID
353
     */
354
    long id();
355
}
356
```
357

358
### Abstract Frame Base Class
359

360
```java { .api }
361
/**
362
 * Abstract base class for video frames with utility methods
363
 */
364
abstract class dc1394video_frame_t_abstract extends Pointer {
365
    /**
366
     * Raw image data pointer
367
     * @return BytePointer to image data
368
     */
369
    abstract BytePointer image();
370
    
371
    /**
372
     * Total frame size in bytes
373
     * @return Total bytes
374
     */
375
    abstract long total_bytes();
376
    
377
    /**
378
     * Converts frame data to Java ByteBuffer for easier access
379
     * @return ByteBuffer view of frame data
380
     */
381
    ByteBuffer getByteBuffer() {
382
        return image().capacity((int)total_bytes()).asByteBuffer();
383
    }
384
}
385
```
386

387
### Capture Callback Interface
388

389
```java { .api }
390
/**
391
 * Callback interface for frame capture notifications
392
 */
393
abstract class dc1394capture_callback_t extends FunctionPointer {
394
    /**
395
     * Called when a frame is available for capture
396
     * @param camera Source camera
397
     * @param user_data User-provided data pointer
398
     */
399
    abstract void call(dc1394camera_t camera, Pointer user_data);
400
}
401
```
402

403
## Constants
404

405
### Capture Policies
406

407
```java { .api }
408
// Frame dequeue policies
409
static final int DC1394_CAPTURE_POLICY_WAIT = 672;  // Block until frame available
410
static final int DC1394_CAPTURE_POLICY_POLL = 673;  // Return immediately if no frame
411
```
412

413
### Capture Flags
414

415
```java { .api }
416
// Capture setup flags
417
static final int DC1394_CAPTURE_FLAGS_DEFAULT = 0;   // Use default capture settings
418
static final int DC1394_CAPTURE_FLAGS_AUTO_ISO = 1; // Auto ISO channel allocation
419
static final int DC1394_CAPTURE_FLAGS_CHANNEL_ALLOC = 2; // Auto channel allocation
420
static final int DC1394_CAPTURE_FLAGS_BANDWIDTH_ALLOC = 4; // Auto bandwidth allocation
421
```
422

423
### Transmission States
424

425
```java { .api }
426
// Video transmission control
427
static final int DC1394_ON = 1;   // Enable transmission
428
static final int DC1394_OFF = 0;  // Disable transmission
429
```
430

431
## Image Data Access
432

433
### Reading Frame Data
434

435
```java
436
// Get frame dimensions
437
int width = frame.size(0);
438
int height = frame.size(1);
439
long imageBytes = frame.image_bytes();
440

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

445
// ByteBuffer access (for easier data manipulation)
446
ByteBuffer buffer = frame.image().capacity((int)imageBytes).asByteBuffer();
447
```
448

449
### Pixel Format Information
450

451
```java
452
// Check color format
453
int colorCoding = frame.color_coding();
454
switch (colorCoding) {
455
    case DC1394_COLOR_CODING_RGB8:
456
        System.out.println("RGB 8-bit format, 3 bytes per pixel");
457
        break;
458
    case DC1394_COLOR_CODING_MONO8:
459
        System.out.println("Monochrome 8-bit format, 1 byte per pixel");
460
        break;
461
    case DC1394_COLOR_CODING_RAW8:
462
        System.out.println("Raw Bayer 8-bit format, needs debayering");
463
        int colorFilter = frame.color_filter();
464
        System.out.println("Bayer pattern: " + colorFilter);
465
        break;
466
}
467

468
// Get bit depth and stride
469
int bitsPerPixel = frame.data_depth();
470
int bytesPerLine = frame.stride();
471
```
472

473
## Performance Considerations
474

475
### Buffer Management
476

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

481
### Frame Processing
482

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

487
### Memory Access
488

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