0
# System Management
1

2
Core system initialization, camera discovery, and resource management functionality for libdc1394.
3

4
## Capabilities
5

6
### System Context Management
7

8
Creates and manages the main libdc1394 system context required for all operations.
9

10
```java { .api }
11
/**
12
 * Creates a new libdc1394 system context
13
 * @return System context handle, or null on failure
14
 */
15
dc1394_t dc1394_new();
16

17
/**
18
 * Releases the libdc1394 system context and associated resources
19
 * @param d System context to release
20
 */
21
void dc1394_free(dc1394_t d);
22

23
/**
24
 * Resets the IEEE 1394 bus
25
 * @param camera Camera connected to the bus to reset
26
 * @return DC1394_SUCCESS on success, error code on failure
27
 */
28
int dc1394_reset_bus(dc1394camera_t camera);
29
```
30

31
**Usage Example:**
32

33
```java
34
import static org.bytedeco.libdc1394.global.dc1394.*;
35

36
// Initialize system
37
dc1394_t d = dc1394_new();
38
if (d == null) {
39
    System.err.println("Failed to initialize libdc1394");
40
    System.exit(1);
41
}
42

43
// Use system context for camera operations...
44

45
// Always release resources
46
dc1394_free(d);
47
```
48

49
### Camera Discovery
50

51
Discovers and enumerates available IEEE 1394 cameras on the system.
52

53
```java { .api }
54
/**
55
 * Enumerates all available cameras on the IEEE 1394 bus
56
 * @param d System context
57
 * @param list Output camera list structure
58
 * @return DC1394_SUCCESS on success, error code on failure
59
 */
60
int dc1394_camera_enumerate(dc1394_t d, dc1394camera_list_t list);
61

62
/**
63
 * Releases camera list resources
64
 * @param list Camera list to release
65
 */
66
void dc1394_camera_free_list(dc1394camera_list_t list);
67

68
/**
69
 * Prints information about a camera
70
 * @param camera Camera to print information for
71
 * @return DC1394_SUCCESS on success, error code on failure
72
 */
73
int dc1394_camera_print_info(dc1394camera_t camera);
74
```
75

76
**Usage Example:**
77

78
```java
79
import org.bytedeco.libdc1394.*;
80
import static org.bytedeco.libdc1394.global.dc1394.*;
81

82
dc1394_t d = dc1394_new();
83
dc1394camera_list_t list = new dc1394camera_list_t();
84

85
// Discover cameras
86
int err = dc1394_camera_enumerate(d, list);
87
if (err != DC1394_SUCCESS) {
88
    dc1394_log_error("Failed to enumerate cameras: " + err);
89
    dc1394_free(d);
90
    return;
91
}
92

93
System.out.println("Found " + list.num() + " cameras");
94

95
// Iterate through discovered cameras
96
for (int i = 0; i < list.num(); i++) {
97
    dc1394camera_id_t id = list.ids().position(i);
98
    System.out.println("Camera " + i + ": GUID=" + 
99
                      Long.toHexString(id.guid()) + ", Unit=" + id.unit());
100
}
101

102
// Always free the list
103
dc1394_camera_free_list(list);
104
dc1394_free(d);
105
```
106

107
### Camera Instantiation
108

109
Creates and manages individual camera instances for control and capture operations.
110

111
```java { .api }
112
/**
113
 * Creates a new camera instance using the camera's GUID
114
 * @param d System context
115
 * @param guid Camera GUID obtained from enumeration
116
 * @return Camera instance, or null on failure
117
 */
118
dc1394camera_t dc1394_camera_new(dc1394_t d, long guid);
119

120
/**
121
 * Creates a new camera instance using GUID and unit number
122
 * @param d System context
123
 * @param guid Camera GUID
124
 * @param unit Unit number on the bus
125
 * @return Camera instance, or null on failure
126
 */
127
dc1394camera_t dc1394_camera_new_unit(dc1394_t d, long guid, int unit);
128

129
/**
130
 * Releases camera instance and associated resources
131
 * @param camera Camera instance to release
132
 */
133
void dc1394_camera_free(dc1394camera_t camera);
134

135
/**
136
 * Checks if two cameras are the same device
137
 * @param camera1 First camera
138
 * @param camera2 Second camera
139
 * @return true if cameras are the same device, false otherwise
140
 */
141
boolean dc1394_is_same_camera(dc1394camera_t camera1, dc1394camera_t camera2);
142
```
143

144
**Usage Example:**
145

