0
# Utility Functions
1

2
Helper functions for format validation, error handling, and data conversion in libdc1394.
3

4
## Capabilities
5

6
### Image Format Utilities
7

8
Helper functions for working with video modes, color coding, and image dimensions.
9

10
```java { .api }
11
/**
12
 * Gets image dimensions from a video mode
13
 * @param camera Camera instance (or null for standard modes)
14
 * @param video_mode Video mode identifier
15
 * @param width Output parameter for image width
16
 * @param height Output parameter for image height
17
 * @return DC1394_SUCCESS on success, error code on failure
18
 */
19
int dc1394_get_image_size_from_video_mode(dc1394camera_t camera, int video_mode, 
20
                                        IntPointer width, IntPointer height);
21

22
/**
23
 * Gets the color coding associated with a video mode
24
 * @param camera Camera instance
25
 * @param video_mode Video mode identifier
26
 * @param color_coding Output parameter for color coding
27
 * @return DC1394_SUCCESS on success, error code on failure
28
 */
29
int dc1394_get_color_coding_from_video_mode(dc1394camera_t camera, int video_mode, 
30
                                          IntPointer color_coding);
31

32
/**
33
 * Gets the data depth (bits per pixel) for a color coding
34
 * @param color_coding Color coding identifier
35
 * @param bits Output parameter for bits per pixel
36
 * @return DC1394_SUCCESS on success, error code on failure
37
 */
38
int dc1394_get_color_coding_data_depth(int color_coding, IntPointer bits);
39

40
/**
41
 * Gets the bit size for a color coding
42
 * @param color_coding Color coding identifier  
43
 * @param bits Output parameter for bit size
44
 * @return DC1394_SUCCESS on success, error code on failure
45
 */
46
int dc1394_get_color_coding_bit_size(int color_coding, IntPointer bits);
47
```
48

49
**Usage Example:**
50

51
```java
52
import org.bytedeco.libdc1394.*;
53
import static org.bytedeco.libdc1394.global.dc1394.*;
54
import org.bytedeco.javacpp.IntPointer;
55

56
// Get image dimensions for a video mode
57
IntPointer width = new IntPointer(1);
58
IntPointer height = new IntPointer(1);
59
int err = dc1394_get_image_size_from_video_mode(camera, DC1394_VIDEO_MODE_640x480_RGB8, 
60
                                               width, height);
61
if (err == DC1394_SUCCESS) {
62
    System.out.println("Image size: " + width.get() + "x" + height.get());
63
}
64

65
// Get color coding information
66
IntPointer color_coding = new IntPointer(1);
67
err = dc1394_get_color_coding_from_video_mode(camera, DC1394_VIDEO_MODE_640x480_RGB8, 
68
                                             color_coding);
69
if (err == DC1394_SUCCESS) {
70
    IntPointer bits = new IntPointer(1);
71
    dc1394_get_color_coding_data_depth(color_coding.get(), bits);
72
    System.out.println("Color coding: " + color_coding.get() + ", Bits per pixel: " + bits.get());
73
}
74
```
75

76
### Video Mode Validation
77

78
Functions to validate and query video mode properties.
79

80
```java { .api }
81
/**
82
 * Checks if a video mode is scalable (Format7)
83
 * @param video_mode Video mode identifier
84
 * @return true if mode is scalable, false otherwise
85
 */
86
boolean dc1394_is_video_mode_scalable(int video_mode);
87

88
/**
89
 * Checks if a video mode is for still image capture
90
 * @param video_mode Video mode identifier
91
 * @return true if mode is for still images, false for video
92
 */
93
boolean dc1394_is_video_mode_still_image(int video_mode);
94

95
/**
96
 * Checks if a color mode represents color data (vs monochrome)
97
 * @param color_mode Color coding identifier
98
 * @param is_color Output parameter: true if color, false if monochrome
99
 * @return DC1394_SUCCESS on success, error code on failure
100
 */
101
int dc1394_is_color(int color_mode, IntPointer is_color);
102
```
103

104
**Usage Example:**
105

106
```java
107
import org.bytedeco.libdc1394.*;
108
import static org.bytedeco.libdc1394.global.dc1394.*;
109
import org.bytedeco.javacpp.IntPointer;
110

111
// Check video mode properties
112
int video_mode = DC1394_VIDEO_MODE_FORMAT7_0;
113
if (dc1394_is_video_mode_scalable(video_mode)) {
114
    System.out.println("This is a scalable (Format7) video mode");
115
}
116

117
if (dc1394_is_video_mode_still_image(video_mode)) {
118
    System.out.println("This mode is for still image capture");
119
} else {
120
    System.out.println("This mode is for video capture");
121
}
122

123
// Check if color coding represents color data
124
IntPointer is_color = new IntPointer(1);
125
int err = dc1394_is_color(DC1394_COLOR_CODING_RGB8, is_color);
126
if (err == DC1394_SUCCESS) {
127
    if (is_color.get() != 0) {
128
        System.out.println("RGB8 is a color format");
129
    } else {
130
        System.out.println("RGB8 is a monochrome format");
131
    }
132
}
133
```
134

135
### Framerate Conversion
136

137
Convert between framerate enumerations and floating-point values.
138

139
```java { .api }
140
/**
141
 * Converts a framerate enumeration to floating-point frames per second
142
 * @param framerate_enum Framerate identifier (DC1394_FRAMERATE_*)
143
 * @param framerate Output parameter for framerate as float
144
 * @return DC1394_SUCCESS on success, error code on failure
145
 */
146
int dc1394_framerate_as_float(int framerate_enum, FloatPointer framerate);
147
```
148

149
**Usage Example:**
150

151
```java
152
import org.bytedeco.libdc1394.*;
153
import static org.bytedeco.libdc1394.global.dc1394.*;
154
import org.bytedeco.javacpp.FloatPointer;
155

156
// Convert framerate enum to float
157
FloatPointer fps = new FloatPointer(1);
158
int err = dc1394_framerate_as_float(DC1394_FRAMERATE_30, fps);
159
if (err == DC1394_SUCCESS) {
160
    System.out.println("Framerate: " + fps.get() + " fps");
161
}
162

163
// Convert all supported framerates
164
int[] framerates = {
165
    DC1394_FRAMERATE_1_875, DC1394_FRAMERATE_3_75, DC1394_FRAMERATE_7_5,
166
    DC1394_FRAMERATE_15, DC1394_FRAMERATE_30, DC1394_FRAMERATE_60,
167
    DC1394_FRAMERATE_120, DC1394_FRAMERATE_240
168
};
169

170
System.out.println("Supported framerates:");
171
for (int framerate : framerates) {
172
    FloatPointer rate = new FloatPointer(1);
173
    if (dc1394_framerate_as_float(framerate, rate) == DC1394_SUCCESS) {
174
        System.out.println("  " + framerate + " -> " + rate.get() + " fps");
175
    }
176
}
177
```
178

179
### Camera Comparison
180

181
Utility functions for comparing camera instances and identifiers.
182

183
```java { .api }
184
/**
185
 * Checks if two camera identifiers refer to the same physical camera
186
 * @param id1 First camera identifier
187
 * @param id2 Second camera identifier  
188
 * @return true if cameras are the same, false otherwise
189
 */
190
boolean dc1394_is_same_camera(dc1394camera_id_t id1, dc1394camera_id_t id2);
191
```
192

193
**Usage Example:**
194

195
```java
196
import org.bytedeco.libdc1394.*;
197
import static org.bytedeco.libdc1394.global.dc1394.*;
198

199
// Compare camera identifiers
200
dc1394camera_list_t list = new dc1394camera_list_t();
201
dc1394_camera_enumerate(d, list);
202

203
if (list.num() >= 2) {
204
    dc1394camera_id_t id1 = list.ids().position(0);
205
    dc1394camera_id_t id2 = list.ids().position(1);
206
    
207
    if (dc1394_is_same_camera(id1, id2)) {
208
        System.out.println("Both IDs refer to the same camera");
209
    } else {
210
        System.out.println("Different cameras detected");
211
        System.out.println("Camera 1 GUID: " + Long.toHexString(id1.guid()));
212
        System.out.println("Camera 2 GUID: " + Long.toHexString(id2.guid()));
213
    }
214
}
215
```
216

217
### String Conversion Utilities
218

219
Get human-readable strings for error codes and feature identifiers.
220

221
```java { .api }
222
/**
223
 * Gets a human-readable string for a feature identifier
224
 * @param feature Feature identifier (DC1394_FEATURE_*)
225
 * @return String representation of the feature name
226
 */
227
BytePointer dc1394_feature_get_string(int feature);
228

229
/**
230
 * Gets a human-readable string for an error code
231
 * @param error Error code returned by libdc1394 functions
232
 * @return String representation of the error
233
 */
234
BytePointer dc1394_error_get_string(int error);
235
```
236

237
**Usage Example:**
238

239
```java
240
import org.bytedeco.libdc1394.*;
241
import static org.bytedeco.libdc1394.global.dc1394.*;
242

243
// Get feature name string
244
BytePointer feature_name = dc1394_feature_get_string(DC1394_FEATURE_BRIGHTNESS);
245
System.out.println("Feature name: " + feature_name.getString());
246

247
// Get error description
248
int err = dc1394_video_set_mode(camera, invalid_mode);
249
if (err != DC1394_SUCCESS) {
250
    BytePointer error_desc = dc1394_error_get_string(err);
251
    System.err.println("Error: " + error_desc.getString());
252
}
253

254
// Print all feature names
255
int[] features = {
256
    DC1394_FEATURE_BRIGHTNESS, DC1394_FEATURE_EXPOSURE, DC1394_FEATURE_SHARPNESS,
257
    DC1394_FEATURE_WHITE_BALANCE, DC1394_FEATURE_HUE, DC1394_FEATURE_SATURATION,
258
    DC1394_FEATURE_GAMMA, DC1394_FEATURE_SHUTTER, DC1394_FEATURE_GAIN,
259
    DC1394_FEATURE_IRIS, DC1394_FEATURE_FOCUS, DC1394_FEATURE_TEMPERATURE
260
};
261

262
System.out.println("Available features:");
263
for (int feature : features) {
264
    BytePointer name = dc1394_feature_get_string(feature);
265
    System.out.println("  " + feature + ": " + name.getString());
266
}
267
```
268