146
```java
147
import org.bytedeco.libdc1394.*;
148
import static org.bytedeco.libdc1394.global.dc1394.*;
149

150
dc1394_t d = dc1394_new();
151
dc1394camera_list_t list = new dc1394camera_list_t();
152

153
// Discover cameras
154
dc1394_camera_enumerate(d, list);
155
if (list.num() == 0) {
156
    System.err.println("No cameras found");
157
    dc1394_camera_free_list(list);
158
    dc1394_free(d);
159
    return;
160
}
161

162
// Create camera instance from first discovered camera
163
long guid = list.ids().guid();
164
dc1394camera_t camera = dc1394_camera_new(d, guid);
165
if (camera == null) {
166
    System.err.println("Failed to create camera instance");
167
    dc1394_camera_free_list(list);
168
    dc1394_free(d);
169
    return;
170
}
171

172
System.out.println("Successfully created camera instance");
173
System.out.println("Camera model: " + camera.model());
174
System.out.println("Camera vendor: " + camera.vendor());
175

176
// Print detailed camera information
177
dc1394_camera_print_info(camera);
178

179
// Always release resources
180
dc1394_camera_free_list(list);
181
dc1394_camera_free(camera);
182
dc1394_free(d);
183
```
184

185
### Power and Reset Control
186

187
Controls camera power state and reset functionality.
188

189
```java { .api }
190
/**
191
 * Sets camera power state
192
 * @param camera Camera instance
193
 * @param pwr Power state (DC1394_ON or DC1394_OFF)
194
 * @return DC1394_SUCCESS on success, error code on failure
195
 */
196
int dc1394_camera_set_power(dc1394camera_t camera, int pwr);
197

198
/**
199
 * Resets the camera
200
 * @param camera Camera instance to reset
201
 * @return DC1394_SUCCESS on success, error code on failure
202
 */
203
int dc1394_camera_reset(dc1394camera_t camera);
204
```
205

206
### Broadcast Control
207

208
Manages broadcast settings for multi-camera operations.
209

210
```java { .api }
211
/**
212
 * Sets camera broadcast mode for multi-camera control
213
 * @param camera Camera instance
214
 * @param pwr Broadcast state (DC1394_ON or DC1394_OFF)
215
 * @return DC1394_SUCCESS on success, error code on failure
216
 */
217
int dc1394_camera_set_broadcast(dc1394camera_t camera, int pwr);
218

219
/**
220
 * Gets camera broadcast mode state
221
 * @param camera Camera instance
222
 * @param pwr Output parameter for broadcast state
223
 * @return DC1394_SUCCESS on success, error code on failure
224
 */
225
int dc1394_camera_get_broadcast(dc1394camera_t camera, IntPointer pwr);
226
```
227

228
## Types
229

230
### System Context
231

232
```java { .api }
233
/**
234
 * Main libdc1394 system context
235
 * Opaque structure - no direct field access
236
 */
237
class dc1394_t extends Pointer {
238
    // Internal implementation hidden
239
}
240
```
241

242
### Camera List Types
243

244
```java { .api }
245
/**
246
 * Camera list container for discovery results
247
 */
248
class dc1394camera_list_t extends Pointer {
249
    /**
250
     * Number of cameras found
251
     * @return Count of discovered cameras
252
     */
253
    int num();
254
    
255
    /**
256
     * Array of camera identifiers
257
     * @return Pointer to first camera ID in array
258
     */
259
    dc1394camera_id_t ids();
260
}
261

262
/**
263
 * Camera identifier with GUID and unit information
264
 */
265
class dc1394camera_id_t extends Pointer {
266
    /**
267
     * Camera unit number on the IEEE 1394 bus
268
     * @return Unit number
269
     */
270
    int unit();
271
    
272
    /**
273
     * Camera globally unique identifier (GUID)
274
     * @return 64-bit GUID
275
     */
276
    long guid();
277
}
278
```
279

280
## Constants
281

282
### Power States
283

284
```java { .api }
285
// Power control states
286
static final int DC1394_ON = 1;
287
static final int DC1394_OFF = 0;
288
```
289

290
### Common Error Codes
291

292
```java { .api }
293
// System operation results
294
static final int DC1394_SUCCESS = 0;
295
static final int DC1394_FAILURE = -1;
296
static final int DC1394_NOT_A_CAMERA = -2;
297
static final int DC1394_FUNCTION_NOT_SUPPORTED = -3;
298
static final int DC1394_CAMERA_NOT_INITIALIZED = -4;
299
static final int DC1394_MEMORY_ALLOCATION_FAILURE = -5;
300
```
301

302
## Error Handling
303

304
System management functions return integer error codes. Always check return values:
305

306
```java
307
int err = dc1394_camera_enumerate(d, list);
308
if (err != DC1394_SUCCESS) {
309
    System.err.println("Camera enumeration failed with error: " + err);
310
    // Handle error appropriately
311
}
312
```
313

314
Use the logging functions for detailed error information:
315

316
```java
317
if (camera == null) {
318
    dc1394_log_error("Failed to create camera instance for GUID: " + 
319
                     Long.toHexString(guid));
320
}
321
```