269
### Data Integrity
270

271
CRC checksum calculation for data validation.
272

273
```java { .api }
274
/**
275
 * Calculates CRC16 checksum of a data buffer
276
 * @param buffer Data buffer to checksum
277
 * @param buffer_size Size of buffer in bytes
278
 * @return CRC16 checksum value
279
 */
280
short dc1394_checksum_crc16(BytePointer buffer, int buffer_size);
281
```
282

283
**Usage Example:**
284

285
```java
286
import org.bytedeco.libdc1394.*;
287
import static org.bytedeco.libdc1394.global.dc1394.*;
288
import org.bytedeco.javacpp.BytePointer;
289

290
// Calculate checksum of frame data
291
dc1394video_frame_t frame = new dc1394video_frame_t();
292
// ... capture frame
293

294
BytePointer image_data = frame.image();
295
int image_size = (int)frame.image_bytes();
296
short crc = dc1394_checksum_crc16(image_data, image_size);
297

298
System.out.println("Frame CRC16: 0x" + Integer.toHexString(crc & 0xFFFF));
299

300
// Validate data integrity by comparing checksums
301
short expected_crc = calculateExpectedCRC(); // Your validation logic
302
if (crc == expected_crc) {
303
    System.out.println("Frame data integrity verified");
304
} else {
305
    System.err.println("Frame data corruption detected!");
306
}
307
```
308

309
## Comprehensive Format Validation Example
310

311
Here's a complete example showing how to use utility functions for robust format validation:
312

313
```java
314
import org.bytedeco.libdc1394.*;
315
import static org.bytedeco.libdc1394.global.dc1394.*;
316
import org.bytedeco.javacpp.*;
317

318
public class FormatValidator {
319
    
320
    public static boolean validateVideoMode(dc1394camera_t camera, int video_mode) {
321
        try {
322
            // Check if video mode is valid
323
            IntPointer width = new IntPointer(1);
324
            IntPointer height = new IntPointer(1);
325
            int err = dc1394_get_image_size_from_video_mode(camera, video_mode, width, height);
326
            if (err != DC1394_SUCCESS) {
327
                System.err.println("Invalid video mode: " + video_mode);
328
                return false;
329
            }
330
            
331
            // Get color coding
332
            IntPointer color_coding = new IntPointer(1);
333
            err = dc1394_get_color_coding_from_video_mode(camera, video_mode, color_coding);
334
            if (err != DC1394_SUCCESS) {
335
                System.err.println("Could not get color coding for video mode: " + video_mode);
336
                return false;
337
            }
338
            
339
            // Check if it's a color or monochrome mode
340
            IntPointer is_color = new IntPointer(1);
341
            dc1394_is_color(color_coding.get(), is_color);
342
            
343
            // Get bit depth
344
            IntPointer bits = new IntPointer(1);
345
            dc1394_get_color_coding_data_depth(color_coding.get(), bits);
346
            
347
            // Print validation results
348
            System.out.println("Video Mode Validation Results:");
349
            System.out.println("  Mode: " + video_mode);
350
            System.out.println("  Dimensions: " + width.get() + "x" + height.get());
351
            System.out.println("  Color Coding: " + color_coding.get());
352
            System.out.println("  Type: " + (is_color.get() != 0 ? "Color" : "Monochrome"));
353
            System.out.println("  Bits per pixel: " + bits.get());
354
            System.out.println("  Scalable: " + dc1394_is_video_mode_scalable(video_mode));
355
            System.out.println("  Still image: " + dc1394_is_video_mode_still_image(video_mode));
356
            
357
            return true;
358
            
359
        } catch (Exception e) {
360
            System.err.println("Exception during video mode validation: " + e.getMessage());
361
            return false;
362
        }
363
    }
364
    
365
    public static void printFramerateInfo(int framerate_enum) {
366
        FloatPointer fps = new FloatPointer(1);
367
        int err = dc1394_framerate_as_float(framerate_enum, fps);
368
        if (err == DC1394_SUCCESS) {
369
            System.out.println("Framerate " + framerate_enum + ": " + fps.get() + " fps");
370
        } else {
371
            System.err.println("Invalid framerate enum: " + framerate_enum);
372
        }
373
    }
374
}
375
```
376

377
This utility functions documentation provides comprehensive coverage of the helper functions that make working with libdc1394 more convenient and robust.